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_SetRepeat() 173 *---------------------------------------------------------------------------- 174 * Purpose: 175 * Set the selected stream to repeat. 176 * 177 * Inputs: 178 * pEASData - handle to data for this instance 179 * streamHandle - handle to stream 180 * repeatCount - repeat count (0 = no repeat, -1 = repeat forever) 181 * 182 * Outputs: 183 * 184 * Side Effects: 185 * 186 * Notes: 187 * 0 = no repeat 188 * 1 = repeat once, i.e. play through twice 189 * -1 = repeat forever 190 *---------------------------------------------------------------------------- 191 */ 192 EAS_PUBLIC EAS_RESULT EAS_SetRepeat (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 repeatCount); 193 194 /*---------------------------------------------------------------------------- 195 * EAS_GetRepeat() 196 *---------------------------------------------------------------------------- 197 * Purpose: 198 * Gets the current repeat count for the selected stream. 199 * 200 * Inputs: 201 * pEASData - handle to data for this instance 202 * streamHandle - handle to stream 203 * pRrepeatCount - pointer to variable to hold repeat count 204 * 205 * Outputs: 206 * 207 * Side Effects: 208 * 209 * Notes: 210 * 0 = no repeat 211 * 1 = repeat once, i.e. play through twice 212 * -1 = repeat forever 213 *---------------------------------------------------------------------------- 214 */ 215 EAS_PUBLIC EAS_RESULT EAS_GetRepeat (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pRepeatCount); 216 217 /*---------------------------------------------------------------------------- 218 * EAS_SetPlaybackRate() 219 *---------------------------------------------------------------------------- 220 * Purpose: 221 * Set the playback rate. 222 * 223 * Inputs: 224 * pEASData - handle to data for this instance 225 * streamHandle - handle to stream 226 * rate - rate (28-bit fractional amount) 227 * 228 * Outputs: 229 * 230 * Side Effects: 231 * 232 *---------------------------------------------------------------------------- 233 */ 234 EAS_PUBLIC EAS_RESULT EAS_SetPlaybackRate (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_U32 rate); 235 #define MAX_PLAYBACK_RATE (EAS_U32)(1L << 29) 236 #define MIN_PLAYBACK_RATE (EAS_U32)(1L << 27) 237 238 /*---------------------------------------------------------------------------- 239 * EAS_SetTransposition) 240 *---------------------------------------------------------------------------- 241 * Purpose: 242 * Sets the key tranposition for the synthesizer. Transposes all 243 * melodic instruments by the specified amount. Range is limited 244 * to +/-12 semitones. 245 * 246 * Inputs: 247 * pEASData - handle to data for this instance 248 * streamHandle - handle to stream 249 * transposition - +/-12 semitones 250 * 251 * Outputs: 252 * 253 * Side Effects: 254 * 255 *---------------------------------------------------------------------------- 256 */ 257 EAS_PUBLIC EAS_RESULT EAS_SetTransposition (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 transposition); 258 #define MAX_TRANSPOSE 12 259 260 /*---------------------------------------------------------------------------- 261 * EAS_SetSynthPolyphony() 262 *---------------------------------------------------------------------------- 263 * Purpose: 264 * Set the polyphony of the synthesizer. Value must be >= 1 and <= the 265 * maximum number of voices. This function will pin the polyphony 266 * at those limits 267 * 268 * Inputs: 269 * pEASData - pointer to overall EAS data structure 270 * synthNum - synthesizer number (0 = onboard, 1 = DSP) 271 * polyphonyCount - the desired polyphony count 272 * 273 * Outputs: 274 * 275 * Side Effects: 276 * 277 *---------------------------------------------------------------------------- 278 */ 279 EAS_PUBLIC EAS_RESULT EAS_SetSynthPolyphony (EAS_DATA_HANDLE pEASData, EAS_I32 synthNum, EAS_I32 polyphonyCount); 280 281 /*---------------------------------------------------------------------------- 282 * EAS_GetSynthPolyphony() 283 *---------------------------------------------------------------------------- 284 * Purpose: 285 * Returns the current polyphony setting of the synthesizer 286 * 287 * Inputs: 288 * pEASData - pointer to overall EAS data structure 289 * synthNum - synthesizer number (0 = onboard, 1 = DSP) 290 * pPolyphonyCount - pointer to variable to receive polyphony count 291 * 292 * Outputs: 293 * 294 * Side Effects: 295 * 296 *---------------------------------------------------------------------------- 297 */ 298 EAS_PUBLIC EAS_RESULT EAS_GetSynthPolyphony (EAS_DATA_HANDLE pEASData, EAS_I32 synthNum, EAS_I32 *pPolyphonyCount); 299 300 /*---------------------------------------------------------------------------- 301 * EAS_SetPolyphony() 302 *---------------------------------------------------------------------------- 303 * Purpose: 304 * Set the polyphony of the stream. Value must be >= 1 and <= the 305 * maximum number of voices. This function will pin the polyphony 306 * at those limits 307 * 308 * Inputs: 309 * pEASData - pointer to overall EAS data structure 310 * streamHandle - handle returned by EAS_OpenFile 311 * polyphonyCount - the desired polyphony count 312 * 313 * Outputs: 314 * 315 * Side Effects: 316 * 317 *---------------------------------------------------------------------------- 318 */ 319 EAS_PUBLIC EAS_RESULT EAS_SetPolyphony (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 polyphonyCount); 320 321 /*---------------------------------------------------------------------------- 322 * EAS_GetPolyphony() 323 *---------------------------------------------------------------------------- 324 * Purpose: 325 * Returns the current polyphony setting of the stream 326 * 327 * Inputs: 328 * pEASData - pointer to overall EAS data structure 329 * streamHandle - handle returned by EAS_OpenFile 330 * pPolyphonyCount - pointer to variable to receive polyphony count 331 * 332 * Outputs: 333 * 334 * Side Effects: 335 * 336 *---------------------------------------------------------------------------- 337 */ 338 EAS_PUBLIC EAS_RESULT EAS_GetPolyphony (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pPolyphonyCount); 339 340 /*---------------------------------------------------------------------------- 341 * EAS_SetPriority() 342 *---------------------------------------------------------------------------- 343 * Purpose: 344 * Set the priority of the stream. Determines which stream's voices 345 * are stolen when there are insufficient voices for all notes. 346 * Value must be in the range of 1-255, lower values are higher 347 * priority. The default priority is 50. 348 * 349 * Inputs: 350 * pEASData - pointer to overall EAS data structure 351 * streamHandle - handle returned by EAS_OpenFile 352 * polyphonyCount - the desired polyphony count 353 * 354 * Outputs: 355 * 356 * Side Effects: 357 * 358 *---------------------------------------------------------------------------- 359 */ 360 EAS_PUBLIC EAS_RESULT EAS_SetPriority (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 priority); 361 362 /*---------------------------------------------------------------------------- 363 * EAS_GetPriority() 364 *---------------------------------------------------------------------------- 365 * Purpose: 366 * Returns the current priority setting of the stream 367 * 368 * Inputs: 369 * pEASData - pointer to overall EAS data structure 370 * streamHandle - handle returned by EAS_OpenFile 371 * pPriority - pointer to variable to receive priority 372 * 373 * Outputs: 374 * 375 * Side Effects: 376 * 377 *---------------------------------------------------------------------------- 378 */ 379 EAS_PUBLIC EAS_RESULT EAS_GetPriority (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pPriority); 380 381 /*---------------------------------------------------------------------------- 382 * EAS_SetVolume() 383 *---------------------------------------------------------------------------- 384 * Purpose: 385 * Set the master volume for the mixer. The default volume setting is 386 * 90 (-10 dB). The volume range is 0 to 100 in 1dB increments. 387 * 388 * Inputs: 389 * pEASData - pointer to overall EAS data structure 390 * volume - the desired master volume 391 * 392 * Outputs: 393 * 394 * 395 * Side Effects: 396 * overrides any previously set master volume from sysex 397 * 398 *---------------------------------------------------------------------------- 399 */ 400 EAS_PUBLIC EAS_RESULT EAS_SetVolume (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 volume); 401 402 /*---------------------------------------------------------------------------- 403 * EAS_GetVolume() 404 *---------------------------------------------------------------------------- 405 * Purpose: 406 * Returns the master volume for the mixer in 1dB increments. 407 * 408 * Inputs: 409 * pEASData - pointer to overall EAS data structure 410 * volume - the desired master volume 411 * 412 * Outputs: 413 * 414 * 415 * Side Effects: 416 * overrides any previously set master volume from sysex 417 * 418 *---------------------------------------------------------------------------- 419 */ 420 EAS_PUBLIC EAS_I32 EAS_GetVolume (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 421 422 /*---------------------------------------------------------------------------- 423 * EAS_SetMaxLoad() 424 *---------------------------------------------------------------------------- 425 * Purpose: 426 * Sets the maximum workload the parsers will do in a single call to 427 * EAS_Render. The units are currently arbitrary, but should correlate 428 * well to the actual CPU cycles consumed. The primary effect is to 429 * reduce the occasional peaks in CPU cycles consumed when parsing 430 * dense parts of a MIDI score. Setting maxWorkLoad to zero disables 431 * the workload limiting function. 432 * 433 * Inputs: 434 * pEASData - handle to data for this instance 435 * maxLoad - the desired maximum workload 436 * 437 * Outputs: 438 * 439 * Side Effects: 440 * 441 *---------------------------------------------------------------------------- 442 */ 443 EAS_PUBLIC EAS_RESULT EAS_SetMaxLoad (EAS_DATA_HANDLE pEASData, EAS_I32 maxLoad); 444 445 /*---------------------------------------------------------------------------- 446 * EAS_SetMaxPCMStreams() 447 *---------------------------------------------------------------------------- 448 * Sets the maximum number of PCM streams allowed in parsers that 449 * use PCM streaming. 450 * 451 * Inputs: 452 * pEASData - pointer to overall EAS data structure 453 * streamHandle - handle returned by EAS_OpenFile 454 * maxNumStreams - maximum number of PCM streams 455 *---------------------------------------------------------------------------- 456 */ 457 EAS_PUBLIC EAS_RESULT EAS_SetMaxPCMStreams (EAS_DATA_HANDLE pEASData, EAS_HANDLE pStream, EAS_I32 maxNumStreams); 458 459 /*---------------------------------------------------------------------------- 460 * EAS_OpenFile() 461 *---------------------------------------------------------------------------- 462 * Purpose: 463 * Opens a file for audio playback. 464 * 465 * Inputs: 466 * pEASData - pointer to overall EAS data structure 467 * locator - pointer to filename or other locating information 468 * pStreamHandle - pointer to stream handle variable 469 * 470 * Outputs: 471 * 472 * 473 * Side Effects: 474 * 475 *---------------------------------------------------------------------------- 476 */ 477 EAS_PUBLIC EAS_RESULT EAS_OpenFile (EAS_DATA_HANDLE pEASData, EAS_FILE_LOCATOR locator, EAS_HANDLE *pStreamHandle); 478 479 #ifdef MMAPI_SUPPORT 480 /*---------------------------------------------------------------------------- 481 * EAS_MMAPIToneControl() 482 *---------------------------------------------------------------------------- 483 * Purpose: 484 * Opens a ToneControl file for audio playback. 485 * 486 * Inputs: 487 * pEASData - pointer to overall EAS data structure 488 * locator - pointer to filename or other locating information 489 * pStreamHandle - pointer to stream handle variable 490 * 491 * Outputs: 492 * 493 * 494 * Side Effects: 495 * 496 *---------------------------------------------------------------------------- 497 */ 498 EAS_PUBLIC EAS_RESULT EAS_MMAPIToneControl (EAS_DATA_HANDLE pEASData, EAS_FILE_LOCATOR locator, EAS_HANDLE *pStreamHandle); 499 500 /*---------------------------------------------------------------------------- 501 * EAS_GetWaveFmtChunk 502 *---------------------------------------------------------------------------- 503 * Helper function to retrieve WAVE file fmt chunk for MMAPI 504 *---------------------------------------------------------------------------- 505 * pEASData - pointer to EAS persistent data object 506 * streamHandle - stream handle 507 * pFmtChunk - pointer to pointer to FMT chunk data 508 *---------------------------------------------------------------------------- 509 */ 510 EAS_PUBLIC EAS_RESULT EAS_GetWaveFmtChunk (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_VOID_PTR *ppFmtChunk); 511 #endif 512 513 /*---------------------------------------------------------------------------- 514 * EAS_GetFileType 515 *---------------------------------------------------------------------------- 516 * Returns the file type (see eas_types.h for enumerations) 517 *---------------------------------------------------------------------------- 518 * pEASData - pointer to EAS persistent data object 519 * streamHandle - stream handle 520 * pFileType - pointer to variable to receive file type 521 *---------------------------------------------------------------------------- 522 */ 523 EAS_PUBLIC EAS_RESULT EAS_GetFileType (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pFileType); 524 525 /*---------------------------------------------------------------------------- 526 * EAS_ParseMetaData() 527 *---------------------------------------------------------------------------- 528 * Purpose: 529 * 530 * 531 * Inputs: 532 * pEASData - pointer to overall EAS data structure 533 * streamHandle - file or stream handle 534 * playLength - pointer to variable to store the play length (in msecs) 535 * 536 * Outputs: 537 * 538 * 539 * Side Effects: 540 * - resets the parser to the start of the file 541 *---------------------------------------------------------------------------- 542 */ 543 EAS_PUBLIC EAS_RESULT EAS_ParseMetaData (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pPlayLength); 544 545 /*---------------------------------------------------------------------------- 546 * EAS_Prepare() 547 *---------------------------------------------------------------------------- 548 * Purpose: 549 * Prepares the synthesizer to play the file or stream. Parses the first 550 * frame of data from the file and arms the synthesizer. 551 * 552 * Inputs: 553 * pEASData - pointer to overall EAS data structure 554 * streamHandle - file or stream handle 555 * 556 * Outputs: 557 * 558 * 559 * Side Effects: 560 * 561 *---------------------------------------------------------------------------- 562 */ 563 EAS_PUBLIC EAS_RESULT EAS_Prepare (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 564 565 /*---------------------------------------------------------------------------- 566 * EAS_State() 567 *---------------------------------------------------------------------------- 568 * Purpose: 569 * Returns the state of an audio file or stream. 570 * 571 * Inputs: 572 * pEASData - pointer to overall EAS data structure 573 * streamHandle - file or stream handle 574 * 575 * Outputs: 576 * 577 * 578 * Side Effects: 579 * 580 *---------------------------------------------------------------------------- 581 */ 582 EAS_PUBLIC EAS_RESULT EAS_State (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_STATE *pState); 583 584 /*---------------------------------------------------------------------------- 585 * EAS_RegisterMetaDataCallback() 586 *---------------------------------------------------------------------------- 587 * Purpose: 588 * Registers a metadata callback function for parsed metadata. To 589 * de-register the callback, call this function again with parameter 590 * cbFunc set to NULL. 591 * 592 * Inputs: 593 * pEASData - pointer to overall EAS data structure 594 * streamHandle - file or stream handle 595 * cbFunc - pointer to host callback function 596 * metaDataBuffer - pointer to metadata buffer 597 * metaDataBufSize - maximum size of the metadata buffer 598 * 599 * Outputs: 600 * 601 * 602 * Side Effects: 603 * 604 *---------------------------------------------------------------------------- 605 */ 606 EAS_PUBLIC EAS_RESULT EAS_RegisterMetaDataCallback ( 607 EAS_DATA_HANDLE pEASData, 608 EAS_HANDLE streamHandle, 609 EAS_METADATA_CBFUNC cbFunc, 610 char *metaDataBuffer, 611 EAS_I32 metaDataBufSize, 612 EAS_VOID_PTR pUserData); 613 614 /*---------------------------------------------------------------------------- 615 * EAS_GetNoteCount () 616 *---------------------------------------------------------------------------- 617 * Returns the total number of notes played in this stream 618 * 619 * Inputs: 620 * pEASData - pointer to overall EAS data structure 621 * streamHandle - file or stream handle 622 * pNoteCount - pointer to variable to receive note count 623 *---------------------------------------------------------------------------- 624 */ 625 EAS_PUBLIC EAS_RESULT EAS_GetNoteCount (EAS_DATA_HANDLE pEASData, EAS_HANDLE pStream, EAS_I32 *pNoteCount); 626 627 /*---------------------------------------------------------------------------- 628 * EAS_CloseFile() 629 *---------------------------------------------------------------------------- 630 * Purpose: 631 * Closes an audio file or stream. Playback should have either paused or 632 * completed (EAS_State returns EAS_PAUSED or EAS_STOPPED). 633 * 634 * Inputs: 635 * pEASData - pointer to overall EAS data structure 636 * streamHandle - file or stream handle 637 * 638 * Outputs: 639 * 640 * 641 * Side Effects: 642 * 643 *---------------------------------------------------------------------------- 644 */ 645 EAS_PUBLIC EAS_RESULT EAS_CloseFile (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 646 647 /*---------------------------------------------------------------------------- 648 * EAS_OpenMIDIStream() 649 *---------------------------------------------------------------------------- 650 * Purpose: 651 * Opens a raw MIDI stream allowing the host to route MIDI cable data directly to the synthesizer 652 * 653 * Inputs: 654 * pEASData - pointer to overall EAS data structure 655 * pStreamHandle - pointer to variable to hold file or stream handle 656 * streamHandle - open stream or NULL for new synthesizer instance 657 * 658 * Outputs: 659 * 660 * 661 * Side Effects: 662 * 663 *---------------------------------------------------------------------------- 664 */ 665 EAS_PUBLIC EAS_RESULT EAS_OpenMIDIStream (EAS_DATA_HANDLE pEASData, EAS_HANDLE *pStreamHandle, EAS_HANDLE streamHandle); 666 667 /*---------------------------------------------------------------------------- 668 * EAS_WriteMIDIStream() 669 *---------------------------------------------------------------------------- 670 * Purpose: 671 * Send data to the MIDI stream device 672 * 673 * Inputs: 674 * pEASData - pointer to overall EAS data structure 675 * streamHandle - stream handle 676 * pBuffer - pointer to buffer 677 * count - number of bytes to write 678 * 679 * Outputs: 680 * 681 * 682 * Side Effects: 683 * 684 *---------------------------------------------------------------------------- 685 */ 686 EAS_PUBLIC EAS_RESULT EAS_WriteMIDIStream(EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_U8 *pBuffer, EAS_I32 count); 687 688 /*---------------------------------------------------------------------------- 689 * EAS_CloseMIDIStream() 690 *---------------------------------------------------------------------------- 691 * Purpose: 692 * Closes a raw MIDI stream 693 * 694 * Inputs: 695 * pEASData - pointer to overall EAS data structure 696 * streamHandle - stream handle 697 * 698 * Outputs: 699 * 700 * 701 * Side Effects: 702 * 703 *---------------------------------------------------------------------------- 704 */ 705 EAS_PUBLIC EAS_RESULT EAS_CloseMIDIStream (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 706 707 /*---------------------------------------------------------------------------- 708 * EAS_Locate() 709 *---------------------------------------------------------------------------- 710 * Purpose: 711 * Locate into the file associated with the handle. 712 * 713 * Inputs: 714 * pEASData - pointer to overall EAS data structure 715 * streamHandle - file handle 716 * milliseconds - playback offset from start of file in milliseconds 717 * 718 * Outputs: 719 * 720 * 721 * Side Effects: 722 * the actual offset will be quantized to the closest update period, typically 723 * a resolution of 5.9ms. Notes that are started prior to this time will not 724 * sound. Any notes currently playing will be shut off. 725 * 726 *---------------------------------------------------------------------------- 727 */ 728 EAS_PUBLIC EAS_RESULT EAS_Locate (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 milliseconds, EAS_BOOL offset); 729 730 /*---------------------------------------------------------------------------- 731 * EAS_GetRenderTime() 732 *---------------------------------------------------------------------------- 733 * Purpose: 734 * Returns the current playback offset 735 * 736 * Inputs: 737 * pEASData - pointer to overall EAS data structure 738 * 739 * Outputs: 740 * Gets the render time clock in msecs. 741 * 742 * Side Effects: 743 * 744 *---------------------------------------------------------------------------- 745 */ 746 EAS_PUBLIC EAS_RESULT EAS_GetRenderTime (EAS_DATA_HANDLE pEASData, EAS_I32 *pTime); 747 748 /*---------------------------------------------------------------------------- 749 * EAS_GetLocation() 750 *---------------------------------------------------------------------------- 751 * Purpose: 752 * Returns the current playback offset 753 * 754 * Inputs: 755 * pEASData - pointer to overall EAS data structure 756 * streamHandle - file handle 757 * 758 * Outputs: 759 * The offset in milliseconds from the start of the current sequence, quantized 760 * to the nearest update period. Actual resolution is typically 5.9 ms. 761 * 762 * Side Effects: 763 * 764 *---------------------------------------------------------------------------- 765 */ 766 EAS_PUBLIC EAS_RESULT EAS_GetLocation (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_I32 *pTime); 767 768 /*---------------------------------------------------------------------------- 769 * EAS_Pause() 770 *---------------------------------------------------------------------------- 771 * Purpose: 772 * Pauses the playback of the data associated with this handle. The audio 773 * is gracefully ramped down to prevent clicks and pops. It may take several 774 * buffers of audio before the audio is muted. 775 * 776 * Inputs: 777 * psEASData - pointer to overall EAS data structure 778 * streamHandle - file or stream handle 779 * 780 * Outputs: 781 * 782 * 783 * Side Effects: 784 * 785 * 786 *---------------------------------------------------------------------------- 787 */ 788 EAS_PUBLIC EAS_RESULT EAS_Pause (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 789 790 /*---------------------------------------------------------------------------- 791 * EAS_Resume() 792 *---------------------------------------------------------------------------- 793 * Purpose: 794 * Resumes the playback of the data associated with this handle. The audio 795 * is gracefully ramped up to prevent clicks and pops. 796 * 797 * Inputs: 798 * psEASData - pointer to overall EAS data structure 799 * streamHandle - file or stream handle 800 * 801 * Outputs: 802 * 803 * 804 * Side Effects: 805 * 806 * 807 *---------------------------------------------------------------------------- 808 */ 809 EAS_PUBLIC EAS_RESULT EAS_Resume (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle); 810 811 /*---------------------------------------------------------------------------- 812 * EAS_GetParameter() 813 *---------------------------------------------------------------------------- 814 * Purpose: 815 * Set the parameter of a module. See E_MODULES for a list of modules 816 * and the header files of the modules for a list of parameters. 817 * 818 * Inputs: 819 * psEASData - pointer to overall EAS data structure 820 * module - enumerated module number 821 * param - enumerated parameter number 822 * pValue - pointer to variable to receive parameter value 823 * 824 * Outputs: 825 * 826 * 827 * Side Effects: 828 * 829 * 830 *---------------------------------------------------------------------------- 831 */ 832 EAS_PUBLIC EAS_RESULT EAS_GetParameter (EAS_DATA_HANDLE pEASData, EAS_I32 module, EAS_I32 param, EAS_I32 *pValue); 833 834 /*---------------------------------------------------------------------------- 835 * EAS_SetParameter() 836 *---------------------------------------------------------------------------- 837 * Purpose: 838 * Set the parameter of a module. See E_MODULES for a list of modules 839 * and the header files of the modules for a list of parameters. 840 * 841 * Inputs: 842 * psEASData - pointer to overall EAS data structure 843 * handle - file or stream handle 844 * module - enumerated module number 845 * param - enumerated parameter number 846 * value - new parameter value 847 * 848 * Outputs: 849 * 850 * 851 * Side Effects: 852 * 853 * 854 *---------------------------------------------------------------------------- 855 */ 856 EAS_PUBLIC EAS_RESULT EAS_SetParameter (EAS_DATA_HANDLE pEASData, EAS_I32 module, EAS_I32 param, EAS_I32 value); 857 858 #ifdef _METRICS_ENABLED 859 /*---------------------------------------------------------------------------- 860 * EAS_MetricsReport() 861 *---------------------------------------------------------------------------- 862 * Purpose: 863 * Displays the current metrics through the EAS_Report interface. 864 * 865 * Inputs: 866 * pEASData - instance data handle 867 * 868 * Outputs: 869 * 870 * 871 * Side Effects: 872 * 873 *---------------------------------------------------------------------------- 874 */ 875 EAS_PUBLIC EAS_RESULT EAS_MetricsReport (EAS_DATA_HANDLE pEASData); 876 877 /*---------------------------------------------------------------------------- 878 * EAS_MetricsReset() 879 *---------------------------------------------------------------------------- 880 * Purpose: 881 * Displays the current metrics through the EAS_Report interface. 882 * 883 * Inputs: 884 * pEASData - instance data handle 885 * 886 * Outputs: 887 * 888 * 889 * Side Effects: 890 * 891 *---------------------------------------------------------------------------- 892 */ 893 EAS_PUBLIC EAS_RESULT EAS_MetricsReset (EAS_DATA_HANDLE pEASData); 894 #endif 895 896 /*---------------------------------------------------------------------------- 897 * EAS_SetSoundLibrary() 898 *---------------------------------------------------------------------------- 899 * Purpose: 900 * Sets the location of the sound library. 901 * 902 * Inputs: 903 * pEASData - instance data handle 904 * streamHandle - file or stream handle 905 * pSoundLib - pointer to sound library 906 * 907 * Outputs: 908 * 909 * 910 * Side Effects: 911 * 912 *---------------------------------------------------------------------------- 913 */ 914 EAS_PUBLIC EAS_RESULT EAS_SetSoundLibrary (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_SNDLIB_HANDLE pSndLib); 915 916 /*---------------------------------------------------------------------------- 917 * EAS_SetHeaderSearchFlag() 918 *---------------------------------------------------------------------------- 919 * By default, when EAS_OpenFile is called, the parsers check the 920 * first few bytes of the file looking for a specific header. Some 921 * mobile devices may add a header to the start of a file, which 922 * will prevent the parser from recognizing the file. If the 923 * searchFlag is set to EAS_TRUE, the parser will search the entire 924 * file looking for the header. This may enable EAS to recognize 925 * some files that it would ordinarily reject. The negative is that 926 * it make take slightly longer to process the EAS_OpenFile request. 927 * 928 * Inputs: 929 * pEASData - instance data handle 930 * searchFlag - search flag (EAS_TRUE or EAS_FALSE) 931 *---------------------------------------------------------------------------- 932 */ 933 EAS_PUBLIC EAS_RESULT EAS_SetHeaderSearchFlag (EAS_DATA_HANDLE pEASData, EAS_BOOL searchFlag); 934 935 /*---------------------------------------------------------------------------- 936 * EAS_SetPlayMode() 937 *---------------------------------------------------------------------------- 938 * Some file formats support special play modes, such as iMode partial 939 * play mode. This call can be used to change the play mode. The 940 * default play mode (usually straight playback) is always zero. 941 * 942 * Inputs: 943 * pEASData - instance data handle 944 * handle - file or stream handle 945 * playMode - play mode (see eas_types.h for enumerations) 946 *---------------------------------------------------------------------------- 947 */ 948 EAS_PUBLIC EAS_RESULT EAS_SetPlayMode (EAS_DATA_HANDLE pEASData, EAS_HANDLE pStream, EAS_I32 playMode); 949 950 #ifdef DLS_SYNTHESIZER 951 /*---------------------------------------------------------------------------- 952 * EAS_LoadDLSCollection() 953 *---------------------------------------------------------------------------- 954 * Purpose: 955 * Downloads a DLS collection 956 * 957 * Inputs: 958 * pEASData - instance data handle 959 * streamHandle - file or stream handle 960 * locator - file locator 961 * 962 * Outputs: 963 * 964 * 965 * Side Effects: 966 * May overlay instruments in the GM sound set 967 * 968 *---------------------------------------------------------------------------- 969 */ 970 EAS_PUBLIC EAS_RESULT EAS_LoadDLSCollection (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_FILE_LOCATOR locator); 971 #endif 972 973 /*---------------------------------------------------------------------------- 974 * EAS_SetFrameBuffer() 975 *---------------------------------------------------------------------------- 976 * Purpose: 977 * Sets the frame buffer pointer passed to the IPC communications functions 978 * 979 * Inputs: 980 * pEASData - instance data handle 981 * locator - file locator 982 * 983 * Outputs: 984 * 985 * 986 * Side Effects: 987 * May overlay instruments in the GM sound set 988 * 989 *---------------------------------------------------------------------------- 990 */ 991 EAS_PUBLIC EAS_RESULT EAS_SetFrameBuffer (EAS_DATA_HANDLE pEASData, EAS_FRAME_BUFFER_HANDLE pFrameBuffer); 992 993 #ifdef EXTERNAL_AUDIO 994 /*---------------------------------------------------------------------------- 995 * EAS_RegExtAudioCallback() 996 *---------------------------------------------------------------------------- 997 * Purpose: 998 * Registers callback functions for audio events. 999 * 1000 * Inputs: 1001 * pEASData - pointer to overall EAS data structure 1002 * streamHandle - file or stream handle 1003 * cbProgChgFunc - pointer to host callback function for program change 1004 * cbEventFunc - pointer to host callback functio for note events 1005 * 1006 * Outputs: 1007 * 1008 * 1009 * Side Effects: 1010 * 1011 *---------------------------------------------------------------------------- 1012 */ 1013 EAS_PUBLIC EAS_RESULT EAS_RegExtAudioCallback (EAS_DATA_HANDLE pEASData, 1014 EAS_HANDLE streamHandle, 1015 EAS_VOID_PTR pInstData, 1016 EAS_EXT_PRG_CHG_FUNC cbProgChgFunc, 1017 EAS_EXT_EVENT_FUNC cbEventFunc); 1018 1019 /*---------------------------------------------------------------------------- 1020 * EAS_GetMIDIControllers() 1021 *---------------------------------------------------------------------------- 1022 * Purpose: 1023 * Returns the current state of MIDI controllers on the requested channel. 1024 * 1025 * Inputs: 1026 * pEASData - pointer to overall EAS data structure 1027 * streamHandle - file or stream handle 1028 * pControl - pointer to structure to receive data 1029 * 1030 * Outputs: 1031 * 1032 * 1033 * Side Effects: 1034 * 1035 *---------------------------------------------------------------------------- 1036 */ 1037 EAS_PUBLIC EAS_RESULT EAS_GetMIDIControllers (EAS_DATA_HANDLE pEASData, EAS_HANDLE streamHandle, EAS_U8 channel, S_MIDI_CONTROLLERS *pControl); 1038 #endif 1039 1040 /*---------------------------------------------------------------------------- 1041 * EAS_SearchFile 1042 *---------------------------------------------------------------------------- 1043 * Search file for specific sequence starting at current file 1044 * position. Returns offset to start of sequence. 1045 * 1046 * Inputs: 1047 * pEASData - pointer to EAS persistent data object 1048 * fileHandle - file handle 1049 * searchString - pointer to search sequence 1050 * len - length of search sequence 1051 * pOffset - pointer to variable to store offset to sequence 1052 * 1053 * Returns EAS_EOF if end-of-file is reached 1054 *---------------------------------------------------------------------------- 1055 */ 1056 EAS_RESULT EAS_SearchFile (EAS_DATA_HANDLE pEASData, EAS_FILE_HANDLE fileHandle, const EAS_U8 *searchString, EAS_I32 len, EAS_I32 *pOffset); 1057 1058 #ifdef __cplusplus 1059 } /* end extern "C" */ 1060 #endif 1061 1062 #endif /* #ifndef _EAS_H */ 1063
