1 /*---------------------------------------------------------------------------- 2 * 3 * File: 4 * eas.h 5 * 6 * Contents and purpose: 7 * The public interface header for the EAS synthesizer. 8 * 9 * This header only contains declarations that are specific 10 * to this implementation. 11 * 12 * DO NOT MODIFY THIS FILE! 13 * 14 * Copyright Sonic Network Inc. 2005, 2006 15 16 * Licensed under the Apache License, Version 2.0 (the "License"); 17 * you may not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, 24 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 *---------------------------------------------------------------------------- 29 * Revision Control: 30 * $Revision: 852 $ 31 * $Date: 2007-09-04 11:43:49 -0700 (Tue, 04 Sep 2007) $ 32 *---------------------------------------------------------------------------- 33 */ 34 35 #ifndef _EAS_H 36 #define _EAS_H 37 38 #include "eas_types.h" 39 40 /* for C++ linkage */ 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /* library version macro */ 46 #define MAKE_LIB_VERSION(a,b,c,d) (((((((EAS_U32) a <<8) | (EAS_U32) b) << 8) | (EAS_U32) c) << 8) | (EAS_U32) d) 47 #define LIB_VERSION MAKE_LIB_VERSION(3, 6, 10, 14) 48 49 typedef struct 50 { 51 EAS_U32 libVersion; 52 EAS_BOOL checkedVersion; 53 EAS_I32 maxVoices; 54 EAS_I32 numChannels; 55 EAS_I32 sampleRate; 56 EAS_I32 mixBufferSize; 57 EAS_BOOL filterEnabled; 58 EAS_U32 buildTimeStamp; 59 EAS_CHAR *buildGUID; 60 } S_EAS_LIB_CONFIG; 61 62 /* enumerated effects module numbers for configuration */ 63 typedef enum 64 { 65 EAS_MODULE_ENHANCER = 0, 66 EAS_MODULE_COMPRESSOR, 67 EAS_MODULE_REVERB, 68 EAS_MODULE_CHORUS, 69 EAS_MODULE_WIDENER, 70 EAS_MODULE_GRAPHIC_EQ, 71 EAS_MODULE_WOW, 72 EAS_MODULE_MAXIMIZER, 73 EAS_MODULE_TONECONTROLEQ, 74 NUM_EFFECTS_MODULES 75 } E_FX_MODULES; 76 77 /* enumerated optional module numbers for configuration */ 78 typedef enum 79 { 80 EAS_MODULE_MMAPI_TONE_CONTROL = 0, 81 EAS_MODULE_METRICS 82 } E_OPT_MODULES; 83 #define NUM_OPTIONAL_MODULES 2 84 85 /* enumerated audio decoders for configuration */ 86 typedef enum 87 { 88 EAS_DECODER_PCM = 0, 89 EAS_DECODER_SMAF_ADPCM, 90 EAS_DECODER_IMA_ADPCM, 91 EAS_DECODER_7BIT_SMAF_ADPCM, 92 EAS_DECODER_NOT_SUPPORTED 93 } E_DECODER_MODULES; 94 #define NUM_DECODER_MODULES 4 95 96 /* defines for EAS_PEOpenStream flags parameter */ 97 #define PCM_FLAGS_STEREO 0x00000100 /* stream is stereo */ 98 #define PCM_FLAGS_8_BIT 0x00000001 /* 8-bit format */ 99 #define PCM_FLAGS_UNSIGNED 0x00000010 /* unsigned format */ 100 #define PCM_FLAGS_STREAMING 0x80000000 /* streaming mode */ 101 102 /* maximum volume setting */ 103 #define EAS_MAX_VOLUME 100 104 105 /*---------------------------------------------------------------------------- 106 * EAS_Init() 107 *---------------------------------------------------------------------------- 108 * Purpose: 109 * Initialize the synthesizer library 110 * 111 * Inputs: 112 * polyphony - number of voices to play (dynamic memory model only) 113 * ppLibData - pointer to data handle variable for this instance 114 * 115 * Outputs: 116 * 117 *---------------------------------------------------------------------------- 118 */ 119 EAS_PUBLIC EAS_RESULT EAS_Init (EAS_DATA_HANDLE *ppEASData); 120 121 /*---------------------------------------------------------------------------- 122 * EAS_Config() 123 *---------------------------------------------------------------------------- 124 * Purpose: 125 * Returns a pointer to a structure containing the configuration options 126 * in this library build. 127 * 128 * Inputs: 129 * 130 * Outputs: 131 * 132 *---------------------------------------------------------------------------- 133 */ 134 EAS_PUBLIC const S_EAS_LIB_CONFIG *EAS_Config (void); 135 136 /*---------------------------------------------------------------------------- 137 * EAS_Shutdown() 138 *---------------------------------------------------------------------------- 139 * Purpose: 140 * Shuts down the library. Deallocates any memory associated with the 141 * synthesizer (dynamic memory model only) 142 * 143 * Inputs: 144 * pEASData - handle to data for this instance 145 * 146 * Outputs: 147 * 148 *---------------------------------------------------------------------------- 149 */ 150 EAS_PUBLIC EAS_RESULT EAS_Shutdown (EAS_DATA_HANDLE pEASData); 151 152 /*---------------------------------------------------------------------------- 153 * EAS_Render() 154 *---------------------------------------------------------------------------- 155 * Purpose: 156 * Parse the Midi data and render PCM audio data. 157 * 158 * Inputs: 159 * pEASData - buffer for internal EAS data 160 * pOut - output buffer pointer 161 * nNumRequested - requested num samples to generate 162 * pnNumGenerated - actual number of samples generated 163 * 164 * Outputs: 165 * EAS_SUCCESS if PCM data was successfully rendered 166 * 167 *---------------------------------------------------------------------------- 168 */ 169 EAS_PUBLIC EAS_RESULT EAS_Render (EAS_DATA_HANDLE pEASData, EAS_PCM *pOut, EAS_I32 numRequested, EAS_I32 *pNumGenerated); 170 171 /*---------------------------------------------------------------------------- 172 * EAS_SetTransposition) 173 *---------------------------------------------------------------------------- 174 * Purpose: 175 * Sets the key tranposition for the synthesizer. Transposes all 176 * melodic instruments by the specified amount. Range is limited 177 * to +/-12 semitones. 178 * 179 * Inputs: 180 * pEASData - handle to data for this instance 181 * streamHandle - handle to stream 182 * transposition - +/-12 semitones 183 * 184 * Outputs: 185 * 186 * Side Effects: 187 * 188 *---------------------------------------------------------------------------- 189 */ 190 EAS_PUBLIC EAS_RESULT EAS_SetTransposition (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 transposition); 191 #define MAX_TRANSPOSE 12 192 193 194 /*---------------------------------------------------------------------------- 195 * EAS_SetVolume() 196 *---------------------------------------------------------------------------- 197 * Purpose: 198 * Set the master volume for the mixer. The default volume setting is 199 * 90 (-10 dB). The volume range is 0 to 100 in 1dB increments. 200 * 201 * Inputs: 202 * pEASData - pointer to overall EAS data structure 203 * volume - the desired master volume 204 * 205 * Outputs: 206 * 207 * 208 * Side Effects: 209 * overrides any previously set master volume from sysex 210 * 211 *---------------------------------------------------------------------------- 212 */ 213 EAS_PUBLIC EAS_RESULT EAS_SetVolume (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 volume); 214 215 /*---------------------------------------------------------------------------- 216 * EAS_OpenFile() 217 *---------------------------------------------------------------------------- 218 * Purpose: 219 * Opens a file for audio playback. 220 * 221 * Inputs: 222 * pEASData - pointer to overall EAS data structure 223 * locator - pointer to filename or other locating information 224 * pStreamHandle - pointer to stream handle variable 225 * 226 * Outputs: 227 * 228 * 229 * Side Effects: 230 * 231 *---------------------------------------------------------------------------- 232 */ 233 EAS_PUBLIC EAS_RESULT EAS_OpenFile (EAS_DATA_HANDLE pEASData, EAS_FILE_LOCATOR locator, EAS_HANDLE *pStreamHandle); 234 235 #ifdef MMAPI_SUPPORT 236 /*---------------------------------------------------------------------------- 237 * EAS_MMAPIToneControl() 238 *---------------------------------------------------------------------------- 239 * Purpose: 240 * Opens a ToneControl file for audio playback. 241 * 242 * Inputs: 243 * pEASData - pointer to overall EAS data structure 244 * locator - pointer to filename or other locating information 245 * pStreamHandle - pointer to stream handle variable 246 * 247 * Outputs: 248 * 249 * 250 * Side Effects: 251 * 252 *---------------------------------------------------------------------------- 253 */ 254 EAS_PUBLIC EAS_RESULT EAS_MMAPIToneControl (EAS_DATA_HANDLE pEASData, EAS_FILE_LOCATOR locator, EAS_HANDLE *pStreamHandle); 255 256 /*---------------------------------------------------------------------------- 257 * EAS_GetWaveFmtChunk 258 *---------------------------------------------------------------------------- 259 * Helper function to retrieve WAVE file fmt chunk for MMAPI 260 *---------------------------------------------------------------------------- 261 * pEASData - pointer to EAS persistent data object 262 * streamHandle - stream handle 263 * pFmtChunk - pointer to pointer to FMT chunk data 264 *---------------------------------------------------------------------------- 265 */ 266 EAS_PUBLIC EAS_RESULT EAS_GetWaveFmtChunk (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_VOID_PTR *ppFmtChunk); 267 #endif 268 269 /*---------------------------------------------------------------------------- 270 * EAS_GetFileType 271 *---------------------------------------------------------------------------- 272 * Returns the file type (see eas_types.h for enumerations) 273 *---------------------------------------------------------------------------- 274 * pEASData - pointer to EAS persistent data object 275 * streamHandle - stream handle 276 * pFileType - pointer to variable to receive file type 277 *---------------------------------------------------------------------------- 278 */ 279 EAS_PUBLIC EAS_RESULT EAS_GetFileType (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pFileType); 280 281 /*---------------------------------------------------------------------------- 282 * EAS_ParseMetaData() 283 *---------------------------------------------------------------------------- 284 * Purpose: 285 * 286 * 287 * Inputs: 288 * pEASData - pointer to overall EAS data structure 289 * streamHandle - file or stream handle 290 * playLength - pointer to variable to store the play length (in msecs) 291 * 292 * Outputs: 293 * 294 * 295 * Side Effects: 296 * - resets the parser to the start of the file 297 *---------------------------------------------------------------------------- 298 */ 299 EAS_PUBLIC EAS_RESULT EAS_ParseMetaData (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pPlayLength); 300 301 /*---------------------------------------------------------------------------- 302 * EAS_Prepare() 303 *---------------------------------------------------------------------------- 304 * Purpose: 305 * Prepares the synthesizer to play the file or stream. Parses the first 306 * frame of data from the file and arms the synthesizer. 307 * 308 * Inputs: 309 * pEASData - pointer to overall EAS data structure 310 * streamHandle - file or stream handle 311 * 312 * Outputs: 313 * 314 * 315 * Side Effects: 316 * 317 *---------------------------------------------------------------------------- 318 */ 319 EAS_PUBLIC EAS_RESULT EAS_Prepare (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 320 321 /*---------------------------------------------------------------------------- 322 * EAS_State() 323 *---------------------------------------------------------------------------- 324 * Purpose: 325 * Returns the state of an audio file or stream. 326 * 327 * Inputs: 328 * pEASData - pointer to overall EAS data structure 329 * streamHandle - file or stream handle 330 * 331 * Outputs: 332 * 333 * 334 * Side Effects: 335 * 336 *---------------------------------------------------------------------------- 337 */ 338 EAS_PUBLIC EAS_RESULT EAS_State (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_STATE *pState); 339 340 /*---------------------------------------------------------------------------- 341 * EAS_RegisterMetaDataCallback() 342 *---------------------------------------------------------------------------- 343 * Purpose: 344 * Registers a metadata callback function for parsed metadata. To 345 * de-register the callback, call this function again with parameter 346 * cbFunc set to NULL. 347 * 348 * Inputs: 349 * pEASData - pointer to overall EAS data structure 350 * streamHandle - file or stream handle 351 * cbFunc - pointer to host callback function 352 * metaDataBuffer - pointer to metadata buffer 353 * metaDataBufSize - maximum size of the metadata buffer 354 * 355 * Outputs: 356 * 357 * 358 * Side Effects: 359 * 360 *---------------------------------------------------------------------------- 361 */ 362 EAS_PUBLIC EAS_RESULT EAS_RegisterMetaDataCallback ( 363 EAS_DATA_HANDLE pEASData, 364 EAS_HANDLE streamHandle, 365 EAS_METADATA_CBFUNC cbFunc, 366 char *metaDataBuffer, 367 EAS_I32 metaDataBufSize, 368 EAS_VOID_PTR pUserData); 369 370 /*---------------------------------------------------------------------------- 371 * EAS_GetNoteCount () 372 *---------------------------------------------------------------------------- 373 * Returns the total number of notes played in this stream 374 * 375 * Inputs: 376 * pEASData - pointer to overall EAS data structure 377 * streamHandle - file or stream handle 378 * pNoteCount - pointer to variable to receive note count 379 *---------------------------------------------------------------------------- 380 */ 381 EAS_PUBLIC EAS_RESULT EAS_GetNoteCount (EAS_DATA_HANDLE pEASData, EAS_HANDLE pStream, EAS_I32 *pNoteCount); 382 383 /*---------------------------------------------------------------------------- 384 * EAS_CloseFile() 385 *---------------------------------------------------------------------------- 386 * Purpose: 387 * Closes an audio file or stream. Playback should have either paused or 388 * completed (EAS_State returns EAS_PAUSED or EAS_STOPPED). 389 * 390 * Inputs: 391 * pEASData - pointer to overall EAS data structure 392 * streamHandle - file or stream handle 393 * 394 * Outputs: 395 * 396 * 397 * Side Effects: 398 * 399 *---------------------------------------------------------------------------- 400 */ 401 EAS_PUBLIC EAS_RESULT EAS_CloseFile (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 402 403 /*---------------------------------------------------------------------------- 404 * EAS_OpenMIDIStream() 405 *---------------------------------------------------------------------------- 406 * Purpose: 407 * Opens a raw MIDI stream allowing the host to route MIDI cable data directly to the synthesizer 408 * 409 * Inputs: 410 * pEASData - pointer to overall EAS data structure 411 * pStreamHandle - pointer to variable to hold file or stream handle 412 * streamHandle - open stream or NULL for new synthesizer instance 413 * 414 * Outputs: 415 * 416 * 417 * Side Effects: 418 * 419 *---------------------------------------------------------------------------- 420 */ 421 EAS_PUBLIC EAS_RESULT EAS_OpenMIDIStream (EAS_DATA_HANDLE pEASData, EAS_HANDLE *pStreamHandle, EAS_HANDLE streamHandle); 422 423 /*---------------------------------------------------------------------------- 424 * EAS_WriteMIDIStream() 425 *---------------------------------------------------------------------------- 426 * Purpose: 427 * Send data to the MIDI stream device 428 * 429 * Inputs: 430 * pEASData - pointer to overall EAS data structure 431 * streamHandle - stream handle 432 * pBuffer - pointer to buffer 433 * count - number of bytes to write 434 * 435 * Outputs: 436 * 437 * 438 * Side Effects: 439 * 440 *---------------------------------------------------------------------------- 441 */ 442 EAS_PUBLIC EAS_RESULT EAS_WriteMIDIStream(EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_U8 *pBuffer, EAS_I32 count); 443 444 /*---------------------------------------------------------------------------- 445 * EAS_CloseMIDIStream() 446 *---------------------------------------------------------------------------- 447 * Purpose: 448 * Closes a raw MIDI stream 449 * 450 * Inputs: 451 * pEASData - pointer to overall EAS data structure 452 * streamHandle - stream handle 453 * 454 * Outputs: 455 * 456 * 457 * Side Effects: 458 * 459 *---------------------------------------------------------------------------- 460 */ 461 EAS_PUBLIC EAS_RESULT EAS_CloseMIDIStream (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 462 463 /*---------------------------------------------------------------------------- 464 * EAS_Locate() 465 *---------------------------------------------------------------------------- 466 * Purpose: 467 * Locate into the file associated with the handle. 468 * 469 * Inputs: 470 * pEASData - pointer to overall EAS data structure 471 * streamHandle - file handle 472 * milliseconds - playback offset from start of file in milliseconds 473 * 474 * Outputs: 475 * 476 * 477 * Side Effects: 478 * the actual offset will be quantized to the closest update period, typically 479 * a resolution of 5.9ms. Notes that are started prior to this time will not 480 * sound. Any notes currently playing will be shut off. 481 * 482 *---------------------------------------------------------------------------- 483 */ 484 EAS_PUBLIC EAS_RESULT EAS_Locate (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 milliseconds, EAS_BOOL offset); 485 486 /*---------------------------------------------------------------------------- 487 * EAS_GetLocation() 488 *---------------------------------------------------------------------------- 489 * Purpose: 490 * Returns the current playback offset 491 * 492 * Inputs: 493 * pEASData - pointer to overall EAS data structure 494 * streamHandle - file handle 495 * 496 * Outputs: 497 * The offset in milliseconds from the start of the current sequence, quantized 498 * to the nearest update period. Actual resolution is typically 5.9 ms. 499 * 500 * Side Effects: 501 * 502 *---------------------------------------------------------------------------- 503 */ 504 EAS_PUBLIC EAS_RESULT EAS_GetLocation (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pTime); 505 506 /*---------------------------------------------------------------------------- 507 * EAS_Pause() 508 *---------------------------------------------------------------------------- 509 * Purpose: 510 * Pauses the playback of the data associated with this handle. The audio 511 * is gracefully ramped down to prevent clicks and pops. It may take several 512 * buffers of audio before the audio is muted. 513 * 514 * Inputs: 515 * psEASData - pointer to overall EAS data structure 516 * streamHandle - file or stream handle 517 * 518 * Outputs: 519 * 520 * 521 * Side Effects: 522 * 523 * 524 *---------------------------------------------------------------------------- 525 */ 526 EAS_PUBLIC EAS_RESULT EAS_Pause (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 527 528 /*---------------------------------------------------------------------------- 529 * EAS_Resume() 530 *---------------------------------------------------------------------------- 531 * Purpose: 532 * Resumes the playback of the data associated with this handle. The audio 533 * is gracefully ramped up to prevent clicks and pops. 534 * 535 * Inputs: 536 * psEASData - pointer to overall EAS data structure 537 * streamHandle - file or stream handle 538 * 539 * Outputs: 540 * 541 * 542 * Side Effects: 543 * 544 * 545 *---------------------------------------------------------------------------- 546 */ 547 EAS_PUBLIC EAS_RESULT EAS_Resume (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 548 549 /*---------------------------------------------------------------------------- 550 * EAS_SetParameter() 551 *---------------------------------------------------------------------------- 552 * Purpose: 553 * Set the parameter of a module. See E_MODULES for a list of modules 554 * and the header files of the modules for a list of parameters. 555 * 556 * Inputs: 557 * psEASData - pointer to overall EAS data structure 558 * handle - file or stream handle 559 * module - enumerated module number 560 * param - enumerated parameter number 561 * value - new parameter value 562 * 563 * Outputs: 564 * 565 * 566 * Side Effects: 567 * 568 * 569 *---------------------------------------------------------------------------- 570 */ 571 EAS_PUBLIC EAS_RESULT EAS_SetParameter (EAS_DATA_HANDLE pEASData, EAS_I32 module, EAS_I32 param, EAS_I32 value); 572 573 #ifdef _METRICS_ENABLED 574 /*---------------------------------------------------------------------------- 575 * EAS_MetricsReport() 576 *---------------------------------------------------------------------------- 577 * Purpose: 578 * Displays the current metrics through the EAS_Report interface. 579 * 580 * Inputs: 581 * pEASData - instance data handle 582 * 583 * Outputs: 584 * 585 * 586 * Side Effects: 587 * 588 *---------------------------------------------------------------------------- 589 */ 590 EAS_PUBLIC EAS_RESULT EAS_MetricsReport (EAS_DATA_HANDLE pEASData); 591 592 /*---------------------------------------------------------------------------- 593 * EAS_MetricsReset() 594 *---------------------------------------------------------------------------- 595 * Purpose: 596 * Displays the current metrics through the EAS_Report interface. 597 * 598 * Inputs: 599 * pEASData - instance data handle 600 * 601 * Outputs: 602 * 603 * 604 * Side Effects: 605 * 606 *---------------------------------------------------------------------------- 607 */ 608 EAS_PUBLIC EAS_RESULT EAS_MetricsReset (EAS_DATA_HANDLE pEASData); 609 #endif 610 611 /*---------------------------------------------------------------------------- 612 * EAS_SearchFile 613 *---------------------------------------------------------------------------- 614 * Search file for specific sequence starting at current file 615 * position. Returns offset to start of sequence. 616 * 617 * Inputs: 618 * pEASData - pointer to EAS persistent data object 619 * fileHandle - file handle 620 * searchString - pointer to search sequence 621 * len - length of search sequence 622 * pOffset - pointer to variable to store offset to sequence 623 * 624 * Returns EAS_EOF if end-of-file is reached 625 *---------------------------------------------------------------------------- 626 */ 627 EAS_RESULT EAS_SearchFile (EAS_DATA_HANDLE pEASData, EAS_FILE_HANDLE fileHandle, const EAS_U8 *searchString, EAS_I32 len, EAS_I32 *pOffset); 628 629 #ifdef __cplusplus 630 } /* end extern "C" */ 631 #endif 632 633 #endif /* #ifndef _EAS_H */ 634