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