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
42extern "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
49typedef 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 */
63typedef 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 */
78typedef 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 */
86typedef 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*/
119EAS_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*/
134EAS_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*/
150EAS_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*/
169EAS_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*/
192EAS_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*/
215EAS_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*/
234EAS_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*/
257EAS_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*/
279EAS_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*/
298EAS_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*/
319EAS_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*/
338EAS_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*/
360EAS_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*/
379EAS_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*/
400EAS_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*/
420EAS_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*/
443EAS_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*/
457EAS_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*/
477EAS_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*/
498EAS_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*/
510EAS_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*/
523EAS_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*/
543EAS_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*/
563EAS_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*/
582EAS_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*/
606EAS_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*/
625EAS_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*/
645EAS_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*/
665EAS_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*/
686EAS_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*/
705EAS_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*/
728EAS_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*/
746EAS_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*/
766EAS_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*/
788EAS_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*/
809EAS_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*/
832EAS_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*/
856EAS_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*/
875EAS_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*/
893EAS_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*/
914EAS_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*/
933EAS_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*/
948EAS_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*/
970EAS_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*/
991EAS_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*/
1013EAS_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*/
1037EAS_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*/
1056EAS_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