1 /*----------------------------------------------------------------------------
2  *
3  * File:
4  * eas_pcm.h
5  *
6  * Contents and purpose:
7  * External function prototypes for eas_pcm.c module
8  *
9  *
10  * Copyright Sonic Network Inc. 2005
11 
12  * Licensed under the Apache License, Version 2.0 (the "License");
13  * you may not use this file except in compliance with the License.
14  * You may obtain a copy of the License at
15  *
16  *      http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  *
24  *----------------------------------------------------------------------------
25  * Revision Control:
26  *   $Revision: 847 $
27  *   $Date: 2007-08-27 21:30:08 -0700 (Mon, 27 Aug 2007) $
28  *----------------------------------------------------------------------------
29 */
30 
31 #ifndef _EAS_PCM_H
32 #define _EAS_PCM_H
33 
34 /* default gain setting - roughly unity gain */
35 #define PCM_DEFAULT_GAIN_SETTING    0x6000
36 
37 typedef struct s_pcm_state_tag *EAS_PCM_HANDLE;
38 typedef void (*EAS_PCM_CALLBACK) (EAS_DATA_HANDLE pEASData, EAS_VOID_PTR cbInstData, EAS_PCM_HANDLE pcmHandle, EAS_STATE state);
39 
40 /* parameters for EAS_PEOpenStream */
41 typedef struct s_pcm_open_params_tag
42 {
43     EAS_FILE_HANDLE     fileHandle;
44     EAS_I32             decoder;
45     EAS_U32             sampleRate;
46     EAS_I32             size;
47     EAS_U32             loopStart;
48     EAS_U32             loopSamples;
49     EAS_I32             blockSize;
50     EAS_U32             flags;
51     EAS_U32             envData;
52     EAS_I16             volume;
53     EAS_PCM_CALLBACK    pCallbackFunc;
54     EAS_VOID_PTR        cbInstData;
55  } S_PCM_OPEN_PARAMS;
56 
57 /*----------------------------------------------------------------------------
58  * EAS_PEInit()
59  *----------------------------------------------------------------------------
60  * Purpose:
61  * Initializes the PCM engine
62  *
63  * Inputs:
64  *
65  *
66  * Outputs:
67  *
68  *
69  * Side Effects:
70  *
71  *----------------------------------------------------------------------------
72 */
73 EAS_RESULT EAS_PEInit (EAS_DATA_HANDLE pEASData);
74 
75 /*----------------------------------------------------------------------------
76  * EAS_PEShutdown()
77  *----------------------------------------------------------------------------
78  * Purpose:
79  * Shuts down the PCM engine
80  *
81  * Inputs:
82  *
83  *
84  * Outputs:
85  *
86  *
87  * Side Effects:
88  *
89  *----------------------------------------------------------------------------
90 */
91 EAS_RESULT EAS_PEShutdown (EAS_DATA_HANDLE pEASData);
92 
93 /*----------------------------------------------------------------------------
94  * EAS_PEOpenStream()
95  *----------------------------------------------------------------------------
96  * Purpose:
97  * Starts up a PCM playback
98  *
99  * Inputs:
100  *
101  *
102  * Outputs:
103  *
104  *
105  * Side Effects:
106  *
107  *----------------------------------------------------------------------------
108 */
109 EAS_RESULT EAS_PEOpenStream (EAS_DATA_HANDLE pEASData, S_PCM_OPEN_PARAMS *pParams, EAS_PCM_HANDLE *pHandle);
110 
111 /*----------------------------------------------------------------------------
112  * EAS_PEContinueStream()
113  *----------------------------------------------------------------------------
114  * Purpose:
115  * Continues a PCM stream
116  *
117  * Inputs:
118  *
119  *
120  * Outputs:
121  *
122  *
123  * Side Effects:
124  *
125  *----------------------------------------------------------------------------
126 */
127 EAS_RESULT EAS_PEContinueStream (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_I32 size);
128 
129 /*----------------------------------------------------------------------------
130  * EAS_PEGetFileHandle()
131  *----------------------------------------------------------------------------
132  * Purpose:
133  * Returns the file handle of a stream
134  *
135  * Inputs:
136  *
137  *
138  * Outputs:
139  *
140  *
141  * Side Effects:
142  *
143  *----------------------------------------------------------------------------
144 */
145 EAS_RESULT EAS_PEGetFileHandle (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_FILE_HANDLE *pFileHandle);
146 
147 /*----------------------------------------------------------------------------
148  * EAS_PERender()
149  *----------------------------------------------------------------------------
150  * Purpose:
151  * Render a buffer of PCM audio
152  *
153  * Inputs:
154  *
155  *
156  * Outputs:
157  *
158  *
159  * Side Effects:
160  *
161  *----------------------------------------------------------------------------
162 */
163 EAS_RESULT EAS_PERender (EAS_DATA_HANDLE pEASData, EAS_I32 numSamples);
164 
165 /*----------------------------------------------------------------------------
166  * EAS_PEUpdateParams()
167  *----------------------------------------------------------------------------
168  * Purpose:
169  * Update the pitch and volume parameters using MIDI controls
170  *
171  * Inputs:
172  *
173  *
174  * Outputs:
175  *
176  *
177  * Side Effects:
178  *
179  *----------------------------------------------------------------------------
180 */
181 EAS_RESULT EAS_PEUpdateParams (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 pitch, EAS_I16 gainLeft, EAS_I16 gainRight);
182 
183 /*----------------------------------------------------------------------------
184  * EAS_PELocate()
185  *----------------------------------------------------------------------------
186  * Purpose:
187  * This function seeks to the requested place in the file. Accuracy
188  * is dependent on the sample rate and block size.
189  *
190  * Inputs:
191  * pEASData         - pointer to overall EAS data structure
192  * pState           - stream handle
193  * time             - media time in milliseconds
194  *----------------------------------------------------------------------------
195 */
196 EAS_RESULT EAS_PELocate (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I32 time);
197 
198 /*----------------------------------------------------------------------------
199  * EAS_PEUpdateVolume()
200  *----------------------------------------------------------------------------
201  * Purpose:
202  * Update the volume parameters for a PCM stream
203  *
204  * Inputs:
205  * pEASData         - pointer to EAS library instance data
206  * handle           - pointer to S_PCM_STATE for this stream
207  * gainLeft         - linear gain multipler in 1.15 fraction format
208  * gainRight        - linear gain multipler in 1.15 fraction format
209  * initial          - initial settings, set current gain
210  *
211  * Outputs:
212  *
213  *
214  * Side Effects:
215  *
216  * Notes
217  * In mono mode, leftGain controls the output gain and rightGain is ignored
218  *----------------------------------------------------------------------------
219 */
220 /*lint -esym(715, pEASData) reserved for future use */
221 EAS_RESULT EAS_PEUpdateVolume (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 volume);
222 
223 /*----------------------------------------------------------------------------
224  * EAS_PEUpdatePitch()
225  *----------------------------------------------------------------------------
226  * Purpose:
227  * Update the pitch parameter for a PCM stream
228  *
229  * Inputs:
230  * pEASData         - pointer to EAS library instance data
231  * pState           - pointer to S_PCM_STATE for this stream
232  * pitch            - new pitch value in pitch cents
233  *----------------------------------------------------------------------------
234 */
235 /*lint -esym(715, pEASData) reserved for future use */
236 EAS_RESULT EAS_PEUpdatePitch (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 pitch);
237 
238 /*----------------------------------------------------------------------------
239  * EAS_PEState()
240  *----------------------------------------------------------------------------
241  * Purpose:
242  * Returns the current state of the stream
243  *
244  * Inputs:
245  * pEASData         - pointer to overall EAS data structure
246  * handle           - pointer to file handle
247  * pState           - pointer to variable to store state
248  *
249  * Outputs:
250  *
251  *
252  * Side Effects:
253  *
254  * Notes:
255  * This interface is also exposed in the internal library for use by the other modules.
256  *----------------------------------------------------------------------------
257 */
258 EAS_RESULT EAS_PEState (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_STATE *pState);
259 
260 /*----------------------------------------------------------------------------
261  * EAS_PEClose()
262  *----------------------------------------------------------------------------
263  * Purpose:
264  * Close the file and clean up
265  *
266  * Inputs:
267  * pEASData         - pointer to overall EAS data structure
268  * handle           - pointer to file handle
269  *
270  * Outputs:
271  *
272  *
273  * Side Effects:
274  *
275  *----------------------------------------------------------------------------
276 */
277 EAS_RESULT EAS_PEClose (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
278 
279 /*----------------------------------------------------------------------------
280  * EAS_PEReset()
281  *----------------------------------------------------------------------------
282  * Purpose:
283  * Reset the sequencer. Used for locating backwards in the file.
284  *
285  * Inputs:
286  * pEASData         - pointer to overall EAS data structure
287  * handle           - pointer to file handle
288  *
289  * Outputs:
290  *
291  *
292  * Side Effects:
293  *
294  *----------------------------------------------------------------------------
295 */
296 EAS_RESULT EAS_PEReset (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
297 
298 /*----------------------------------------------------------------------------
299  * EAS_PEPause()
300  *----------------------------------------------------------------------------
301  * Purpose:
302  * Mute and pause rendering a PCM stream. Sets the gain target to zero and stops the playback
303  * at the end of the next audio frame.
304  *
305  * Inputs:
306  * pEASData         - pointer to EAS library instance data
307  * handle           - pointer to S_PCM_STATE for this stream
308  *
309  * Outputs:
310  *
311  *
312  * Side Effects:
313  *
314  *----------------------------------------------------------------------------
315 */
316 EAS_RESULT EAS_PEPause (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
317 
318 /*----------------------------------------------------------------------------
319  * EAS_PEResume()
320  *----------------------------------------------------------------------------
321  * Purpose:
322  * Resume rendering a PCM stream. Sets the gain target back to its
323  * previous setting and restarts playback at the end of the next audio
324  * frame.
325  *
326  * Inputs:
327  * pEASData         - pointer to EAS library instance data
328  * handle           - pointer to S_PCM_STATE for this stream
329  *
330  * Outputs:
331  *
332  *
333  * Side Effects:
334  *
335  *----------------------------------------------------------------------------
336 */
337 EAS_RESULT EAS_PEResume (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
338 
339 /*----------------------------------------------------------------------------
340  * EAS_PERelease()
341  *----------------------------------------------------------------------------
342  * Purpose:
343  * Put the PCM stream envelope into release.
344  *
345  * Inputs:
346  * pEASData         - pointer to EAS library instance data
347  * handle           - pointer to S_PCM_STATE for this stream
348  *
349  * Outputs:
350  *
351  *
352  * Side Effects:
353  *
354  *----------------------------------------------------------------------------
355 */
356 EAS_RESULT EAS_PERelease (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
357 
358 #endif /* end _EAS_PCM_H */
359 
360