eas_pcm.h revision a8c89077d78769bf4840fa91609edc51fe2fa02d 
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
37typedef struct s_pcm_state_tag *EAS_PCM_HANDLE;
38typedef 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 */
41typedef 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*/
73EAS_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*/
91EAS_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*/
109EAS_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*/
127EAS_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*/
145EAS_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*/
163EAS_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*/
181EAS_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*/
196EAS_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 */
221EAS_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 */
236EAS_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*/
258EAS_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*/
277EAS_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*/
296EAS_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*/
316EAS_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*/
337EAS_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*/
356EAS_RESULT EAS_PERelease (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);
357
358#endif /* end _EAS_PCM_H */
359
360