ocrm.bsky.social
the game where you go into mines and start crafting! but for consoles (forked directly from smartcmd's github)
1//############################################################################
2//## ##
3//## Miles Sound System ##
4//## ##
5//############################################################################
6//## ##
7//## Contact RAD Game Tools at 425-893-4300 for technical support. ##
8//## ##
9//############################################################################
10
11#ifndef MSS_VERSION
12
13// also update versions below for the docs
14
15// for cdep and installs
16#define MILESVERSION "9.3m"
17// see below in docs section
18#define MILESMAJORVERSION 9
19#define MILESMINORVERSION 3
20#define MILESSUBVERSION 11
21#define MILESBUILDVERSION 0
22#define MILESVERSIONDATE "20-Jun-14"
23#define MILESCOPYRIGHT "Copyright (C) 1991-2014, RAD Game Tools, Inc."
24
25// source files use these defines
26#define MSS_VERSION MILESVERSION
27#define MSS_MAJOR_VERSION MILESMAJORVERSION
28#define MSS_MINOR_VERSION MILESMINORVERSION
29#define MSS_SUB_VERSION MILESSUBVERSION
30#define MSS_BUILD_VERSION MILESBUILDVERSION
31
32#define MSS_VERSION_DATE MILESVERSIONDATE
33#define MSS_COPYRIGHT MILESCOPYRIGHT
34
35#endif
36
37#if !defined(MSS_H) && !defined(__RADRES__)
38#define MSS_H
39
40// doc system stuff
41#ifndef EXPAPI
42#define EXPAPI
43#endif
44#ifndef EXPTYPE
45#define EXPTYPE
46#endif
47#ifndef EXPMACRO
48#define EXPMACRO
49#endif
50#ifndef EXPCONST
51#define EXPCONST
52#endif
53#ifndef EXPOUT
54#define EXPOUT
55#endif
56#ifndef EXPTYPEBEGIN
57#define EXPTYPEBEGIN
58#endif
59#ifndef EXPTYPEEND
60#define EXPTYPEEND
61#endif
62#ifndef EXPGROUP
63#define EXPGROUP(GroupName)
64#endif
65#ifndef DEFGROUP
66#define DEFGROUP(GroupName, Info)
67#endif
68
69// For docs
70EXPGROUP(_NullGroup)
71#define MilesVersion "9.3m" EXPMACRO
72#define MilesMajorVersion 9 EXPMACRO
73#define MilesMinorVersion 3 EXPMACRO
74#define MilesBuildNumber 11 EXPMACRO
75#define MilesCustomization 0 EXPMACRO
76EXPGROUP(_RootGroup)
77
78
79// IS_WINDOWS for Windows or Win32
80// IS_WIN64 for Win64
81// IS_WIN32 for Win32
82// IS_WIN32API for Windows, Xbox and Xenon
83// IS_64REGS when CPU registers are 64-bit - Xenon, PS3, Win64 and PS2
84// IS_32 for at least 32-bit pointers
85// IS_LE for little endian (PCs)
86// IS_BE for big endian (Macs, x360, ps3)
87// IS_X86 for Intel
88// IS_MAC for Mac
89// IS_MACHO for Macho Mac
90// IS_PPC for PPC Mac
91// IS_68K for 68K Mac
92// IS_LINUX for Linux
93// IS_XBOX for Xbox
94// IS_XENON for Xbox 360
95// IS_PS2 for PS/2
96// IS_PS3 for PS/3
97// IS_SPU for PS3 SPU
98// IS_WII for Wii
99
100#include "rrCore.h"
101
102//#define MILES_CHECK_OFFSETS
103#ifdef MILES_CHECK_OFFSETS
104 #include <stddef.h>
105#endif
106
107#ifdef __RADNT__
108#define IS_WIN32
109#if defined(__RAD64__)
110#define IS_WIN64
111#endif
112#endif
113
114#if defined(__RADWIN__) && !defined(__RADXENON__) && !defined(__RADXBOX__) && !defined(__RADWINRTAPI__)
115#define IS_WINDOWS
116#endif
117
118#if defined(__RADWIN__)
119#define IS_WIN32API
120#endif
121
122#if defined(__RAD64__) && defined(__RADWIN__)
123#define IS_WIN64
124#endif
125
126// 16-bit not supported anymore
127#define IS_32
128
129#ifdef __RADLITTLEENDIAN__
130#define IS_LE
131#endif
132
133#ifdef __RADBIGENDIAN__
134#define IS_BE
135#endif
136
137#ifdef __RADX86__
138#define IS_X86
139#endif
140
141#ifdef __RADMAC__
142#define IS_MAC
143#endif
144
145#ifdef __RADPPC__
146#define IS_PPC
147#endif
148
149#ifdef __RAD68K__
150#define IS_68K
151#endif
152
153#ifdef __RADLINUX__
154#define IS_LINUX
155#endif
156
157//
158// MSS_STATIC_RIB is used to determine whether anything loaded
159// through the RIB interface is loaded via RIB_load_application_providers
160// or via a static declaration from the user (Register_RIB)
161// mirror this in rib.h
162//
163#if defined(__RADANDROID__) || defined(__RADPSP__) || defined(__RADPSP2__) || \
164 defined(__RADWII__) || defined(__RADWIIU__) || defined(__RAD3DS__) || defined(__RADIPHONE__) || \
165 defined(__RADXENON__) || defined(__RADPS4__) || defined(__RADPS3__) || defined(__RADSPU__) || \
166 defined(__RADDURANGO__) || defined(__RADWINRTAPI__)
167 #define MSS_STATIC_RIB
168 // WinRT is weird in that we statically pull in the RIBs, but we dynamically link Midi
169 #ifndef __RADWINRTAPI__
170 #define MSS_STATIC_MIDI
171 #endif
172#elif defined(__RADWIN__) || defined(__RADLINUX__) || defined(__RADMAC__)
173 // not static.
174#else
175 #error "MSS needs to know whether it is being distributed as a static lib!"
176#endif
177
178// Retain the old IS_STATIC define for example code
179#ifdef MSS_STATIC_RIB
180 #define IS_STATIC
181#endif
182
183#ifdef __RADXBOX__
184#define IS_XBOX
185#endif
186
187#ifdef __RADXENON__
188#define IS_XENON
189#endif
190
191#ifdef __RADWII__
192#define IS_WII
193#endif
194
195#ifdef __RADWIIU__
196#define IS_WIIU
197#endif
198
199#ifdef __RADPS2__
200#define IS_PS2
201#endif
202
203#ifdef __RADPS3__
204#define IS_PS3
205#ifndef HOST_SPU_PROCESS
206 #define HOST_SPU_PROCESS
207#endif
208#endif
209
210#ifdef __RADSPU__
211#define IS_PS3
212#define IS_SPU
213#endif
214
215#ifdef __RADPSP__
216#define IS_PSP
217#endif
218
219#ifdef __RADPSP2__
220#define IS_PSP2
221#endif
222
223#ifdef __RADDOS__
224#define IS_DOS
225#endif
226
227#ifdef __RAD64REGS__
228#define IS_64REGS
229#endif
230
231#ifdef __RADMACH__
232#define IS_MACHO
233#endif
234
235#ifdef __RADIPHONE__
236#define IS_IPHONE
237#endif
238
239#ifdef __RADIPHONESIM__
240#define IS_IPHONESIM
241#endif
242
243#ifdef __RAD3DS__
244#define IS_3DS
245#endif
246
247#define MSSRESTRICT RADRESTRICT
248
249#define MSS_STRUCT RADSTRUCT
250
251#define C8 char
252typedef void VOIDFUNC(void);
253
254
255#if (!defined(IS_LE) && !defined(IS_BE))
256 #error MSS.H did not detect your platform. Define _WINDOWS, WIN32, WIN64, or macintosh.
257#endif
258
259//
260// Pipeline filters supported on following platforms
261//
262
263#define MSS_FLT_SUPPORTED 1
264#define EXTRA_BUILD_BUFFERS 1
265#define FLT_A (MAX_SPEAKERS)
266
267#if defined(IS_WIN32API)
268 #define MSS_VFLT_SUPPORTED 1
269#endif
270
271#define MSS_REVERB_SUPPORTED 1
272
273//================
274
275EXPGROUP(Basic Types)
276#define AILCALL EXPTAG(AILCALL)
277/*
278 Internal calling convention that all external Miles functions use.
279
280 Usually cdecl or stdcall on Windows.
281*/
282
283#define AILCALLBACK EXPTAG(AILCALLBACK docproto)
284/*
285 Calling convention that user supplied callbacks <b>from</b> Miles use.
286
287 Usually cdecl or stdcall on Windows.
288*/
289
290EXPGROUP(_RootGroup)
291#undef AILCALL
292#undef AILCALLBACK
293//================
294
295RADDEFSTART
296
297#define MSSFOURCC U32
298#ifdef IS_LE
299 #define MSSMAKEFOURCC(ch0, ch1, ch2, ch3) \
300 ((U32)(U8)(ch0) | ((U32)(U8)(ch1) << 8) | \
301 ((U32)(U8)(ch2) << 16) | ((U32)(U8)(ch3) << 24 ))
302#else
303
304 #define MSSMAKEFOURCC(ch0, ch1, ch2, ch3) \
305 (((U32)(U8)(ch0) << 24) | ((U32)(U8)(ch1) << 16) | \
306 ((U32)(U8)(ch2) << 8) | ((U32)(U8)(ch3) ))
307#endif
308
309#define MSSmmioFOURCC(w,x,y,z) MSSMAKEFOURCC(w,x,y,z)
310
311#if defined(__RADWINRTAPI__)
312
313 #define AILLIBCALLBACK RADLINK
314 #define AILCALL RADLINK
315 #define AILEXPORT RADEXPLINK
316 #define AILCALLBACK RADLINK
317 #define DXDEF RADEXPFUNC
318 #define DXDEC RADEXPFUNC
319
320#elif defined(IS_WINDOWS)
321
322 typedef char CHAR;
323 typedef short SHORT;
324 typedef int BOOL;
325 typedef long LONG;
326 typedef CHAR *LPSTR, *PSTR;
327
328 #ifdef IS_WIN64
329 typedef unsigned __int64 ULONG_PTR, *PULONG_PTR;
330 #else
331 #ifdef _Wp64
332 #if !defined(__midl) && (defined(_X86_) || defined(_M_IX86)) && _MSC_VER >= 1300
333 typedef __w64 unsigned long ULONG_PTR, *PULONG_PTR;
334 #else
335 typedef unsigned long ULONG_PTR, *PULONG_PTR;
336 #endif
337 #else
338 typedef unsigned long ULONG_PTR, *PULONG_PTR;
339 #endif
340 #endif
341
342 typedef ULONG_PTR DWORD_PTR, *PDWORD_PTR;
343 typedef unsigned long DWORD;
344 typedef unsigned short WORD;
345 typedef unsigned int UINT;
346 typedef struct HWAVE__ *HWAVE;
347 typedef struct HWAVEIN__ *HWAVEIN;
348 typedef struct HWAVEOUT__ *HWAVEOUT;
349 typedef HWAVEIN *LPHWAVEIN;
350 typedef HWAVEOUT *LPHWAVEOUT;
351
352 #ifndef WAVE_MAPPER
353 #define WAVE_MAPPER ((UINT)-1)
354 #endif
355
356 typedef struct waveformat_tag *LPWAVEFORMAT;
357
358 typedef struct HMIDIOUT__ *HMIDIOUT;
359 typedef HMIDIOUT *LPHMIDIOUT;
360 typedef struct HWND__ *HWND;
361 typedef struct HINSTANCE__ *HINSTANCE;
362 typedef HINSTANCE HMODULE;
363 typedef struct wavehdr_tag *LPWAVEHDR;
364
365 #define MSS_MAIN_DEF __cdecl
366
367 //
368 // If compiling MSS DLL, use __declspec(dllexport) for both
369 // declarations and definitions
370 //
371
372 #ifdef IS_WIN32
373
374 #if !defined(FORNONWIN) && !defined(__RADNTBUILDLINUX__)
375 #define AILLIBCALLBACK __stdcall
376 #define AILCALL __stdcall
377 #define AILCALLBACK __stdcall
378 #define AILEXPORT __stdcall
379 #else
380 #define AILLIBCALLBACK __cdecl
381 #define AILCALL __cdecl
382 #define AILCALLBACK __cdecl
383 #define AILEXPORT __cdecl
384 #endif
385
386 #ifdef __RADINDLL__
387 #define DXDEC __declspec(dllexport)
388 #define DXDEF __declspec(dllexport)
389 #else
390
391 #if defined( __BORLANDC__ ) || defined( MSS_SPU_PROCESS )
392 #define DXDEC extern
393 #else
394 #define DXDEC __declspec(dllimport)
395 #endif
396
397 #endif
398
399 #ifdef IS_WIN64
400 #define MSSDLLNAME "MSS64.DLL"
401 #define MSS_REDIST_DIR_NAME "redist64"
402 #else
403 #define MSSDLLNAME "MSS32.DLL"
404 #define MSS_REDIST_DIR_NAME "redist"
405 #endif
406
407 #define MSS_DIR_SEP "\\"
408 #define MSS_DIR_UP ".." MSS_DIR_SEP
409 #define MSS_DIR_UP_TWO MSS_DIR_UP MSS_DIR_UP
410
411 #endif
412
413 typedef void * LPVOID;
414 typedef LPVOID AILLPDIRECTSOUND;
415 typedef LPVOID AILLPDIRECTSOUNDBUFFER;
416
417#elif defined( IS_MAC ) || defined(IS_IPHONE) || defined(IS_LINUX)
418
419 #if defined(__RADARM__) || defined(__RADX64__)
420 #define AILLIBCALLBACK
421 #define AILCALL
422 #define AILEXPORT
423 #define AILCALLBACK
424 #elif defined(__RADX86__)
425 #define AILLIBCALLBACK __attribute__((cdecl))
426 #define AILCALL __attribute__((cdecl))
427 #define AILCALLBACK __attribute__((cdecl))
428 #define AILEXPORT __attribute__((cdecl))
429 #else
430 #error "No fn call decorators specified"
431 #endif
432
433 #ifdef __RADINDLL__
434 #define DXDEC __attribute__((visibility("default")))
435 #define DXDEF __attribute__((visibility("default")))
436 #else
437 #define DXDEC extern
438 #define DXDEF
439 #endif
440
441 #ifdef __RADX64__
442 #define MSS_REDIST_DIR_NAME "redist/x64"
443 #elif defined(IS_X86)
444 #define MSS_REDIST_DIR_NAME "redist/x86"
445 #elif defined(__RADARM__)
446 #define MSS_REDIST_DIR_NAME ""
447 #else
448 #error "No Redist Dir Specified"
449 #endif
450
451 #define MSS_DIR_SEP "/"
452 #define MSS_DIR_UP ".." MSS_DIR_SEP
453 #define MSS_DIR_UP_TWO MSS_DIR_UP MSS_DIR_UP
454
455 #define MSS_MAIN_DEF
456
457#elif defined(IS_XENON)
458
459 #define AILLIBCALLBACK __stdcall
460 #define AILCALL __stdcall
461 #define AILEXPORT __stdcall
462 #define AILCALLBACK __stdcall
463
464 #define DXDEC extern
465 #define DXDEF
466
467 typedef void * AILLPDIRECTSOUND;
468 typedef void * AILLPDIRECTSOUNDBUFFER;
469
470#else
471
472 #define AILLIBCALLBACK
473 #define AILCALL
474 #define AILEXPORT
475 #define AILCALLBACK
476
477 #define DXDEC extern
478 #define DXDEF
479
480#endif
481
482
483//
484// Misc. constant definitions
485//
486
487#define MAX_DRVRS 16 // Max. # of simultaneous drivers
488#define MAX_TIMERS 16 // Max. # of simultaneous timers
489#define MAX_NOTES 32 // Max # of notes "on"
490#define FOR_NEST 4 // # of nested XMIDI FOR loops
491#define NUM_CHANS 16 // # of possible MIDI channels
492#define MAX_W_VOICES 16 // Max virtual wave synth voice cnt
493#define MAX_W_ENTRIES 512 // 512 wave library entries max.
494#ifdef IS_WIN32
495#define MAX_SPEAKERS 9 // Up to 9 hardware output channels supported on Win32
496#elif defined(IS_PS3) || defined(IS_WII) || defined(IS_WIIU) || defined(__RADWINRTAPI__) || defined(__RADSEKRIT2__)
497#define MAX_SPEAKERS 8 // Up to 8 hardware output channels on PS3, PS2, Wii, WiiU
498#elif defined(IS_PSP) || defined(IS_IPHONE) || defined(IS_3DS) || defined(IS_PSP2) || defined(__RADANDROID__)
499#define MAX_SPEAKERS 2 // Up to 2 hardware output channels on PSP
500#else
501#define MAX_SPEAKERS 6 // Up to 6 hardware output channels supported on other platforms
502#endif
503#define MAX_RECEIVER_SPECS 32 // Up to 32 receiver point specifications
504
505#define MAX_BUSSES 4 // # of busses that can be active.
506#define MILES_MAX_STATES 4 // # of state pushes allowed.
507
508
509#define MIN_CHAN ( 1-1) // Min channel recognized (0-based)
510#define MAX_CHAN (16-1) // Max channel recognized
511#define MIN_LOCK_CHAN ( 1-1) // Min channel available for locking
512#define MAX_LOCK_CHAN (16-1) // Max channel available for locking
513#define PERCUSS_CHAN (10-1) // Percussion channel (no locking)
514
515#define AIL_MAX_FILE_HEADER_SIZE 8192 // AIL_set_named_sample_file() requires at least 8K
516 // of data or the entire file image, whichever is less,
517 // to determine sample format
518#define DIG_F_16BITS_MASK 1
519#define DIG_F_STEREO_MASK 2
520#define DIG_F_ADPCM_MASK 4
521#define DIG_F_XBOX_ADPCM_MASK 8
522#define DIG_F_MULTICHANNEL_MASK 16
523#define DIG_F_OUTPUT_FILTER_IN_USE 32
524
525#define DIG_F_MONO_8 0 // PCM data formats
526#define DIG_F_MONO_16 (DIG_F_16BITS_MASK)
527#define DIG_F_STEREO_8 (DIG_F_STEREO_MASK)
528#define DIG_F_MULTICHANNEL_8 (DIG_F_MULTICHANNEL_MASK) // (not actually supported)
529#define DIG_F_STEREO_16 (DIG_F_STEREO_MASK|DIG_F_16BITS_MASK)
530#define DIG_F_MULTICHANNEL_16 (DIG_F_MULTICHANNEL_MASK|DIG_F_16BITS_MASK)
531#define DIG_F_ADPCM_MONO_16 (DIG_F_ADPCM_MASK |DIG_F_16BITS_MASK)
532#define DIG_F_ADPCM_STEREO_16 (DIG_F_ADPCM_MASK |DIG_F_16BITS_MASK|DIG_F_STEREO_MASK)
533#define DIG_F_ADPCM_MULTICHANNEL_16 (DIG_F_ADPCM_MASK |DIG_F_16BITS_MASK|DIG_F_STEREO_MASK)
534#define DIG_F_XBOX_ADPCM_MONO_16 (DIG_F_XBOX_ADPCM_MASK |DIG_F_16BITS_MASK)
535#define DIG_F_XBOX_ADPCM_STEREO_16 (DIG_F_XBOX_ADPCM_MASK |DIG_F_16BITS_MASK|DIG_F_STEREO_MASK)
536#define DIG_F_XBOX_ADPCM_MULTICHANNEL_16 (DIG_F_XBOX_ADPCM_MASK |DIG_F_16BITS_MASK|DIG_F_MULTICHANNEL_MASK)
537
538#define DIG_F_NOT_8_BITS (DIG_F_16BITS_MASK | DIG_F_ADPCM_MASK | DIG_F_XBOX_ADPCM_MASK | DIG_F_MULTICHANNEL_MASK)
539
540#define DIG_F_USING_ASI 16
541
542#define DIG_PCM_POLARITY 0x0004 // PCM flags used by driver hardware
543#define DIG_PCM_SPLIT 0x0008
544#define DIG_BUFFER_SERVICE 0x0010
545#define DIG_DUAL_DMA 0x0020
546#define DIG_RECORDING_SUPPORTED 0x8000
547
548#ifndef WAVE_FORMAT_PCM
549 #define WAVE_FORMAT_PCM 1
550#endif
551#ifndef WAVE_FORMAT_IMA_ADPCM
552 #define WAVE_FORMAT_IMA_ADPCM 0x0011
553#endif
554#ifndef WAVE_FORMAT_XBOX_ADPCM
555 #define WAVE_FORMAT_XBOX_ADPCM 0x0069
556#endif
557#ifndef WAVE_FORMAT_EXTENSIBLE
558 #define WAVE_FORMAT_EXTENSIBLE 0xFFFE
559#endif
560
561typedef enum
562{
563 MSS_SPEAKER_MONO = 0,
564 MSS_SPEAKER_FRONT_LEFT = 0, // Speaker order indexes correspond to
565 MSS_SPEAKER_FRONT_RIGHT = 1, // bitmasks in PSDK's ksmedia.h
566 MSS_SPEAKER_FRONT_CENTER = 2, // Also see microsoft.com/whdc/device/audio/multichaud.mspx
567 MSS_SPEAKER_LOW_FREQUENCY = 3,
568 MSS_SPEAKER_BACK_LEFT = 4,
569 MSS_SPEAKER_BACK_RIGHT = 5,
570 MSS_SPEAKER_FRONT_LEFT_OF_CENTER = 6,
571 MSS_SPEAKER_FRONT_RIGHT_OF_CENTER = 7,
572 MSS_SPEAKER_BACK_CENTER = 8,
573 MSS_SPEAKER_SIDE_LEFT = 9,
574 MSS_SPEAKER_SIDE_RIGHT = 10,
575 MSS_SPEAKER_TOP_CENTER = 11,
576 MSS_SPEAKER_TOP_FRONT_LEFT = 12,
577 MSS_SPEAKER_TOP_FRONT_CENTER = 13,
578 MSS_SPEAKER_TOP_FRONT_RIGHT = 14,
579 MSS_SPEAKER_TOP_BACK_LEFT = 15,
580 MSS_SPEAKER_TOP_BACK_CENTER = 16,
581 MSS_SPEAKER_TOP_BACK_RIGHT = 17,
582 MSS_SPEAKER_MAX_INDEX = 17,
583 MSS_SPEAKER_FORCE_32 = 0x7fffffff
584} MSS_SPEAKER;
585
586//
587// Pass to AIL_midiOutOpen for NULL MIDI driver
588//
589
590#define MIDI_NULL_DRIVER ((U32)(S32)-2)
591
592
593//
594// Non-specific XMIDI/MIDI controllers and event types
595//
596
597#define SYSEX_BYTE 105
598#define PB_RANGE 106
599#define CHAN_MUTE 107
600#define CALLBACK_PFX 108
601#define SEQ_BRANCH 109
602#define CHAN_LOCK 110
603#define CHAN_PROTECT 111
604#define VOICE_PROTECT 112
605#define TIMBRE_PROTECT 113
606#define PATCH_BANK_SEL 114
607#define INDIRECT_C_PFX 115
608#define FOR_LOOP 116
609#define NEXT_LOOP 117
610#define CLEAR_BEAT_BAR 118
611#define CALLBACK_TRIG 119
612#define SEQ_INDEX 120
613
614#define GM_BANK_MSB 0
615#define MODULATION 1
616#define DATA_MSB 6
617#define PART_VOLUME 7
618#define PANPOT 10
619#define EXPRESSION 11
620#define GM_BANK_LSB 32
621#define DATA_LSB 38
622#define SUSTAIN 64
623#define REVERB 91
624#define CHORUS 93
625#define RPN_LSB 100
626#define RPN_MSB 101
627#define RESET_ALL_CTRLS 121
628#define ALL_NOTES_OFF 123
629
630#define EV_NOTE_OFF 0x80
631#define EV_NOTE_ON 0x90
632#define EV_POLY_PRESS 0xa0
633#define EV_CONTROL 0xb0
634#define EV_PROGRAM 0xc0
635#define EV_CHAN_PRESS 0xd0
636#define EV_PITCH 0xe0
637#define EV_SYSEX 0xf0
638#define EV_ESC 0xf7
639#define EV_META 0xff
640
641#define META_EOT 0x2f
642#define META_TEMPO 0x51
643#define META_TIME_SIG 0x58
644
645//
646// SAMPLE.system_data[] usage
647//
648
649#define VOC_BLK_PTR 1 // Pointer to current block
650#define VOC_REP_BLK 2 // Pointer to beginning of repeat loop block
651#define VOC_N_REPS 3 // # of iterations left in repeat loop
652#define VOC_MARKER 4 // Marker to search for, or -1 if all
653#define VOC_MARKER_FOUND 5 // Desired marker found if 1, else 0
654#define STR_HSTREAM 6 // Stream, if any, that owns the HSAMPLE
655#define SSD_TEMP 7 // Temporary storage location for general use
656#define EVT_HANDLE_MAGIC 1 // EventSystem handle.magic
657#define EVT_HANDLE_INDEX 2 // EventSystem handle.index
658
659//
660// Timer status values
661//
662
663#define AILT_FREE 0 // Timer handle is free for allocation
664#define AILT_STOPPED 1 // Timer is stopped
665#define AILT_RUNNING 2 // Timer is running
666
667//
668// SAMPLE.status flag values
669//
670
671#define SMP_FREE 0x0001 // Sample is available for allocation
672
673#define SMP_DONE 0x0002 // Sample has finished playing, or has
674 // never been started
675
676#define SMP_PLAYING 0x0004 // Sample is playing
677
678#define SMP_STOPPED 0x0008 // Sample has been stopped
679
680#define SMP_PLAYINGBUTRELEASED 0x0010 // Sample is playing, but digital handle
681 // has been temporarily released
682
683
684
685//
686// SEQUENCE.status flag values
687//
688
689#define SEQ_FREE 0x0001 // Sequence is available for allocation
690
691#define SEQ_DONE 0x0002 // Sequence has finished playing, or has
692 // never been started
693
694#define SEQ_PLAYING 0x0004 // Sequence is playing
695
696#define SEQ_STOPPED 0x0008 // Sequence has been stopped
697
698#define SEQ_PLAYINGBUTRELEASED 0x0010 // Sequence is playing, but MIDI handle
699 // has been temporarily released
700
701#ifdef IS_WINDOWS
702
703//
704// AIL_set_direct_buffer_control() command values
705//
706
707#define AILDS_RELINQUISH 0 // App returns control of secondary buffer
708#define AILDS_SEIZE 1 // App takes control of secondary buffer
709#define AILDS_SEIZE_LOOP 2 // App wishes to loop the secondary buffer
710
711#endif
712
713#ifndef MSS_BASIC
714
715#ifndef FILE_ERRS
716 #define FILE_ERRS
717
718 #define AIL_NO_ERROR 0
719 #define AIL_IO_ERROR 1
720 #define AIL_OUT_OF_MEMORY 2
721 #define AIL_FILE_NOT_FOUND 3
722 #define AIL_CANT_WRITE_FILE 4
723 #define AIL_CANT_READ_FILE 5
724 #define AIL_DISK_FULL 6
725 #define AIL_NO_AVAIL_ASYNC 7
726#endif
727
728#define MIN_VAL 0
729#define NOM_VAL 1
730#define MAX_VAL 2
731
732
733EXPGROUP(Basic Types)
734EXPTYPEBEGIN typedef SINTa HMSSENUM;
735#define MSS_FIRST ((HMSSENUM)-1)
736EXPTYPEEND
737/*
738 specifies a type used to enumerate through a list of properties.
739
740 $:MSS_FIRST use this value to start the enumeration process.
741
742The Miles enumeration functions all work similarly - you set a local variable of type HMSSENUM to MSS_FIRST and then call
743the enumeration function until it returns 0.
744
745*/
746
747
748
749
750//
751// Preference names and default values
752//
753
754#define AIL_MM_PERIOD 0
755#define DEFAULT_AMP 1 // Default MM timer period = 5 msec.
756
757#define AIL_TIMERS 1
758#define DEFAULT_AT 16 // 16 allocatable HTIMER handles
759
760#define AIL_ENABLE_MMX_SUPPORT 2 // Enable MMX support if present
761#define DEFAULT_AEMS YES // (may be changed at any time)
762
763
764#define DIG_MIXER_CHANNELS 3
765#define DEFAULT_DMC 64 // 64 allocatable SAMPLE structures
766
767#define DIG_ENABLE_RESAMPLE_FILTER 4 // Enable resampling filter by
768#define DEFAULT_DERF YES // default
769
770#define DIG_RESAMPLING_TOLERANCE 5
771#define DEFAULT_DRT 131 // Resampling triggered at +/- 0.2%
772
773// 1 ms per mix. The PS3 has frag count restrictions, so we use 5 ms.
774#define DIG_DS_FRAGMENT_SIZE 6
775#ifdef __RADPS3__
776# define DEFAULT_DDFS 5
777#else
778# define DEFAULT_DDFS 1
779#endif
780
781// We want ~256 ms of buffers. PS3 must be 8, 16, or 32.
782#define DIG_DS_FRAGMENT_CNT 7
783#ifdef __RADPS3__
784# define DEFAULT_DDFC 32
785#else
786# define DEFAULT_DDFC 256
787#endif
788
789// Mix ahead ~48 ms. PS3 is based off on 5 ms frag size above...
790#define DIG_DS_MIX_FRAGMENT_CNT 8
791#ifdef __RADPS3__
792# define DEFAULT_DDMFC 8
793#else
794# define DEFAULT_DDMFC 48
795#endif
796
797#define DIG_LEVEL_RAMP_SAMPLES 9
798#define DEFAULT_DLRS 32 // Ramp level changes over first 32 samples in each buffer to reduce zipper noise
799
800
801#define DIG_MAX_PREDELAY_MS 10
802#define DEFAULT_MPDMS 500 // Max predelay reverb time in ms
803
804#define DIG_3D_MUTE_AT_MAX 11
805#define DEFAULT_D3MAM YES // on by default
806
807#define DIG_DS_USE_PRIMARY 12
808#define DEFAULT_DDUP NO // Mix into secondary DirectSound buffer by default
809
810
811#define DIG_DS_DSBCAPS_CTRL3D 13
812#define DEFAULT_DDDC NO // Do not use DSBCAPS_CTRL3D by default
813
814#define DIG_DS_CREATION_HANDLER 14
815#define DEFAULT_DDCH 0 // Use DirectSoundCreate() by default
816
817
818#define DIG_MAX_CHAIN_ELEMENT_SIZE 15
819#define DEFAULT_MCES 8192 // max of 8192 bytes/waveOut buffer
820
821#define DIG_MIN_CHAIN_ELEMENT_TIME 16
822#define DEFAULT_MCET 100 // 100 milliseconds buffers
823
824
825#define DIG_USE_WAVEOUT 17
826#define DEFAULT_DUW NO // Use DirectSound by default
827
828#define DIG_OUTPUT_BUFFER_SIZE 18
829#define DEFAULT_DOBS 49152 // Windows: waveout 48K output buffer size
830
831
832#define DIG_PREFERRED_WO_DEVICE 19
833#define DEFAULT_DPWOD ((UINTa)-1) // Preferred WaveOut device == WAVE_MAPPER
834
835#define DIG_PREFERRED_DS_DEVICE 20
836#define DEFAULT_DPDSD 0 // Preferred DirectSound device == default NULL GUID
837
838
839#define MDI_SEQUENCES 21
840#define DEFAULT_MS 8 // 8 sequence handles/driver
841
842#define MDI_SERVICE_RATE 22
843#define DEFAULT_MSR 120 // XMIDI sequencer timing = 120 Hz
844
845#define MDI_DEFAULT_VOLUME 23
846#define DEFAULT_MDV 127 // Default sequence volume = 127 (0-127)
847
848#define MDI_QUANT_ADVANCE 24
849#define DEFAULT_MQA 1 // Beat/bar count +1 interval
850
851#define MDI_ALLOW_LOOP_BRANCHING 25
852#define DEFAULT_ALB NO // Branches cancel XMIDI FOR loops
853
854#define MDI_DEFAULT_BEND_RANGE 26
855#define DEFAULT_MDBR 2 // Default pitch-bend range = 2
856
857#define MDI_DOUBLE_NOTE_OFF 27
858#define DEFAULT_MDNO NO // For stuck notes on SB daughterboards
859
860#define MDI_SYSEX_BUFFER_SIZE 28
861#define DEFAULT_MSBS 1536 // Default sysex buffer = 1536 bytes
862
863
864#define DLS_VOICE_LIMIT 29
865#define DEFAULT_DVL 64 // 64 voices supported
866
867#define DLS_TIMEBASE 30
868#define DEFAULT_DTB 120 // 120 intervals/second by default
869
870#define DLS_BANK_SELECT_ALIAS 31
871#define DEFAULT_DBSA NO // Do not treat controller 114 as bank
872
873#define DLS_STREAM_BOOTSTRAP 32 // Don't submit first stream buffer
874#define DEFAULT_DSB YES // until at least 2 available
875
876#define DLS_VOLUME_BOOST 33
877#define DEFAULT_DVB 0 // Boost final volume by 0 dB
878
879#define DLS_ENABLE_FILTERING 34 // Filtering = on by default
880#define DEFAULT_DEF YES // (may be changed at any time)
881
882
883#define DLS_GM_PASSTHROUGH 35 // Pass unrecognized traffic on to
884#define DEFAULT_DGP YES // default GM driver layer
885 // (may be changed at any time)
886
887#define DLS_ADPCM_TO_ASI_THRESHOLD 36 // Size in samples to switch to ASI
888#define DEFAULT_DATAT 32768
889
890#ifdef __RAD3DS__
891# define AIL_3DS_USE_SYSTEM_CORE 32 // Defaults to 0
892#endif
893
894#define N_PREFS 40 // # of preference types
895
896#if defined(IS_WIN32API) || defined(IS_WII)
897 #pragma pack(push, 1)
898#endif
899
900typedef struct Mwavehdr_tag {
901 C8 * lpData;
902 U32 dwBufferLength;
903 U32 dwBytesRecorded;
904 UINTa dwUser;
905 U32 dwFlags;
906 U32 dwLoops;
907 struct Mwavehdr_tag *lpNext;
908 UINTa reserved;
909} MWAVEHDR;
910typedef MSS_STRUCT Mwaveformat_tag {
911 U16 wFormatTag;
912 U16 nChannels;
913 U32 nSamplesPerSec;
914 U32 nAvgBytesPerSec;
915 U16 nBlockAlign;
916} MWAVEFORMAT;
917typedef MSS_STRUCT Mpcmwaveformat_tag {
918 MWAVEFORMAT wf;
919 U16 wBitsPerSample;
920} MPCMWAVEFORMAT;
921typedef MSS_STRUCT Mwaveformatex_tag {
922 U16 wFormatTag;
923 U16 nChannels;
924 U32 nSamplesPerSec;
925 U32 nAvgBytesPerSec;
926 U16 nBlockAlign;
927 U16 wBitsPerSample;
928 U16 cbSize;
929} MWAVEFORMATEX;
930typedef MSS_STRUCT Mwaveformatextensible_tag {
931 MWAVEFORMATEX Format;
932 union {
933 U16 wValidBitsPerSample;
934 U16 wSamplesPerBlock;
935 U16 wReserved;
936 } Samples;
937 U32 dwChannelMask;
938 U8 SubFormat[16];
939} MWAVEFORMATEXTENSIBLE;
940
941#if defined(IS_WIN32API) || defined(IS_WII)
942 #pragma pack(pop)
943#endif
944
945// This will fail if structure packing isn't correct for the compiler we are running.
946RR_COMPILER_ASSERT(sizeof(MWAVEFORMATEXTENSIBLE) == 40);
947
948
949typedef struct _AILSOUNDINFO {
950 S32 format;
951 void const* data_ptr;
952 U32 data_len;
953 U32 rate;
954 S32 bits;
955 S32 channels;
956 U32 channel_mask;
957 U32 samples;
958 U32 block_size;
959 void const* initial_ptr;
960} AILSOUNDINFO;
961
962// asis use these callbacks
963typedef void * (AILCALL MSS_ALLOC_TYPE)( UINTa size, UINTa user, char const * filename, U32 line );
964typedef void (AILCALL MSS_FREE_TYPE)( void * ptr, UINTa user, char const * filename, U32 line );
965
966// helper functions that just turn around and call AIL_mem_alloc_lock
967DXDEC void * AILCALL MSS_alloc_info( UINTa size, UINTa user, char const * filename, U32 line );
968DXDEC void AILCALL MSS_free_info( void * ptr, UINTa user, char const * filename, U32 line );
969
970#if defined(STANDALONEMIXRIB) && !defined(FORNONWIN)
971#define MSS_CALLBACK_ALIGNED_NAME( name ) name##_fixup
972#define MSS_DEC_CB_STACK_ALIGN( name ) DXDEC void AILCALL MSS_CALLBACK_ALIGNED_NAME(name)(void);
973#else
974#define MSS_CALLBACK_ALIGNED_NAME( name ) name
975#define MSS_DEC_CB_STACK_ALIGN( name )
976#endif
977
978MSS_DEC_CB_STACK_ALIGN( MSS_alloc_info )
979MSS_DEC_CB_STACK_ALIGN( MSS_free_info)
980
981
982#ifndef RIB_H // RIB.H contents included if RIB.H not already included
983
984#define RIB_H
985#define ARY_CNT(x) (sizeof((x)) / sizeof((x)[0]))
986
987// ----------------------------------
988// RIB data types
989// ----------------------------------
990
991typedef S32 RIBRESULT;
992
993#define RIB_NOERR 0 // Success -- no error
994#define RIB_NOT_ALL_AVAILABLE 1 // Some requested functions/attribs not available
995#define RIB_NOT_FOUND 2 // Resource not found
996#define RIB_OUT_OF_MEM 3 // Out of system RAM
997
998//
999// Handle to interface provider
1000//
1001
1002typedef UINTa HPROVIDER;
1003
1004//
1005// Handle representing token used to obtain property data
1006//
1007// This needs to be large enough to store a function pointer
1008//
1009
1010typedef UINTa HPROPERTY;
1011
1012//
1013// Data types for RIB properties
1014//
1015
1016typedef enum
1017{
1018 RIB_NONE = 0, // No type
1019 RIB_CUSTOM, // Used for pointers to application-specific structures
1020 RIB_DEC, // Used for 32-bit integer values to be reported in decimal
1021 RIB_HEX, // Used for 32-bit integer values to be reported in hex
1022 RIB_FLOAT, // Used for 32-bit single-precision FP values
1023 RIB_PERCENT, // Used for 32-bit single-precision FP values to be reported as percentages
1024 RIB_BOOL, // Used for Boolean-constrained integer values to be reported as TRUE or FALSE
1025 RIB_STRING, // Used for pointers to null-terminated ASCII strings
1026 RIB_READONLY = 0x80000000 // Property is read-only
1027}
1028RIB_DATA_SUBTYPE;
1029
1030//
1031// RIB_ENTRY_TYPE structure, used to register an interface or request one
1032//
1033
1034typedef enum
1035{
1036 RIB_FUNCTION = 0,
1037 RIB_PROPERTY, // Property: read-only or read-write data type
1038 RIB_ENTRY_FORCE_32 = 0x7fffffff
1039}
1040RIB_ENTRY_TYPE;
1041
1042//
1043// RIB_INTERFACE_ENTRY, used to represent a function or data entry in an
1044// interface
1045//
1046
1047typedef struct
1048{
1049 RIB_ENTRY_TYPE type; // See list above
1050 const C8 *entry_name; // Name of desired function or property
1051 UINTa token; // Function pointer or property token
1052 RIB_DATA_SUBTYPE subtype; // Property subtype
1053}
1054RIB_INTERFACE_ENTRY;
1055
1056//
1057// Standard RAD Interface Broker provider identification properties
1058//
1059
1060#define PROVIDER_NAME ((U32) (S32) (-100)) // RIB_STRING name of decoder
1061#define PROVIDER_VERSION ((U32) (S32) (-101)) // RIB_HEX BCD version number
1062
1063//
1064// Standard function to obtain provider properties (see PROVIDER_ defines
1065// above)
1066//
1067// Each provider of a searchable interface must export this function
1068//
1069
1070typedef S32 (AILCALL *PROVIDER_PROPERTY) (HPROPERTY index,
1071 void * before_value,
1072 void const * new_value,
1073 void * after_value
1074 );
1075
1076//
1077// Macros to simplify interface registrations/requests for functions,
1078// and properties
1079//
1080
1081#define FN(entry_name) { RIB_FUNCTION, #entry_name, (UINTa) &(entry_name), RIB_NONE }
1082#define REG_FN(entry_name) { RIB_FUNCTION, #entry_name, (UINTa) &(entry_name), RIB_NONE }
1083
1084#define PR(entry_name,ID) { RIB_PROPERTY, (entry_name), (UINTa) &(ID), RIB_NONE }
1085#define REG_PR(entry_name,ID,subtype) { RIB_PROPERTY, (entry_name), (UINTa) (ID), subtype }
1086
1087#define RIB_register(x,y,z) RIB_register_interface ((HPROVIDER)(x), y, ARY_CNT(z), z)
1088#define RIB_unregister(x,y,z) RIB_unregister_interface((HPROVIDER)(ssx), y, ARY_CNT(z), z)
1089#define RIB_unregister_all(x) RIB_unregister_interface((HPROVIDER)(x), 0, 0, 0)
1090#define RIB_free_libraries() RIB_free_provider_library((HPROVIDER)(0));
1091#define RIB_request(x,y,z) RIB_request_interface (x, y, ARY_CNT(z), z)
1092
1093// passed to RIB DLLs in Miles 9 and up (so RIBS don't have to link to MSS32.dll)
1094typedef HPROVIDER AILCALL RIB_ALLOC_PROVIDER_HANDLE_TYPE(long module);
1095
1096typedef RIBRESULT AILCALL RIB_REGISTER_INTERFACE_TYPE (HPROVIDER provider,
1097 C8 const *interface_name,
1098 S32 entry_count,
1099 RIB_INTERFACE_ENTRY const *rlist);
1100
1101typedef RIBRESULT AILCALL RIB_UNREGISTER_INTERFACE_TYPE (HPROVIDER provider,
1102 C8 const *interface_name,
1103 S32 entry_count,
1104 RIB_INTERFACE_ENTRY const *rlist);
1105
1106#define RIB_registerP(x,y,z) rib_reg ((HPROVIDER)(x), y, ARY_CNT(z), z)
1107#define RIB_unregister_allP(x) rib_unreg ((HPROVIDER)(x), 0, 0, 0)
1108
1109
1110// ----------------------------------
1111// Standard RIB API prototypes
1112// ----------------------------------
1113
1114DXDEC HPROVIDER AILCALL RIB_alloc_provider_handle (long module);
1115DXDEC void AILCALL RIB_free_provider_handle (HPROVIDER provider);
1116
1117DXDEC HPROVIDER AILCALL RIB_load_provider_library (C8 const *filename);
1118DXDEC void AILCALL RIB_free_provider_library (HPROVIDER provider);
1119
1120DXDEC RIBRESULT AILCALL RIB_register_interface (HPROVIDER provider,
1121 C8 const *interface_name,
1122 S32 entry_count,
1123 RIB_INTERFACE_ENTRY const *rlist);
1124
1125DXDEC RIBRESULT AILCALL RIB_unregister_interface (HPROVIDER provider,
1126 C8 const *interface_name,
1127 S32 entry_count,
1128 RIB_INTERFACE_ENTRY const *rlist);
1129
1130DXDEC RIBRESULT AILCALL RIB_request_interface (HPROVIDER provider,
1131 C8 const *interface_name,
1132 S32 entry_count,
1133 RIB_INTERFACE_ENTRY *rlist);
1134
1135DXDEC RIBRESULT AILCALL RIB_request_interface_entry (HPROVIDER provider,
1136 C8 const *interface_name,
1137 RIB_ENTRY_TYPE entry_type,
1138 C8 const *entry_name,
1139 UINTa *token);
1140
1141DXDEC S32 AILCALL RIB_enumerate_interface (HPROVIDER provider,
1142 C8 const *interface_name,
1143 RIB_ENTRY_TYPE type,
1144 HMSSENUM *next,
1145 RIB_INTERFACE_ENTRY *dest);
1146
1147DXDEC S32 AILCALL RIB_enumerate_providers (C8 const *interface_name,
1148 HMSSENUM *next,
1149 HPROVIDER *dest);
1150
1151DXDEC C8 * AILCALL RIB_type_string (void const * data,
1152 RIB_DATA_SUBTYPE subtype);
1153
1154DXDEC HPROVIDER AILCALL RIB_find_file_provider (C8 const *interface_name,
1155 C8 const *property_name,
1156 C8 const *file_suffix);
1157
1158DXDEC HPROVIDER AILCALL RIB_find_provider (C8 const *interface_name,
1159 C8 const *property_name,
1160 void const *property_value);
1161
1162//
1163// Static library definitions
1164//
1165
1166#ifdef MSS_STATIC_RIB
1167 #define RIB_MAIN_NAME( name ) name##_RIB_Main
1168
1169 DXDEC S32 AILCALL RIB_MAIN_NAME(SRS)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1170 DXDEC S32 AILCALL RIB_MAIN_NAME(DTS)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1171 DXDEC S32 AILCALL RIB_MAIN_NAME(DolbySurround)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1172 DXDEC S32 AILCALL RIB_MAIN_NAME(MP3Dec)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1173 DXDEC S32 AILCALL RIB_MAIN_NAME(OggDec)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1174 DXDEC S32 AILCALL RIB_MAIN_NAME(BinkADec)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1175 DXDEC S32 AILCALL RIB_MAIN_NAME(SpxDec)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1176 DXDEC S32 AILCALL RIB_MAIN_NAME(SpxEnc)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1177 DXDEC S32 AILCALL RIB_MAIN_NAME(Voice)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1178 DXDEC S32 AILCALL RIB_MAIN_NAME(SpxVoice)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1179 DXDEC S32 AILCALL RIB_MAIN_NAME(DSP)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1180
1181#ifdef IS_XENON
1182 DXDEC S32 AILCALL RIB_MAIN_NAME(XMADec)( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1183#endif
1184
1185 #define Register_RIB(name) RIB_load_static_provider_library(RIB_MAIN_NAME(name),#name)
1186
1187#else // MSS_STATIC_RIB
1188 #define RIB_MAIN_NAME( name ) RIB_Main
1189 DXDEC S32 AILCALL RIB_Main( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1190#endif // MSS_STATIC_RIB
1191
1192typedef S32 ( AILCALL * RIB_MAIN_FUNC) ( HPROVIDER provider_handle, U32 up_down, RIB_ALLOC_PROVIDER_HANDLE_TYPE * rib_alloc, RIB_REGISTER_INTERFACE_TYPE * rib_reg, RIB_UNREGISTER_INTERFACE_TYPE * rib_unreg );
1193
1194DXDEC HPROVIDER AILCALL RIB_load_static_provider_library (RIB_MAIN_FUNC main, const char* description);
1195
1196
1197DXDEC HPROVIDER AILCALL RIB_find_files_provider (C8 const *interface_name,
1198 C8 const *property_name_1,
1199 C8 const *file_suffix_1,
1200 C8 const *property_name_2,
1201 C8 const *file_suffix_2);
1202
1203DXDEC HPROVIDER AILCALL RIB_find_file_dec_provider (C8 const *interface_name,
1204 C8 const *property_name_1,
1205 U32 decimal_property_value_1,
1206 C8 const *property_name_2,
1207 C8 const *file_suffix_2);
1208
1209DXDEC S32 AILCALL RIB_load_application_providers
1210 (C8 const *filespec);
1211
1212DXDEC void AILCALL RIB_set_provider_user_data (HPROVIDER provider,
1213 U32 index,
1214 SINTa value);
1215
1216DXDEC SINTa AILCALL RIB_provider_user_data (HPROVIDER provider,
1217 U32 index);
1218
1219DXDEC void AILCALL RIB_set_provider_system_data
1220 (HPROVIDER provider,
1221 U32 index,
1222 SINTa value);
1223
1224DXDEC SINTa AILCALL RIB_provider_system_data (HPROVIDER provider,
1225 U32 index);
1226
1227DXDEC C8 * AILCALL RIB_error (void);
1228
1229#endif // RIB_H
1230
1231
1232#ifndef MSS_ASI_VERSION // MSSASI.H contents included if MSSASI.H not already included
1233
1234#define AIL_ASI_VERSION 1
1235#define AIL_ASI_REVISION 0
1236
1237//
1238// Handle to stream being managed by ASI codec
1239//
1240
1241typedef SINTa HASISTREAM;
1242
1243//
1244// ASI result codes
1245//
1246
1247typedef S32 ASIRESULT;
1248
1249#define ASI_NOERR 0 // Success -- no error
1250#define ASI_NOT_ENABLED 1 // ASI not enabled
1251#define ASI_ALREADY_STARTED 2 // ASI already started
1252#define ASI_INVALID_PARAM 3 // Invalid parameters used
1253#define ASI_INTERNAL_ERR 4 // Internal error in ASI driver
1254#define ASI_OUT_OF_MEM 5 // Out of system RAM
1255#define ASI_ERR_NOT_IMPLEMENTED 6 // Feature not implemented
1256#define ASI_NOT_FOUND 7 // ASI supported device not found
1257#define ASI_NOT_INIT 8 // ASI not initialized
1258#define ASI_CLOSE_ERR 9 // ASI not closed correctly
1259
1260// ----------------------------------
1261// Application-provided ASI callbacks
1262// ----------------------------------
1263
1264//
1265// AILASIFETCHCB: Called by ASI to obtain data from stream source
1266//
1267// offset normally will be either 0 at the first call made by the codec
1268// or -1 to specify a continuous stream, except when ASI_stream_seek()
1269// is called to restart the stream codec at a new stream offset. In this
1270// case, the application must execute the seek operation on the ASI codec's
1271// behalf.
1272//
1273// In response to this callback, the application should read the requested
1274// data and copy it to the specified destination buffer, returning the number
1275// of bytes copied (which can be less than bytes_requested if the end of
1276// the stream is reached).
1277//
1278
1279
1280typedef S32 (AILCALLBACK * AILASIFETCHCB) (UINTa user, // User value passed to ASI_open_stream()
1281 void *dest, // Location to which stream data should be copied by app
1282 S32 bytes_requested, // # of bytes requested by ASI codec
1283 S32 offset); // If not -1, application should seek to this point in stream
1284
1285//############################################################################
1286//## ##
1287//## Interface "ASI codec" ##
1288//## ##
1289//############################################################################
1290
1291//
1292// Initialize ASI stream codec
1293//
1294// No other ASI functions may be called outside an ASI_startup() /
1295// ASI_shutdown() pair, except for the standard RIB function
1296// PROVIDER_property() where appropriate.
1297//
1298
1299typedef ASIRESULT (AILCALL *ASI_STARTUP)(void);
1300
1301//
1302// Shut down ASI codec
1303//
1304
1305typedef ASIRESULT (AILCALL * ASI_SHUTDOWN)(void);
1306
1307//
1308// Return codec error message, or NULL if no errors have occurred since
1309// last call
1310//
1311// The ASI error text state is global to all streams
1312//
1313
1314typedef C8 * (AILCALL * ASI_ERROR)(void);
1315
1316//############################################################################
1317//## ##
1318//## Interface "ASI stream" ##
1319//## ##
1320//############################################################################
1321
1322//
1323// Open a stream, returning handle to stream
1324//
1325
1326typedef HASISTREAM (AILCALL *ASI_STREAM_OPEN) (MSS_ALLOC_TYPE * palloc,
1327 MSS_FREE_TYPE * pfree,
1328 UINTa user, // User value passed to fetch callback
1329 AILASIFETCHCB fetch_CB, // Source data fetch handler
1330 U32 total_size); // Total size for %-done calculations (0=unknown)
1331
1332//
1333// Translate data in stream, returning # of bytes actually decoded or encoded
1334//
1335// Any number of bytes may be requested. Requesting more data than is
1336// available in the codec's internal buffer will cause the AILASIFETCHCB
1337// handler to be called to fetch more data from the stream.
1338//
1339
1340typedef S32 (AILCALL *ASI_STREAM_PROCESS) (HASISTREAM stream, // Handle of stream
1341 void *buffer, // Destination for processed data
1342 S32 buffer_size); // # of bytes to return in buffer
1343
1344//
1345// Restart stream decoding process at new offset
1346//
1347// Relevant for decoders only
1348//
1349// Seek destination is given as offset in bytes from beginning of stream
1350//
1351// At next ASI_stream_process() call, decoder will seek to the closest possible
1352// point in the stream which occurs at or after the specified position
1353//
1354// This function has no effect for decoders which do not support random
1355// seeks on a given stream type
1356//
1357// Warning: some decoders may need to implement seeking by reparsing
1358// the entire stream up to the specified offset, through multiple calls
1359// to the data-fetch callback. This operation may be extremely
1360// time-consuming on large files or slow network connections.
1361//
1362// A stream_offset value of -1 may be used to inform the decoder that the
1363// application has changed the input stream offset on its own, e.g. for a
1364// double-buffering application where the ASI decoder is not accessing the
1365// stream directly. ASI decoders should respond to this by flushing all
1366// internal buffers and resynchronizing themselves to the data stream.
1367//
1368
1369typedef ASIRESULT (AILCALL *ASI_STREAM_SEEK) (HASISTREAM stream,
1370 S32 stream_offset);
1371
1372//
1373// Retrieve or set a property value by index (returns 1 on success)
1374//
1375
1376typedef S32 (AILCALL *ASI_STREAM_PROPERTY) (HASISTREAM stream,
1377 HPROPERTY property,
1378 void * before_value,
1379 void const * new_value,
1380 void * after_value
1381 );
1382
1383//
1384// Close stream, freeing handle and all internally-allocated resources
1385//
1386
1387typedef ASIRESULT (AILCALL *ASI_STREAM_CLOSE) (HASISTREAM stream);
1388
1389#endif // MSS_ASI_VERSION
1390
1391//############################################################################
1392//## ##
1393//## Interface "MSS mixer services" ##
1394//## ##
1395//############################################################################
1396
1397//
1398// Operation flags used by mixer and filter modules
1399//
1400
1401#define M_DEST_STEREO 1 // Set to enable stereo mixer output
1402#define M_SRC_16 2 // Set to enable mixing of 16-bit samples
1403#define M_FILTER 4 // Set to enable filtering when resampling
1404#define M_SRC_STEREO 8 // Set to enable mixing of stereo input samples
1405#define M_RESAMPLE 16 // Set to enable playback ratios other than 65536
1406#define M_VOL_SCALING 32 // Set to enable volume scalars other than 2048
1407#define M_COPY16_NOVOL 64
1408
1409#ifdef IS_32
1410
1411//
1412// Initialize mixer
1413//
1414// No other mixer functions may be called outside a MIXER_startup() /
1415// MIXER_shutdown() pair, except for the standard RIB function
1416// PROVIDER_property() as appropriate.
1417//
1418
1419typedef void (AILCALL *MIXER_STARTUP)(void);
1420
1421//
1422// Shut down mixer
1423//
1424
1425typedef void (AILCALL *MIXER_SHUTDOWN)(void);
1426
1427//
1428// Flush mixer buffer
1429//
1430
1431typedef void (AILCALL *MIXER_FLUSH) (S32 *dest,
1432 S32 len
1433#ifdef IS_X86
1434 ,U32 MMX_available
1435#endif
1436 );
1437
1438//
1439// Perform audio mixing operation
1440//
1441
1442typedef void (AILCALL *MIXER_MERGE) (void const * *src,
1443 U32 *src_fract,
1444 void const *src_end,
1445 S32 * *dest,
1446 void *dest_end,
1447 S32 *left_val,
1448 S32 *right_val,
1449 S32 playback_ratio,
1450 S32 scale_left,
1451 S32 scale_right,
1452 U32 operation
1453#ifdef IS_X86
1454 ,U32 MMX_available
1455#endif
1456 );
1457
1458//
1459// Translate mixer buffer contents to final output format
1460//
1461// "option" parameter is big_endian_output on Mac, MMX on x86, overwrite flag on PS2
1462//
1463
1464typedef void (AILCALL *MIXER_COPY) (void const *src,
1465 S32 src_len,
1466 void *dest,
1467 U32 operation
1468#if defined(IS_BE) || defined(IS_X86)
1469 ,U32 option
1470#endif
1471 );
1472
1473#else
1474
1475//
1476// Initialize mixer
1477//
1478// No other mixer functions may be called outside a MIXER_startup() /
1479// MIXER_shutdown() pair, except for the standard RIB function
1480// PROVIDER_property() as appropriate.
1481//
1482
1483typedef void (AILCALL *MIXER_STARTUP)(void);
1484
1485//
1486// Shut down mixer
1487//
1488
1489typedef void (AILCALL *MIXER_SHUTDOWN)(void);
1490
1491//
1492// Flush mixer buffer
1493//
1494
1495typedef void (AILCALL *MIXER_FLUSH) (S32 *dest,
1496 S32 len,
1497 U32 MMX_available);
1498
1499//
1500// Perform audio mixing operation
1501//
1502
1503typedef void (AILCALL *MIXER_MERGE) (U32 src_sel,
1504 U32 dest_sel,
1505 U32 *src_fract,
1506 U32 *src_offset,
1507 U32 *dest_offset,
1508 U32 src_end_offset,
1509 U32 dest_end_offset,
1510 S32 *left_val,
1511 S32 *right_val,
1512 S32 playback_ratio,
1513 S32 scale_both,
1514 U32 operation);
1515
1516//
1517// Translate mixer buffer contents to final output format
1518//
1519
1520typedef void (AILCALL *MIXER_COPY) (void const *src,
1521 S32 src_len,
1522 void *dest,
1523 U32 operation,
1524 U32 option);
1525#endif
1526
1527
1528typedef struct _MSS_BB // Used in both MC and conventional mono/stereo configurations
1529{
1530 S32 *buffer; // Build buffer
1531 S32 bytes; // Size in bytes
1532 S32 chans; // Always mono (1) or stereo (2)
1533
1534 S32 speaker_offset; // Destination offset in interleaved PCM block for left channel
1535} MSS_BB;
1536
1537typedef struct _ADPCMDATATAG
1538{
1539 U32 blocksize;
1540 U32 extrasamples;
1541 U32 blockleft;
1542 U32 step;
1543 UINTa savesrc;
1544 U32 sample;
1545 UINTa destend;
1546 UINTa srcend;
1547 U32 samplesL;
1548 U32 samplesR;
1549 U16 moresamples[16];
1550} ADPCMDATA;
1551
1552typedef void (AILCALL * MIXER_MC_COPY) ( MSS_BB * build,
1553 S32 n_build_buffers,
1554 void * lpWaveAddr,
1555 S32 hw_format,
1556#ifdef IS_X86
1557 S32 use_MMX,
1558#endif
1559 S32 samples_per_buffer,
1560 S32 physical_channels_per_sample );
1561
1562
1563typedef void (AILCALL * MIXER_ADPCM_DECODE ) ( void * dest,
1564 void const * in,
1565 S32 out_len,
1566 S32 in_len,
1567 S32 input_format,
1568 ADPCMDATA *adpcm_data);
1569
1570//
1571// Type definitions
1572//
1573
1574struct _DIG_DRIVER;
1575
1576struct _MDI_DRIVER;
1577
1578typedef struct _DIG_DRIVER * HDIGDRIVER; // Handle to digital driver
1579
1580typedef struct _MDI_DRIVER * HMDIDRIVER; // Handle to XMIDI driver
1581
1582typedef struct _SAMPLE * HSAMPLE; // Handle to sample
1583
1584typedef struct _SEQUENCE * HSEQUENCE; // Handle to sequence
1585
1586typedef S32 HTIMER; // Handle to timer
1587
1588
1589//
1590// Function pointer types
1591//
1592
1593typedef void (AILCALLBACK* AILINCB) (void const *data, S32 len, UINTa user_data);
1594
1595typedef void (AILCALLBACK* AILTRACECB) (C8 *text, S32 nest_depth);
1596
1597typedef void (AILCALLBACK* AILTIMERCB) (UINTa user);
1598
1599typedef void (AILCALLBACK* AILSAMPLECB) (HSAMPLE sample);
1600
1601typedef void (AILCALLBACK* AILMIXERCB) (HDIGDRIVER dig);
1602
1603typedef F32 (AILCALLBACK* AILFALLOFFCB) (HSAMPLE sample, F32 distance, F32 rolloff_factor, F32 min_dist, F32 max_dist);
1604
1605typedef S32 (AILCALLBACK* AILEVENTCB) (HMDIDRIVER hmi,HSEQUENCE seq,S32 status,S32 data_1,S32 data_2);
1606
1607typedef S32 (AILCALLBACK* AILTIMBRECB) (HMDIDRIVER hmi,S32 bank,S32 patch);
1608
1609typedef S32 (AILCALLBACK* AILPREFIXCB) (HSEQUENCE seq,S32 log,S32 data);
1610
1611typedef void (AILCALLBACK* AILTRIGGERCB) (HSEQUENCE seq,S32 log,S32 data);
1612
1613typedef void (AILCALLBACK* AILBEATCB) (HMDIDRIVER hmi,HSEQUENCE seq,S32 beat,S32 measure);
1614
1615typedef void (AILCALLBACK* AILSEQUENCECB) (HSEQUENCE seq);
1616
1617typedef S32 (AILCALLBACK *SS_STREAM_CB) (HSAMPLE S, S16 *dest_mono_sample_buffer, S32 dest_buffer_size);
1618
1619//
1620// Handle to sample and driver being managed by pipeline filter
1621//
1622
1623typedef SINTa HSAMPLESTATE;
1624typedef SINTa HDRIVERSTATE;
1625
1626//
1627// Digital pipeline stages
1628//
1629// These are the points at which external modules may be installed into
1630// a given HSAMPLE or HDIGDRIVER's processing pipeline
1631//
1632
1633typedef enum
1634{
1635 SP_ASI_DECODER = 0, // Must be "ASI codec stream" provider
1636 SP_FILTER, // Must be "MSS pipeline filter" provider
1637 SP_FILTER_0 = SP_FILTER, // Must be "MSS pipeline filter" provider
1638 SP_FILTER_1, // Must be "MSS pipeline filter" provider
1639 SP_FILTER_2, // Must be "MSS pipeline filter" provider
1640 SP_FILTER_3, // Must be "MSS pipeline filter" provider
1641 SP_FILTER_4, // Must be "MSS pipeline filter" provider
1642 SP_FILTER_5, // Must be "MSS pipeline filter" provider
1643 SP_FILTER_6, // Must be "MSS pipeline filter" provider
1644 SP_FILTER_7, // Must be "MSS pipeline filter" provider
1645 SP_MERGE, // Must be "MSS mixer" provider
1646 N_SAMPLE_STAGES, // Placeholder for end of list (= # of valid sample pipeline stages)
1647 SP_OUTPUT = N_SAMPLE_STAGES, // Used to set/get prefs/attribs on a driver's output or matrix filter (if present)
1648 SAMPLE_ALL_STAGES // Used to signify all pipeline stages, for shutdown
1649}
1650SAMPLESTAGE;
1651
1652#define N_SP_FILTER_STAGES 8 // SP_FILTER_0 ... SP_FILTER_7
1653
1654typedef enum
1655{
1656 DP_FLUSH = 0, // Must be "MSS mixer" provider
1657 DP_DEFAULT_FILTER, // Must be "MSS pipeline filter" provider (sets the default)
1658 DP_DEFAULT_MERGE, // Must be "MSS mixer" provider (sets the default)
1659 DP_COPY, // Must be "MSS mixer" provider
1660 DP_MC_COPY, // Must be "MSS mixer" provider
1661 DP_ADPCM_DECODE, // Must be "MSS mixer" provider
1662 N_DIGDRV_STAGES, // Placeholder for end of list (= # of valid stages)
1663 DIGDRV_ALL_STAGES // Used to signify all pipeline stages, for shutdown
1664}
1665DIGDRVSTAGE;
1666
1667typedef struct
1668 {
1669 ASI_STREAM_OPEN ASI_stream_open;
1670 ASI_STREAM_PROCESS ASI_stream_process;
1671 ASI_STREAM_SEEK ASI_stream_seek;
1672 ASI_STREAM_CLOSE ASI_stream_close;
1673 ASI_STREAM_PROPERTY ASI_stream_property;
1674
1675 HPROPERTY INPUT_BIT_RATE;
1676 HPROPERTY INPUT_SAMPLE_RATE;
1677 HPROPERTY INPUT_BITS;
1678 HPROPERTY INPUT_CHANNELS;
1679 HPROPERTY OUTPUT_BIT_RATE;
1680 HPROPERTY OUTPUT_SAMPLE_RATE;
1681 HPROPERTY OUTPUT_BITS;
1682 HPROPERTY OUTPUT_CHANNELS;
1683 HPROPERTY OUTPUT_CHANNEL_MASK;
1684 HPROPERTY OUTPUT_RESERVOIR;
1685 HPROPERTY POSITION;
1686 HPROPERTY PERCENT_DONE;
1687 HPROPERTY MIN_INPUT_BLOCK_SIZE;
1688 HPROPERTY RAW_RATE;
1689 HPROPERTY RAW_BITS;
1690 HPROPERTY RAW_CHANNELS;
1691 HPROPERTY REQUESTED_RATE;
1692 HPROPERTY REQUESTED_BITS;
1693 HPROPERTY REQUESTED_CHANS;
1694 HPROPERTY STREAM_SEEK_POS;
1695 HPROPERTY DATA_START_OFFSET;
1696 HPROPERTY DATA_LEN;
1697 HPROPERTY EXACT_SEEK;
1698 HPROPERTY EXACT_GETPOS;
1699 HPROPERTY SEEK_LOOKUP;
1700 HPROPERTY SET_LOOPING_SAMPLES;
1701 HPROPERTY CLEAR_LOOP_META;
1702
1703 HASISTREAM stream;
1704 }
1705ASISTAGE;
1706
1707typedef struct
1708 {
1709 struct _FLTPROVIDER *provider;
1710 HSAMPLESTATE sample_state[MAX_SPEAKERS];
1711 }
1712FLTSTAGE;
1713
1714typedef struct
1715{
1716 S32 active; // Pass-through if 0, active if 1
1717 HPROVIDER provider;
1718
1719 union
1720 {
1721 ASISTAGE ASI;
1722 MIXER_MERGE MSS_mixer_merge;
1723 FLTSTAGE FLT;
1724 }
1725 TYPE;
1726}
1727SPINFO;
1728
1729typedef struct
1730{
1731 S32 active; // Pass-through if 0, active if 1
1732 HPROVIDER provider;
1733
1734 union
1735 {
1736 MIXER_FLUSH MSS_mixer_flush;
1737 MIXER_COPY MSS_mixer_copy;
1738 MIXER_MC_COPY MSS_mixer_mc_copy;
1739 MIXER_ADPCM_DECODE MSS_mixer_adpcm_decode;
1740 }
1741 TYPE;
1742}
1743DPINFO;
1744
1745//
1746// Other data types
1747//
1748
1749typedef enum
1750{
1751 WIN32_HWAVEOUT, // waveOut handle for HDIGDRIVER, if any
1752 WIN32_HWAVEIN, // waveIn handle for HDIGINPUT, if any
1753 WIN32_LPDS, // lpDirectSound pointer for HSAMPLE
1754 WIN32_LPDSB, // lpDirectSoundBuffer pointer for HSAMPLE
1755 WIN32_HWND, // HWND that will be used to open DirectSound driver
1756 WIN32_POSITION_ERR, // Nonzero if DirectSound play cursor stops moving (e.g., headphones removed)
1757
1758 PS3_AUDIO_PORT, // cellaudio port that Miles is using
1759 PS3_AUDIO_ADDRESS, // address of cellaudio sound buffer
1760 PS3_AUDIO_LENGTH, // length of cellaudio sound buffer
1761 PS3_AUDIO_POSITION, // current playback position of cellaudio sound buffer
1762
1763 PSP_SUBMIT_THREAD, // Handle to thread submitting chucks of audio to the hw
1764 PSP_AUDIO_PORT, // Port # Miles is using, -1 for simple audio, >= 0 for libwave
1765
1766 PSP2_SUBMIT_THREAD, // Handle to thread submitting chucks of audio to the hw
1767 PSP2_AUDIO_PORT, // Port # Miles is using
1768
1769 OAL_CONTEXT, // OpenAL Context
1770 OAL_DEVICE, // OpenAL Device
1771
1772 XB_LPDS, // lpDirectSound pointer for HSAMPLE
1773 XB_LPDSB, // lpDirectSoundBuffer pointer for HSAMPLE
1774
1775 XB360_LPXAB // IXAudioSourceVoice pointer for HDIGDRIVER
1776}
1777MSS_PLATFORM_PROPERTY;
1778
1779
1780typedef struct _AIL_INPUT_INFO // Input descriptor type
1781{
1782 AILINCB callback; // Callback function to receive incoming data
1783 UINTa user_data; // this is a user defined value
1784 U32 device_ID; // DS LPGUID or wave device ID
1785 U32 hardware_format; // e.g., DIG_F_STEREO_16
1786 U32 hardware_rate; // e.g., 22050
1787 S32 buffer_size; // Maximum # of bytes to be passed to callback (-1 to use DIG_INPUT_LATENCY)
1788} AIL_INPUT_INFO;
1789
1790typedef struct _AILTIMER // Timer instance
1791{
1792 AILTIMERCB callback;
1793 U64 next;
1794 U64 delta;
1795 UINTa user;
1796 U32 status;
1797} AILTIMERSTR;
1798
1799#ifndef IS_WIN64
1800
1801 #define OFSblocksize 0 // these constants valid for 32-bit versions only!
1802 #define OFSextrasamples 4
1803 #define OFSblockleft 8
1804 #define OFSstep 12
1805 #define OFSsavesrc 16
1806 #define OFSsample 20
1807 #define OFSdestend 24
1808 #define OFSsrcend 28
1809 #define OFSsamplesL 32
1810 #define OFSsamplesR 36
1811 #define OFSmoresamples 40
1812
1813#endif
1814
1815typedef struct LOWPASS_INFO
1816{
1817 S32 X0, X1;
1818 S32 Y0, Y1;
1819 S32 A, B0, B1;
1820 S32 flags;
1821 S32 queuedA, queuedB;
1822 F32 calculated_cut;
1823 F32 cutoff;
1824} LOWPASS_INFO;
1825
1826
1827typedef union STAGE_BUFFER
1828{
1829 union STAGE_BUFFER * next;
1830 U8 data[ 1 ];
1831} STAGE_BUFFER;
1832
1833typedef struct _MSSVECTOR3D
1834{
1835 F32 x;
1836 F32 y;
1837 F32 z;
1838} MSSVECTOR3D;
1839
1840#define MILES_TANGENT_LINEAR 0
1841#define MILES_TANGENT_CURVE 1
1842#define MILES_TANGENT_STEP 2
1843#define MILES_MAX_FALLOFF_GRAPH_POINTS 5
1844
1845#define MILES_MAX_SEGMENT_COUNT 10
1846
1847typedef struct _MSSGRAPHPOINT
1848{
1849 F32 X, Y, ITX, ITY, OTX, OTY; // Point & tangents.
1850 S32 IType, OType;
1851} MSSGRAPHPOINT;
1852
1853typedef struct _S3DSTATE // Portion of HSAMPLE that deals with 3D positioning
1854{
1855 MSSVECTOR3D position; // 3D position
1856 MSSVECTOR3D face; // 3D orientation
1857 MSSVECTOR3D up; // 3D up-vector
1858 MSSVECTOR3D velocity; // 3D velocity
1859
1860 S32 doppler_valid; // TRUE if OK to apply Doppler shift
1861 F32 doppler_shift; // Scalar for S->playback rate
1862
1863 F32 inner_angle; // Cone attenuation parameters
1864 F32 outer_angle; // (Angles divided by two and convered to rads for dot-product comparisons)
1865 F32 outer_volume;
1866 S32 cone_enabled;
1867
1868 F32 max_dist; // Sample distances
1869 F32 min_dist;
1870 S32 dist_changed; // TRUE if min/max distances have changed and need to be sent to the hardware
1871
1872 S32 auto_3D_atten; // TRUE if distance/cone attenuation should be applied to wet signal
1873 F32 atten_3D; // Attenuation due to distance/cone effects, calculated by software 3D positioner
1874 F32 rolloff; // per sample rolloff factor to use instead of global rolloff, if non zero.
1875
1876 F32 exclusion_3D; // exclusion value computed by falloff graph. -1 if not affected.
1877 F32 lowpass_3D; // low pass cutoff computed by falloff graph. -1 if not affected.
1878
1879 F32 spread;
1880
1881 HSAMPLE owner; // May be NULL if used for temporary/internal calculations
1882 AILFALLOFFCB falloff_function; // User function for min/max distance calculations, if desired
1883
1884 MSSVECTOR3D position_graph[MILES_MAX_SEGMENT_COUNT];
1885 S32 position_graph_count;
1886
1887 MSSGRAPHPOINT volgraph[MILES_MAX_FALLOFF_GRAPH_POINTS];
1888 MSSGRAPHPOINT excgraph[MILES_MAX_FALLOFF_GRAPH_POINTS];
1889 MSSGRAPHPOINT lpgraph[MILES_MAX_FALLOFF_GRAPH_POINTS];
1890 MSSGRAPHPOINT spreadgraph[MILES_MAX_FALLOFF_GRAPH_POINTS];
1891
1892 U8 volgraphcnt;
1893 U8 excgraphcnt;
1894 U8 lpgraphcnt;
1895 U8 spreadgraphcnt;
1896
1897} S3DSTATE;
1898
1899typedef struct _SMPBUF
1900{
1901 void const *start; // Sample buffer address (W)
1902 U32 len; // Sample buffer size in bytes (W)
1903 U32 pos; // Index to next byte (R/W)
1904 U32 done; // Nonzero if buffer with len=0 sent by app
1905 S32 reset_ASI; // Reset the ASI decoder at the end of the buffer
1906 S32 reset_seek_pos; // New destination offset in stream source data, for ASI codecs that care
1907} SMPBUF;
1908
1909typedef struct _SAMPLE // Sample instance
1910{
1911 U32 tag; // HSAM
1912
1913 HDIGDRIVER driver; // Driver for playback
1914
1915 S32 index; // Numeric index of this sample
1916
1917 SMPBUF buf[8]; // Source data buffers
1918
1919 U32 src_fract; // Fractional part of source address
1920
1921 U32 mix_delay; // ms until start mixing (decreased every buffer mix)
1922 F32 max_output_mix_volume; // max_volume of any speaker at last mix
1923
1924 U64 mix_bytes; // total number of bytes sent to the mixer for this sample.
1925
1926 S32 group_id; // ID for grouped operations.
1927
1928 // size of the next dynamic arrays
1929 U32 chan_buf_alloced;
1930 U32 chan_buf_used;
1931 U8* chan_buf_ptr;
1932
1933 // these are dynamic arrays sized as n_channels long (so 1 for mono, 2 stereo, 6 for 5.1)
1934 S32 *left_val;
1935 S32 *right_val;
1936 S32 *last_decomp;
1937 LOWPASS_INFO *lp; // low pass info
1938
1939
1940 // these are dynamic arrays pointing to dynamic arrays, each of the sub arrays are n_channels long or [MAX_SPEAKERS][n_channels]
1941 F32 **user_channel_levels; // Channel levels set by AIL_set_sample_channel_levels() [source_channels][driver->logical_channels]
1942 S32 **cur_scale; // Calculated 11-bit volume scale factors for current/previous mixing interval
1943 S32 **prev_scale; // (These are all indexed by build buffer*2, not speaker indexes!)
1944 S32 **ramps_left;
1945
1946 // these are dynamic arrays
1947 F32 *auto_3D_channel_levels; // Channel levels set by 3D positioner (always 1.0 if not 3D-positioned)
1948 F32 *speaker_levels; // one level per speaker (multiplied after user or 3D)
1949
1950 S8 *speaker_enum_to_source_chan; // array[MSS_SPEAKER_xx] = -1 if not present, else channel #
1951 // 99% of the time this is a 1:1 mapping and is zero.
1952
1953 S32 lp_any_on; // are any of the low pass filters on?
1954 S32 user_channels_need_deinterlace; // do any of the user channels require a stereo sample to be deinterlaced?
1955
1956 S32 n_buffers; // # of buffers (default = 2)
1957 S32 head;
1958 S32 tail;
1959 S32 starved; // Buffer stream has run out of data
1960 S32 exhaust_ASI; // Are we prolonging the buffer lifetime until ASI output is exhausted?
1961
1962 S32 loop_count; // # of cycles-1 (1=one-shot, 0=indefinite)
1963 S32 loop_start; // Starting offset of loop block (0=SOF)
1964 S32 loop_end; // End offset of loop block (-1=EOF)
1965 S32 orig_loop_count; // Original loop properties specified by app, before any
1966 S32 orig_loop_start; // alignment constraints
1967 S32 orig_loop_end;
1968
1969 S32 format; // DIG_F format (8/16 bits, mono/stereo/multichannel)
1970 S32 n_channels; // # of channels (which can be >2 for multichannel formats)
1971 U32 channel_mask; // Same as WAVEFORMATEXTENSIBLE.dwChannelMask
1972
1973 S32 original_playback_rate; // Playback rate in hertz
1974 F32 playback_rate_factor; // Fractional playback rate, normally 1.0
1975
1976 F32 save_volume; // Sample volume 0-1.0
1977 F32 save_pan; // Mono panpot/stereo balance (0=L ... 1.0=R)
1978
1979 F32 left_volume; // Left/mono volume 0 to 1.0
1980 F32 right_volume; // Right volume 0 to 1.0
1981 F32 wet_level; // reverb level 0 to 1.0
1982 F32 dry_level; // non-reverb level 0 to 1.0
1983 F32 sys_level; // system control
1984
1985 F32 extra_volume; // Volume scalar for ramping or otherwise.
1986 F32 extra_wet;
1987 F32 extra_lp;
1988 F32 extra_rate;
1989
1990
1991 U32 low_pass_changed; // bit mask for what channels changed.
1992
1993 S32 bus; // Bus assignment for this sample.
1994 S32 bus_comp_sends; // Which buses this bus routes compressor input to.
1995 S32 bus_comp_installed; // Nonzero if we have a compressor installed.
1996 U32 bus_comp_input; // The input to use for this bus's compressor, if we have one installed
1997 S32 bus_override_wet; // If true, samples on this bus will use the bus's wet level instead of their own.
1998 U32 bus_signal_strength; // The bus level.
1999 S32 bus_enable_limiter; // If true, a basic limiter will be run on the samples prior to clamping to S16.
2000 S32 bus_limiter_atten; // The attenuation that was applied on the last bus pass.
2001
2002 S32 fade_to_stop; // # of samples to fade to stop over. ( currently fixed at the volramp count )
2003
2004 U64 mix_start_time; // arbitrary non-zero id for starting sounds synced.
2005
2006 S16 pop_fade_total;
2007 S16 pop_fade_time;
2008 U8 pop_fade_stop; // nonzero we end the sample when it fades out.
2009
2010 U8 state_level; // Level the sample was started at.
2011#ifdef IS_WIIU
2012 S8 route_to_drc;
2013#endif
2014
2015 F32 obstruction;
2016 F32 occlusion;
2017 F32 exclusion;
2018
2019 S32 service_type; // 1 if single-buffered; 2 if streamed
2020
2021 AILSAMPLECB SOB; // Start-of-block callback function
2022 AILSAMPLECB EOB; // End-of-buffer callback function
2023 AILSAMPLECB EOS; // End-of-sample callback function
2024
2025 SINTa user_data [8]; // Miscellaneous user data
2026 SINTa system_data[8]; // Miscellaneous system data
2027 SINTa hl_marker_list;
2028
2029 ADPCMDATA adpcm;
2030
2031 S32 doeob; // Flags to trigger callbacks
2032 S32 dosob;
2033 S32 doeos;
2034
2035 S32 vol_ramps;
2036 S32 resamp_tolerance;
2037 S32 enable_resamp_filter;
2038
2039 //
2040 // Sample pipeline stages
2041 //
2042
2043 SPINFO pipeline[N_SAMPLE_STAGES];
2044 S32 n_active_filters; // # of SP_FILTER_n stages active
2045
2046 //
2047 // 3D-related state for all platforms (including Xbox)
2048 //
2049
2050 S32 is_3D; // TRUE if channel levels are derived automatically from 3D positional state, FALSE if they're controlled manually
2051
2052 S3DSTATE S3D; // Software version applies 3D positioning only if is_3D == TRUE, but output filters always use it
2053
2054#ifdef MSS_VFLT_SUPPORTED
2055 void *voice; // Optional object used by output filter to store per-sample information such as DS3D buffers
2056#endif
2057
2058 F32 leftb_volume; // Left/mono volume 0 to 1.0 (back)
2059 F32 rightb_volume; // Right volume 0 to 1.0 (back)
2060 F32 center_volume; // Center volume 0 to 1.0
2061 F32 low_volume; // Low volume 0 to 1.0
2062 F32 save_fb_pan; // Sample volume 0-1.0
2063 F32 save_center; // saved center level
2064 F32 save_low; // saved sub level
2065
2066#if defined(HOST_SPU_PROCESS) || defined(MSS_SPU_PROCESS)
2067 S32 spu_on;
2068 U32 align[1];
2069#endif
2070
2071#if defined(IS_WINDOWS)
2072
2073 //
2074 // DirectSound-specific data
2075 //
2076
2077 S32 service_interval; // Service sample every n ms
2078 S32 service_tick; // Current service countdown value
2079 S32 buffer_segment_size; // Buffer segment size to fill
2080
2081 S32 prev_segment; // Previous segment # (0...n)
2082 S32 prev_cursor; // Previous play cursor location
2083
2084 S32 bytes_remaining; // # of bytes left to play (if not -1)
2085
2086 S32 direct_control; // 1 if app controls buffer, 0 if MSS
2087
2088#endif
2089} SAMPLE;
2090
2091#ifdef MILES_CHECK_OFFSETS
2092 RR_COMPILER_ASSERT((RR_MEMBER_OFFSET(SAMPLE, save_low) & 3) == 0);
2093#endif
2094
2095//
2096// used for AIL_process
2097//
2098
2099typedef struct _AILMIXINFO {
2100 AILSOUNDINFO Info;
2101 ADPCMDATA mss_adpcm;
2102 U32 src_fract;
2103 S32 left_val;
2104 S32 right_val;
2105} AILMIXINFO;
2106
2107
2108
2109DXDEC U32 AILCALL AIL_get_timer_highest_delay (void);
2110
2111DXDEC void AILCALL AIL_serve(void);
2112
2113#ifdef IS_MAC
2114
2115 typedef void * LPSTR;
2116
2117 #define WHDR_DONE 0
2118
2119 typedef struct _WAVEIN
2120 {
2121 long temp;
2122 } * HWAVEIN;
2123
2124 typedef struct _WAVEHDR
2125 {
2126 S32 dwFlags;
2127 S32 dwBytesRecorded;
2128 S32 dwUser;
2129 S32 temp;
2130 void * lpData;
2131 S32 dwBufferLength;
2132 S32 longdwLoops;
2133 S32 dwLoops;
2134 void * lpNext;
2135 U32 * reserved;
2136
2137 } WAVEHDR, * LPWAVEHDR;
2138
2139#endif
2140
2141#define N_WAVEIN_BUFFERS 8 // Use a ring of 8 buffers by default
2142
2143typedef struct _DIG_INPUT_DRIVER *HDIGINPUT; // Handle to digital input driver
2144
2145#ifdef IS_MAC
2146
2147 #define AIL_DIGITAL_INPUT_DEFAULT 0
2148
2149 typedef struct _DIG_INPUT_DRIVER // Handle to digital input driver
2150 {
2151 U32 tag; // HDIN
2152 S32 input_enabled; // 1 if enabled, 0 if not
2153 U32 incoming_buffer_size;
2154 void * incoming_buffer[ 2 ];
2155 void* outgoing_buffer;
2156 U32 which_buffer;
2157 AIL_INPUT_INFO info; // Input device descriptor
2158 AILMIXINFO incoming_info;
2159 long device;
2160#ifdef IS_MAC
2161 char InternalRecordingState[128]; // Hide this so we dont' have to #include OS stuff everywhere.
2162#endif
2163 } DIG_INPUT_DRIVER;
2164
2165#else
2166
2167#define AIL_DIGITAL_INPUT_DEFAULT ((U32)WAVE_MAPPER)
2168
2169typedef struct _DIG_INPUT_DRIVER // Handle to digital input driver
2170{
2171 U32 tag; // HDIN
2172
2173 HTIMER background_timer; // Background timer handle
2174
2175 AIL_INPUT_INFO info; // Input device descriptor
2176
2177 S32 input_enabled; // 1 if enabled, 0 if not
2178
2179 UINTa callback_user; // Callback user value
2180
2181 //
2182 // Provider-independent data
2183 //
2184
2185 U32 DMA_size; // Size of each DMA sub-buffer in bytes
2186 void *DMA[N_WAVEIN_BUFFERS]; // Simulated DMA buffers
2187
2188 U32 silence; // Silence value for current format (0 or 128)
2189
2190 S32 device_active; // 1 if buffers submittable, 0 if not
2191
2192#if defined(IS_WINDOWS) && !defined(__RADWINRTAPI__)
2193 //
2194 // waveOut-specific data
2195 //
2196
2197 HWAVEIN hWaveIn; // Handle to wave input device
2198 volatile MWAVEHDR wavehdr[N_WAVEIN_BUFFERS]; // Handles to wave headers
2199
2200#endif
2201} DIG_INPUT_DRIVER;
2202#endif
2203
2204
2205typedef struct REVERB_CONSTANT_INFO
2206{
2207 F32* start0,* start1,* start2,* start3,* start4,* start5;
2208 F32* end0,* end1,* end2,* end3,* end4,* end5;
2209 F32 C0, C1, C2, C3, C4, C5;
2210 F32 A;
2211 F32 B0, B1;
2212} REVERB_CONSTANT_INFO;
2213
2214typedef struct REVERB_UPDATED_INFO
2215{
2216 F32 * address0, * address1, * address2, * address3, * address4, * address5;
2217 F32 X0, X1, Y0, Y1;
2218} REVERB_UPDATED_INFO;
2219
2220typedef struct REVERB_INFO
2221{
2222 REVERB_UPDATED_INFO u;
2223 REVERB_CONSTANT_INFO c;
2224} REVERB_INFO;
2225
2226typedef struct REVERB_SETTINGS
2227{
2228 S32 room_type; // Changes to this drive master_wet and duration/damping/predelay!
2229 F32 master_wet; // Master reverb level 0-1.0
2230 F32 master_dry; // Master non-reverb level 0-1.0
2231
2232 REVERB_INFO ri;
2233
2234 S32 *reverb_build_buffer;
2235 S32 reverb_total_size;
2236 S32 reverb_fragment_size;
2237 S32 reverb_buffer_size;
2238 S32 reverb_on;
2239 U32 reverb_off_time_ms;
2240
2241 U32 reverb_duration_ms;
2242
2243 F32 reverb_decay_time_s;
2244 F32 reverb_predelay_s;
2245 F32 reverb_damping;
2246
2247 S32 reverb_head;
2248 S32 reverb_tail;
2249} REVERB_SETTINGS;
2250
2251
2252typedef struct _MSS_RECEIVER_LIST
2253{
2254 MSSVECTOR3D direction; // Normalized direction vector from listener
2255
2256 S32 speaker_index[MAX_SPEAKERS]; // List of speakers affected by sounds in this direction
2257 F32 speaker_level[MAX_SPEAKERS]; // Each speaker's degree of effect from this source
2258 S32 n_speakers_affected;
2259} MSS_RECEIVER_LIST;
2260
2261typedef struct _D3DSTATE
2262{
2263 S32 mute_at_max;
2264
2265 MSSVECTOR3D listen_position;
2266 MSSVECTOR3D listen_face;
2267 MSSVECTOR3D listen_up;
2268 MSSVECTOR3D listen_cross;
2269 MSSVECTOR3D listen_velocity;
2270
2271 F32 rolloff_factor;
2272 F32 doppler_factor;
2273 F32 distance_factor;
2274 F32 falloff_power;
2275
2276 //
2277 // Precalculated listener info
2278 //
2279
2280 S32 ambient_channels [MAX_SPEAKERS]; // E.g., LFE
2281 S32 n_ambient_channels;
2282
2283 S32 directional_channels[MAX_SPEAKERS+1]; // Channel index, or -1 if virtual
2284 MSSVECTOR3D listener_to_speaker [MAX_SPEAKERS+1];
2285 S32 n_directional_channels;
2286
2287 MSS_RECEIVER_LIST receiver_specifications[MAX_RECEIVER_SPECS]; // Constellation of receiver vectors
2288 S32 n_receiver_specs;
2289
2290 MSSVECTOR3D speaker_positions [MAX_SPEAKERS]; // Listener-relative speaker locations
2291
2292 F32 speaker_wet_reverb_response [MAX_SPEAKERS]; // Reverb sensitivity of each speaker
2293 F32 speaker_dry_reverb_response [MAX_SPEAKERS];
2294} D3DSTATE;
2295
2296typedef enum
2297{
2298 MSS_MC_INVALID = 0, // Used for configuration-function errors
2299 MSS_MC_MONO = 1, // For compatibility with S32 channel param
2300 MSS_MC_STEREO = 2,
2301 MSS_MC_USE_SYSTEM_CONFIG = 0x10, // Leave space between entries for new variations
2302 MSS_MC_HEADPHONES = 0x20, // with similar quality levels/speaker counts
2303 MSS_MC_DOLBY_SURROUND = 0x30,
2304 MSS_MC_SRS_CIRCLE_SURROUND = 0x40,
2305 MSS_MC_40_DTS = 0x48,
2306 MSS_MC_40_DISCRETE = 0x50,
2307 MSS_MC_51_DTS = 0x58,
2308 MSS_MC_51_DISCRETE = 0x60,
2309 MSS_MC_61_DISCRETE = 0x70,
2310 MSS_MC_71_DISCRETE = 0x80,
2311 MSS_MC_81_DISCRETE = 0x90,
2312 MSS_MC_DIRECTSOUND3D = 0xA0,
2313 MSS_MC_EAX2 = 0xC0,
2314 MSS_MC_EAX3 = 0xD0,
2315 MSS_MC_EAX4 = 0xE0,
2316 MSS_MC_FORCE_32 = 0x7fffffff
2317}
2318MSS_MC_SPEC;
2319
2320
2321typedef struct _DIG_DRIVER // Handle to digital audio driver
2322{
2323 U32 tag; // HDIG
2324
2325 HTIMER backgroundtimer; // Background timer handle
2326
2327 U32 num_mixes; // incrementing number of mixes
2328
2329 S32 mix_ms; // rough ms per mix
2330
2331
2332 F32 master_volume; // Master sample volume 0-1.0
2333
2334 S32 DMA_rate; // Hardware sample rate
2335 S32 hw_format; // DIG_F code in use
2336 S32 n_active_samples; // # of samples being processed
2337
2338 MSS_MC_SPEC channel_spec; // Original "channels" value passed to AIL_open_digital_driver()
2339
2340 D3DSTATE D3D; // 3D listener parms for all platforms
2341
2342
2343#if defined(IS_PSP2) || defined(IS_PSP) || defined(IS_XENON) || defined(IS_IPHONE) || defined(IS_MAC) || defined(IS_LINUX) || defined(IS_3DS) || defined(IS_WIIU) || defined(__RADWINRTAPI__) || defined(__RADSEKRIT2__) || defined(__RADANDROID__) // generic dig platforms
2344#define IS_GENERICDIG
2345 void* dig_ss; // Sound system ptr (embed in mss.h?)
2346 void* dig_heap; // Sound system heap.
2347#endif
2348
2349#ifdef IS_XENON
2350 void* x2_voiceptr; //! \todo get rid of this? Only expose dig_ss?
2351#endif
2352
2353 S32 quiet; // # of consecutive quiet sample periods
2354 S32 playing; // Playback active if non-zero
2355
2356 S32 bytes_per_channel; // # of bytes per channel (always 1 or 2 for 8- or 16-bit hardware output)
2357 S32 samples_per_buffer; // # of samples per build buffer / half-buffer
2358 S32 physical_channels_per_sample; // # of channels per *physical* sample (1 or 2, or more in discrete MC mode)
2359 S32 logical_channels_per_sample; // # of logical channels per sample (may differ from physical channel count in matrix formats)
2360
2361#ifdef IS_LINUX
2362 S32 released; // has the sound manager been released?
2363#endif
2364
2365 HSAMPLE samples; // Pointer to list of SAMPLEs
2366
2367 U32 *sample_status; // SMP_ flags: _FREE, _DONE, _PLAYING, moved out of SAMPLEs for faster iteration
2368 S32 n_samples; // # of SAMPLEs
2369
2370 SINTa system_data[8]; // Miscellaneous system data
2371
2372 HSAMPLE bus_samples[MAX_BUSSES]; // Sample handles the bus will route through.
2373 S32 bus_active_count[MAX_BUSSES]; // Number of samples mixed on the bus last mix.
2374 void* bus_ptrs[MAX_BUSSES]; // Buffers for each bus to mix in to.
2375
2376 void* pushed_states[MILES_MAX_STATES];
2377 U8 state_index;
2378
2379 //
2380 // Build buffers
2381 //
2382 // In multichannel mode, source samples may be mixed into more than one
2383 // build buffer
2384 //
2385
2386 MSS_BB build[MAX_SPEAKERS+EXTRA_BUILD_BUFFERS];
2387 S32 n_build_buffers; // # of build buffers actually used for output processing
2388
2389 S32 hardware_buffer_size; // Size of each output buffer
2390
2391 S32 enable_limiter;
2392 S32 limiter_atten; // attenuation level from last hw copy.
2393
2394 S32 scheduled_sample_count; // # of samples that are waiting to be started at an exact time.
2395
2396 AILMIXERCB mixcb; // callback for each mix.
2397
2398#if defined(IS_WINDOWS) && !defined(__RADWINRTAPI__)
2399
2400 //
2401 // waveOut-specific interface data
2402 //
2403
2404 HWAVEOUT hWaveOut; // Wave output driver
2405
2406 U32 reset_works; // TRUE if OK to do waveOutReset
2407 U32 request_reset; // If nonzero, do waveOutReset ASAP
2408
2409 LPWAVEHDR first; // Pointer to first WAVEHDR in chain
2410 S32 n_buffers; // # of output WAVEHDRs in chain
2411
2412 LPWAVEHDR volatile *return_list; // Circular list of returned WAVEHDRs
2413 S32 volatile return_head; // Head of WAVEHDR list (insertion point)
2414 S32 volatile return_tail; // Tail of WAVEHDR list (retrieval point)
2415
2416 //
2417 // DirectSound-specific interface data
2418 //
2419
2420 UINTa guid; // The guid id of the ds driver
2421 AILLPDIRECTSOUND pDS; // DirectSound output driver (don't
2422 // use with Smacker directly anymore!)
2423
2424 U32 ds_priority; // priority opened with
2425
2426 S32 emulated_ds; // is ds emulated or not?
2427 AILLPDIRECTSOUNDBUFFER lppdsb; // primary buffer or null
2428
2429 UINTa dsHwnd; // HWND used with DirectSound
2430
2431 AILLPDIRECTSOUNDBUFFER * lpbufflist; // List of pointers to secondary buffers
2432 HSAMPLE *samp_list; // HSAMPLE associated with each buffer
2433 S32 *sec_format; // DIG_F_ format for secondary buffer
2434 S32 max_buffs; // Max. allowable # of secondary buffers
2435
2436 //
2437 // Driver output configuration
2438 //
2439 // Note: # of "logical" (source) channels per sample = dig->channels_per_sample
2440 // # of "physical" (DAC) channels per sample = dig->wformat.wf.nChannels
2441 //
2442 // These may be different if a matrix format (e.g., Dolby/SRS)
2443 // is in use!
2444 //
2445
2446 MPCMWAVEFORMAT wformat; // format from waveout open
2447 C8 wfextra[32]; // Extension to PCMWAVEFORMAT (e.g., WAVE_FORMAT_EXTENSIBLE)
2448
2449 //
2450 // Misc. data
2451 //
2452
2453 S32 released; // has the sound manager been released?
2454
2455 HDIGDRIVER next; // Pointer to next HDIGDRIVER in use
2456
2457 //
2458 // Vars for waveOut emulation
2459 //
2460
2461 S32 DS_initialized;
2462
2463 AILLPDIRECTSOUNDBUFFER DS_sec_buff; // Secondary buffer (or NULL if none)
2464 AILLPDIRECTSOUNDBUFFER DS_out_buff; // Output buffer (may be sec or prim)
2465 S32 DS_buffer_size; // Size of entire output buffer
2466
2467 S32 DS_frag_cnt; // Total fragment count and size, and
2468 S32 DS_frag_size; // last fragment occupied by play cursor
2469 S32 DS_last_frag;
2470 S32 DS_last_write;
2471 S32 DS_last_timer;
2472 S32 DS_skip_time;
2473
2474 S32 DS_use_default_format; // 1 to force use of default DS primary buffer format
2475
2476 U32 position_error; // last status from position report (can be used
2477 // to watch for headset removal)
2478 U32 last_ds_play;
2479 U32 last_ds_write;
2480 U32 last_ds_move;
2481
2482#endif
2483
2484#ifdef IS_X86
2485 S32 use_MMX; // Use MMX with this driver if TRUE
2486#endif
2487
2488 U64 mix_total;
2489 U64 last_polled;
2490 U32 last_percent;
2491
2492 void * MC_buffer;
2493 //
2494 // Digital driver pipeline filter stages
2495 //
2496
2497 DPINFO pipeline[N_DIGDRV_STAGES];
2498
2499#ifdef MSS_VFLT_SUPPORTED
2500 struct _FLTPROVIDER *voice_filter;
2501 SS_STREAM_CB stream_callback;
2502#endif
2503
2504 struct _FLTPROVIDER *matrix_filter;
2505
2506 //
2507 // Reverb
2508 // If no busses are active, 0 is still used as the base reverb.
2509 //
2510 REVERB_SETTINGS reverb[MAX_BUSSES];
2511
2512#ifdef IS_PS3
2513 HDIGDRIVER next; // Pointer to next HDIGDRIVER in use
2514
2515 void * hw_buf;
2516 U32 hw_datarate;
2517 U32 hw_align;
2518 U32 port;
2519 S32 hw_buffer_size;
2520 S32 snd_frag_cnt;
2521 S32 snd_frag_size;
2522 S32 snd_last_frag;
2523 S32 snd_last_write;
2524 S32 snd_skip_time;
2525 U32 snd_last_play;
2526 U32 snd_last_move;
2527 S32 snd_last_timer;
2528#endif
2529
2530#ifdef IS_GENERICDIG
2531 HDIGDRIVER next;
2532#endif
2533
2534#if defined(IS_WINDOWS)
2535 S32 no_wom_done; // don't process WOM_DONEs on this driver
2536 U32 wom_done_buffers;
2537#endif
2538
2539#if defined(HOST_SPU_PROCESS) || defined(MSS_SPU_PROCESS)
2540 U32 spu_num;
2541 S32 spu_on;
2542 U64 spu_total;
2543 U64 spu_last_polled;
2544 U32 spu_last_percent;
2545 #ifdef IS_PS3
2546 U32 align[ 2 ];
2547 #else
2548 U32 align[ 1 ];
2549 #endif
2550#endif
2551
2552 U64 adpcm_time;
2553 U64 deinterlace_time;
2554 U64 mix_time;
2555 U64 rev_time;
2556 U64 reformat_time;
2557 U64 lowpass_time;
2558 U64 filter_time;
2559 U64 copy_time;
2560 U64 sob_time;
2561 U64 eob_time;
2562 U64 eos_time;
2563 U64 spu_wait_time;
2564 U64 asi_times[4];
2565
2566 HSAMPLE adpcm_sam;
2567 HSAMPLE deinterlace_sam;
2568 HSAMPLE mix_sam;
2569 HSAMPLE rev_sam;
2570 HSAMPLE reformat_sam;
2571 HSAMPLE lowpass_sam;
2572 HSAMPLE filter_sam;
2573 HSAMPLE asi_sams[4];
2574
2575 U32 adpcm_num;
2576 U32 deinterlace_num;
2577 U32 mix_num;
2578 U32 rev_num;
2579 U32 reformat_num;
2580 U32 lowpass_num;
2581 U32 filter_num;
2582 U32 asi_nums[4];
2583
2584
2585 // these clauses have to be at the end of the structure!!
2586#ifdef IS_WII
2587 HDIGDRIVER next; // Pointer to next HDIGDRIVER in use
2588
2589 U32 hw_datarate;
2590 S32 hw_buffer_size;
2591 S32 each_buffer_size;
2592 S32 snd_frag_cnt;
2593 S32 snd_frag_size;
2594 S32 snd_last_frag;
2595 S32 snd_last_write;
2596 S32 snd_skip_time;
2597 U32 snd_last_play;
2598 U32 snd_last_move;
2599 S32 snd_last_timer;
2600
2601 void * buffer[ 2 ];
2602 U32 physical[ 2 ];
2603
2604 #ifdef AX_OUTPUT_BUFFER_DOUBLE
2605 AXVPB* voice[ 2 ];
2606 #endif
2607
2608#endif
2609
2610#ifdef XAUDIOFRAMESIZE_NATIVE
2611 XAUDIOPACKET packet;
2612#endif
2613
2614} DIG_DRIVER;
2615
2616#ifdef MILES_CHECK_OFFSETS
2617 RR_COMPILER_ASSERT((RR_MEMBER_OFFSET(DIG_DRIVER, filter_num) & 3) == 0);
2618#endif
2619
2620typedef struct // MIDI status log structure
2621 {
2622 S32 program [NUM_CHANS]; // Program Change
2623 S32 pitch_l [NUM_CHANS]; // Pitch Bend LSB
2624 S32 pitch_h [NUM_CHANS]; // Pitch Bend MSB
2625
2626 S32 c_lock [NUM_CHANS]; // Channel Lock
2627 S32 c_prot [NUM_CHANS]; // Channel Lock Protection
2628 S32 c_mute [NUM_CHANS]; // Channel Mute
2629 S32 c_v_prot [NUM_CHANS]; // Voice Protection
2630 S32 bank [NUM_CHANS]; // Patch Bank Select
2631 S32 gm_bank_l [NUM_CHANS]; // GM Bank Select
2632 S32 gm_bank_m [NUM_CHANS]; // GM Bank Select
2633 S32 indirect [NUM_CHANS]; // ICA indirect controller value
2634 S32 callback [NUM_CHANS]; // Callback Trigger
2635
2636 S32 mod [NUM_CHANS]; // Modulation
2637 S32 vol [NUM_CHANS]; // Volume
2638 S32 pan [NUM_CHANS]; // Panpot
2639 S32 exp [NUM_CHANS]; // Expression
2640 S32 sus [NUM_CHANS]; // Sustain
2641 S32 reverb [NUM_CHANS]; // Reverb
2642 S32 chorus [NUM_CHANS]; // Chorus
2643
2644 S32 bend_range[NUM_CHANS]; // Bender Range (data MSB, RPN 0 assumed)
2645
2646 S32 RPN_L [NUM_CHANS]; // RPN # LSB
2647 S32 RPN_M [NUM_CHANS]; // RPN # MSB
2648 }
2649CTRL_LOG;
2650
2651typedef struct _SEQUENCE // XMIDI sequence state table
2652{
2653 char tag[4]; // HSEQ
2654
2655 HMDIDRIVER driver; // Driver for playback
2656
2657 U32 status; // SEQ_ flagsstruct
2658
2659 void const *TIMB; // XMIDI IFF chunk pointers
2660 void const *RBRN;
2661 void const *EVNT;
2662
2663 U8 const *EVNT_ptr; // Current event pointer
2664
2665 U8 *ICA; // Indirect Controller Array
2666
2667 AILPREFIXCB prefix_callback; // XMIDI Callback Prefix handler
2668 AILTRIGGERCB trigger_callback; // XMIDI Callback Trigger handler
2669 AILBEATCB beat_callback; // XMIDI beat/bar change handler
2670 AILSEQUENCECB EOS; // End-of-sequence callback function
2671
2672 S32 loop_count; // 0=one-shot, -1=indefinite, ...
2673
2674 S32 interval_count; // # of intervals until next event
2675 S32 interval_num; // # of intervals since start
2676
2677 S32 volume; // Sequence volume 0-127
2678 S32 volume_target; // Target sequence volume 0-127
2679 S32 volume_accum; // Accumulated volume period
2680 S32 volume_period; // Period for volume stepping
2681
2682 S32 tempo_percent; // Relative tempo percentage 0-100
2683 S32 tempo_target; // Target tempo 0-100
2684 S32 tempo_accum; // Accumulated tempo period
2685 S32 tempo_period; // Period for tempo stepping
2686 S32 tempo_error; // Error counter for tempo DDA
2687
2688 S32 beat_count; // Sequence playback position
2689 S32 measure_count;
2690
2691 S32 time_numerator; // Sequence timing data
2692 S32 time_fraction;
2693 S32 beat_fraction;
2694 S32 time_per_beat;
2695
2696 U8 const *FOR_ptrs[FOR_NEST]; // Loop stack
2697 S32 FOR_loop_count [FOR_NEST];
2698
2699 S32 chan_map [NUM_CHANS]; // Physical channel map for sequence
2700
2701 CTRL_LOG shadow; // Controller values for sequence
2702
2703 S32 note_count; // # of notes "on"
2704
2705 S32 note_chan [MAX_NOTES]; // Channel for queued note (-1=free)
2706 S32 note_num [MAX_NOTES]; // Note # for queued note
2707 S32 note_time [MAX_NOTES]; // Remaining duration in intervals
2708
2709 SINTa user_data [8]; // Miscellaneous user data
2710 SINTa system_data[8]; // Miscellaneous system data
2711
2712} SEQUENCE;
2713
2714#if defined(IS_MAC) || defined(IS_LINUX) || defined(IS_XENON) || defined(IS_PS3) || defined(IS_WII) || defined(IS_PSP) || defined(IS_PSP2) || defined(__RADWINRTAPI__) || defined(__RADSEKRIT2__) || defined(__RADANDROID__)
2715
2716struct MIDIHDR;
2717struct MIDIOUT;
2718typedef struct MIDIOUT* HMIDIOUT;
2719typedef HMIDIOUT* LPHMIDIOUT;
2720
2721#endif
2722
2723typedef struct _MDI_DRIVER // Handle to XMIDI driver
2724{
2725 char tag[4]; // HMDI
2726
2727 HTIMER timer; // XMIDI quantization timer
2728 S32 interval_time; // XMIDI quantization timer interval in uS
2729
2730 HSEQUENCE sequences; // Pointer to list of SEQUENCEs
2731 S32 n_sequences; // # of SEQUENCEs
2732
2733 S32 lock [NUM_CHANS]; // 1 if locked, 2 if protected, else 0
2734 HSEQUENCE locker[NUM_CHANS]; // HSEQUENCE which locked channel
2735 HSEQUENCE owner [NUM_CHANS]; // HSEQUENCE which owned locked channel
2736 HSEQUENCE user [NUM_CHANS]; // Last sequence to use channel
2737 S32 state [NUM_CHANS]; // Lock state prior to being locked
2738
2739 S32 notes [NUM_CHANS]; // # of active notes in channel
2740
2741 AILEVENTCB event_trap; // MIDI event trap callback function
2742 AILTIMBRECB timbre_trap; // Timbre request callback function
2743
2744 S32 master_volume; // Master XMIDI note volume 0-127
2745
2746 SINTa system_data[8]; // Miscellaneous system data
2747
2748#if (defined(IS_WINDOWS) && !defined(__RADWINRTAPI__)) || defined(IS_MAC) || defined(IS_LINUX)
2749
2750 S32 released; // has the hmidiout handle been released
2751 U32 deviceid; // ID of the MIDI device
2752 U8 *sysdata; // SysEx buffer
2753
2754#endif
2755
2756#if defined(IS_XENON) || defined(IS_WII) || defined(IS_PS3) || defined(IS_PSP) || defined(IS_3DS) || defined(IS_IPHONE) || defined(IS_PSP2) || defined(IS_WIIU) || defined(__RADWINRTAPI__) || defined(__RADSEKRIT2__) || defined(__RADANDROID__)
2757 HMDIDRIVER next; // Pointer to next HMDIDRIVER in use
2758#endif
2759
2760#ifdef IS_LINUX
2761 struct MIDIHDR *mhdr; // SysEx header
2762 HMDIDRIVER next; // Pointer to next HMDIDRIVER in use
2763 HMIDIOUT hMidiOut; // MIDI output driver
2764#endif
2765
2766#if defined(IS_WINDOWS) && !defined(__RADWINRTAPI__)
2767
2768 struct midihdr_tag *mhdr; // SysEx header
2769
2770 HMDIDRIVER next; // Pointer to next HMDIDRIVER in use
2771
2772 HMIDIOUT hMidiOut; // MIDI output driver
2773
2774#else
2775
2776 #if defined(IS_MAC)
2777 struct MIDIHDR *mhdr; // SysEx header
2778 HMDIDRIVER next; // Pointer to next HMDIDRIVER in use
2779 HMIDIOUT hMidiOut; // MIDI output driver
2780 #endif
2781
2782#endif
2783
2784} MDI_DRIVER;
2785
2786#if defined(IS_WIN32API) || defined(IS_WII)
2787 #pragma pack(push, 1)
2788#endif
2789
2790typedef MSS_STRUCT // XMIDI TIMB IFF chunk
2791 {
2792 S8 name[4];
2793
2794 U8 msb;
2795 U8 lsb;
2796 U8 lsb2;
2797 U8 lsb3;
2798
2799 U16 n_entries;
2800
2801 U16 timbre[1];
2802 }
2803TIMB_chunk;
2804
2805typedef MSS_STRUCT // XMIDI RBRN IFF entry
2806 {
2807 S16 bnum;
2808 U32 offset;
2809 }
2810RBRN_entry;
2811
2812#if defined(IS_WIN32API) || defined(IS_WII)
2813 #pragma pack(pop)
2814#endif
2815
2816typedef struct // Wave library entry
2817{
2818 S32 bank; // XMIDI bank, MIDI patch for sample
2819 S32 patch;
2820
2821 S32 root_key; // Root MIDI note # for sample (or -1)
2822
2823 U32 file_offset; // Offset of wave data from start-of-file
2824 U32 size; // Size of wave sample in bytes
2825
2826 S32 format; // DIG_F format (8/16 bits, mono/stereo)
2827 S32 playback_rate; // Playback rate in hertz
2828}
2829WAVE_ENTRY;
2830
2831typedef struct // Virtual "wave synthesizer" descriptor
2832{
2833 HMDIDRIVER mdi; // MIDI driver for use with synthesizer
2834 HDIGDRIVER dig; // Digital driver for use with synthesizer
2835
2836 WAVE_ENTRY *library; // Pointer to wave library
2837
2838 AILEVENTCB prev_event_fn; // Previous MIDI event trap function
2839 AILTIMBRECB prev_timb_fn; // Previous timbre request trap function
2840
2841 CTRL_LOG controls; // MIDI controller states
2842
2843 WAVE_ENTRY *wave [NUM_CHANS];// Pointer to WAVE_ENTRY for each channel
2844
2845 HSAMPLE S [MAX_W_VOICES]; // List of HSAMPLE voices
2846 S32 n_voices; // Actual # of voices allocated to synth
2847
2848 S32 chan [MAX_W_VOICES]; // MIDI channel for each voice, or -1
2849 S32 note [MAX_W_VOICES]; // MIDI note number for voice
2850 S32 root [MAX_W_VOICES]; // MIDI root note for voice
2851 S32 rate [MAX_W_VOICES]; // Playback rate for voice
2852 S32 vel [MAX_W_VOICES]; // MIDI note velocity for voice
2853 U32 time [MAX_W_VOICES]; // Timestamp for voice
2854
2855 U32 event; // Event counter for LRU timestamps
2856}
2857WAVE_SYNTH;
2858
2859typedef WAVE_SYNTH * HWAVESYNTH;// Handle to virtual wave synthesizer
2860
2861
2862//
2863// DIG_DRIVER list
2864//
2865
2866extern HDIGDRIVER DIG_first;
2867
2868//
2869// MDI_DRIVER list
2870//
2871
2872extern HMDIDRIVER MDI_first;
2873
2874//
2875// Miscellaneous system services
2876//
2877
2878#define FILE_READ_WITH_SIZE ((void*)(SINTa)-1)
2879
2880
2881typedef void * (AILCALLBACK *AILMEMALLOCCB)(UINTa size);
2882typedef void (AILCALLBACK *AILMEMFREECB)(void *);
2883
2884#define AIL_mem_alloc_lock_trk(size) AIL_mem_alloc_lock_info( size, __FILE__, __LINE__ )
2885#define AIL_file_read_trk(file,dest) AIL_file_read_info( file, dest, __FILE__, __LINE__ )
2886#define AIL_file_size_trk(file) AIL_file_size_info( file, __FILE__, __LINE__ )
2887
2888//#define MSS_NONTRACKED
2889#ifdef MSS_NONTRACKED
2890 DXDEC void * AILCALL AIL_mem_alloc_lock(UINTa size);
2891 DXDEC void * AILCALL AIL_file_read(char const * filename, void * dest );
2892 DXDEC S32 AILCALL AIL_file_size(char const * filename );
2893#else
2894 #define AIL_mem_alloc_lock(size) AIL_mem_alloc_lock_trk(size)
2895 #define AIL_file_read(file,dest) AIL_file_read_trk(file,dest)
2896 #define AIL_file_size(file) AIL_file_size_trk(file)
2897#endif
2898
2899DXDEC void * AILCALL AIL_mem_alloc_lock_info(UINTa size, char const * file, U32 line);
2900DXDEC void AILCALL AIL_mem_free_lock (void *ptr);
2901
2902
2903DXDEC S32 AILCALL AIL_file_error (void);
2904
2905DXDEC S32 AILCALL AIL_file_size_info(char const *filename,
2906 char const * caller,
2907 U32 line);
2908
2909DXDEC void * AILCALL AIL_file_read_info(char const *filename,
2910 void *dest,
2911 char const * caller,
2912 U32 line);
2913
2914DXDEC S32 AILCALL AIL_file_write (char const *filename,
2915 void const *buf,
2916 U32 len);
2917
2918DXDEC S32 AILCALL AIL_WAV_file_write
2919 (char const *filename,
2920 void const *buf,
2921 U32 len,
2922 S32 rate,
2923 S32 format);
2924
2925DXDEC S32 AILCALL AIL_file_append (char const *filename,
2926 void const *buf, U32 len);
2927
2928DXDEC AILMEMALLOCCB AILCALL AIL_mem_use_malloc(AILMEMALLOCCB fn);
2929DXDEC AILMEMFREECB AILCALL AIL_mem_use_free (AILMEMFREECB fn);
2930
2931
2932#define MSSBreakPoint RR_BREAK
2933
2934
2935//
2936// Compiler-independent CRTL helper functions for PS2
2937// Exported here for use in demo programs as well as MSS itself
2938//
2939
2940#if defined(IS_PSP)
2941
2942 DXDEC F32 AILCALL AIL_sin(F32 x);
2943 DXDEC F32 AILCALL AIL_cos(F32 x);
2944 DXDEC F32 AILCALL AIL_tan( F32 x );
2945 DXDEC F32 AILCALL AIL_acos(F32 x);
2946 DXDEC F32 AILCALL AIL_atan(F32 x);
2947 DXDEC F32 AILCALL AIL_ceil( F32 x );
2948 DXDEC F32 AILCALL AIL_floor( F32 x );
2949 DXDEC F32 AILCALL AIL_fsqrt( F32 x );
2950 DXDEC F32 AILCALL AIL_fabs ( F32 x );
2951 DXDEC F32 AILCALL AIL_log10( F32 x );
2952 DXDEC F32 AILCALL AIL_log( F32 x );
2953 DXDEC F32 AILCALL AIL_pow( F32 x, F32 p );
2954 DXDEC F32 AILCALL AIL_frexpf( F32 x, S32 *pw2 );
2955 DXDEC F32 AILCALL AIL_ldexpf( F32 x, S32 pw2 );
2956 #define AIL_exp(x) AIL_pow(2.718281828F,(x))
2957
2958#else
2959
2960 #ifdef IS_WATCOM
2961 #define AIL_pow powf
2962 #define AIL_tan tanf
2963 #else
2964 #define AIL_tan tan
2965 #define AIL_pow pow
2966 #endif
2967
2968 #define AIL_sin sin
2969 #define AIL_cos cos
2970 #define AIL_acos acos
2971 #define AIL_atan atan
2972 #define AIL_ceil ceil
2973 #define AIL_floor floor
2974
2975 #if defined(IS_PS3) && !defined(IS_SPU)
2976 DXDEC F32 AILCALL AIL_fsqrt( F32 val );
2977 #else
2978 #define AIL_fsqrt(arg) ((F32) sqrt(arg))
2979 #endif
2980
2981 #define AIL_fabs fabs
2982 #define AIL_log10 log10
2983 #define AIL_log log
2984 #define AIL_frexpf(a1,a2) ((F32) frexp(a1,a2))
2985 #define AIL_ldexpf(a1,a2) ((F32) ldexp(a1,a2))
2986 #define AIL_exp exp
2987
2988#endif
2989
2990//
2991// High-level support services
2992//
2993
2994DXDEC S32 AILCALL AIL_startup (void);
2995
2996DXDEC SINTa AILCALL AIL_get_preference (U32 number);
2997
2998DXDEC void AILCALL AIL_shutdown (void);
2999
3000DXDEC SINTa AILCALL AIL_set_preference (U32 number,
3001 SINTa value);
3002
3003DXDEC char *AILCALL AIL_last_error (void);
3004
3005DXDEC void AILCALL AIL_set_error (char const * error_msg);
3006
3007#ifdef IS_WIIU
3008DXDEC void AILCALL AIL_set_wiiu_file_client (void* ptr_to_fsclient, void* ptr_to_fscmdblock);
3009#endif
3010
3011#ifdef __RADIPHONE__
3012//
3013// On iOS, audio session interruptions stop the audio queues, and we have to manually restart them.
3014//
3015// This should be called whenever you get an Interruption Ended msg via your Audio Session callback.
3016//
3017DXDEC void AILCALL AIL_ios_post_audio_session_interrupt_end(HDIGDRIVER dig);
3018#endif
3019
3020//
3021// Low-level support services
3022//
3023
3024#ifdef IS_X86
3025
3026DXDEC U32 AILCALL AIL_MMX_available (void);
3027
3028#endif
3029
3030#define AIL_lock AIL_lock_mutex
3031#define AIL_unlock AIL_unlock_mutex
3032
3033DXDEC void AILCALL AIL_lock_mutex (void);
3034DXDEC void AILCALL AIL_unlock_mutex (void);
3035
3036#define AIL_delay AIL_sleep
3037DXDEC void AILCALL AIL_sleep (U32 ms);
3038
3039DXDEC AILTRACECB AILCALL AIL_configure_logging (char const * filename,
3040 AILTRACECB cb,
3041 S32 level);
3042
3043
3044//
3045// Process services
3046//
3047
3048DXDEC HTIMER AILCALL AIL_register_timer (AILTIMERCB fn);
3049
3050DXDEC UINTa AILCALL AIL_set_timer_user (HTIMER timer,
3051 UINTa user);
3052
3053DXDEC void AILCALL AIL_set_timer_period (HTIMER timer,
3054 U32 microseconds);
3055
3056DXDEC void AILCALL AIL_set_timer_frequency (HTIMER timer,
3057 U32 hertz);
3058
3059DXDEC void AILCALL AIL_set_timer_divisor (HTIMER timer,
3060 U32 PIT_divisor);
3061
3062DXDEC void AILCALL AIL_start_timer (HTIMER timer);
3063DXDEC void AILCALL AIL_start_all_timers (void);
3064
3065DXDEC void AILCALL AIL_stop_timer (HTIMER timer);
3066DXDEC void AILCALL AIL_stop_all_timers (void);
3067
3068DXDEC void AILCALL AIL_release_timer_handle (HTIMER timer);
3069DXDEC void AILCALL AIL_release_all_timers (void);
3070
3071DXDEC S32 AILCALL AIL_timer_thread_handle(void* o_handle);
3072
3073#ifdef IS_MAC
3074 #if defined(__PROCESSES__)
3075 DXDEC ProcessSerialNumber AIL_Process(void);
3076 #endif
3077#endif
3078
3079//
3080// high-level digital services
3081//
3082
3083#define AIL_OPEN_DIGITAL_FORCE_PREFERENCE 1
3084#define AIL_OPEN_DIGITAL_NEED_HW_3D 2
3085#define AIL_OPEN_DIGITAL_NEED_FULL_3D 4
3086#define AIL_OPEN_DIGITAL_NEED_LIGHT_3D 8
3087#define AIL_OPEN_DIGITAL_NEED_HW_REVERB 16
3088#define AIL_OPEN_DIGITAL_NEED_REVERB 32
3089#define AIL_OPEN_DIGITAL_USE_IOP_CORE0 64
3090
3091#define AIL_OPEN_DIGITAL_USE_SPU0 (1<<24)
3092#define AIL_OPEN_DIGITAL_USE_SPU1 (2<<24)
3093#define AIL_OPEN_DIGITAL_USE_SPU2 (3<<24)
3094#define AIL_OPEN_DIGITAL_USE_SPU3 (4<<24)
3095#define AIL_OPEN_DIGITAL_USE_SPU4 (5<<24)
3096#define AIL_OPEN_DIGITAL_USE_SPU5 (6<<24)
3097#define AIL_OPEN_DIGITAL_USE_SPU6 (7<<24)
3098
3099#define AIL_OPEN_DIGITAL_USE_SPU( num ) ( ( num + 1 ) << 24 )
3100
3101#ifdef IS_GENERICDIG
3102
3103 struct _RadSoundSystem;
3104 typedef S32 (*RADSS_OPEN_FUNC)(struct _RadSoundSystem* i_SoundSystem, U32 i_MinBufferSizeInMs, U32 i_Frequency, U32 i_ChannelCount, U32 i_MaxLockSize, U32 i_Flags);
3105
3106 DXDEC HDIGDRIVER AILCALL AIL_open_generic_digital_driver(U32 frequency, S32 bits, S32 channel, U32 flags, RADSS_OPEN_FUNC dig_open);
3107
3108 #ifdef IS_WIN32
3109 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_DSInstallDriver(UINTa, UINTa);
3110 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_WOInstallDriver(UINTa, UINTa);
3111
3112 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3113 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_DSInstallDriver(0, 0))
3114
3115 #elif defined(IS_3DS)
3116 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_3DSInstallDriver(UINTa, UINTa);
3117
3118 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3119 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_3DSInstallDriver(0, 0))
3120
3121 #elif defined(__RADANDROID__)
3122
3123 DXDEC void AILCALL AIL_set_asset_manager(void* asset_manager);
3124
3125 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_SLESInstallDriver(UINTa, UINTa);
3126
3127 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3128 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_SLESInstallDriver(0, 0))
3129
3130
3131 #elif defined(IS_PSP2)
3132 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_PSP2InstallDriver(UINTa, UINTa);
3133
3134 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3135 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_PSP2InstallDriver(0, 0))
3136
3137 #elif defined(__RADSEKRIT2__)
3138 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_SonyInstallDriver(UINTa, UINTa);
3139
3140 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3141 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_SonyInstallDriver(0, 0))
3142
3143 #elif defined(IS_PSP)
3144 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_PSPInstallDriver(UINTa, UINTa);
3145
3146 #define AIL_OPEN_DIGITAL_USE_SIMPLEAUDIO ~0U
3147
3148 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3149 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_PSPInstallDriver(0, 0))
3150
3151 #elif defined(IS_XENON) || defined(__RADWINRTAPI__)
3152 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_XAudio2InstallDriver(UINTa, UINTa);
3153
3154 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3155 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_XAudio2InstallDriver(0, 0))
3156
3157 #elif defined(IS_WIIU)
3158 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_AXInstallDriver(UINTa, UINTa);
3159
3160 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3161 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_AXInstallDriver(0, 0))
3162
3163 #elif defined(IS_MAC) || defined(IS_IPHONE)
3164 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_OalInstallDriver(UINTa, UINTa);
3165 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_CAInstallDriver(UINTa, UINTa);
3166
3167 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3168 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_CAInstallDriver(0, 0))
3169
3170 #elif defined(IS_LINUX)
3171 DXDEC RADSS_OPEN_FUNC AILCALL RADSS_OalInstallDriver(UINTa, UINTa);
3172
3173 #define AIL_open_digital_driver(frequency, bits, channel, flags) \
3174 AIL_open_generic_digital_driver(frequency, bits, channel, flags, RADSS_OalInstallDriver(0, 0))
3175 #endif
3176#else // IS_GENERICDIG
3177
3178DXDEC HDIGDRIVER AILCALL AIL_open_digital_driver( U32 frequency,
3179 S32 bits,
3180 S32 channel,
3181 U32 flags );
3182
3183#endif // not IS_GENERICDIG
3184
3185DXDEC void AILCALL AIL_close_digital_driver( HDIGDRIVER dig );
3186
3187#ifdef IS_LINUX
3188
3189#define AIL_MSS_version(str,len) \
3190{ \
3191 strncpy(str, MSS_VERSION, len); \
3192}
3193
3194DXDEC S32 AILCALL AIL_digital_handle_release(HDIGDRIVER drvr);
3195
3196DXDEC S32 AILCALL AIL_digital_handle_reacquire
3197 (HDIGDRIVER drvr);
3198#elif defined( IS_WINDOWS )
3199
3200#define AIL_MSS_version(str,len) \
3201{ \
3202 HINSTANCE l=LoadLibrary(MSSDLLNAME); \
3203 if ((UINTa)l<=32) \
3204 *(str)=0; \
3205 else { \
3206 LoadString(l,1,str,len); \
3207 FreeLibrary(l); \
3208 } \
3209}
3210
3211DXDEC S32 AILCALL AIL_digital_handle_release(HDIGDRIVER drvr);
3212
3213DXDEC S32 AILCALL AIL_digital_handle_reacquire
3214 (HDIGDRIVER drvr);
3215
3216#elif defined( IS_MAC )
3217
3218#if defined(__RESOURCES__)
3219
3220 typedef MSS_STRUCT MSS_VersionType_
3221 {
3222 Str255 version_name;
3223 } MSS_VersionType;
3224
3225 #define AIL_MSS_version(str,len) \
3226 { \
3227 long _res = HOpenResFile(0,0,"\p" MSSDLLNAME,fsRdPerm); \
3228 if (_res==-1) \
3229 { \
3230 str[0]=0; \
3231 } \
3232 else \
3233 { \
3234 Handle _H; \
3235 short _Err; \
3236 long _cur= CurResFile(); \
3237 UseResFile(_res); \
3238 _H = GetResource('vers', 2); \
3239 _Err = ResError(); \
3240 if((_Err != noErr) || (_H==0)) \
3241 { \
3242 str[0]=0; \
3243 UseResFile(_cur); \
3244 CloseResFile(_res); \
3245 } \
3246 else \
3247 { \
3248 if (GetHandleSize(_H)==0) \
3249 { \
3250 str[0]=0; \
3251 UseResFile(_cur); \
3252 CloseResFile(_res); \
3253 } \
3254 else \
3255 { \
3256 MSS_VersionType * _vt = (MSS_VersionType*)*_H; \
3257 if ((U32)_vt->version_name[6]>4) \
3258 _vt->version_name[6]-=4; \
3259 else \
3260 _vt->version_name[6]=0; \
3261 if (((U32)len) <= ((U32)_vt->version_name[6])) \
3262 _vt->version_name[6] = (U8)len-1; \
3263 memcpy( str, _vt->version_name+11, _vt->version_name[6] ); \
3264 str[_vt->version_name[6]]=0; \
3265 UseResFile(_cur); \
3266 CloseResFile(_res); \
3267 } \
3268 ReleaseResource(_H); \
3269 } \
3270 } \
3271 }
3272
3273 #endif
3274
3275 DXDEC S32 AILCALL AIL_digital_handle_release(HDIGDRIVER drvr);
3276
3277 DXDEC S32 AILCALL AIL_digital_handle_reacquire
3278 (HDIGDRIVER drvr);
3279
3280#endif
3281
3282DXDEC void AILCALL AIL_debug_log (char const * ifmt, ...);
3283
3284DXDEC S32 AILCALL AIL_sprintf(char *dest,
3285 char const *fmt, ...);
3286
3287DXDEC char* AILCALL AIL_set_redist_directory(char const*dir);
3288
3289DXDEC S32 AILCALL AIL_background_CPU_percent (void);
3290
3291DXDEC S32 AILCALL AIL_digital_CPU_percent (HDIGDRIVER dig);
3292
3293#ifdef HOST_SPU_PROCESS
3294DXDEC S32 AILCALL AIL_digital_SPU_percent (HDIGDRIVER dig);
3295#endif
3296
3297DXDEC S32 AILCALL AIL_digital_latency (HDIGDRIVER dig);
3298
3299DXDEC HSAMPLE AILCALL AIL_allocate_sample_handle
3300 (HDIGDRIVER dig);
3301
3302
3303EXPGROUP(Digital Audio Services)
3304
3305#define MILES_PUSH_REVERB 1
3306#define MILES_PUSH_VOLUME 2
3307#define MILES_PUSH_3D 4
3308#define MILES_PUSH_RESET 8
3309
3310DXDEC EXPAPI void AILCALL AIL_push_system_state(HDIGDRIVER dig, U32 flags, S16 crossfade_ms);
3311/*
3312 Pushes the current system state, allowing for a temporary "clean" driver to use, and then
3313 revert from.
3314
3315 $:dig The driver to push
3316 $:flags Logical "or" of options controlling the extent of the push. See discussion.
3317 $:crossfade_ms The number of milliseconds to fade the transition over. [0, 32767]
3318
3319 By default (ie flags == 0), effectively nothing happens. Since the operation neither affects
3320 any subsystems nor resets the playing samples, a push immediately followed by a pop should
3321 have no audible effects.
3322
3323 However, any samples started during the push will be stopped (via $AIL_end_fade_sample) when the system is popped.
3324 Streams will return SMP_DONE via $AIL_stream_status. It is up to the client code to perform any cleanup required.
3325
3326 The flags can alter the above behavior in the following ways:
3327
3328 $* <b>MILES_PUSH_RESET</b> - This flag causes the system to revert to a "new" state when pushed. Without any
3329 other flags this will only be apparent with samples - any playing samples will cease to be processed
3330 (though they will still report SMP_PLAYING). When the system is popped, these samples will resume.
3331
3332 $* <b>MILES_PUSH_REVERB</b> - When present, reverb state will be affected in addition to sample state.
3333 If MILES_PUSH_RESET is present, the reverb will be cleared to zero on push. Otherwise, it will be retained,
3334 and only affected when popped.
3335
3336 $* <b>MILES_PUSH_3D</b> - When present, 3d listener state will be affected in addition to sample state.
3337 If MILES_PUSH_RESET is present, the 3d listener state will be reverted to the same state as a new driver. Otherwise
3338 it will be retained and only affected when popped.
3339
3340 $* <b>MILES_PUSH_VOLUME</b> - When present, master volume will be affected in addition to sample state.
3341 If MILES_PUSH_RESET is present, the master volume will be set to 1.0f, otherwise it will be retained and only
3342 affected when popped.
3343
3344 $-
3345
3346 If you want more control over whether a sample will be affected by a push or a pop operation,
3347 see $AIL_set_sample_level_mask.
3348
3349*/
3350
3351DXDEC EXPAPI void AILCALL AIL_pop_system_state(HDIGDRIVER dig, S16 crossfade_ms);
3352/*
3353 Pops the current system state and returns the system to the way it
3354 was before the last push.
3355
3356 $:dig The driver to pop.
3357 $:crossfade_ms The number of milliseconds to crossfade the transition over - [0, 32767]
3358
3359 See $AIL_push_system_state for documentation.
3360*/
3361
3362DXDEC EXPAPI U8 AILCALL AIL_system_state_level(HDIGDRIVER dig);
3363/*
3364 Returns the current level the system has been pushed to.
3365
3366 $:dig The driver to inspect
3367 $:return A value between 0 and MILES_MAX_STATES, representing the depth of the current system stack.
3368*/
3369
3370DXDEC EXPAPI void AILCALL AIL_set_sample_level_mask(HSAMPLE S, U8 mask);
3371/*
3372 Sets the system levels at which a sample will play.
3373
3374 $:S The sample to set the mask for.
3375 $:mask The bitmask of levels for which the sample will play.
3376
3377 Under normal push/pop operations, a sample's mask is set when it is
3378 started to the level the system is at. If the system is pushed
3379 without a reset, then the mask is adjusted to include the new level.
3380 When a system is popped, if the sample is going to continue playing,
3381 the state mask is adjusted to remove the level the system is popping
3382 <i>from</i>.
3383
3384 If you have a sample playing on a higher system level that needs
3385 to continue after a pop, you can adjust the sample's mask by using
3386 this function in conjunction with $AIL_system_state_level and
3387 $AIL_sample_level_mask:
3388
3389 ${
3390 AIL_set_sample_level_mask(S, AIL_sample_level_mask(S) |= (1 << (AIL_system_state_level(dig) - 1)));
3391 $}
3392*/
3393
3394DXDEC EXPAPI U8 AILCALL AIL_sample_level_mask(HSAMPLE S);
3395/*
3396 Return the mask used to determine if the sample will play at a given system level.
3397
3398 $:S The sample to inspect.
3399 $:return The level mask for the sample.
3400
3401 See $AIL_set_sample_level_mask.
3402*/
3403
3404DXDEC EXPAPI U64 AILCALL AIL_digital_mixed_samples(HDIGDRIVER dig);
3405/*
3406 Returns the number of samples that have been mixed in to the hardware.
3407
3408 Used for timing samples for start via $AIL_schedule_start_sample.
3409*/
3410
3411#define AIL_digital_samples_per_second(dig) (dig->DMA_rate)
3412
3413
3414DXDEC EXPAPI void AILCALL AIL_enable_limiter(HDIGDRIVER dig, S32 on_off);
3415/*
3416 Enables a basic limiter to prevent clipping.
3417
3418 $:dig The driver to enable the limiter on.
3419 $:on_off If non-zero, the limiter will be enabled, otherwise it will be disabled.
3420
3421 By default limiters are off. Currently they are not configurable. They kick on around
3422 -10 db, and with a 0db signal will attenuate by about -18 db. Limiters run prior to
3423 the 16 bit clamp.
3424
3425 See also $AIL_bus_enable_limiter.
3426*/
3427
3428EXPGROUP(bus_section)
3429
3430DXDEC EXPAPI HSAMPLE AILCALL AIL_allocate_bus(HDIGDRIVER dig);
3431/*
3432 Allocates a bus to mix samples to.
3433
3434 $:dig The HDIGDRIVER to allocate the bus on.
3435 $:return The HSAMPLE for the new bus.
3436
3437 A bus allows you to treat a group of samples as one sample. With the bus sample you can
3438 do almost all of the things you can do with a normal sample handle. The only exception
3439 is you can't adjust the playback rate of the sample.
3440
3441 Use $AIL_bus_sample_handle to get the HSAMPLE associated with a bus.
3442
3443 Each call to AIL_allocate_bus adds a new bus, up to a total bus count of MAX_BUSSES. After
3444 the first call, two busses exist - the main bus and the first aux bus. The HSAMPLE returned
3445 is for the first aux bus (index 1)
3446*/
3447
3448DXDEC EXPAPI void AILCALL AIL_bus_enable_limiter(HDIGDRIVER dig, S32 bus_index, S32 on_off);
3449/*
3450 Enables a basic limiter to prevent clipping.
3451
3452 $:dig The driver containing the bus to enable the limiter on.
3453 $:bus_index The index of the bus to enable the limiter on.
3454 $:on_off If non-zero, the limiter will be enabled, otherwise it will be disabled.
3455
3456 By default limiters are off. Currently they are not configurable. They kick on around
3457 -10 db, and with a 0db signal will attenuate by about -18 db. Limiters run prior to
3458 the 16 bit clamp.
3459
3460 See also $AIL_enable_limiter.
3461*/
3462
3463DXDEC EXPAPI HSAMPLE AILCALL AIL_bus_sample_handle(HDIGDRIVER dig, S32 bus_index);
3464/*
3465 Returns the HSAMPLE associated with a bus.
3466
3467 $:dig The HDIGDRIVER the bus resides within.
3468 $:bus_index The index of the bus to return the HSAMPLE for.
3469 $:return The HSAMPLE for the bus index.
3470
3471 If the bus has not been allocated, or no busses have been allocated, this returns 0. This
3472 means that for the "Main Bus" - index 0 - it will still return zero if no additional busses
3473 have been allocated.
3474*/
3475
3476DXDEC EXPAPI void AILCALL AIL_set_sample_bus(HSAMPLE S, S32 bus_index);
3477/*
3478 Assigns an HSAMPLE to a bus.
3479
3480 $:S The HSAMPLE to assign.
3481 $:bus_index The bus index to assign the sample to.
3482
3483 If the given bus has not been allocated, this function has no effect.
3484*/
3485
3486DXDEC EXPAPI S32 AILCALL AIL_sample_bus(HSAMPLE S);
3487/*
3488 Returns the bus an HSAMPLE is assigned to.
3489
3490 $:S The HSAMPLE to check.
3491 $:return The index of the bus the sample is assigned.
3492
3493 All samples by default are assigned to bus 0.
3494*/
3495
3496DXDEC EXPAPI S32 AILCALL AIL_install_bus_compressor(HDIGDRIVER dig, S32 bus_index, SAMPLESTAGE filter_stage, S32 input_bus_index);
3497/*
3498 Installs the Compressor filter on to a bus, using another bus as the input for
3499 compression/limiting.
3500
3501 $:dig The driver the busses exist on.
3502 $:bus_index The index of the bus the compressor will affect.
3503 $:filter_stage The SAMPLESTAGE the compressor will use on the bus HSAMPLE.
3504 $:input_bus_index The bus index the compressor will use as <b>input</b>.
3505
3506 This installs a side chain compressor in to a given bus. It acts exactly like
3507 any other filter you would put on an HSAMPLE, except the input_bus_index bus pipe's
3508 its signal strength to the filter, allowing it to attenuate the bus_index bus based
3509 on another bus's contents.
3510
3511 To control the compressor parameters, access the bus's HSAMPLE via $AIL_bus_sample_handle and
3512 use $AIL_sample_stage_property exactly as you would any other filter. The filter's properties
3513 are documented under $(Compressor Filter)
3514*/
3515
3516DXDEC void AILCALL AIL_set_speaker_configuration
3517 (HDIGDRIVER dig,
3518 MSSVECTOR3D *array,
3519 S32 n_channels,
3520 F32 falloff_power);
3521
3522DXDEC MSSVECTOR3D *
3523 AILCALL AIL_speaker_configuration
3524 (HDIGDRIVER dig,
3525 S32 *n_physical_channels,
3526 S32 *n_logical_channels,
3527 F32 *falloff_power,
3528 MSS_MC_SPEC *channel_spec);
3529
3530DXDEC void AILCALL AIL_set_listener_relative_receiver_array
3531 (HDIGDRIVER dig,
3532 MSS_RECEIVER_LIST *array,
3533 S32 n_receivers);
3534
3535DXDEC MSS_RECEIVER_LIST *
3536 AILCALL AIL_listener_relative_receiver_array
3537 (HDIGDRIVER dig,
3538 S32 *n_receivers);
3539DXDEC void AILCALL AIL_set_speaker_reverb_levels
3540 (HDIGDRIVER dig,
3541 F32 *wet_array,
3542 F32 *dry_array,
3543 MSS_SPEAKER const *speaker_index_array,
3544 S32 n_levels);
3545
3546DXDEC S32 AILCALL AIL_speaker_reverb_levels (HDIGDRIVER dig,
3547 F32 * *wet_array,
3548 F32 * *dry_array,
3549 MSS_SPEAKER const * *speaker_index_array);
3550
3551
3552DXDEC
3553void AILCALL AIL_set_sample_speaker_scale_factors (HSAMPLE S, //)
3554 MSS_SPEAKER const * dest_speaker_indexes,
3555 F32 const * levels,
3556 S32 n_levels );
3557DXDEC
3558void AILCALL AIL_sample_speaker_scale_factors (HSAMPLE S, //)
3559 MSS_SPEAKER const * dest_speaker_indexes,
3560 F32 * levels,
3561 S32 n_levels );
3562
3563DXDEC
3564S32 AILEXPORT AIL_set_sample_is_3D (HSAMPLE S, //)
3565 S32 onoff);
3566
3567//DXDEC F32 AILEXPORT AIL_calculate_sample_final_attenuation(HSAMPLE S);
3568/*
3569 Returns the attenuation that a sample will have.
3570
3571 $:S Sample to compute.
3572*/
3573
3574DXDEC
3575S32 AILEXPORT AIL_calculate_3D_channel_levels (HDIGDRIVER dig, //)
3576 F32 *channel_levels,
3577 MSS_SPEAKER const * *speaker_array,
3578 MSSVECTOR3D *src_pos,
3579 MSSVECTOR3D *src_face,
3580 MSSVECTOR3D *src_up,
3581 F32 src_inner_angle,
3582 F32 src_outer_angle,
3583 F32 src_outer_volume,
3584 F32 src_max_dist,
3585 F32 src_min_dist,
3586 MSSVECTOR3D *listen_pos,
3587 MSSVECTOR3D *listen_face,
3588 MSSVECTOR3D *listen_up,
3589 F32 rolloff_factor,
3590 MSSVECTOR3D *doppler_velocity,
3591 F32 *doppler_shift);
3592
3593
3594DXDEC void AILCALL AIL_release_sample_handle (HSAMPLE S);
3595
3596DXDEC S32 AILCALL AIL_init_sample (HSAMPLE S,
3597 S32 format);
3598
3599DXDEC S32 AILCALL AIL_set_sample_file (HSAMPLE S,
3600 void const *file_image,
3601 S32 block);
3602
3603DXDEC S32 AILCALL AIL_set_sample_info (HSAMPLE S,
3604 AILSOUNDINFO const * info);
3605
3606DXDEC S32 AILCALL AIL_set_named_sample_file (HSAMPLE S,
3607 C8 const *file_type_suffix,
3608 void const *file_image,
3609 U32 file_size,
3610 S32 block);
3611
3612DXDEC HPROVIDER AILCALL AIL_set_sample_processor (HSAMPLE S,
3613 SAMPLESTAGE pipeline_stage,
3614 HPROVIDER provider);
3615
3616DXDEC HPROVIDER AILCALL AIL_set_digital_driver_processor
3617 (HDIGDRIVER dig,
3618 DIGDRVSTAGE pipeline_stage,
3619 HPROVIDER provider);
3620
3621DXDEC HPROVIDER AILCALL AIL_sample_processor (HSAMPLE S,
3622 SAMPLESTAGE pipeline_stage);
3623
3624DXDEC HPROVIDER AILCALL AIL_digital_driver_processor
3625 (HDIGDRIVER dig,
3626 DIGDRVSTAGE pipeline_stage);
3627
3628DXDEC void AILCALL AIL_set_sample_adpcm_block_size
3629 (HSAMPLE S,
3630 U32 blocksize);
3631
3632DXDEC void AILCALL AIL_set_sample_address (HSAMPLE S,
3633 void const *start,
3634 U32 len);
3635
3636DXDEC void AILCALL AIL_start_sample (HSAMPLE S);
3637
3638EXPGROUP(Digital Audio Services)
3639
3640DXDEC EXPAPI void AILCALL AIL_schedule_start_sample(HSAMPLE S, U64 mix_time_to_start);
3641/*
3642 Marks the specified sample to begin at the exact time specified.
3643
3644 $:S The sample to start
3645 $:mix_time_to_start The time to start the sample, in samples.
3646
3647 Once set, the sample will have $AIL_start_sample called automatically
3648 when the mixer reaches the specified time. The sample's delay will
3649 be automatically adjusted such that the sample starts mid-block.
3650
3651 ${
3652 // Get the current time.
3653 U64 mix_time = AIL_digital_mixed_samples(dig);
3654
3655 // Schedule to start 1 second out
3656 mix_time += AIL_digital_samples_per_second(dig);
3657 AIL_schedule_start_sample(S, mix_time );
3658 $}
3659*/
3660
3661DXDEC EXPAPI U64 AILCALL AIL_sample_schedule_time(HSAMPLE S);
3662/*
3663 Returns the mix time the sample is scheduled to start at, or 0 if not scheduled.
3664
3665 $:S The sample to query.
3666*/
3667
3668DXDEC void AILCALL AIL_stop_sample (HSAMPLE S);
3669
3670DXDEC void AILCALL AIL_end_fade_sample (HSAMPLE S);
3671
3672DXDEC void AILCALL AIL_resume_sample (HSAMPLE S);
3673
3674DXDEC void AILCALL AIL_end_sample (HSAMPLE S);
3675
3676DXDEC EXPAPI void AILCALL AIL_set_sample_id(HSAMPLE S, S32 id);
3677/*
3678 Set an ID on a sample for use in synchronized control.
3679
3680 $:S The sample to alter
3681 $:id The id to use.
3682*/
3683
3684DXDEC EXPAPI S32 AILCALL AIL_sample_id(HSAMPLE S);
3685/*
3686 Return the current ID for a sample.
3687
3688 $:S Sample to access
3689*/
3690
3691DXDEC EXPAPI void AILCALL AIL_start_sample_group(HDIGDRIVER dig, S32 start_id, S32 set_to_id);
3692/*
3693 Start a group of samples at the same time.
3694
3695 $:dig The driver the samples are allocated from.
3696 $:start_id The ID to start
3697 $:set_to_id The ID to set the samples to once they have started.
3698
3699 This function atomically calls $AIL_start_sample on all the samples to ensure the samples start in sync.
3700*/
3701
3702DXDEC EXPAPI void AILCALL AIL_stop_sample_group(HDIGDRIVER dig, S32 stop_id, S32 set_to_id);
3703/*
3704 Stops a group of samples at the same time.
3705
3706 $:dig The driver the samples are allocated from.
3707 $:stop_id The ID to stop
3708 $:set_to_id The ID to set the samples to once they have stopped.
3709
3710 This function atomically calls $AIL_stop_sample on all the samples to ensure they stop at the same point.
3711*/
3712
3713DXDEC EXPAPI void AILCALL AIL_resume_sample_group(HDIGDRIVER dig, S32 resume_id, S32 set_to_id);
3714/*
3715 Resumes a group of samples at the same time.
3716
3717 $:dig The driver the samples are allocated from.
3718 $:resume_id The ID to resume
3719 $:set_to_id The ID to set the samples to once they have resumed.
3720
3721 This function atomically calls $AIL_resume_sample on all the samples to ensure the samples start in sync.
3722*/
3723
3724DXDEC EXPAPI void AILCALL AIL_end_sample_group(HDIGDRIVER dig, S32 end_id);
3725/*
3726 Ends a group of samples at the same time.
3727
3728 $:dig The driver the samples are allocated from.
3729 $:end_id The ID to end
3730
3731 This function atomically calls $AIL_end_sample on all the samples.
3732*/
3733
3734DXDEC void AILCALL AIL_set_sample_playback_rate
3735 (HSAMPLE S,
3736 S32 playback_rate);
3737
3738DXDEC void AILCALL AIL_set_sample_playback_rate_factor
3739 (HSAMPLE S,
3740 F32 playback_rate_factor);
3741
3742DXDEC void AILCALL AIL_set_sample_playback_delay
3743 (HSAMPLE S,
3744 S32 playback_delay);
3745
3746DXDEC void AILCALL AIL_set_sample_volume_pan (HSAMPLE S,
3747 F32 volume,
3748 F32 pan);
3749
3750DXDEC void AILCALL AIL_set_sample_volume_levels(HSAMPLE S,
3751 F32 left_level,
3752 F32 right_level);
3753
3754DXDEC void AILCALL AIL_set_sample_channel_levels (HSAMPLE S,
3755 MSS_SPEAKER const *source_speaker_indexes,
3756 MSS_SPEAKER const *dest_speaker_indexes,
3757 F32 const *levels,
3758 S32 n_levels);
3759
3760DXDEC void AILCALL AIL_set_sample_reverb_levels(HSAMPLE S,
3761 F32 dry_level,
3762 F32 wet_level);
3763
3764DXDEC void AILCALL AIL_set_sample_low_pass_cut_off(HSAMPLE S,
3765 S32 /*-1 or MSS_SPEAKER*/ channel,
3766 F32 cut_off);
3767
3768DXDEC void AILCALL AIL_set_sample_loop_count (HSAMPLE S,
3769 S32 loop_count);
3770
3771DXDEC void AILCALL AIL_set_sample_loop_block (HSAMPLE S,
3772 S32 loop_start_offset,
3773 S32 loop_end_offset);
3774
3775DXDEC EXPAPI S32 AILCALL AIL_set_sample_loop_samples(HSAMPLE S, S32 loop_start_samples, S32 loop_end_samples);
3776/*
3777 Defines the loop points on a sample in samples rather than bytes.
3778
3779 $:S The sample to alter.
3780 $:loop_start_samples The sample count in to the file to start the looping.
3781 $:loop_end_samples The sample count in the file to end the looping.
3782 $:return 1 if successful, 0 otherwise. Check $AIL_last_error for details.
3783
3784 For uncompressed samples, this largely reverts to $AIL_set_sample_loop_block, since the mapping
3785 is straightforward. For compressed formats (like bink audio or mp3), looping in sample space is
3786 non trivial and must be handled on a format-by-format basis. For the moment, only Bink Audio
3787 supports this functionality - all other ASI formats will return failure.
3788
3789 If a loop's length is too short, it may be extended.
3790*/
3791
3792
3793DXDEC S32 AILCALL AIL_sample_loop_block (HSAMPLE S,
3794 S32 *loop_start_offset,
3795 S32 *loop_end_offset);
3796
3797DXDEC U32 AILCALL AIL_sample_status (HSAMPLE S);
3798
3799DXDEC U32 AILCALL AIL_sample_mixed_ms (HSAMPLE S);
3800
3801DXDEC S32 AILCALL AIL_sample_playback_rate (HSAMPLE S);
3802
3803DXDEC F32 AILCALL AIL_sample_playback_rate_factor (HSAMPLE S);
3804
3805DXDEC S32 AILCALL AIL_sample_playback_delay (HSAMPLE S);
3806
3807DXDEC void AILCALL AIL_sample_volume_pan (HSAMPLE S, F32* volume, F32* pan);
3808
3809DXDEC S32 AILCALL AIL_sample_channel_count (HSAMPLE S, U32 *mask);
3810
3811DXDEC void AILCALL AIL_sample_channel_levels (HSAMPLE S,
3812 MSS_SPEAKER const *source_speaker_indexes,
3813 MSS_SPEAKER const *dest_speaker_indexes,
3814 F32 *levels,
3815 S32 n_levels);
3816
3817DXDEC void AILCALL AIL_sample_volume_levels (HSAMPLE S,
3818 F32 *left_level,
3819 F32 *right_level);
3820
3821DXDEC void AILCALL AIL_sample_reverb_levels (HSAMPLE S,
3822 F32 *dry_level,
3823 F32 *wet_level);
3824
3825DXDEC F32 AILCALL AIL_sample_output_levels (HSAMPLE S,
3826 MSS_SPEAKER const *source_speaker_indexes,
3827 MSS_SPEAKER const *dest_speaker_indexes,
3828 F32 *levels,
3829 S32 n_levels);
3830
3831DXDEC F32 AILCALL AIL_sample_low_pass_cut_off(HSAMPLE S, S32 /*-1 or MSS_SPEAKER*/ channel);
3832
3833DXDEC S32 AILCALL AIL_sample_loop_count (HSAMPLE S);
3834
3835DXDEC void AILCALL AIL_set_digital_master_volume_level
3836 (HDIGDRIVER dig,
3837 F32 master_volume);
3838
3839DXDEC F32 AILCALL AIL_digital_master_volume_level (HDIGDRIVER dig);
3840
3841DXDEC void AILCALL AIL_set_sample_51_volume_pan( HSAMPLE S,
3842 F32 volume,
3843 F32 pan,
3844 F32 fb_pan,
3845 F32 center_level,
3846 F32 sub_level );
3847
3848DXDEC void AILCALL AIL_sample_51_volume_pan ( HSAMPLE S,
3849 F32* volume,
3850 F32* pan,
3851 F32* fb_pan,
3852 F32* center_level,
3853 F32* sub_level );
3854
3855DXDEC void AILCALL AIL_set_sample_51_volume_levels( HSAMPLE S,
3856 F32 f_left_level,
3857 F32 f_right_level,
3858 F32 b_left_level,
3859 F32 b_right_level,
3860 F32 center_level,
3861 F32 sub_level );
3862
3863DXDEC void AILCALL AIL_sample_51_volume_levels ( HSAMPLE S,
3864 F32* f_left_level,
3865 F32* f_right_level,
3866 F32* b_left_level,
3867 F32* b_right_level,
3868 F32* center_level,
3869 F32* sub_level );
3870DXDEC void AILCALL AIL_set_digital_master_reverb
3871 (HDIGDRIVER dig,
3872 S32 bus_index,
3873 F32 reverb_decay_time,
3874 F32 reverb_predelay,
3875 F32 reverb_damping);
3876
3877DXDEC void AILCALL AIL_digital_master_reverb
3878 (HDIGDRIVER dig,
3879 S32 bus_index,
3880 F32* reverb_time,
3881 F32* reverb_predelay,
3882 F32* reverb_damping);
3883
3884DXDEC void AILCALL AIL_set_digital_master_reverb_levels
3885 (HDIGDRIVER dig,
3886 S32 bus_index,
3887 F32 dry_level,
3888 F32 wet_level);
3889
3890DXDEC void AILCALL AIL_digital_master_reverb_levels
3891 (HDIGDRIVER dig,
3892 S32 bus_index,
3893 F32 * dry_level,
3894 F32 * wet_level);
3895
3896
3897//
3898// low-level digital services
3899//
3900
3901DXDEC S32 AILCALL AIL_minimum_sample_buffer_size(HDIGDRIVER dig,
3902 S32 playback_rate,
3903 S32 format);
3904
3905DXDEC S32 AILCALL AIL_set_sample_buffer_count (HSAMPLE S,
3906 S32 n_buffers);
3907
3908DXDEC S32 AILCALL AIL_sample_loaded_len (HSAMPLE S);
3909
3910DXDEC S32 AILCALL AIL_sample_buffer_count (HSAMPLE S);
3911
3912DXDEC S32 AILCALL AIL_sample_buffer_available (HSAMPLE S);
3913
3914DXDEC S32 AILCALL AIL_load_sample_buffer (HSAMPLE S,
3915 S32 buff_num,
3916 void const *buffer,
3917 U32 len);
3918
3919DXDEC void AILCALL AIL_request_EOB_ASI_reset (HSAMPLE S,
3920 U32 buff_num,
3921 S32 new_stream_position);
3922
3923DXDEC S32 AILCALL AIL_sample_buffer_info (HSAMPLE S, //)
3924 S32 buff_num,
3925 U32 *pos,
3926 U32 *len,
3927 S32 *head,
3928 S32 *tail);
3929
3930DXDEC U32 AILCALL AIL_sample_granularity (HSAMPLE S);
3931
3932DXDEC void AILCALL AIL_set_sample_position (HSAMPLE S,
3933 U32 pos);
3934
3935DXDEC U32 AILCALL AIL_sample_position (HSAMPLE S);
3936
3937DXDEC AILSAMPLECB AILCALL AIL_register_SOB_callback
3938 (HSAMPLE S,
3939 AILSAMPLECB SOB);
3940
3941DXDEC AILSAMPLECB AILCALL AIL_register_EOB_callback
3942 (HSAMPLE S,
3943 AILSAMPLECB EOB);
3944
3945DXDEC AILSAMPLECB AILCALL AIL_register_EOS_callback
3946 (HSAMPLE S,
3947 AILSAMPLECB EOS);
3948
3949DXDEC AILMIXERCB AILCALL AIL_register_mix_callback(HDIGDRIVER dig, AILMIXERCB mixcb);
3950
3951DXDEC AILFALLOFFCB AILCALL AIL_register_falloff_function_callback
3952 (HSAMPLE S,
3953 AILFALLOFFCB falloff_cb);
3954
3955DXDEC void AILCALL AIL_set_sample_user_data (HSAMPLE S,
3956 U32 index,
3957 SINTa value);
3958
3959DXDEC SINTa AILCALL AIL_sample_user_data (HSAMPLE S,
3960 U32 index);
3961
3962DXDEC S32 AILCALL AIL_active_sample_count (HDIGDRIVER dig);
3963
3964DXDEC void AILCALL AIL_digital_configuration (HDIGDRIVER dig,
3965 S32 *rate,
3966 S32 *format,
3967 char *string);
3968
3969DXDEC S32 AILCALL AIL_platform_property (void *object,
3970 MSS_PLATFORM_PROPERTY property,
3971 void *before_value,
3972 void const *new_value,
3973 void *after_value);
3974
3975
3976DXDEC void AILCALL AIL_set_sample_ms_position (HSAMPLE S, //)
3977 S32 milliseconds);
3978
3979DXDEC U32 AILCALL AIL_sample_ms_lookup (HSAMPLE S, //)
3980 S32 milliseconds,
3981 S32* actualms);
3982
3983DXDEC void AILCALL AIL_sample_ms_position (HSAMPLE S, //)
3984 S32 * total_milliseconds,
3985 S32 * current_milliseconds);
3986
3987//
3988// Digital input services
3989//
3990
3991#if defined(IS_WINDOWS)
3992 #define MSS_HAS_INPUT 1
3993#elif defined(IS_MAC)
3994 #define MSS_HAS_INPUT 1
3995#else
3996 #define MSS_HAS_INPUT 0
3997#endif
3998
3999#if MSS_HAS_INPUT
4000
4001DXDEC HDIGINPUT AILCALL AIL_open_input (AIL_INPUT_INFO *info);
4002
4003DXDEC void AILCALL AIL_close_input (HDIGINPUT dig);
4004
4005DXDEC AIL_INPUT_INFO *
4006 AILCALL AIL_get_input_info (HDIGINPUT dig);
4007
4008DXDEC S32 AILCALL AIL_set_input_state (HDIGINPUT dig,
4009 S32 enable);
4010#endif
4011
4012
4013//
4014// High-level XMIDI services
4015//
4016
4017DXDEC HMDIDRIVER AILCALL AIL_open_XMIDI_driver( U32 flags );
4018
4019#define AIL_OPEN_XMIDI_NULL_DRIVER 1
4020
4021DXDEC void AILCALL AIL_close_XMIDI_driver( HMDIDRIVER mdi );
4022
4023#if defined(IS_MAC) || defined(IS_LINUX)
4024
4025DXDEC S32 AILCALL AIL_MIDI_handle_release
4026 (HMDIDRIVER mdi);
4027
4028DXDEC S32 AILCALL AIL_MIDI_handle_reacquire
4029 (HMDIDRIVER mdi);
4030
4031#elif defined( IS_WINDOWS )
4032
4033DXDEC S32 AILCALL AIL_midiOutOpen(HMDIDRIVER *drvr,
4034 LPHMIDIOUT *lphMidiOut,
4035 S32 dwDeviceID);
4036
4037DXDEC void AILCALL AIL_midiOutClose (HMDIDRIVER mdi);
4038
4039DXDEC S32 AILCALL AIL_MIDI_handle_release
4040 (HMDIDRIVER mdi);
4041
4042DXDEC S32 AILCALL AIL_MIDI_handle_reacquire
4043 (HMDIDRIVER mdi);
4044
4045#endif
4046
4047DXDEC HSEQUENCE AILCALL AIL_allocate_sequence_handle
4048 (HMDIDRIVER mdi);
4049
4050DXDEC void AILCALL AIL_release_sequence_handle
4051 (HSEQUENCE S);
4052
4053DXDEC S32 AILCALL AIL_init_sequence (HSEQUENCE S,
4054 void const *start,
4055 S32 sequence_num);
4056
4057DXDEC void AILCALL AIL_start_sequence (HSEQUENCE S);
4058
4059DXDEC void AILCALL AIL_stop_sequence (HSEQUENCE S);
4060
4061DXDEC void AILCALL AIL_resume_sequence (HSEQUENCE S);
4062
4063DXDEC void AILCALL AIL_end_sequence (HSEQUENCE S);
4064
4065DXDEC void AILCALL AIL_set_sequence_tempo (HSEQUENCE S,
4066 S32 tempo,
4067 S32 milliseconds);
4068
4069DXDEC void AILCALL AIL_set_sequence_volume (HSEQUENCE S,
4070 S32 volume,
4071 S32 milliseconds);
4072
4073DXDEC void AILCALL AIL_set_sequence_loop_count
4074 (HSEQUENCE S,
4075 S32 loop_count);
4076
4077DXDEC U32 AILCALL AIL_sequence_status (HSEQUENCE S);
4078
4079DXDEC S32 AILCALL AIL_sequence_tempo (HSEQUENCE S);
4080
4081DXDEC S32 AILCALL AIL_sequence_volume (HSEQUENCE S);
4082
4083DXDEC S32 AILCALL AIL_sequence_loop_count (HSEQUENCE S);
4084
4085DXDEC void AILCALL AIL_set_XMIDI_master_volume
4086 (HMDIDRIVER mdi,
4087 S32 master_volume);
4088
4089DXDEC S32 AILCALL AIL_XMIDI_master_volume (HMDIDRIVER mdi);
4090
4091
4092//
4093// Low-level XMIDI services
4094//
4095
4096DXDEC S32 AILCALL AIL_active_sequence_count (HMDIDRIVER mdi);
4097
4098DXDEC S32 AILCALL AIL_controller_value (HSEQUENCE S,
4099 S32 channel,
4100 S32 controller_num);
4101
4102DXDEC S32 AILCALL AIL_channel_notes (HSEQUENCE S,
4103 S32 channel);
4104
4105DXDEC void AILCALL AIL_sequence_position (HSEQUENCE S,
4106 S32 *beat,
4107 S32 *measure);
4108
4109DXDEC void AILCALL AIL_branch_index (HSEQUENCE S,
4110 U32 marker);
4111
4112DXDEC AILPREFIXCB AILCALL AIL_register_prefix_callback
4113 (HSEQUENCE S,
4114 AILPREFIXCB callback);
4115
4116DXDEC AILTRIGGERCB AILCALL AIL_register_trigger_callback
4117 (HSEQUENCE S,
4118 AILTRIGGERCB callback);
4119
4120DXDEC AILSEQUENCECB AILCALL AIL_register_sequence_callback
4121 (HSEQUENCE S,
4122 AILSEQUENCECB callback);
4123
4124DXDEC AILBEATCB AILCALL AIL_register_beat_callback (HSEQUENCE S,
4125 AILBEATCB callback);
4126
4127DXDEC AILEVENTCB AILCALL AIL_register_event_callback (HMDIDRIVER mdi,
4128 AILEVENTCB callback);
4129
4130DXDEC AILTIMBRECB AILCALL AIL_register_timbre_callback
4131 (HMDIDRIVER mdi,
4132 AILTIMBRECB callback);
4133
4134DXDEC void AILCALL AIL_set_sequence_user_data (HSEQUENCE S,
4135 U32 index,
4136 SINTa value);
4137
4138DXDEC SINTa AILCALL AIL_sequence_user_data (HSEQUENCE S,
4139 U32 index);
4140
4141DXDEC void AILCALL AIL_register_ICA_array (HSEQUENCE S,
4142 U8 *array);
4143
4144DXDEC S32 AILCALL AIL_lock_channel (HMDIDRIVER mdi);
4145
4146DXDEC void AILCALL AIL_release_channel (HMDIDRIVER mdi,
4147 S32 channel);
4148
4149DXDEC void AILCALL AIL_map_sequence_channel (HSEQUENCE S,
4150 S32 seq_channel,
4151 S32 new_channel);
4152
4153DXDEC S32 AILCALL AIL_true_sequence_channel (HSEQUENCE S,
4154 S32 seq_channel);
4155
4156DXDEC void AILCALL AIL_send_channel_voice_message
4157 (HMDIDRIVER mdi,
4158 HSEQUENCE S,
4159 S32 status,
4160 S32 data_1,
4161 S32 data_2);
4162
4163DXDEC void AILCALL AIL_send_sysex_message (HMDIDRIVER mdi,
4164 void const *buffer);
4165
4166DXDEC HWAVESYNTH
4167 AILCALL AIL_create_wave_synthesizer (HDIGDRIVER dig,
4168 HMDIDRIVER mdi,
4169 void const *wave_lib,
4170 S32 polyphony);
4171
4172DXDEC void AILCALL AIL_destroy_wave_synthesizer (HWAVESYNTH W);
4173
4174DXDEC void AILCALL AIL_set_sequence_ms_position (HSEQUENCE S, //)
4175 S32 milliseconds);
4176
4177DXDEC void AILCALL AIL_sequence_ms_position(HSEQUENCE S, //)
4178 S32 *total_milliseconds,
4179 S32 *current_milliseconds);
4180
4181
4182
4183//
4184// red book functions
4185//
4186
4187#ifdef IS_WINDOWS
4188
4189#pragma pack(push, 1)
4190
4191typedef MSS_STRUCT _REDBOOK {
4192 U32 DeviceID;
4193 U32 paused;
4194 U32 pausedsec;
4195 U32 lastendsec;
4196} REDBOOK;
4197
4198#pragma pack(pop)
4199
4200typedef MSS_STRUCT _REDBOOK* HREDBOOK;
4201
4202#define REDBOOK_ERROR 0
4203#define REDBOOK_PLAYING 1
4204#define REDBOOK_PAUSED 2
4205#define REDBOOK_STOPPED 3
4206
4207
4208DXDEC HREDBOOK AILCALL AIL_redbook_open(U32 which);
4209
4210DXDEC HREDBOOK AILCALL AIL_redbook_open_drive(S32 drive);
4211
4212DXDEC void AILCALL AIL_redbook_close(HREDBOOK hand);
4213
4214DXDEC void AILCALL AIL_redbook_eject(HREDBOOK hand);
4215
4216DXDEC void AILCALL AIL_redbook_retract(HREDBOOK hand);
4217
4218DXDEC U32 AILCALL AIL_redbook_status(HREDBOOK hand);
4219
4220DXDEC U32 AILCALL AIL_redbook_tracks(HREDBOOK hand);
4221
4222DXDEC U32 AILCALL AIL_redbook_track(HREDBOOK hand);
4223
4224DXDEC void AILCALL AIL_redbook_track_info(HREDBOOK hand,U32 tracknum,
4225 U32* startmsec,U32* endmsec);
4226
4227DXDEC U32 AILCALL AIL_redbook_id(HREDBOOK hand);
4228
4229DXDEC U32 AILCALL AIL_redbook_position(HREDBOOK hand);
4230
4231DXDEC U32 AILCALL AIL_redbook_play(HREDBOOK hand,U32 startmsec, U32 endmsec);
4232
4233DXDEC U32 AILCALL AIL_redbook_stop(HREDBOOK hand);
4234
4235DXDEC U32 AILCALL AIL_redbook_pause(HREDBOOK hand);
4236
4237DXDEC U32 AILCALL AIL_redbook_resume(HREDBOOK hand);
4238
4239DXDEC F32 AILCALL AIL_redbook_volume_level(HREDBOOK hand);
4240
4241DXDEC F32 AILCALL AIL_redbook_set_volume_level(HREDBOOK hand, F32 volume);
4242
4243#endif
4244
4245DXDEC U32 AILCALL AIL_ms_count(void);
4246DXDEC U32 AILCALL AIL_us_count(void);
4247DXDEC U64 AILCALL AIL_ms_count64(void);
4248DXDEC U64 AILCALL AIL_us_count64(void);
4249DXDEC U64 AILCALL AIL_get_time(void);
4250DXDEC U64 AILCALL AIL_time_to_ms(U64 time);
4251DXDEC U64 AILCALL AIL_ms_to_time(U64 ms);
4252
4253DXDEC void AILCALL MilesUseTelemetry( void * context );
4254DXDEC void AILCALL MilesUseTmLite( void* context );
4255
4256//
4257//
4258//
4259
4260#define MSSIO_FLAGS_DONT_CLOSE_HANDLE 1
4261#define MSSIO_FLAGS_QUERY_SIZE_ONLY 2
4262#define MSSIO_FLAGS_DONT_USE_OFFSET 4
4263
4264#define MSSIO_STATUS_COMPLETE 1
4265#define MSSIO_STATUS_ERROR_FAILED_OPEN 0x1003
4266#define MSSIO_STATUS_ERROR_FAILED_READ 0x1004
4267#define MSSIO_STATUS_ERROR_SHUTDOWN 0x1005
4268#define MSSIO_STATUS_ERROR_CANCELLED 0x1006
4269#define MSSIO_STATUS_ERROR_MEMORY_ALLOC_FAIL 0x1007
4270#define MSSIO_STATUS_ERROR_MASK 0x1000
4271
4272// returns percent full (1.0 = 100%)
4273typedef F32 (AILCALLBACK *MilesAsyncStreamCallback)(void* i_User);
4274
4275struct MilesAsyncRead
4276{
4277 char FileName[256];
4278 U64 Offset;
4279 S64 Count;
4280 void* Buffer;
4281 void* StreamUserData;
4282 MilesAsyncStreamCallback StreamCB;
4283 char const * caller;
4284 U32 caller_line;
4285 UINTa FileHandle;
4286 S32 Flags;
4287 S32 ReadAmt; // current read amt.
4288 S32 AdditionalBuffer;
4289 S32 volatile Status; // This is only valid after a call to MilesAsyncFileWait or MilesAsyncFileCancel has succeeded.
4290 char Internal[48+128];
4291};
4292
4293DXDEC S32 AILCALL MilesAsyncFileRead(struct MilesAsyncRead* i_Request);
4294DXDEC S32 AILCALL MilesAsyncFileCancel(struct MilesAsyncRead* i_Request); // 1 if the request has completed, 0 otherwise. Use Wait if needed.
4295DXDEC S32 AILCALL MilesAsyncFileStatus(struct MilesAsyncRead* i_Request, U32 i_MS); // 1 if complete, 0 if timeout exceeded.
4296DXDEC S32 AILCALL MilesAsyncStartup();
4297DXDEC S32 AILCALL MilesAsyncShutdown();
4298DXDEC S32 AILCALL AIL_IO_thread_handle(void* o_Handle);
4299DXDEC void AILCALL MilesAsyncSetPaused(S32 i_IsPaused);
4300
4301typedef S32 (AILCALLBACK * MilesAsyncFileRead_callback)(struct MilesAsyncRead* i_Request);
4302typedef S32 (AILCALLBACK * MilesAsyncFileCancel_callback)(struct MilesAsyncRead* i_Request); // 1 if the request has completed, 0 otherwise. Use Wait if needed.
4303typedef S32 (AILCALLBACK * MilesAsyncFileStatus_callback)(struct MilesAsyncRead* i_Request, U32 i_MS); // 1 if complete, 0 if timeout exceeded.
4304typedef S32 (AILCALLBACK * MilesAsyncStartup_callback)();
4305typedef S32 (AILCALLBACK * MilesAsyncShutdown_callback)();
4306typedef void (AILCALLBACK * MilesAsyncSetPaused_callback)(S32 i_IsPaused);
4307typedef S32 (AILCALLBACK * AIL_IO_thread_handle_callback)(void* o_Handle);
4308
4309DXDEC void AILCALL AIL_set_async_callbacks(
4310 MilesAsyncFileRead_callback read,
4311 MilesAsyncFileCancel_callback cancel,
4312 MilesAsyncFileStatus_callback status,
4313 MilesAsyncStartup_callback startup,
4314 MilesAsyncShutdown_callback shutdown,
4315 MilesAsyncSetPaused_callback setpaused,
4316 AIL_IO_thread_handle_callback threadhandle);
4317
4318//
4319//
4320//
4321
4322typedef struct _STREAM* HSTREAM; // Handle to stream
4323
4324typedef void (AILCALLBACK* AILSTREAMCB) (HSTREAM stream);
4325
4326#define MSS_STREAM_CHUNKS 8
4327
4328typedef struct _STREAM
4329{
4330 S32 block_oriented; // 1 if this is an ADPCM or ASI-compressed stream
4331 S32 using_ASI; // 1 if using ASI decoder to uncompress stream data
4332 ASISTAGE *ASI; // handy pointer to our ASI coded
4333
4334 HSAMPLE samp; // the sample handle
4335
4336 UINTa fileh; // the open file handle
4337
4338 U8* bufs[MSS_STREAM_CHUNKS]; // the data buffers
4339 S32 reset_ASI[MSS_STREAM_CHUNKS]; // should we reset the ASI at the end of the buffer?
4340 S32 reset_seek_pos[MSS_STREAM_CHUNKS]; // new stream position after reset
4341 S32 bufstart[MSS_STREAM_CHUNKS]; // offset of where this buffer started
4342 S32 loadedsizes[MSS_STREAM_CHUNKS]; // sizes of the data to be started
4343
4344 struct MilesAsyncRead asyncs[MSS_STREAM_CHUNKS];
4345 S32 asyncs_loaded[MSS_STREAM_CHUNKS]; // 0=unloaded, 1=loading, 2=loaded, but not started
4346 S32 next_read_offset; // offset to pass to the next read, so the seek occurs internally. -1 to not seek.
4347
4348 S32 into_Miles_index; // index of buffer that we will async into next
4349 S32 read_IO_index; // index of buffer to be loaded into Miles next
4350
4351 S32 bufsize; // size of each buffer
4352
4353 U32 datarate; // datarate in bytes per second
4354 S32 filerate; // original datarate of the file
4355 S32 filetype; // file format type
4356 U32 filemask; // channel mask for stream file
4357 S32 totallen; // total length of the sound data
4358
4359 S32 substart; // subblock loop start
4360 S32 sublen; // subblock loop len
4361
4362 U32 blocksize; // ADPCM block size
4363
4364 S32 loadedsome; // have we done any loads?
4365
4366 U32 startpos; // point that the sound data begins
4367 U32 async_pos; // position if the last async completed
4368
4369 U32 loopsleft; // how many loops are left
4370
4371 U32 error; // read error has occurred
4372
4373 S32 preload; // preload the file into the first buffer
4374 U32 preloadpos; // position to use in preload
4375 U32 noback; // no background processing
4376 S32 alldone; // alldone
4377 S32 primeamount; // amount to load after a seek
4378 S32 primeleft; // amount to read before starting
4379
4380 S32 playcontrol; // control: 0=stopped, 1=started, |8=paused, |16=sample paused
4381
4382 AILSTREAMCB callback; // end of stream callback
4383
4384 SINTa user_data[8]; // Miscellaneous user data
4385 void* next; // pointer to next stream
4386
4387 S32 autostreaming; // are we autostreaming this stream
4388
4389 F32 level; // io percent full
4390 F32 last_level; // old io percent
4391 F32 percent_mult; // factor to scale by
4392 S32 stream_count; // unique number of the stream
4393
4394 S32 docallback; // set when it time to poll for a callback
4395
4396 S32 was_popped; // set to 1 if the stream needs to be freed due to a system push/pop - causes SMP_DONE to be stream_status
4397} MSTREAM_TYPE;
4398
4399
4400DXDEC HSTREAM AILCALL AIL_open_stream(HDIGDRIVER dig, char const * filename, S32 stream_mem);
4401
4402DXDEC void AILCALL AIL_close_stream(HSTREAM stream);
4403
4404DXDEC HSAMPLE AILCALL AIL_stream_sample_handle(HSTREAM stream);
4405
4406DXDEC S32 AILCALL AIL_service_stream(HSTREAM stream, S32 fillup);
4407
4408DXDEC void AILCALL AIL_start_stream(HSTREAM stream);
4409
4410DXDEC void AILCALL AIL_pause_stream(HSTREAM stream, S32 onoff);
4411
4412DXDEC S32 AILCALL AIL_stream_loop_count(HSTREAM stream);
4413
4414DXDEC void AILCALL AIL_set_stream_loop_count(HSTREAM stream, S32 count);
4415
4416DXDEC void AILCALL AIL_set_stream_loop_block (HSTREAM S,
4417 S32 loop_start_offset,
4418 S32 loop_end_offset);
4419
4420DXDEC S32 AILCALL AIL_stream_status(HSTREAM stream);
4421
4422DXDEC F32 AILCALL AIL_stream_filled_percent(HSTREAM stream);
4423
4424DXDEC void AILCALL AIL_set_stream_position(HSTREAM stream,S32 offset);
4425
4426DXDEC S32 AILCALL AIL_stream_position(HSTREAM stream);
4427
4428DXDEC void AILCALL AIL_stream_info(HSTREAM stream, S32* datarate, S32* sndtype, S32* length, S32* memory);
4429
4430DXDEC AILSTREAMCB AILCALL AIL_register_stream_callback(HSTREAM stream, AILSTREAMCB callback);
4431
4432DXDEC void AILCALL AIL_auto_service_stream(HSTREAM stream, S32 onoff);
4433
4434DXDEC void AILCALL AIL_set_stream_user_data (HSTREAM S,
4435 U32 index,
4436 SINTa value);
4437
4438DXDEC SINTa AILCALL AIL_stream_user_data (HSTREAM S,
4439 U32 index);
4440
4441DXDEC void AILCALL AIL_set_stream_ms_position (HSTREAM S,
4442 S32 milliseconds);
4443
4444DXDEC void AILCALL AIL_stream_ms_position (HSTREAM S, //)
4445 S32 * total_milliseconds,
4446 S32 * current_milliseconds);
4447
4448//! \todo MSS_FILE not needed anymore?
4449typedef char MSS_FILE;
4450
4451typedef U32 (AILCALLBACK*AIL_file_open_callback) (MSS_FILE const* Filename,
4452 UINTa* FileHandle);
4453
4454typedef void (AILCALLBACK*AIL_file_close_callback) (UINTa FileHandle);
4455
4456#define AIL_FILE_SEEK_BEGIN 0
4457#define AIL_FILE_SEEK_CURRENT 1
4458#define AIL_FILE_SEEK_END 2
4459
4460typedef S32 (AILCALLBACK*AIL_file_seek_callback) (UINTa FileHandle,
4461 S32 Offset,
4462 U32 Type);
4463
4464typedef U32 (AILCALLBACK*AIL_file_read_callback) (UINTa FileHandle,
4465 void* Buffer,
4466 U32 Bytes);
4467
4468DXDEC void AILCALL AIL_set_file_callbacks (AIL_file_open_callback opencb,
4469 AIL_file_close_callback closecb,
4470 AIL_file_seek_callback seekcb,
4471 AIL_file_read_callback readcb);
4472
4473DXDEC void AILCALL AIL_file_callbacks(AIL_file_open_callback* opencb,
4474 AIL_file_close_callback* closecb,
4475 AIL_file_seek_callback* seekcb,
4476 AIL_file_read_callback* readcb);
4477
4478#ifdef IS_32
4479
4480typedef void* (AILCALLBACK *AIL_file_async_read_callback) (UINTa FileHandle,
4481 void* Buffer,
4482 U32 Bytes);
4483
4484typedef S32 (AILCALLBACK*AIL_file_async_status_callback) (void* async,
4485 S32 wait,
4486 U32* BytesRead);
4487
4488DXDEC void AILCALL AIL_set_file_async_callbacks (AIL_file_open_callback opencb,
4489 AIL_file_close_callback closecb,
4490 AIL_file_seek_callback seekcb,
4491 AIL_file_async_read_callback areadcb,
4492 AIL_file_async_status_callback statuscb);
4493
4494#endif
4495
4496//
4497// High-level DLS functions
4498//
4499
4500typedef struct _DLSFILEID {
4501 SINTa id;
4502 struct _DLSFILEID* next;
4503} DLSFILEID;
4504
4505typedef struct _DLSFILEID* HDLSFILEID;
4506
4507typedef struct _DLSDEVICE {
4508 VOIDFUNC* pGetPref;
4509 VOIDFUNC* pSetPref;
4510 VOIDFUNC* pMSSOpen;
4511 VOIDFUNC* pOpen;
4512 VOIDFUNC* pClose;
4513 VOIDFUNC* pLoadFile;
4514 VOIDFUNC* pLoadMem;
4515 VOIDFUNC* pUnloadFile;
4516 VOIDFUNC* pUnloadAll;
4517 VOIDFUNC* pGetInfo;
4518 VOIDFUNC* pCompact;
4519 VOIDFUNC* pSetAttr;
4520 SINTa DLSHandle;
4521 U32 format;
4522 U32 buffer_size;
4523 void* buffer[2];
4524 HSAMPLE sample;
4525 HMDIDRIVER mdi;
4526 HDIGDRIVER dig;
4527 HDLSFILEID first;
4528#if defined(__RADNT__)
4529
4530 #ifdef MSS_STATIC_RIB
4531 #error "Bad defines - can't have a static rib on NT"
4532 #endif
4533 HMODULE lib;
4534#elif defined(MSS_STATIC_RIB)
4535 char* DOSname;
4536#endif
4537} DLSDEVICE;
4538
4539typedef struct _DLSDEVICE* HDLSDEVICE;
4540
4541typedef struct _AILDLSINFO {
4542 char Description[128];
4543 S32 MaxDLSMemory;
4544 S32 CurrentDLSMemory;
4545 S32 LargestSize;
4546 S32 GMAvailable;
4547 S32 GMBankSize;
4548} AILDLSINFO;
4549
4550#ifdef MSS_STATIC_RIB
4551
4552typedef struct _AILSTATICDLS {
4553 char* description;
4554 VOIDFUNC* pDLSOpen;
4555 VOIDFUNC* pMSSOpen;
4556 VOIDFUNC* pOpen;
4557 VOIDFUNC* pClose;
4558 VOIDFUNC* pLoadFile;
4559 VOIDFUNC* pLoadMem;
4560 VOIDFUNC* pUnloadFile;
4561 VOIDFUNC* pUnloadAll;
4562 VOIDFUNC* pGetInfo;
4563 VOIDFUNC* pCompact;
4564 VOIDFUNC* pSetAttr;
4565} AILSTATICDLS;
4566
4567#endif // MSS_STATIC_RIB
4568
4569
4570DXDEC HDLSDEVICE AILCALL AIL_DLS_open(HMDIDRIVER mdi, HDIGDRIVER dig,
4571#ifdef MSS_STATIC_RIB
4572 AILSTATICDLS const * staticdls,
4573#elif defined(__RADNT__)
4574 char const * libname,
4575#endif
4576 U32 flags, U32 rate, S32 bits, S32 channels);
4577
4578//
4579// Parameters for the dwFlag used in DLSClose() and flags in AIL_DLS_close
4580//
4581
4582#define RETAIN_DLS_COLLECTION 0x00000001
4583#define RETURN_TO_BOOTUP_STATE 0x00000002
4584#define RETURN_TO_GM_ONLY_STATE 0x00000004
4585#define DLS_COMPACT_MEMORY 0x00000008
4586
4587DXDEC void AILCALL AIL_DLS_close(HDLSDEVICE dls, U32 flags);
4588
4589DXDEC HDLSFILEID AILCALL AIL_DLS_load_file(HDLSDEVICE dls, char const* filename, U32 flags);
4590
4591DXDEC HDLSFILEID AILCALL AIL_DLS_load_memory(HDLSDEVICE dls, void const* memfile, U32 flags);
4592
4593//
4594// other parameters for AIL_DLS_unload
4595//
4596
4597#define AIL_DLS_UNLOAD_MINE 0
4598#define AIL_DLS_UNLOAD_ALL ((HDLSFILEID)(UINTa)(SINTa)-1)
4599
4600DXDEC void AILCALL AIL_DLS_unload(HDLSDEVICE dls, HDLSFILEID dlsid);
4601
4602DXDEC void AILCALL AIL_DLS_compact(HDLSDEVICE dls);
4603
4604DXDEC void AILCALL AIL_DLS_get_info(HDLSDEVICE dls, AILDLSINFO* info, S32* PercentCPU);
4605
4606DXDEC HSAMPLE AILCALL AIL_DLS_sample_handle(HDLSDEVICE dls);
4607
4608
4609//
4610// Quick-integration service functions and data types
4611//
4612
4613typedef struct
4614{
4615 U32 const *data;
4616 S32 size;
4617 S32 type;
4618 void *handle;
4619 S32 status;
4620 void* next;
4621 S32 speed;
4622 F32 volume;
4623 F32 extravol;
4624 F32 dry;
4625 F32 wet;
4626 F32 cutoff;
4627 HDLSFILEID dlsid;
4628 void* dlsmem;
4629 void* dlsmemunc;
4630 S32 milliseconds;
4631 S32 length;
4632 SINTa userdata;
4633}
4634AUDIO_TYPE;
4635
4636
4637#define QSTAT_DONE 1 // Data has finished playing
4638#define QSTAT_LOADED 2 // Data has been loaded, but not yet played
4639#define QSTAT_PLAYING 3 // Data is currently playing
4640
4641typedef AUDIO_TYPE * HAUDIO; // Generic handle to any audio data type
4642
4643#define AIL_QUICK_USE_WAVEOUT 2
4644#define AIL_QUICK_MIDI_AND_DLS 2
4645#define AIL_QUICK_DLS_ONLY 3
4646#define AIL_QUICK_MIDI_AND_VORTEX_DLS 4
4647#define AIL_QUICK_MIDI_AND_SONICVIBES_DLS 5
4648
4649DXDEC S32 AILCALL
4650 AIL_quick_startup (
4651 S32 use_digital,
4652 S32 use_MIDI,
4653 U32 output_rate,
4654 S32 output_bits,
4655 S32 output_channels);
4656
4657DXDEC void AILCALL AIL_quick_shutdown (void);
4658
4659DXDEC void AILCALL AIL_quick_handles (HDIGDRIVER* pdig,
4660 HMDIDRIVER* pmdi,
4661 HDLSDEVICE* pdls );
4662
4663DXDEC HAUDIO AILCALL AIL_quick_load (char const *filename);
4664
4665DXDEC HAUDIO AILCALL AIL_quick_load_mem (void const *mem,
4666 U32 size);
4667
4668DXDEC HAUDIO AILCALL AIL_quick_load_named_mem (void const *mem,
4669 char const *filename,
4670 U32 size);
4671
4672DXDEC HAUDIO AILCALL AIL_quick_copy (HAUDIO audio);
4673
4674DXDEC void AILCALL AIL_quick_unload (HAUDIO audio);
4675
4676DXDEC S32 AILCALL AIL_quick_play (HAUDIO audio,
4677 U32 loop_count);
4678
4679DXDEC void AILCALL AIL_quick_halt (HAUDIO audio);
4680
4681DXDEC S32 AILCALL AIL_quick_status (HAUDIO audio);
4682
4683DXDEC HAUDIO AILCALL AIL_quick_load_and_play (char const *filename,
4684 U32 loop_count,
4685 S32 wait_request);
4686
4687DXDEC void AILCALL AIL_quick_set_speed (HAUDIO audio, S32 speed);
4688
4689DXDEC void AILCALL AIL_quick_set_volume (HAUDIO audio, F32 volume, F32 extravol);
4690
4691DXDEC void AILCALL AIL_quick_set_reverb_levels (HAUDIO audio,
4692 F32 dry_level,
4693 F32 wet_level);
4694
4695DXDEC void AILCALL AIL_quick_set_low_pass_cut_off(HAUDIO S,
4696 S32 channel,
4697 F32 cut_off);
4698
4699DXDEC void AILCALL AIL_quick_set_ms_position(HAUDIO audio,S32 milliseconds);
4700
4701DXDEC S32 AILCALL AIL_quick_ms_position(HAUDIO audio);
4702
4703DXDEC S32 AILCALL AIL_quick_ms_length(HAUDIO audio);
4704
4705
4706#define AIL_QUICK_XMIDI_TYPE 1
4707#define AIL_QUICK_DIGITAL_TYPE 2
4708#define AIL_QUICK_DLS_XMIDI_TYPE 3
4709#define AIL_QUICK_MPEG_DIGITAL_TYPE 4
4710#define AIL_QUICK_OGG_VORBIS_TYPE 5
4711#define AIL_QUICK_V12_VOICE_TYPE 6
4712#define AIL_QUICK_V24_VOICE_TYPE 7
4713#define AIL_QUICK_V29_VOICE_TYPE 8
4714#define AIL_QUICK_OGG_SPEEX_TYPE 9
4715#define AIL_QUICK_S8_VOICE_TYPE 10
4716#define AIL_QUICK_S16_VOICE_TYPE 11
4717#define AIL_QUICK_S32_VOICE_TYPE 12
4718#define AIL_QUICK_BINKA_TYPE 13
4719
4720DXDEC S32 AILCALL AIL_quick_type(HAUDIO audio);
4721
4722DXDEC S32 AILCALL AIL_WAV_info(void const* WAV_image, AILSOUNDINFO* info);
4723
4724DXDEC S32 AILCALL AIL_WAV_marker_count(void const *WAV_image);
4725
4726DXDEC S32 AILCALL AIL_WAV_marker_by_index(void const *WAV_image, S32 n, C8 const **name);
4727
4728DXDEC S32 AILCALL AIL_WAV_marker_by_name(void const *WAV_image, C8 *name);
4729
4730DXDEC S32 AILCALL AIL_size_processed_digital_audio(
4731 U32 dest_rate,
4732 U32 dest_format,
4733 S32 num_srcs,
4734 AILMIXINFO const * src);
4735
4736DXDEC S32 AILCALL AIL_process_digital_audio(
4737 void *dest_buffer,
4738 S32 dest_buffer_size,
4739 U32 dest_rate,
4740 U32 dest_format,
4741 S32 num_srcs,
4742 AILMIXINFO* src);
4743
4744#define AIL_LENGTHY_INIT 0
4745#define AIL_LENGTHY_SET_PROPERTY 1
4746#define AIL_LENGTHY_UPDATE 2
4747#define AIL_LENGTHY_DONE 3
4748
4749typedef S32 (AILCALLBACK* AILLENGTHYCB)(U32 state,UINTa user);
4750
4751typedef S32 (AILCALLBACK* AILCODECSETPROP)(char const* property,void const * value);
4752
4753DXDEC S32 AILCALL AIL_compress_ASI(AILSOUNDINFO const * info, //)
4754 char const* filename_ext,
4755 void** outdata,
4756 U32* outsize,
4757 AILLENGTHYCB callback);
4758
4759DXDEC S32 AILCALL AIL_decompress_ASI(void const* indata, //)
4760 U32 insize,
4761 char const* filename_ext,
4762 void** wav,
4763 U32* wavsize,
4764 AILLENGTHYCB callback);
4765
4766DXDEC S32 AILCALL AIL_compress_ADPCM(AILSOUNDINFO const * info,
4767 void** outdata, U32* outsize);
4768
4769DXDEC S32 AILCALL AIL_decompress_ADPCM(AILSOUNDINFO const * info,
4770 void** outdata, U32* outsize);
4771
4772DXDEC S32 AILCALL AIL_compress_DLS(void const* dls,
4773 char const* compression_extension,
4774 void** mls, U32* mlssize,
4775 AILLENGTHYCB callback);
4776
4777DXDEC S32 AILCALL AIL_merge_DLS_with_XMI(void const* xmi, void const* dls,
4778 void** mss, U32* msssize);
4779
4780DXDEC S32 AILCALL AIL_extract_DLS( void const *source_image, //)
4781 U32 source_size,
4782 void * *XMI_output_data,
4783 U32 *XMI_output_size,
4784 void * *DLS_output_data,
4785 U32 *DLS_output_size,
4786 AILLENGTHYCB callback);
4787
4788#define AILFILTERDLS_USINGLIST 1
4789
4790DXDEC S32 AILCALL AIL_filter_DLS_with_XMI(void const* xmi, void const* dls,
4791 void** dlsout, U32* dlssize,
4792 S32 flags, AILLENGTHYCB callback);
4793
4794#define AILMIDITOXMI_USINGLIST 1
4795#define AILMIDITOXMI_TOLERANT 2
4796
4797DXDEC S32 AILCALL AIL_MIDI_to_XMI (void const* MIDI,
4798 U32 MIDI_size,
4799 void* *XMIDI,
4800 U32 * XMIDI_size,
4801 S32 flags);
4802
4803#define AILDLSLIST_ARTICULATION 1
4804#define AILDLSLIST_DUMP_WAVS 2
4805
4806#if defined(IS_WIN32) || defined(IS_MAC) || defined(IS_LINUX)
4807
4808DXDEC S32 AILCALL AIL_list_DLS (void const* DLS,
4809 char** lst,
4810 U32 * lst_size,
4811 S32 flags,
4812 C8 * title);
4813
4814#define AILMIDILIST_ROLANDSYSEX 1
4815#define AILMIDILIST_ROLANDUN 2
4816#define AILMIDILIST_ROLANDAB 4
4817
4818DXDEC S32 AILCALL AIL_list_MIDI (void const* MIDI,
4819 U32 MIDI_size,
4820 char** lst,
4821 U32 * lst_size,
4822 S32 flags);
4823#endif
4824
4825#define AILFILETYPE_UNKNOWN 0
4826#define AILFILETYPE_PCM_WAV 1
4827#define AILFILETYPE_ADPCM_WAV 2
4828#define AILFILETYPE_OTHER_WAV 3
4829#define AILFILETYPE_VOC 4
4830#define AILFILETYPE_MIDI 5
4831#define AILFILETYPE_XMIDI 6
4832#define AILFILETYPE_XMIDI_DLS 7
4833#define AILFILETYPE_XMIDI_MLS 8
4834#define AILFILETYPE_DLS 9
4835#define AILFILETYPE_MLS 10
4836#define AILFILETYPE_MPEG_L1_AUDIO 11
4837#define AILFILETYPE_MPEG_L2_AUDIO 12
4838#define AILFILETYPE_MPEG_L3_AUDIO 13
4839#define AILFILETYPE_OTHER_ASI_WAV 14
4840#define AILFILETYPE_XBOX_ADPCM_WAV 15
4841#define AILFILETYPE_OGG_VORBIS 16
4842#define AILFILETYPE_V12_VOICE 17
4843#define AILFILETYPE_V24_VOICE 18
4844#define AILFILETYPE_V29_VOICE 19
4845#define AILFILETYPE_OGG_SPEEX 20
4846#define AILFILETYPE_S8_VOICE 21
4847#define AILFILETYPE_S16_VOICE 22
4848#define AILFILETYPE_S32_VOICE 23
4849#define AILFILETYPE_BINKA 24
4850
4851DXDEC S32 AILCALL AIL_file_type(void const* data, U32 size);
4852
4853DXDEC S32 AILCALL AIL_file_type_named(void const* data, char const* filename, U32 size);
4854
4855DXDEC S32 AILCALL AIL_find_DLS (void const* data, U32 size,
4856 void** xmi, U32* xmisize,
4857 void** dls, U32* dlssize);
4858typedef struct
4859{
4860 //
4861 // File-level data accessible to app
4862 //
4863 // This is valid after AIL_inspect_MP3() is called (even if the file contains no valid frames)
4864 //
4865
4866 U8 *MP3_file_image; // Original MP3_file_image pointer passed to AIL_inspect_MP3()
4867 S32 MP3_image_size; // Original MP3_image_size passed to AIL_inspect_MP3()
4868
4869 U8 *ID3v2; // ID3v2 tag, if not NULL
4870 S32 ID3v2_size; // Size of tag in bytes
4871
4872 U8 *ID3v1; // ID3v1 tag, if not NULL (always 128 bytes long if present)
4873
4874 U8 *start_MP3_data; // Pointer to start of data area in file (not necessarily first valid frame)
4875 U8 *end_MP3_data; // Pointer to last valid byte in MP3 data area (before ID3v1 tag, if any)
4876
4877 //
4878 // Information about current frame being inspected, valid if AIL_enumerate_MP3_frames() returns
4879 // TRUE
4880 //
4881
4882 S32 sample_rate; // Sample rate in Hz (normally constant across all frames in file)
4883 S32 bit_rate; // Bits/second for current frame
4884 S32 channels_per_sample; // 1 or 2
4885 S32 samples_per_frame; // Always 576 or 1152 samples in each MP3 frame, depending on rate
4886
4887 S32 byte_offset; // Offset of frame from start_MP3_data (i.e., suitable for use as loop point)
4888 S32 next_frame_expected; // Anticipated offset of next frame to be enumerated, if any
4889 S32 average_frame_size; // Average source bytes per frame, determined solely by bit rate and sample rate
4890 S32 data_size; // # of data-only bytes in this particular frame
4891 S32 header_size; // 4 or 6 bytes, depending on CRC
4892 S32 side_info_size; // Valid for layer 3 side info only
4893 S32 ngr; // Always 2 for MPEG1, else 1
4894 S32 main_data_begin; // Always 0 in files with no bit reservoir
4895 S32 hpos; // Current bit position in header/side buffer
4896
4897 S32 MPEG1; // Data copied directly from frame header, see ISO docs for info...
4898 S32 MPEG25;
4899 S32 layer;
4900 S32 protection_bit;
4901 S32 bitrate_index;
4902 S32 sampling_frequency;
4903 S32 padding_bit;
4904 S32 private_bit;
4905 S32 mode;
4906 S32 mode_extension;
4907 S32 copyright;
4908 S32 original;
4909 S32 emphasis;
4910
4911 //
4912 // LAME/Xing info tag data
4913 //
4914
4915 S32 Xing_valid;
4916 S32 Info_valid;
4917 U32 header_flags;
4918 S32 frame_count;
4919 S32 byte_count;
4920 S32 VBR_scale;
4921 U8 TOC[100];
4922 S32 enc_delay;
4923 S32 enc_padding;
4924
4925 //
4926 // Private (undocumented) data used during frame enumeration
4927 //
4928
4929 U8 *ptr;
4930 S32 bytes_left;
4931
4932 S32 check_valid;
4933 S32 check_MPEG1;
4934 S32 check_MPEG25;
4935 S32 check_layer;
4936 S32 check_protection_bit;
4937 S32 check_sampling_frequency;
4938 S32 check_mode;
4939 S32 check_copyright;
4940 S32 check_original;
4941}
4942MP3_INFO;
4943
4944DXDEC void AILCALL AIL_inspect_MP3 (MP3_INFO *inspection_state,
4945 U8 *MP3_file_image,
4946 S32 MP3_image_size);
4947
4948DXDEC S32 AILCALL AIL_enumerate_MP3_frames (MP3_INFO *inspection_state);
4949
4950typedef struct
4951{
4952 //
4953 // File-level data accessible to app
4954 //
4955 // This is valid after AIL_inspect_Ogg() is called (even if the file contains no valid pages)
4956 //
4957
4958 U8 *Ogg_file_image; // Originally passed to AIL_inspect_Ogg()
4959 S32 Ogg_image_size; // Originally passed to AIL_inspect_Ogg()
4960
4961 U8 *start_Ogg_data; // Pointer to start of data area in file
4962 U8 *end_Ogg_data; // Pointer to last valid byte in data area
4963
4964 // Information lifted from the header after AIL_inspect_Ogg() is called.
4965 S32 channel_count;
4966 S32 sample_rate;
4967
4968 //
4969 // Information about current page being inspected, valid if AIL_enumerate_Ogg_pages() returns
4970 // TRUE
4971 //
4972
4973 S32 page_num; // 32-bit page sequence number from OggS header at byte offset 16
4974
4975 S32 sample_count; // Total # of samples already generated by encoder at the time the current page was written
4976
4977 S32 byte_offset; // Offset of page from start_Ogg_data (i.e., suitable for use as loop point)
4978 S32 next_page_expected; // Anticipated offset of next page to be enumerated, if any
4979
4980 //
4981 // Private (undocumented) data used during page enumeration
4982 //
4983
4984 U8 *ptr;
4985 S32 bytes_left;
4986}
4987OGG_INFO;
4988
4989DXDEC void AILCALL AIL_inspect_Ogg (OGG_INFO *inspection_state,
4990 U8 *Ogg_file_image,
4991 S32 Ogg_file_size);
4992
4993DXDEC S32 AILCALL AIL_enumerate_Ogg_pages (OGG_INFO *inspection_state);
4994
4995typedef struct
4996{
4997 const char* file_image;
4998 S32 image_size;
4999
5000 S32 channel_count;
5001 S32 sample_rate;
5002
5003 S32 total_samples;
5004 S32 samples_per_frame;
5005
5006 const char* current_frame;
5007
5008 // output data - byte offset for current frame.
5009 S32 byte_offset;
5010} BINKA_INFO;
5011
5012DXDEC U32 AILCALL AIL_inspect_BinkA(BINKA_INFO* state, char const* file_image, S32 file_size);
5013DXDEC S32 AILCALL AIL_enumerate_BinkA_frames(BINKA_INFO* state);
5014
5015//
5016// RAD room types - currently the same as EAX
5017//
5018
5019enum
5020{
5021 ENVIRONMENT_GENERIC, // factory default
5022 ENVIRONMENT_PADDEDCELL,
5023 ENVIRONMENT_ROOM, // standard environments
5024 ENVIRONMENT_BATHROOM,
5025 ENVIRONMENT_LIVINGROOM,
5026 ENVIRONMENT_STONEROOM,
5027 ENVIRONMENT_AUDITORIUM,
5028 ENVIRONMENT_CONCERTHALL,
5029 ENVIRONMENT_CAVE,
5030 ENVIRONMENT_ARENA,
5031 ENVIRONMENT_HANGAR,
5032 ENVIRONMENT_CARPETEDHALLWAY,
5033 ENVIRONMENT_HALLWAY,
5034 ENVIRONMENT_STONECORRIDOR,
5035 ENVIRONMENT_ALLEY,
5036 ENVIRONMENT_FOREST,
5037 ENVIRONMENT_CITY,
5038 ENVIRONMENT_MOUNTAINS,
5039 ENVIRONMENT_QUARRY,
5040 ENVIRONMENT_PLAIN,
5041 ENVIRONMENT_PARKINGLOT,
5042 ENVIRONMENT_SEWERPIPE,
5043 ENVIRONMENT_UNDERWATER,
5044 ENVIRONMENT_DRUGGED,
5045 ENVIRONMENT_DIZZY,
5046 ENVIRONMENT_PSYCHOTIC,
5047
5048 ENVIRONMENT_COUNT // total number of environments
5049};
5050
5051//
5052// enumerated values for EAX
5053//
5054
5055#ifndef EAX_H_INCLUDED
5056
5057enum
5058{
5059 EAX_ENVIRONMENT_GENERIC, // factory default
5060 EAX_ENVIRONMENT_PADDEDCELL,
5061 EAX_ENVIRONMENT_ROOM, // standard environments
5062 EAX_ENVIRONMENT_BATHROOM,
5063 EAX_ENVIRONMENT_LIVINGROOM,
5064 EAX_ENVIRONMENT_STONEROOM,
5065 EAX_ENVIRONMENT_AUDITORIUM,
5066 EAX_ENVIRONMENT_CONCERTHALL,
5067 EAX_ENVIRONMENT_CAVE,
5068 EAX_ENVIRONMENT_ARENA,
5069 EAX_ENVIRONMENT_HANGAR,
5070 EAX_ENVIRONMENT_CARPETEDHALLWAY,
5071 EAX_ENVIRONMENT_HALLWAY,
5072 EAX_ENVIRONMENT_STONECORRIDOR,
5073 EAX_ENVIRONMENT_ALLEY,
5074 EAX_ENVIRONMENT_FOREST,
5075 EAX_ENVIRONMENT_CITY,
5076 EAX_ENVIRONMENT_MOUNTAINS,
5077 EAX_ENVIRONMENT_QUARRY,
5078 EAX_ENVIRONMENT_PLAIN,
5079 EAX_ENVIRONMENT_PARKINGLOT,
5080 EAX_ENVIRONMENT_SEWERPIPE,
5081 EAX_ENVIRONMENT_UNDERWATER,
5082 EAX_ENVIRONMENT_DRUGGED,
5083 EAX_ENVIRONMENT_DIZZY,
5084 EAX_ENVIRONMENT_PSYCHOTIC,
5085
5086 EAX_ENVIRONMENT_COUNT // total number of environments
5087};
5088
5089#define EAX_REVERBMIX_USEDISTANCE (-1.0F)
5090
5091#endif
5092
5093#define MSS_BUFFER_HEAD (-1)
5094
5095//
5096// Auxiliary 2D interface calls
5097//
5098
5099DXDEC HDIGDRIVER AILCALL AIL_primary_digital_driver (HDIGDRIVER new_primary);
5100
5101//
5102// 3D-related calls
5103//
5104
5105DXDEC S32 AILCALL AIL_room_type (HDIGDRIVER dig,
5106 S32 bus_index);
5107
5108DXDEC void AILCALL AIL_set_room_type (HDIGDRIVER dig,
5109 S32 bus_index,
5110 S32 room_type);
5111
5112DXDEC F32 AILCALL AIL_3D_rolloff_factor (HDIGDRIVER dig);
5113
5114DXDEC void AILCALL AIL_set_3D_rolloff_factor (HDIGDRIVER dig,
5115 F32 factor);
5116
5117DXDEC F32 AILCALL AIL_3D_doppler_factor (HDIGDRIVER dig);
5118
5119DXDEC void AILCALL AIL_set_3D_doppler_factor (HDIGDRIVER dig,
5120 F32 factor);
5121
5122DXDEC F32 AILCALL AIL_3D_distance_factor (HDIGDRIVER dig);
5123
5124DXDEC void AILCALL AIL_set_3D_distance_factor (HDIGDRIVER dig,
5125 F32 factor);
5126
5127DXDEC void AILCALL AIL_set_sample_obstruction (HSAMPLE S,
5128 F32 obstruction);
5129
5130DXDEC void AILCALL AIL_set_sample_occlusion (HSAMPLE S,
5131 F32 occlusion);
5132
5133DXDEC void AILCALL AIL_set_sample_exclusion (HSAMPLE S,
5134 F32 exclusion);
5135
5136DXDEC F32 AILCALL AIL_sample_obstruction (HSAMPLE S);
5137
5138DXDEC F32 AILCALL AIL_sample_occlusion (HSAMPLE S);
5139
5140DXDEC F32 AILCALL AIL_sample_exclusion (HSAMPLE S);
5141
5142EXPGROUP(3D Digital Audio Services)
5143
5144DXDEC EXPAPI void AILCALL AIL_set_sample_3D_volume_falloff(HSAMPLE S, MSSGRAPHPOINT* graph, S32 pointcount);
5145/*
5146 Sets a sample's volume falloff graph.
5147
5148 $:S Sample to affect
5149 $:graph The array of points to use as the graph.
5150 $:pointcount The number of points passed in. Must be less than or equal to MILES_MAX_FALLOFF_GRAPH_POINTS. Passing 0 removes the graph.
5151
5152 This marks a sample as having a volume falloff graph. If a sample has a volume graph, it no
5153 longer attenuates as per the default falloff function, and as such, its "minimum distance" no
5154 longer has any effect. However, the "max distance" still clamps the sample to full attenuation.
5155
5156 A graph with only one point is treated as a line, returning graph[0].Y always.
5157
5158 Otherwise, the graph is evaluated as follows:
5159
5160
5161
5162 The distance to the listener is evaluated.
5163
5164 The two points with X values bounding "distance" are located.
5165
5166 If the distance is past the last graph point, graph[pointcount-1].Y is returned.
5167
5168 If either the output tangent type of the previous point, or the input tangent type of the next point are
5169 MILES_TANGENT_STEP, previous->Y is returned.
5170
5171 Otherwise, the segment is evaluated as a hermite curve. ITX and ITY are ignore if ITYpe is MILES_TANGENT_LINEAR,
5172 and likewise OTX and OTY are ignored if OType is MILES_TANGENT_LINEAR.
5173*/
5174
5175DXDEC EXPAPI void AILCALL AIL_set_sample_3D_lowpass_falloff(HSAMPLE S, MSSGRAPHPOINT* graph, S32 pointcount);
5176/*
5177 Sets a sample's low pass cutoff falloff graph.
5178
5179 $:S Sample to affect
5180 $:graph The array of points to use as the graph.
5181 $:pointcount The number of points passed in. Must be less than or equal to MILES_MAX_FALLOFF_GRAPH_POINTS. Passing 0 removes the graph.
5182
5183 This marks a sample as having a low pass cutoff that varies as a function of distance to the listener. If
5184 a sample has such a graph, $AIL_set_sample_low_pass_cut_off will be called constantly, and thus shouldn't be
5185 called otherwise.
5186
5187 The graph is evaluated the same as $AIL_set_sample_3D_volume_falloff.
5188*/
5189
5190DXDEC EXPAPI void AILCALL AIL_set_sample_3D_exclusion_falloff(HSAMPLE S, MSSGRAPHPOINT* graph, S32 pointcount);
5191/*
5192 Sets a sample's exclusion falloff graph.
5193
5194 $:S Sample to affect
5195 $:graph The array of points to use as the graph.
5196 $:pointcount The number of points passed in. Must be less than or equal to MILES_MAX_FALLOFF_GRAPH_POINTS. Passing 0 removes the graph.
5197
5198 This marks a sample as having an exclusion that varies as a function of distance to the listener. If
5199 a sample has such a graph, auto_3D_wet_atten will be disabled to prevent double affects, as exclusion
5200 affects reverb wet level.
5201
5202 The graph is evaluated the same as $AIL_set_sample_3D_volume_falloff.
5203*/
5204
5205DXDEC EXPAPI void AILCALL AIL_set_sample_3D_spread_falloff(HSAMPLE S, MSSGRAPHPOINT* graph, S32 pointcount);
5206/*
5207 Sets a sample's spread falloff graph.
5208
5209 $:S Sample to affect
5210 $:graph The array of points to use as the graph.
5211 $:pointcount The number of points passed in. Must be less than or equal to MILES_MAX_FALLOFF_GRAPH_POINTS. Passing 0 removes the graph.
5212
5213 This marks a sample as having a spread that varies as a function of distance to the listener. See
5214 $AIL_set_sample_3D_spread.
5215
5216 The graph is evaluated the same as $AIL_set_sample_3D_volume_falloff.
5217*/
5218
5219DXDEC EXPAPI void AILCALL AIL_set_sample_3D_position_segments(HSAMPLE S, MSSVECTOR3D* points, S32 point_count);
5220/*
5221 Sets a sample's position as a series of line segments.
5222
5223 $:S Sample to affect
5224 $:points The 3D points representing the line segments. 0 reverts to classic point based positioning. All
5225 segments are connected - N points represents N - 1 chained line segments.
5226 $:point_count Size of points array. Minimum 2 (unless removing), max MILES_MAX_SEGMENT_COUNT
5227
5228 This marks a sample as having a position that is not a single point. When 3D attenuation is computed,
5229 the closest point to the listener is found by walking each segment. That position is then used in all
5230 other computations (cones, falloffs, etc). Spatialization is done using all segments as a directional
5231 source.
5232
5233 If there is neither spread falloff nor volume falloff specified, spread will be automatically applied
5234 when the listener is within min_distance to the closest point. See $AIL_set_sample_3D_spread_falloff
5235 and $AIL_set_sample_3D_volume_falloff.
5236
5237*/
5238
5239DXDEC EXPAPI void AILCALL AIL_set_sample_3D_spread(HSAMPLE S, F32 spread);
5240/*
5241 Sets a sample's "spread" value.
5242
5243 $:S Sample to affect.
5244 $:spread The value to set the spread to.
5245
5246 Spread is how much the directionality of a sample "spreads" to more speakers - emulating
5247 the effect a sound has when it occupies more than a point source. For instance, a sound
5248 point source that sits directly to the left of the listener would have a very strong left
5249 speaker signal, and a fairly weak right speaker signal. Via spread, the signal would be
5250 more even, causing the source to feel as though it is coming from an area, rather than
5251 a point source.
5252
5253 A spread of 1 will effectively negate any spatialization effects other than distance attenuation.
5254*/
5255
5256DXDEC void AILCALL AIL_set_sample_3D_distances (HSAMPLE S,
5257 F32 max_dist,
5258 F32 min_dist,
5259 S32 auto_3D_wet_atten);
5260
5261
5262DXDEC void AILCALL AIL_sample_3D_distances (HSAMPLE S,
5263 F32 * max_dist,
5264 F32 * min_dist,
5265 S32 * auto_3D_wet_atten);
5266
5267DXDEC void AILCALL AIL_set_sample_3D_cone (HSAMPLE S,
5268 F32 inner_angle,
5269 F32 outer_angle,
5270 F32 outer_volume_level);
5271
5272DXDEC void AILCALL AIL_sample_3D_cone (HSAMPLE S,
5273 F32* inner_angle,
5274 F32* outer_angle,
5275 F32* outer_volume_level);
5276
5277DXDEC void AILCALL AIL_set_sample_3D_position (HSAMPLE obj,
5278 F32 X,
5279 F32 Y,
5280 F32 Z);
5281
5282DXDEC void AILCALL AIL_set_sample_3D_velocity (HSAMPLE obj,
5283 F32 dX_per_ms,
5284 F32 dY_per_ms,
5285 F32 dZ_per_ms,
5286 F32 magnitude);
5287
5288DXDEC void AILCALL AIL_set_sample_3D_velocity_vector (HSAMPLE obj,
5289 F32 dX_per_ms,
5290 F32 dY_per_ms,
5291 F32 dZ_per_ms);
5292
5293DXDEC void AILCALL AIL_set_sample_3D_orientation (HSAMPLE obj,
5294 F32 X_face,
5295 F32 Y_face,
5296 F32 Z_face,
5297 F32 X_up,
5298 F32 Y_up,
5299 F32 Z_up);
5300
5301DXDEC S32 AILCALL AIL_sample_3D_position (HSAMPLE obj,
5302 F32 *X,
5303 F32 *Y,
5304 F32 *Z);
5305
5306DXDEC void AILCALL AIL_sample_3D_velocity (HSAMPLE obj,
5307 F32 *dX_per_ms,
5308 F32 *dY_per_ms,
5309 F32 *dZ_per_ms);
5310
5311DXDEC void AILCALL AIL_sample_3D_orientation (HSAMPLE obj,
5312 F32 *X_face,
5313 F32 *Y_face,
5314 F32 *Z_face,
5315 F32 *X_up,
5316 F32 *Y_up,
5317 F32 *Z_up);
5318
5319DXDEC void AILCALL AIL_update_sample_3D_position (HSAMPLE obj,
5320 F32 dt_milliseconds);
5321
5322DXDEC void AILCALL AIL_set_listener_3D_position (HDIGDRIVER dig,
5323 F32 X,
5324 F32 Y,
5325 F32 Z);
5326
5327DXDEC void AILCALL AIL_set_listener_3D_velocity (HDIGDRIVER dig,
5328 F32 dX_per_ms,
5329 F32 dY_per_ms,
5330 F32 dZ_per_ms,
5331 F32 magnitude);
5332
5333DXDEC void AILCALL AIL_set_listener_3D_velocity_vector (HDIGDRIVER dig,
5334 F32 dX_per_ms,
5335 F32 dY_per_ms,
5336 F32 dZ_per_ms);
5337
5338DXDEC void AILCALL AIL_set_listener_3D_orientation (HDIGDRIVER dig,
5339 F32 X_face,
5340 F32 Y_face,
5341 F32 Z_face,
5342 F32 X_up,
5343 F32 Y_up,
5344 F32 Z_up);
5345
5346DXDEC void AILCALL AIL_listener_3D_position (HDIGDRIVER dig,
5347 F32 *X,
5348 F32 *Y,
5349 F32 *Z);
5350
5351DXDEC void AILCALL AIL_listener_3D_velocity (HDIGDRIVER dig,
5352 F32 *dX_per_ms,
5353 F32 *dY_per_ms,
5354 F32 *dZ_per_ms);
5355
5356DXDEC void AILCALL AIL_listener_3D_orientation (HDIGDRIVER dig,
5357 F32 *X_face,
5358 F32 *Y_face,
5359 F32 *Z_face,
5360 F32 *X_up,
5361 F32 *Y_up,
5362 F32 *Z_up);
5363
5364DXDEC void AILCALL AIL_update_listener_3D_position (HDIGDRIVER dig,
5365 F32 dt_milliseconds);
5366
5367#if defined( HOST_SPU_PROCESS )
5368
5369DXDEC S32 AILCALL MilesStartAsyncThread( S32 thread_num, void const * param );
5370
5371DXDEC S32 AILCALL MilesRequestStopAsyncThread( S32 thread_num );
5372
5373DXDEC S32 AILCALL MilesWaitStopAsyncThread( S32 thread_num );
5374
5375#endif
5376
5377
5378//-----------------------------------------------------------------------------
5379//
5380// MSS 8 Bank API
5381//
5382//-----------------------------------------------------------------------------
5383
5384EXPGROUP(Miles High Level Event System)
5385
5386// misc character maxes.
5387#define MSS_MAX_ASSET_NAME_BYTES 512
5388#define MSS_MAX_PATH_BYTES 512
5389
5390#ifdef DOCS_ONLY
5391
5392EXPTYPE typedef struct MSSSOUNDBANK {};
5393/*
5394 Internal structure.
5395
5396 Use $HMSOUNDBANK instead.
5397*/
5398
5399#endif
5400
5401EXPTYPE typedef struct SoundBank *HMSOUNDBANK;
5402/*
5403 Describes a handle to an open sound bank.
5404
5405 This handle typedef refers to an open soundbank which is usually obtained from the $AIL_add_soundbank function.
5406*/
5407
5408EXPGROUP(highlevel_util)
5409
5410DXDEC EXPAPI HMSOUNDBANK AILCALL AIL_open_soundbank(char const *filename, char const* name);
5411/*
5412 Open a sound bank. If you are using the event execution engine, use the add soundbank function
5413 provided there.
5414
5415 $:return 0 on fail, or a valid HMSOUNDBANK.
5416 $:filename The filename of the soundbank to open.
5417
5418 Opens a sound bank for use with the MSS8 high level functions. The sound bank must be
5419 closed with $AIL_close_soundbank. Use $AIL_add_soundbank if the Miles Event system is used.
5420*/
5421
5422DXDEC EXPAPI void AILCALL AIL_close_soundbank(HMSOUNDBANK bank);
5423/*
5424 Close a soundbank previously opened with $AIL_open_soundbank.
5425
5426 $:bank Soundbank to close.
5427
5428 Close a soundbank previously opened with $AIL_open_soundbank. Presets/events loaded from
5429 this soundbank are no longer valid.
5430*/
5431
5432DXDEC EXPAPI char const * AILCALL AIL_get_soundbank_filename(HMSOUNDBANK bank);
5433/*
5434 Return the filename used to open the given soundbank.
5435
5436 $:bank Soundbank to query.
5437
5438 $:return A pointer to the filename for the given soundbank, or 0 if bank is invalid.
5439
5440 Returns a pointer to the filename for a soundbank. This pointer should not be deleted.
5441*/
5442
5443DXDEC EXPAPI char const * AILCALL AIL_get_soundbank_name(HMSOUNDBANK bank);
5444/*
5445 Return the name of the given soundbank.
5446
5447 $:bank Soundbank to query.
5448
5449 $:return A pointer to the name of the sound bank, or 0 if the bank is invalid.
5450
5451 The name of the bank is the name used in asset names. This is distinct from the
5452 file name of the bank.
5453
5454 The return value should not be deleted.
5455*/
5456
5457DXDEC EXPAPI S32 AILCALL AIL_get_soundbank_mem_usage(HMSOUNDBANK bank);
5458/*
5459 Returns the amount of data used by the soundbank management structures.
5460
5461 $:bank Soundbank to query.
5462 $:return Total memory allocated.
5463
5464 Returns the memory used via AIL_mem_alloc_lock during the creation of this structure.
5465*/
5466
5467DXDEC EXPAPI S32 AILCALL AIL_enumerate_sound_presets(HMSOUNDBANK bank, HMSSENUM* next, char const* list, char const** name);
5468/*
5469 Enumerate the sound presets stored in a soundbank.
5470
5471 $:bank Containing soundbank.
5472 $:next Enumeration token. Prior to first call, initialize to MSS_FIRST
5473 $:list Optional filter. If specified, presets will only enumerate from the given preset sound preset list.
5474 $:name The pointer to the currently enumerated preset name. This should not be deleted.
5475
5476 $:return Returns 0 when enumeration is complete.
5477
5478 Enumerates the sound presets available inside of a bank file. Example usage:
5479
5480 ${
5481 HMSSENUM Token = MSS_FIRST;
5482 const char* PresetName = 0;
5483 while (AIL_enumerate_sound_presets(MyBank, &Token, 0, &PresetName))
5484 {
5485 printf("Found a preset named %s!", PresetName);
5486
5487 $AIL_apply_sound_preset(MySample, MyBank, PresetName);
5488 }
5489 $}
5490
5491 Note that name should NOT be deleted by the caller - this points at memory owned by
5492 Miles.
5493*/
5494
5495DXDEC EXPAPI S32 AILCALL AIL_enumerate_environment_presets(HMSOUNDBANK bank, HMSSENUM* next, char const* list, char const** name);
5496/*
5497 Enumerate the environment presets stored in a soundbank.
5498
5499 $:bank Containing soundbank.
5500 $:next Enumeration token. Prior to first call, initialize to MSS_FIRST
5501 $:list Optional filter. If specified, presets will only enumerate from the given environment preset list.
5502 $:name The pointer to the currently enumerated preset name. This should not be deleted.
5503 $:return Returns 0 when enumeration is complete.
5504
5505 Enumerates the environment presets available inside of a bank file. Example usage:
5506
5507 ${
5508 HMSSENUM Token = MSS_FIRST;
5509 const char* PresetName = 0;
5510 while (AIL_enumerate_environment_presets(MyBank, &Token, 0, &PresetName))
5511 {
5512 printf("Found a preset named %s!", PresetName);
5513
5514 AIL_apply_environment_preset(MyDriver, MyBank, PresetName);
5515 }
5516 $}
5517
5518 Note that name should NOT be deleted by the caller - this points at memory owned by
5519 Miles.
5520*/
5521
5522
5523DXDEC EXPAPI S32 AILCALL AIL_enumerate_sound_assets(HMSOUNDBANK bank, HMSSENUM* next, char const** name);
5524/*
5525 Enumerate sounds stored in a soundbank.
5526
5527 $:bank Containing soundbank.
5528 $:next Enumeration token. Prior to first call, initialize to MSS_FIRST
5529 $:name The pointer to the currently enumerated sound name. This should not be deleted.
5530 $:return Returns 0 when enumeration is complete.
5531
5532 Enumerates the sounds available inside of a bank file. Example usage:
5533
5534 ${
5535 HMSSENUM Token = MSS_FIRST;
5536 const char* SoundName = 0;
5537 while (AIL_enumerate_sound_assets(MyBank, &Token, &SoundName))
5538 {
5539 char filename[MSS_MAX_PATH_BYTES];
5540 AIL_sound_asset_filename(MyBank, SoundName, filename);
5541
5542 printf("Found a sound named %s!", SoundName);
5543
5544 S32* pData = (S32*)AIL_file_read(filename, FILE_READ_WITH_SIZE);
5545 AIL_mem_free_lock(pData);
5546 }
5547 $}
5548
5549 Note that name should NOT be deleted by the caller - this points at memory owned by
5550 Miles.
5551*/
5552
5553DXDEC EXPAPI S32 AILCALL AIL_enumerate_events(HMSOUNDBANK bank, HMSSENUM* next, char const * list, char const ** name);
5554/*
5555 Enumerate the events stored in a soundbank.
5556
5557 $:bank Soundbank to enumerate within.
5558 $:next Enumeration token. Prior to first call, initialize to MSS_FIRST
5559 $:list Optional filter. If specified, event will only enumerate from the given event list.
5560 $:name The pointer to the currently enumerated preset name. This should not be deleted.
5561 $:return Returns 0 when enumeration is complete.
5562
5563 Enumerates the events available inside of a bank file. Example usage:
5564
5565 ${
5566 HMSSENUM Token = MSS_FIRST;
5567 const char* EventName = 0;
5568 while (AIL_enumerate_events(MyBank, &Token, 0, &EventName))
5569 {
5570 printf("Found an event named %s!", EventName);
5571
5572 const U8* EventContents = 0;
5573 AIL_get_event_contents(MyBank, EventName, &EventContents);
5574
5575 AIL_enqueue_event(EventContents, 0, 0, 0, 0);
5576 }
5577 $}
5578
5579 Note that name should NOT be deleted by the caller - this points at memory owned by
5580 Miles.
5581*/
5582
5583DXDEC EXPAPI void* AILCALL AIL_find_environment_preset(HMSOUNDBANK bank, char const *name);
5584/*
5585 Returns the raw environment data associated with the given name.
5586
5587 $:bank The bank to look within
5588 $:name The name of the asset to search for, including bank name.
5589
5590 $:return Raw environment data. This should not be deleted.
5591
5592 This function is designed to be used with $AIL_apply_raw_environment_preset.
5593*/
5594
5595DXDEC EXPAPI void* AILCALL AIL_find_sound_preset(HMSOUNDBANK bank, char const* name);
5596/*
5597 Returns the raw preset data associated with the given name.
5598
5599 $:bank The bank to look within
5600 $:name The name of the asset to search for, including bank name.
5601
5602 $:return Raw preset data. This should not be deleted.
5603
5604 This function is designed to be used with $AIL_apply_raw_sound_preset.
5605*/
5606
5607DXDEC EXPAPI S32 AILCALL AIL_apply_raw_sound_preset(HSAMPLE sample, void* preset);
5608/*
5609 Applies the sound preset to the given sample.
5610
5611 $:sample The sample to modify.
5612 $:preset The raw preset data to apply, returned from $AIL_find_sound_preset
5613
5614 Updates sample properties based on the desired settings specified in the given preset.
5615*/
5616
5617DXDEC EXPAPI S32 AILCALL AIL_apply_sound_preset(HSAMPLE sample, HMSOUNDBANK bank, char const *name);
5618/*
5619 Apply the sound preset to the given sample.
5620
5621 $:sample The sample that will have its properties updated by the preset.
5622 $:bank The sound bank containing the named preset.
5623 $:name The name of the preset to apply.
5624 $:return Returns 0 on fail - check for sample/bank validity, and that the preset is in the correct bank.
5625
5626 This will alter the properties on a given sample, based on the given preset.
5627*/
5628
5629DXDEC EXPAPI S32 AILCALL AIL_unapply_raw_sound_preset(HSAMPLE sample, void* preset);
5630/*
5631 Returns the properties altered by the preset to their default state.
5632
5633 $:sample The sample to update.
5634 $:preset The raw preset data to unapply, returned from $AIL_find_sound_preset
5635*/
5636
5637DXDEC EXPAPI S32 AILCALL AIL_unapply_sound_preset(HSAMPLE sample, HMSOUNDBANK bank, char const *name);
5638/*
5639 Restore the properties affected by the given preset to defaults.
5640
5641 $:sample The sample that will have its properties updated by the preset.
5642 $:bank The sound bank containing the named preset.
5643 $:name The name of the preset to apply.
5644 $:return Returns 0 on fail - check for sample/bank validity, and that the preset is in the correct bank.
5645
5646 Presets may or may not affect any given property. Only the properties affected by the specified
5647 preset will have their values restored to default.
5648*/
5649
5650typedef S32 (*MilesResolveFunc)(void* context, char const* exp, S32 explen, EXPOUT void* output, S32 isfloat);
5651/*
5652 Callback type for resolving variable expressions to values.
5653
5654 $:context Value passed to AIL_resolve_raw_*_preset().
5655 $:exp The string expression to resolve.
5656 $:explen Length of exp.
5657 $:output Pointer to the memory to receive the result value.
5658 $:isfloat nonzero if the output needs to be a float.
5659
5660 The function callback should convert variable expressions in to an output value of the
5661 requested type.
5662*/
5663
5664DXDEC EXPAPI S32 AILCALL AIL_resolve_raw_sound_preset(void* preset, void* context, MilesResolveFunc eval);
5665/*
5666 Compute the value of properties for the current value of variables using the given lookup function.
5667
5668 $:preset The raw preset as returns from $AIL_find_sound_preset.
5669 $:context The context to pass in to the resolution function.
5670 $:eval A function pointer to use for resolving expressions to values.
5671 $:return 0 if the preset is invalid.
5672
5673 This function converts variable expressions that were stored in the preset in to values
5674 that can be used by the event system. The values are stored in the preset itself, all that
5675 has to happen is this is called with a valid resolve function prior to calling
5676 $AIL_apply_raw_sound_preset.
5677*/
5678
5679DXDEC EXPAPI S32 AILCALL AIL_resolve_raw_environment_preset(void* env, MilesResolveFunc eval);
5680/*
5681 Compute the value of properties for the current value of variables using the given lookup function.
5682
5683 $:env The raw preset as returns from $AIL_find_environment_preset.
5684 $:context The context to pass in to the resolution function.
5685 $:eval A function pointer to use for resolving expressions to values.
5686 $:return 0 if the preset is invalid.
5687
5688 This function converts variable expressions that were stored in the environment in to values
5689 that can be used by the event system. The values are stored in the environment itself, all that
5690 has to happen is this is called with a valid resolve function prior to calling
5691 $AIL_apply_raw_environment_preset.
5692*/
5693
5694
5695DXDEC EXPAPI S32 AILCALL AIL_apply_raw_environment_preset(HDIGDRIVER dig, void* environment);
5696/*
5697 Applies the environment to the given driver.
5698
5699 $:dig The driver to modify.
5700 $:environment The raw environment data to apply, returned from $AIL_find_environment_preset
5701
5702 Updates driver properties based on the desired settings specified in the given environment.
5703*/
5704
5705DXDEC EXPAPI S32 AILCALL AIL_apply_environment_preset(HDIGDRIVER dig, HMSOUNDBANK bank, char const *name);
5706/*
5707 Apply the environment preset to the given driver.
5708
5709 $:dig The driver that will have its properties updated by the preset.
5710 $:bank The sound bank containing the named preset.
5711 $:name The name of the preset to apply.
5712 $:return Returns 0 on fail - check for sample/bank validity, and that the preset is in the correct bank.
5713
5714 This will alter properties on a given driver, based on the given preset.
5715*/
5716
5717DXDEC EXPAPI S32 AILCALL AIL_unapply_raw_environment_preset(HDIGDRIVER dig, void* environment);
5718/*
5719 Returns the properties the environment affects to default state.
5720
5721 $:dig The driver to modify.
5722 $:environment The raw environment data to unapply, returned from $AIL_find_environment_preset
5723*/
5724
5725DXDEC EXPAPI S32 AILCALL AIL_unapply_environment_preset(HDIGDRIVER dig, HMSOUNDBANK bank, char const *name);
5726/*
5727 Restore the properties affected by the given preset to defaults.
5728
5729 $:dig The driver that will have its properties updated by the preset.
5730 $:bank The sound bank containing the named preset.
5731 $:name The name of the preset to apply.
5732 $:return Returns 0 on fail - check for sample/bank validity, and that the preset is in the correct bank.
5733
5734 Presets may or may not affect any given property. Only the properties affected by the specified
5735 preset will have its value restored to default.
5736*/
5737
5738EXPTYPE typedef struct _MILESBANKSOUNDINFO
5739{
5740 // If this changes at all, compiled banks must be versioned...
5741 S32 ChannelCount;
5742 U32 ChannelMask;
5743 S32 Rate;
5744 S32 DataLen;
5745 S32 SoundLimit;
5746 S32 IsExternal;
5747 U32 DurationMs;
5748 S32 StreamBufferSize;
5749 S32 IsAdpcm;
5750 S32 AdpcmBlockSize;
5751 F32 MixVolumeDAC;
5752} MILESBANKSOUNDINFO;
5753/*
5754 Structure containing all metadata associated with a sound asset.
5755
5756 $:ChannelCount The number of channels the sound assets contains.
5757 $:ChannelMask The channel mask for the sound asset.
5758 $:Rate The sample rate for the sound asset.
5759 $:DataLen The byte count the asset requires if fully loaded.
5760 $:SoundLimit The maximum number of instances of this sound that is allowed to play at once.
5761 $:IsExternal Nonzero if the sound is stored external to the sound bank. See the eventexternal sample.
5762 $:DurationMs The length of the sound asset, in milliseconds.
5763 $:StreamBufferSize If the sound is played as a stream, this is the buffer to use for this sound.
5764 $:IsAdpcm Nonzero if the asset is an adpcm sound, and needs to be initialized as such.
5765 $:AdpcmBlockSize The adpcm block size if the asset is adpcm encoded.
5766 $:MixVolumeDAC The attenuation to apply to all instances of this sound, as a DAC scalar.
5767
5768 See $AIL_sound_asset_info.
5769*/
5770
5771
5772DXDEC EXPAPI S32 AILCALL AIL_sound_asset_info(HMSOUNDBANK bank, char const* name, char* out_name, MILESBANKSOUNDINFO* out_info);
5773/*
5774 Return the meta data associated with a sound assets in a sound bank.
5775
5776 $:bank The soundbank containing the sound asset.
5777 $:name The name of the sound asset to find.
5778 $:out_name Optional - Pointer to a buffer that is filled with the sound filename to use for loading.
5779 $:out_info Pointer to a $MILESBANKSOUNDINFO structure that is filled with meta data about the sound asset.
5780 $:return Returns the byte size of the buffer required for out_name.
5781
5782 This function must be called in order to resolve the sound asset name to
5783 something that can be used by miles. To ensure safe buffer containment, call
5784 once with out_name as null to get the size needed.
5785
5786 For external deployment see the eventexternal example program.
5787*/
5788
5789DXDEC EXPAPI SINTa AILCALL AIL_get_marker_list(HMSOUNDBANK bank, char const* sound_name);
5790/*
5791 Return an opaque value representing the list of markers attached to a given sound name.
5792
5793 $:bank The bank containing the sound asset.
5794 $:sound_name The name of the sound asset.
5795
5796 $:return on fail/nonexistent list, or a nonzero opaque value to be passed to $AIL_find_marker_in_list.
5797
5798 Returns the marker list for a given sound asset. This value should just be passed directly to $AIL_find_marker_in_list
5799 to retrieve the offset for a marker by name.
5800*/
5801
5802DXDEC EXPAPI S32 AILCALL AIL_find_marker_in_list(SINTa marker_list, char const * marker_name, S32* is_samples);
5803/*
5804 Returns the byte offset into a sample corresponding to the given marker name.
5805
5806 $:marker_list The marker list returned from $AIL_get_marker_list.
5807 $:marker_name The name of the marker to look up.
5808 $:is_samples returns whether the marker is at a sample location instead of a byte location.
5809
5810 $:return -1 if the marker was not found, or the byte offset of the marker.
5811
5812 Looks up an offset to use in functions such as $AIL_set_sample_position. marker_list can be retrieved with
5813 $AIL_get_marker_list.
5814*/
5815
5816// ----------------------------
5817// End MSS8 declarations
5818// ----------------------------
5819
5820//
5821// Event routines
5822//
5823typedef struct _MEMDUMP* HMEMDUMP;
5824#define HMSSEVENTCONSTRUCT HMEMDUMP
5825
5826/*!
5827 function
5828 {
5829 ExcludeOn = 1
5830
5831 Name = "AIL_create_event", "Creates an empty event to be filled with steps."
5832
5833 ReturnType = "HMSSEVENTCONSTRUCT", "An empty event to be passed to the various step addition functions, or 0 if out of memory."
5834
5835 Discussion = "Primarily designed for offline use, this function is the first step in
5836 creating an event that can be consumed by the MilesEvent system. Usage is as follows:
5837
5838 HMSSEVENTCONSTRUCT hEvent = AIL_create_event();
5839
5840 // misc add functions
5841 AIL_add_start_sound_event_step(hEvent, ...);
5842 AIL_add_control_sounds_event_step(hEvent, ...);
5843 // etc
5844
5845 char* pEvent = AIL_close_event(hEvent);
5846
5847 // Do something with the event
5848
5849 AIL_mem_free_lock(pEvent);
5850
5851 Note that if immediately passed to AIL_enqueue_event(), the memory must remain valid until the following
5852 $AIL_complete_event_queue_processing.
5853
5854 Events are generally tailored to the MilesEvent system, even though there is nothing preventing you
5855 from writing your own event system, or creation ui.
5856 "
5857 }
5858*/
5859DXDEC HMSSEVENTCONSTRUCT AILCALL AIL_create_event(void);
5860
5861/*!
5862 function
5863 {
5864 ExcludeOn = 1
5865
5866 Name = "AIL_close_event", "Returns a completed event, ready for enqueueing in to the MilesEvent system."
5867
5868 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to complete."
5869
5870 ReturnType = "char*", "An allocated event string that can be passed to AIL_next_event_step or enqueued in the
5871 MilesEvent system via AIL_enqueue_event."
5872
5873 Discussion = "The returned pointer must be deleted via AIL_mem_free_lock(). Note that if the MilesEvent system
5874 is used, the event pointer must remain valid through the following $AIL_complete_event_queue_processing call."
5875
5876 }
5877*/
5878DXDEC U8* AILCALL AIL_close_event(HMSSEVENTCONSTRUCT i_Event);
5879
5880EXPTYPEBEGIN typedef S32 MILES_START_STEP_EVICTION_TYPE;
5881#define MILES_START_STEP_PRIORITY 0
5882#define MILES_START_STEP_DISTANCE 1
5883#define MILES_START_STEP_VOLUME 2
5884#define MILES_START_STEP_OLDEST 3
5885EXPTYPEEND
5886/*
5887 Determines the behavior of a sound if it encounters a limit trying to play.
5888
5889 $:MILES_START_STEP_PRIORITY Evict a sound less than our priority.
5890 $:MILES_START_STEP_DISTANCE Evict the farthest sound from the listener.
5891 $:MILES_START_STEP_VOLUME Evict the quietest sound after mixing, using the loudest channel as the qualifier.
5892 $:MILES_START_STEP_OLDEST Evict the sound that has been playing the longest.
5893
5894 See also $AIL_add_start_sound_event_step.
5895*/
5896
5897EXPTYPEBEGIN typedef S32 MILES_START_STEP_SELECTION_TYPE;
5898#define MILES_START_STEP_RANDOM 0
5899#define MILES_START_STEP_NO_REPEATS 1
5900#define MILES_START_STEP_IN_ORDER 2
5901#define MILES_START_STEP_RANDOM_ALL_BEFORE_REPEAT 3
5902#define MILES_START_STEP_BLENDED 4
5903#define MILES_START_STEP_SELECT_MASK 0x7
5904#define MILES_START_STEP_SELECT_BITS 3
5905EXPTYPEEND
5906/*
5907 Determines the usage of the sound names list in the $AIL_add_start_sound_event_step.
5908
5909 $:MILES_START_STEP_RANDOM Randomly select from the list, and allow the same
5910 sound to play twice in a row. This is the only selection type that doesn't require
5911 a state variable.
5912 $:MILES_START_STEP_NO_REPEATS Randomly select from the list, but prevent the last sound from being the same.
5913 $:MILES_START_STEP_IN_ORDER Play the list in order, looping.
5914 $:MILES_START_STEP_RANDOM_ALL_BEFORE_REPEAT Randomly select from the list, but don't allow duplicates until all sounds have been played.
5915 $:MILES_START_STEP_BLENDED Play *all* of the sounds, using the state variable as both the variable name to poll,
5916 and the name of the blend function to look up. The blend should have been specified prior to execution of
5917 this step in the runtime, see $AIL_add_setblend_event_step.
5918 $:MILES_START_STEP_SELECT_MASK Expect a value from the game to determine which sound to play, added in to the other selection type.
5919*/
5920
5921/*!
5922 function
5923 {
5924 ExcludeOn = 1
5925
5926 Name = "AIL_add_start_sound_event_step", "Adds a step to a given event to start a sound with the given specifications."
5927
5928 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add the step to."
5929 In = "const char*", "i_SoundNames", "The names and associated weights for the event step to choose from.
5930 If there are multiple names listed, the sound will be chosen at random based on the given weights. This
5931 string is of the form 'BankName1/SoundName1:Weight1:BankName2/SoundName2:Weight2:' etc. The string must always
5932 terminate in a ':'. Weight must be between 0 and 200. To provide a null sound to randomly choose to not play anything, use
5933 an empty string as an entry."
5934
5935 In = "const char*", "i_PresetName", "[optional] The name of the preset, of the form 'PresetList/PresetName'"
5936 In = "U8", "i_PresetIsDynamic", "Nonzero if the preset should poll the value of variables every frame, instead of only when applied."
5937 In = "const char*", "i_EventName", "[optional] The name of the event to execute upon completion of the sound, of the form 'PresetList/PresetName'"
5938 In = "const char*", "i_StartMarker", "[optional] The name of a marker to use as the loop start point."
5939 In = "const char*", "i_EndMarker", "[optional] The name of a marker to use as the loop end point."
5940 In = "const char*", "i_StateVar", "[optional] The name of a variable to use for storing state associated with this start sound step."
5941 In = "char const*", "i_VarInit", "[optional] A list of variable names, mins, and maxes to use for randomizing the sound instance state."
5942 In = "const char*", "i_Labels", "[optional] A comma delimited list of labels to assign to the sound."
5943 In = "U32", "i_Streaming", "If nonzero, the sound will be set up and started as a stream."
5944 In = "U8", "i_CanLoad", "If nonzero, the sound is allowed to hit the disk instead of only accessing cached sounds. If true, this might cause a hitch."
5945 In = "U16", "i_Delay", "The minimum delay in ms to apply to the sound before start."
5946 In = "U16", "i_DelayMax", "The maximum delay in ms to apply to the sound before start."
5947 In = "U8", "i_Priority", "The priority to assign to the sound. If a sound encounters a limit based on its labels, it will evict any sound
5948 with a priority strictly less than the given priority."
5949 In = "U8", "i_LoopCount", "The loop count as per AIL_set_sample_loop_count."
5950 In = "const char*", "i_StartOffset", "[optional] The name of the marker to use as the sound's initial offset."
5951 In = "F32", "i_VolMin", "The min volume value to randomly select for initial volume for the sound. In LinLoud."
5952 In = "F32", "i_VolMax", "The max volume value to randomly select for initial volume for the sound. In LinLoud."
5953 In = "F32", "i_PitchMin", "The min pitch to randomly select from for initial playback. In sT."
5954 In = "F32", "i_PitchMax", "The max pitch to randomly select from for initial playback. In sT."
5955 In = "F32", "i_FadeInTime", "The time to fade the sound in over. Interpolation is linear in loudness."
5956 In = "U8", "i_EvictionType", "The basis for deciding what sound will get kicked out if a limit is hit when trying to play this sound. See $MILES_START_STEP_EVICTION_TYPE."
5957 In = "U8", "i_SelectType", "The method to use for selecting the sound to play from the sound name list. See $MILES_START_SOUND_SELECTION_TYPE."
5958
5959 ReturnType = "S32", "Returns 1 on success."
5960
5961 Discussion = "Adds an event that can start a sound. If the sound names list contains multiple entries, one will be selected
5962 randomly based on the given weights and the selection type. Weights are effectively ratios for likelihood. A sound with 100 weight will be twice as likely
5963 as a sound with 50 weight. Some times you may want to have an event that only *might* play a sound. To do this, add a empty sound name
5964 with an associated weight.
5965 "
5966 }
5967*/
5968DXDEC
5969S32
5970AILCALL
5971AIL_add_start_sound_event_step(
5972 HMSSEVENTCONSTRUCT i_Event,
5973 const char* i_SoundNames,
5974 const char* i_PresetName,
5975 U8 i_PresetIsDynamic,
5976 const char* i_EventName,
5977 const char* i_StartMarker, const char* i_EndMarker,
5978 char const* i_StateVar, char const* i_VarInit,
5979 const char* i_Labels, U32 i_Streaming, U8 i_CanLoad,
5980 U16 i_Delay, U16 i_DelayMax, U8 i_Priority, U8 i_LoopCount,
5981 const char* i_StartOffset,
5982 F32 i_VolMin, F32 i_VolMax, F32 i_PitchMin, F32 i_PitchMax,
5983 F32 i_FadeInTime,
5984 U8 i_EvictionType,
5985 U8 i_SelectType
5986 );
5987
5988/*!
5989 function
5990 {
5991 ExcludeOn = 1
5992
5993 Name = "AIL_add_cache_sounds_event_step", "Adds a step to an event to load a list of sounds in to memory for play."
5994
5995 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
5996 In = "const char*", "bankName", "The bank filename containing all of the sounds."
5997 In = "const char*", "i_Sounds", "A list of colon separated sounds to load from the bank file."
5998
5999 ReturnType = "S32", "Returns 1 on success."
6000
6001 Discussion = "In general events are not allowed to hit the disk in order to prevent unexpected hitching during
6002 gameplay. In order to facilitate that, sounds need to be preloaded by this event. Each cache step can only
6003 load sounds from a single bank file, so for multiple bank files, multiple steps will be needed.
6004
6005 In order to release the data loaded by this event, AIL_add_uncache_sounds_event_step() needs to
6006 be called with the same parameters.
6007
6008 If you are using MilesEvent, the data is refcounted so the sound will not be freed until all
6009 samples using it complete."
6010 }
6011*/
6012DXDEC
6013S32
6014AILCALL
6015AIL_add_cache_sounds_event_step(
6016 HMSSEVENTCONSTRUCT i_Event, const char* bankName, const char* i_Sounds);
6017
6018
6019/*!
6020 function
6021 {
6022 ExcludeOn = 1
6023
6024 Name = "AIL_add_uncache_sounds_event_step", "Adds a step to an event to free a list of sounds previously loaded in to memory for play."
6025
6026 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6027 In = "const char*", "bankName", "The bank filename containing all of the sounds."
6028 In = "const char*", "i_Sounds", "A list of colon separated sounds from the bank file to uncache."
6029
6030 ReturnType = "S32", "Returns 1 on success."
6031
6032 Discussion = "This event released sounds loaded via AIL_add_cache_sounds_event_step()"
6033 }
6034*/
6035DXDEC
6036S32
6037AILCALL
6038AIL_add_uncache_sounds_event_step(
6039 HMSSEVENTCONSTRUCT i_Event, const char* bankName, const char* i_Sounds);
6040
6041
6042EXPTYPEBEGIN typedef S32 MILES_CONTROL_STEP_TYPE;
6043#define MILES_CONTROL_STEP_STOP 3
6044#define MILES_CONTROL_STEP_STOP_NO_EVENTS 4
6045#define MILES_CONTROL_STEP_PASS 0
6046#define MILES_CONTROL_STEP_PAUSE 1
6047#define MILES_CONTROL_STEP_RESUME 2
6048#define MILES_CONTROL_STEP_STOP_FADE 5
6049
6050EXPTYPEEND
6051/*
6052 Determines how the playhead is adjusted during a $AIL_add_control_sounds_event_step.
6053
6054 $:MILES_CONTROL_STEP_STOP Stop the affected sounds.
6055 $:MILES_CONTROL_STEP_PASS Do not change the playhead.
6056 $:MILES_CONTROL_STEP_PAUSE Pause the affected sounds.
6057 $:MILES_CONTROL_STEP_RESUME Resume the affected sounds.
6058 $:MILES_CONTROL_STEP_STOP_NO_EVENTS Stop the affected sounds, and prevent their completion events from playing.
6059 $:MILES_CONTROL_STEP_STOP_FADE Stop the sound after fading the sound out linearly in loudness.
6060*/
6061
6062#define MILES_CONTROL_STEP_IGNORELOOP 255
6063
6064/*!
6065 function
6066 {
6067 ExcludeOn = 1
6068
6069 Name = "AIL_add_control_sounds_event_step", "Adds a step to an event to control sample playback by label."
6070
6071 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6072 In = "const char*", "i_Labels", "[optional] A comma seperated list of labels to control."
6073 In = "const char*", "i_MarkerStart", "[optional] If exists, sets the loop start to the marker's offset."
6074 In = "const char*", "i_MarkerEnd", "[optional] If exists, sets the loop end to the marker's offset."
6075 In = "const char*", "i_Position", "[optional] If exists, sets the current playback position to the marker's offset."
6076 In = "const char*", "i_PresetName", "[optional] The name of the preset to apply, of the form Bank/PresetList/PresetName."
6077 In = "U8", "i_PresetApplyType", "If nonzero, the preset is applied dynamically(the variables are polled every frame)."
6078 In = "U8", "i_LoopCount", "If the loop count is not to be affected, pass MILES_CONTROL_STEP_IGNORELOOP. Otherwise, the sample's loop count will be set to this value."
6079 In = "U8", "i_Type", "The control type requested. See $MILES_CONTROL_STEP_TYPE."
6080
6081 ReturnType = "S32", "Returns 1 on success."
6082
6083 Discussion = "Controls playback of current instances. The sounds are matched either on name or label. If
6084 i_Labels is null, all sounds will be controlled.
6085 "
6086 }
6087*/
6088DXDEC
6089S32
6090AILCALL
6091AIL_add_control_sounds_event_step(
6092 HMSSEVENTCONSTRUCT i_Event,
6093 const char* i_Labels, const char* i_MarkerStart, const char* i_MarkerEnd, const char* i_Position,
6094 const char* i_PresetName,
6095 U8 i_PresetApplyType,
6096 F32 i_FadeOutTime,
6097 U8 i_LoopCount, U8 i_Type);
6098
6099
6100/*!
6101 function
6102 {
6103 ExcludeOn = 1
6104
6105 Name = "AIL_add_apply_environment_event_step", "Adds a step to an event to apply an environment preset."
6106
6107 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6108 In = "const char*", "i_EnvName", "The name of the environment preset to apply, of the form EnvList/EnvName."
6109 In = "U8", "i_IsDynamic", "If nonzero, any variables in the environment are polled every frame."
6110
6111 ReturnType = "S32", "Returns 1 on success."
6112
6113 Discussion = "Applies the specified environment preset to the current HDIGDRIVER."
6114 }
6115*/
6116DXDEC S32 AILCALL AIL_add_apply_environment_event_step(HMSSEVENTCONSTRUCT i_Event, const char* i_EnvName, U8 i_IsDynamic);
6117
6118/*!
6119 function
6120 {
6121 ExcludeOn = 1
6122
6123 Name = "AIL_add_comment_event_step", "Adds a step that represents a comment to the user of the editing tool."
6124
6125 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6126 In = "const char*", "i_Comment", "A string to display in the editing tool."
6127
6128 ReturnType = "S32", "Returns 1 on success."
6129
6130 Discussion = "This event is ignored in the runtime, and only exist for editing convenience."
6131 }
6132*/
6133DXDEC S32 AILCALL AIL_add_comment_event_step(HMSSEVENTCONSTRUCT i_Event, const char* i_Comment);
6134
6135EXPTYPEBEGIN typedef S32 MILES_RAMP_TYPE;
6136#define MILES_RAMPTYPE_VOLUME 0
6137#define MILES_RAMPTYPE_WET 1
6138#define MILES_RAMPTYPE_LOWPASS 2
6139#define MILES_RAMPTYPE_RATE 3
6140EXPTYPEEND
6141/*
6142 The different values the ramps can affect.
6143
6144 $:MILES_RAMPTYPE_VOLUME The ramp will adjust the sample's volume, and will interpolate in loudness level. Target is in dB.
6145 $:MILES_RAMPTYPE_WET The ramp will affect the sample's reverb wet level, and will interpolate in loudness. Target is in dB.
6146 $:MILES_RAMPTYPE_LOWPASS The ramp will affect the sample's low pass cutoff. Interpolation and target are in Hz.
6147 $:MILES_RAMPTYPE_RATE The ramp will affect the sample's playback rate. Interpolation and target are in sT.
6148*/
6149
6150EXPTYPEBEGIN typedef S32 MILES_INTERP_TYPE;
6151#define MILES_INTERP_LINEAR 0
6152#define MILES_INTERP_EXP 1
6153#define MILES_INTERP_SCURVE 2
6154EXPTYPEEND
6155/*
6156 The different ways the interpolation occurs for a ramp.
6157
6158 $:MILES_INTERP_LINEAR The ramp will lerp between the current value and the target.
6159 $:MILES_INTERP_EXP The ramp will move toward the target slowly at first, then faster as it closes on its total time.
6160 $:MILES_INTERP_SCURVE The ramp will quickly move to about halfway, then slowly move, then move more quickly as it ends.
6161*/
6162
6163DXDEC EXPAPI S32 AILCALL AIL_add_ramp_event_step(
6164 HMSSEVENTCONSTRUCT i_Event, char const* i_Name, char const* i_Labels,
6165 F32 i_Time, char const* i_Target, U8 i_Type, U8 i_ApplyToNew, U8 i_InterpolationType);
6166/*
6167 Add an event step that updates or creates a new ramp in the runtime.
6168
6169 $:i_Event The event to add the step to.
6170 $:i_Name The name of the ramp. If this name already exists, the ramp will shift its target to the new value.
6171 $:i_Labels The label query determining the sounds the ramp will affect.
6172 $:i_Time The length the time in seconds the ramp will take to reach its target.
6173 $:i_Target The target value, or a variable expression representing the target value. The target's type is
6174 dependent on i_Type.
6175 $:i_Type One of the $MILES_RAMP_TYPE values.
6176 $:i_ApplyToNew If 1, the ramp will affect sounds that start after the ramp is created. If not, it will only affect sounds that
6177 are playing when the ramp is created. This value can not be changed once the ramp has been created.
6178 $:i_InterpolationType The method the ramp will affect the target values. One of $MILES_INTERP_TYPE values.
6179
6180 Ramps are means of interpolating aspects of samples. They are removed from the system if they are targeted to
6181 a value for their type that is a non-op - meaning 0 dB, 0 sT, or >24000 Hz.
6182
6183 Ramps use the current value as the start point for the interpolation. They stay at the target point,
6184 so you can use the same ramp name to adjust a sound's volume down, and later ramp it back up.
6185*/
6186
6187DXDEC EXPAPI S32 AILCALL AIL_add_setblend_event_step(HMSSEVENTCONSTRUCT i_Event,
6188 char const* i_Name, S32 i_SoundCount, F32 const* i_InMin, F32 const* i_InMax,
6189 F32 const* i_OutMin, F32 const* i_OutMax, F32 const* i_MinP, F32 const* i_MaxP);
6190/*
6191 Defines a named blend function to be referenced by a blended sound later.
6192
6193 $:i_Event The event to add the step to.
6194 $:i_Name The name of the blend. This is the name that will be
6195 referenced by the state variable in start sound, as well as the variable name
6196 to set by the game to update the blend for an instance.
6197 $:i_SoundCount The number of sounds this blend will affect. Max 10.
6198 $:i_InMin Array of length i_SoundCount representing the value of the blend variable the sound will start to fade in.
6199 $:i_InMax Array of length i_SoundCount representing the value of the blend variable the sound will reach full volume.
6200 $:i_OutMin Array of length i_SoundCount representing the value of the blend variable the sound will start to fade out.
6201 $:i_OutMax Array of length i_SoundCount representing the value of the blend variable the sound will cease to be audible.
6202 $:i_MinP Array of length i_SoundCount representing the pitch of the sound when it starts to fade in.
6203 $:i_MaxP Array of length i_SoundCount representing the pitch of the sound when it has completed fading out.
6204
6205 This step only sets up the lookup for when a blended sound is actually started. When a blended sound plays, every frame it
6206 polls its state variable, then searches for a blend of the same name. If it finds both, then it uses its index in
6207 the start sounds list to find its relevant values from the blended sound definition.
6208
6209 Once it has the correct values, it uses them to affect the sample as stated in the parameter docs above.
6210*/
6211
6212/*!
6213 function
6214 {
6215 ExcludeOn = 1
6216
6217 Name = "AIL_add_sound_limit_event_step", "Adds a step that defines the maximum number of playing sounds per label."
6218
6219 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6220 In = "const char*", "i_SoundLimits", "A string of the form `"label count:anotherlabel count`"."
6221
6222 ReturnType = "S32", "Returns 1 on success."
6223
6224 Discussion = "Defines limits for instances of sounds on a per label basis. Sounds with multiple labels
6225 must fit under the limits for all of their labels. By default sounds are not limited other than the
6226 Miles max sample count."
6227 }
6228*/
6229DXDEC S32 AILCALL
6230AIL_add_sound_limit_event_step(HMSSEVENTCONSTRUCT i_Event, char const* i_LimitName, const char* i_SoundLimits);
6231
6232/*!
6233 function
6234 {
6235 ExcludeOn = 1
6236
6237 Name = "AIL_add_persist_preset_event_step", "Adds a preset that applies to current sound instances, and continues to be applied to new sounds as they are started."
6238 In = "HMSSEVENTCONSTRUCT", "i_Event", "The event to add on to."
6239 In = "const char*", "i_PresetName", "The name of the preset, of the form PresetList/PresetName. See discussion."
6240 In = "const char*", "i_PersistName", "The name of this persisted preset, for future removal."
6241 In = "const char*", "i_Labels", "The labels to apply this preset to."
6242 In = "U8", "i_IsDynamic", "If nonzero, the preset polls its variables every frame."
6243
6244 ReturnType = "S32", "Returns 1 on success."
6245
6246 Discussion = "Defines a preset by name that remains in the system, testing against all started sounds for label match. If a
6247 match occurs, then the preset is applied to the new sound, before the preset specified in the startsound step itself.
6248
6249 In order to remove a persisted preset, refer to it by name, but leave all other parameters null.
6250
6251 Example:
6252
6253 // Persist a preset for players.
6254 AIL_add_persist_preset_event_step(hEvent, , `"Bank/PlayerEffects/Underwater`", `"Underwater`", `"player`");
6255
6256 // Remove the above preset.
6257 AIL_add_persist_preset_event_step(hEvent, 0, `"Underwater`", 0);"
6258 }
6259*/
6260DXDEC S32 AILCALL
6261AIL_add_persist_preset_event_step(HMSSEVENTCONSTRUCT i_Event, const char* i_PresetName, const char* i_PersistName,
6262 const char* i_Labels, U8 i_IsDynamic
6263 );
6264
6265DXDEC EXPAPI S32 AILCALL AIL_get_event_contents(HMSOUNDBANK bank, char const * name, U8 const** event);
6266/*
6267 Return the event data for an event, by name.
6268
6269 $:bank Soundbank containing the event.
6270 $:name Name of the event to retrieve.
6271 $:event Returns an output pointer to the event contents. Note that this string isn't null terminated, and
6272 thus shouldn't be checked via strlen, etc.
6273 $:return Returns 0 on fail.
6274
6275 Normally, event contents are meant to be handled by the Miles high-level system via $AIL_enqueue_event,
6276 rather than inspected directly.
6277*/
6278
6279DXDEC EXPAPI S32 AILCALL AIL_add_clear_state_event_step(HMSSEVENTCONSTRUCT i_Event);
6280/*
6281 Clears all persistent state in the runtime.
6282
6283 $:i_Event The event to add the step to.
6284
6285 This removes all state that can stick around after an event in done executing. Ramps, Blends, Persisted
6286 Preset, etc.
6287*/
6288
6289DXDEC EXPAPI S32 AILCALL AIL_add_exec_event_event_step(HMSSEVENTCONSTRUCT i_Event, char const* i_EventName);
6290/*
6291 Adds a step to run another named event.
6292
6293 $:i_Event The event to add the step to.
6294 $:i_EventName The name of the event, of the form "Bank/Path/To/Event".
6295
6296 When this step is encountered, the event is enqueued, so it will be executed the following frame (currently). It has the same parent
6297 event mechanics as a completion event, so the QueuedId for a sound started by it will be for the event
6298 that fired this step.
6299*/
6300
6301
6302DXDEC EXPAPI S32 AILCALL AIL_add_enable_limit_event_step(HMSSEVENTCONSTRUCT i_Event, char const* i_LimitName);
6303/*
6304 Adds a step to set the currently active limit.
6305
6306 $:i_Event The event to add the step to.
6307 $:i_EventName The name of the limit, as defined by a set_limits event.
6308
6309*/
6310
6311DXDEC EXPAPI S32 AILCALL AIL_add_set_lfo_event_step(HMSSEVENTCONSTRUCT i_Event, char const* i_Name, char const* i_Base, char const* i_Amp, char const* i_Freq, S32 i_Invert, S32 i_Polarity, S32 i_Waveform, S32 i_DutyCycle, S32 i_IsLFO);
6312/*
6313 Adds a step to define a variable that oscillates over time.
6314
6315 $:i_Event The event to add the step to.
6316 $:i_Name The nane of the variable to oscillate.
6317 $:i_Base The value to oscillate around, or a variable name to use as the base.
6318 $:i_Amp The maximum value to reach, or a variable name to use as the amplitude.
6319 $:i_Freq The rate at which the oscillation occurs, or a variable name to use as the rate. Rate should not exceed game tick rate / 2.
6320 $:i_Invert Whether the waveform should be inverted.
6321 $:i_Polarity Bipolar (1) or Unipolar (0) - whether the waveform goes around the base or only above it.
6322 $:i_Waveform Sine wave (0), Triangle (1), Saw (2), or Square(3)
6323 $:i_DutyCycle Only valid for square, determines what percent of the wave is "on". (0-100)
6324 $:i_IsLFO If zero, Base is the default value to assign the variable when the settings are applied, and the rest of the parameters are ignored.
6325*/
6326
6327DXDEC EXPAPI S32 AILCALL AIL_add_move_var_event_step(HMSSEVENTCONSTRUCT i_Event, char const* i_Name, const F32 i_Times[2], const S32 i_InterpolationTypes[2], const F32 i_Values[3]);
6328/*
6329 Adds a step to set and move a variable over time on a curve.
6330
6331 $:i_Event The event to add the step to.
6332 $:i_Name The variable to move.
6333 $:i_Times The midpoint and final times for the curves
6334 $:i_InterpolationTypes The curve type for the two curves - Curve In (0), Curve Out (1), S-Curve (2), Linear (3)
6335 $:i_Values The initial, midpoint, and final values for the variable.
6336
6337 The variable is locked to this curve over the timeperiod - no interpolation from a previous value is done.
6338
6339 If an existing move var exists when the new one is added, the old one is replaced.
6340*/
6341
6342enum EVENT_STEPTYPE
6343{
6344 EVENT_STEPTYPE_STARTSOUND = 1,
6345 EVENT_STEPTYPE_CONTROLSOUNDS,
6346 EVENT_STEPTYPE_APPLYENV,
6347 EVENT_STEPTYPE_COMMENT,
6348 EVENT_STEPTYPE_CACHESOUNDS,
6349 EVENT_STEPTYPE_PURGESOUNDS,
6350 EVENT_STEPTYPE_SETLIMITS,
6351 EVENT_STEPTYPE_PERSIST,
6352 EVENT_STEPTYPE_VERSION,
6353 EVENT_STEPTYPE_RAMP,
6354 EVENT_STEPTYPE_SETBLEND,
6355 EVENT_STEPTYPE_CLEARSTATE,
6356 EVENT_STEPTYPE_EXECEVENT,
6357 EVENT_STEPTYPE_ENABLELIMIT,
6358 EVENT_STEPTYPE_SETLFO,
6359 EVENT_STEPTYPE_MOVEVAR
6360};
6361
6362//! Represents an immutable string that is not null terminated, and shouldn't be deleted.
6363struct _MSSSTRINGC
6364{
6365 const char* str;
6366 S32 len;
6367};
6368typedef struct _MSSSTRINGC MSSSTRINGC;
6369
6370
6371/*!
6372 Represents a single step that needs to be executed for an event.
6373
6374 All of the members in the structures share the same definition as
6375 their counterpart params in the functions that added them during
6376 event construction.
6377*/
6378struct EVENT_STEP_INFO
6379{
6380 //! type controls which struct in the union is accessed.
6381 enum EVENT_STEPTYPE type;
6382 union
6383 {
6384 struct
6385 {
6386 MSSSTRINGC soundname;
6387 MSSSTRINGC presetname;
6388 MSSSTRINGC eventname;
6389 MSSSTRINGC labels;
6390 MSSSTRINGC markerstart;
6391 MSSSTRINGC markerend;
6392 MSSSTRINGC startoffset;
6393 MSSSTRINGC statevar;
6394 MSSSTRINGC varinit;
6395 U32 stream;
6396 F32 volmin,volmax,pitchmin,pitchmax;
6397 F32 fadeintime;
6398 U16 delaymin;
6399 U16 delaymax;
6400 U8 canload;
6401 U8 priority;
6402 U8 loopcount;
6403 U8 evictiontype;
6404 U8 selecttype;
6405 U8 presetisdynamic;
6406 } start;
6407
6408 struct
6409 {
6410 MSSSTRINGC labels;
6411 MSSSTRINGC markerstart;
6412 MSSSTRINGC markerend;
6413 MSSSTRINGC position;
6414 MSSSTRINGC presetname;
6415 F32 fadeouttime;
6416 U8 presetapplytype;
6417 U8 loopcount;
6418 U8 type;
6419 } control;
6420
6421 struct
6422 {
6423 MSSSTRINGC envname;
6424 U8 isdynamic;
6425 } env;
6426
6427 struct
6428 {
6429 MSSSTRINGC comment;
6430 } comment;
6431
6432 struct
6433 {
6434 MSSSTRINGC lib;
6435 const char** namelist;
6436 S32 namecount;
6437 } load;
6438
6439 struct
6440 {
6441 MSSSTRINGC limits;
6442 MSSSTRINGC name;
6443 } limits;
6444
6445 struct
6446 {
6447 MSSSTRINGC name;
6448 MSSSTRINGC presetname;
6449 MSSSTRINGC labels;
6450 U8 isdynamic;
6451 } persist;
6452
6453 struct
6454 {
6455 MSSSTRINGC name;
6456 MSSSTRINGC labels;
6457 MSSSTRINGC target;
6458 F32 time;
6459 U8 type;
6460 U8 apply_to_new;
6461 U8 interpolate_type;
6462 } ramp;
6463
6464 struct
6465 {
6466 MSSSTRINGC name;
6467 F32 inmin[10];
6468 F32 inmax[10];
6469 F32 outmin[10];
6470 F32 outmax[10];
6471 F32 minp[10];
6472 F32 maxp[10];
6473 U8 count;
6474 } blend;
6475
6476 struct
6477 {
6478 MSSSTRINGC eventname;
6479 } exec;
6480
6481 struct
6482 {
6483 MSSSTRINGC limitname;
6484 } enablelimit;
6485
6486 struct
6487 {
6488 MSSSTRINGC name;
6489 MSSSTRINGC base;
6490 MSSSTRINGC amplitude;
6491 MSSSTRINGC freq;
6492 S32 invert;
6493 S32 polarity;
6494 S32 waveform;
6495 S32 dutycycle;
6496 S32 islfo;
6497 } setlfo;
6498
6499 struct
6500 {
6501 MSSSTRINGC name;
6502 F32 time[2];
6503 S32 interpolate_type[2];
6504 F32 value[3];
6505 } movevar;
6506 };
6507};
6508
6509/*!
6510 function
6511 {
6512 ExcludeOn = 1
6513
6514 Name = "AIL_next_event_step", "Retrieves the next step in the event buffer, parsing it in to a provided buffer."
6515
6516 In = "const U8*", "i_EventString", "The event returned by $AIL_close_event, or a previous call to $AIL_next_event_step"
6517 Out = "const EVENT_STEP_INFO*", "o_Step", "A pointer to the step struct will be stored here."
6518 In = "void*", "i_Buffer", "A working buffer for the function to use for parsing."
6519 In = "S32", "i_BufferSize", "The size in bytes of the working buffer."
6520
6521 ReturnType = "U8 char*", "Returns 0 on fail or when the event string has been exhausted of steps. Otherwise, returns
6522 the string location of the next event step in the buffer."
6523
6524 Discussion = "This function parses the event string in to a struct for usage by the user. This function should only be
6525 used by the MilesEvent system. It returns the pointer to the next step to be passed to this function to get the
6526 next step. In this manner it can be used in a loop:
6527
6528 // Create an event to stop all sounds.
6529 HMSSEVENTCONSTRUCT hEvent = AIL_create_event();
6530 AIL_add_control_sound_event_step(hEvent, 0, 0, 0, 0, 0, 0, 255, 3);
6531 char* pEvent = AIL_close_event(hEvent);
6532
6533 char EventBuffer[4096];
6534 EVENT_STEP_INFO* pStep = 0;
6535 char* pCurrentStep = pEvent;
6536
6537 while (pCurrentStep)
6538 {
6539 pStep = 0;
6540 pCurrentStep = AIL_next_event_step(pCurrentStep, &pStep, EventBuffer, 4096);
6541 if (pStep == 0)
6542 {
6543 // Error, or an empty event. If $AIL_last_error is an empty string, then it was an empty event.
6544 break;
6545 }
6546
6547 // Handle event step.
6548 switch (pStep->type)
6549 {
6550 default: break;
6551 }
6552 }
6553
6554 AIL_mem_free_lock(pEvent);
6555 "
6556 }
6557*/
6558DXDEC const U8* AILCALL AIL_next_event_step(const U8* i_EventString, struct EVENT_STEP_INFO** o_Step, void* i_Buffer, S32 i_BufferSize);
6559
6560
6561// Old style names.
6562#define AIL_find_event MilesFindEvent
6563#define AIL_clear_event_queue MilesClearEventQueue
6564#define AIL_register_random MilesRegisterRand
6565#define AIL_enumerate_sound_instances MilesEnumerateSoundInstances
6566#define AIL_enumerate_preset_persists MilesEnumeratePresetPersists
6567#define AIL_enqueue_event MilesEnqueueEvent
6568#define AIL_enqueue_event_system MilesEnqueueEventContext
6569#define AIL_enqueue_event_by_name MilesEnqueueEventByName
6570#define AIL_begin_event_queue_processing MilesBeginEventQueueProcessing
6571#define AIL_complete_event_queue_processing MilesCompleteEventQueueProcessing
6572#define AIL_startup_event_system MilesStartupEventSystem
6573#define AIL_shutdown_event_system MilesShutdownEventSystem
6574#define AIL_add_soundbank MilesAddSoundBank
6575#define AIL_release_soundbank MilesReleaseSoundBank
6576#define AIL_set_sound_label_limits MilesSetSoundLabelLimits
6577#define AIL_text_dump_event_system MilesTextDumpEventSystem
6578#define AIL_event_system_state MilesGetEventSystemState
6579#define AIL_get_event_length MilesGetEventLength
6580#define AIL_stop_sound_instances MilesStopSoundInstances
6581#define AIL_pause_sound_instances MilesPauseSoundInstances
6582#define AIL_resume_sound_instances MilesResumeSoundInstances
6583#define AIL_start_sound_instance MilesStartSoundInstance
6584#define AIL_set_event_error_callback MilesSetEventErrorCallback
6585#define AIL_set_event_bank_functions MilesSetBankFunctions
6586#define AIL_get_event_bank_functions MilesGetBankFunctions
6587
6588#define AIL_set_variable_int MilesSetVarI
6589#define AIL_set_variable_float MilesSetVarF
6590#define AIL_variable_int MilesGetVarI
6591#define AIL_variable_float MilesGetVarF
6592
6593#define AIL_set_sound_start_offset MilesSetSoundStartOffset
6594#define AIL_requeue_failed_asyncs MilesRequeueAsyncs
6595#define AIL_add_event_system MilesAddEventSystem
6596
6597#define AIL_audition_local_host MilesAuditionLocalHost
6598#define AIL_audition_connect MilesAuditionConnect
6599#define AIL_audition_startup MilesAuditionStartup
6600#define AIL_audition_shutdown MilesAuditionShutdown
6601EXPGROUP(Miles High Level Event System)
6602
6603EXPTYPE typedef void* HEVENTSYSTEM;
6604/*
6605 The type used to distinguish between running event systems.
6606
6607 Only used if multiple event systems are running. See the eventmultiple example.
6608*/
6609
6610DXDEC EXPAPI HEVENTSYSTEM AILCALL AIL_startup_event_system(HDIGDRIVER dig, S32 command_buf_len, EXPOUT char* memory_buf, S32 memory_len);
6611/*
6612 Initializes the Miles Event system and associates it with an open digital driver.
6613
6614 $:dig The digital sound driver that this event system should use.
6615 $:command_buf_len An optional number of bytes to use for the command buffer. If you pass 0, a reasonable default will be used (currently 5K).
6616 $:memory_buf An optional pointer to a memory buffer buffer that the event system will use for all event allocations.
6617 Note that the sound data itself is not stored in this buffer - it is only for internal buffers, the command buffer, and instance data.
6618 Use 0 to let Miles to allocate this buffer itself.
6619 $:memory_len If memory_buf is non-null, then this parameter provides the length. If memory_buf is null, the Miles will
6620 allocate this much memory for internal buffers. If both memory_buf and memory_len are null, the Miles will allocate reasonable default (currently 64K).
6621 $:return Returns 0 on startup failure.
6622
6623 This function starts up the Miles Event System, which is used to trigger events throughout your game.
6624 You call it after $AIL_open_digital_driver.
6625*/
6626
6627DXDEC EXPAPI HEVENTSYSTEM AILCALL AIL_add_event_system(HDIGDRIVER dig);
6628/*
6629 Creates an additional event system attached to a different driver, in the event that you need to trigger events
6630 tied to different sound devices.
6631
6632 $:dig The digital sound driver to attach the new event system to.
6633 $:return A handle to the event system to use in various high level functions.
6634
6635 Both systems will access the same set of loaded soundbanks, and are updated when $AIL_begin_event_queue_processing is called.
6636
6637 To enqueue events to the new system, use $AIL_enqueue_event_system.
6638
6639 To iterate the sounds for the new system, pass the $HEVENTSYSTEM as the first parameter to $AIL_enumerate_sound_instances.
6640
6641 To access or set global variables for the new system, pass the $HEVENTSYSTEM as the context in the variable access functions.
6642
6643 See also the <i>eventmultiple.cpp</i> example program.
6644*/
6645
6646DXDEC EXPAPI void AILCALL AIL_shutdown_event_system( void );
6647/*
6648 Shuts down the Miles event system.
6649
6650 This function will closes everything in the event system - it ignores reference counts. It will free
6651 all event memory, sound banks, and samples used by the system.
6652*/
6653
6654DXDEC EXPAPI HMSOUNDBANK AILCALL AIL_add_soundbank(char const * filename, char const* name);
6655/*
6656 Open and add a sound bank for use with the event system.
6657
6658 $:filename Filename of the bank to load.
6659 $:name The name of the soundbank to load - this is only used for auditioning.
6660 $:return The handle to the newly loaded soundbank (zero on failure).
6661
6662 This function opens the sound bank and makes it available to the event system. The filename
6663 is the name on the media, and the name is the symbolic name you used in the Miles Sound Studio.
6664 You might, for example, be using a soundbank with a platform extension, like: 'gamebank_ps3.msscmp',
6665 and while using the name 'gamebank' for authoring and auditioning.
6666
6667 Sound data is not loaded when this function is called - it is only loaded when the relevant Cache Sounds
6668 is played, or a sound requiring it plays.
6669
6670 This function will access the disc, so you will usually call it at level load time.
6671
6672 If you are using the Auditioner, $AIL_audition_startup and $AIL_audition_connect must be called prior
6673 to this function.
6674*/
6675
6676DXDEC EXPAPI S32 AILCALL AIL_release_soundbank(HMSOUNDBANK bank);
6677/*
6678 Releases a sound bank from the event system.
6679
6680 $:bank The bank to close.
6681 $:return Returns non-zero for success (zero on failure).
6682
6683 This function closes a given soundbank. Any data references in the event system need to be removed beforehand - with
6684 $AIL_enqueue_event_by_name usage this should only be pending sounds with completion events.
6685
6686 Any other data references still existing (queued events, persisted presets, etc) will report errors when used,
6687 but will not crash.
6688
6689 Releasing a sound bank does not free any cached sounds loaded from the bank - any sounds from the bank should be freed
6690 via a Purge Sounds event step. If this does not occur, the sound data will still be loaded, but the
6691 sound metadata will be gone, so Start Sound events will not work. Purge Sounds will still work.
6692
6693 This is different from Miles 8, which would maintain a reference count for all data.
6694*/
6695
6696DXDEC U8 const * AILCALL AIL_find_event(HMSOUNDBANK bank,char const* event_name);
6697/*
6698 (EXPAPI removed to prevent release in docs)
6699
6700 Searches for an event by name in the event system.
6701
6702 $:bank The soundbank to search within, or 0 to search all open banks (which is the normal case).
6703 $:event_name The name of the event to find. This name should be of the form "soundbank/event_list/event_name".
6704 $:return A pointer to the event contents (or 0, if the event isn't found).
6705
6706 This function is normally used as the event parameter for $AIL_enqueue_event. It
6707 searches one or all open soundbanks for a particular event name.
6708
6709 <b>This is deprecated</b>. If you know the event name, you should use $AIL_enqueue_event_by_name, or $AIL_enqueue_event with
6710 MILESEVENT_ENQUEUE_BY_NAME.
6711
6712 Events that are not enqueued by name can not be tracked by the Auditioner.
6713*/
6714
6715DXDEC EXPAPI U64 AILCALL AIL_enqueue_event_system(HEVENTSYSTEM system, U8 const * event, void* user_buffer, S32 user_buffer_len, S32 enqueue_flags, U64 apply_to_ID );
6716/*
6717 Enqueue an event to a specific system. Used only if you have multiple event systems running.
6718
6719 $:system The event system to attach the event to.
6720 $:return See $AIL_enqueue_event for return description.
6721
6722 For full information on the parameters, see $AIL_enqueue_event.
6723*/
6724
6725DXDEC EXPAPI U64 AILCALL AIL_enqueue_event_by_name(char const* name);
6726/*
6727 Enqueue an event by name.
6728
6729 $:name The full name of the event, eg "soundbank/path/to/event".
6730 $:return See $AIL_enqueue_event for return description.
6731
6732 This is the most basic way to enqueue an event. It enqueues an event by name, and as a result the event will be tracked by the auditioner.
6733
6734 For when you need more control over the event, but still want it to be tracked by the auditioner, it is equivalent
6735 to calling $AIL_enqueue_event_end_named($AIL_enqueue_event_start(), name)
6736
6737 For introduction to the auditioning system, see $integrating_events.
6738*/
6739
6740DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_start();
6741/*
6742 Start assembling a packet to use for enqueuing an event.
6743
6744 $:return A token used for passing to functions that add data to the event.
6745
6746 This is used to pass more data to an event that will be executed. For instance, if
6747 an event is going to spatialize a sound, but there's no need to move the sound over the course of
6748 its lifetime, you can add positional data to the event via $AIL_enqueue_event_position. When a
6749 sound is started it will use that for its initial position, and there is no need to do any
6750 game object <-> event id tracking.
6751
6752 ${
6753 // Start the enqueue.
6754 S32 enqueue_token = AIL_enqueue_event_start();
6755
6756 // Tell all sounds started by the event to position at (100, 100, 100)
6757 AIL_enqueue_event_position(&enqueue_token, 100, 100, 100);
6758
6759 // Complete the token and enqueue the event to the command buffer.
6760 AIL_enqueue_event_end_named(enqueue_token);
6761 $}
6762
6763 The enqueue process is still completely thread safe. No locks are used, however only 8
6764 enqueues can be "assembling" at the same time - if more than that occur, the $AIL_enqueue_event_start
6765 will yield the thread until a slot is open.
6766
6767 The ONLY time that should happen is if events enqueues are started but never ended:
6768
6769 ${
6770 // Start the enqueue
6771 S32 enqueue_token = AIL_enqueue_event_start();
6772
6773 // Try to get the game position
6774 Vector3* position = GetPositionOfSomething(my_game_object);
6775 if (position == 0)
6776 return; // OOPS! enqueue_token was leaked here, never to be reclaimed.
6777
6778 $}
6779
6780 Each event has a limit to the amount of data that can be attached to it. Currently this
6781 amount is 512 bytes - which should cover all use cases. If any enqueue functions return 0,
6782 then this amount has been reached. The ErrorHandler will be called as well, with $AIL_last_error
6783 reporting that the enqueue buffer was filled.
6784*/
6785
6786DXDEC EXPAPI void AILCALL AIL_enqueue_event_cancel(S32 token);
6787/*
6788 Clears a enqueue token without passing it to the command buffer
6789
6790 $:token A token created with $AIL_enqueue_event_start.
6791
6792 Used to handle the case where you decided to not actually enqueue the event you've assembled.
6793
6794 In general it's better to handle anything that can fail before actually starting
6795 to create the enqueue.
6796*/
6797
6798DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_position(S32* token, F32 x, F32 y, F32 z);
6799/*
6800 Pass an initial position to an event to use for sound spatialization.
6801
6802 $:token A token created with $AIL_enqueue_event_start.
6803 $:return 0 if the enqueue buffer is full
6804
6805 If the event queued starts a sound, the sound's position will be set to the given coordinates.
6806
6807 Setting the position of a sample automatically enables 3D spatialization.
6808*/
6809
6810DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_velocity(S32* token, F32 vx, F32 vy, F32 vz, F32 mag);
6811/*
6812 Pass an initial velocity to an event to use for sound spatialization.
6813
6814 $:token A token created with $AIL_enqueue_event_start.
6815 $:return 0 if the enqueue buffer is full
6816
6817 If the event queued starts a sound, the sound's velocity will be set to the given vector.
6818
6819 Setting the velocity of a sample does NOT automatically enable 3D spatialization.
6820*/
6821
6822DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_buffer(S32* token, void* user_buffer, S32 user_buffer_len, S32 user_buffer_is_ptr);
6823/*
6824 Attaches a user buffer to the event.
6825
6826 $:token A token created with $AIL_enqueue_event_start.
6827 $:user_buffer Pointer to a user buffer to pass with the event. If user_buffer_is_ptr is 1, the pointer is copied
6828 directly and user_buffer_len is ignored.
6829 $:user_buffer_len The size of the user_buffer to attach to the event.
6830 $:user_buffer_is_ptr If 1, the pointer is copied and user_buffer_len is ignored.
6831 $:return 0 if the enqueue buffer is full
6832
6833 User buffers are helpful for bridging the gap between game objects and sound objects.
6834
6835 There are two use cases available in this function
6836
6837 $* <b>Pointer</b> If user_buffer_is_ptr is 1, then the value passed to user_buffer is copied directly as the
6838 user buffer contents, and then exposed during sound enumeration. This is equivalent in spirit to
6839 the void* value that often accompanies callbacks. In this case, user_buffer_len is ignored, as
6840 user_buffer is never dereferenced.
6841 $* <b>Buffer</b> If user_buffer_is_ptr is 0, then user_buffer_len bytes are copied from user_buffer and
6842 carried with the event. During sound enumeration this buffer is made available, and you never have to
6843 worry about memory management.
6844 $-
6845
6846 Pointer-
6847 ${
6848 struct useful_data
6849 {
6850 S32 game_stat;
6851 S32 needed_info;
6852 };
6853
6854 useful_data* data = (useful_data*)malloc(sizeof(useful_data));
6855 data->game_stat = 1;
6856 data->needed_info = 2;
6857
6858 // Pointer - the "data" pointer will be copied directly, so we can't free() "data" until after the sound
6859 // completes and we're done using it in the enumeration loop.
6860 S32 ptr_token = AIL_enqueue_event_start();
6861 AIL_enqueue_event_buffer(&ptr_token, data, 0, 1);
6862 AIL_enqueue_event_end_named(ptr_token, "mybank/myevent");
6863 $}
6864
6865 Buffer-
6866 ${
6867 struct useful_data
6868 {
6869 S32 game_stat;
6870 S32 needed_info;
6871 };
6872
6873 useful_data data;
6874 data.game_stat = 1;
6875 data.needed_info = 2;
6876
6877 // Buffer - the "data" structure will be copied internally, so we can free() the data - or just use
6878 // a stack variable like this
6879 S32 buf_token = AIL_enqueue_event_start();
6880 AIL_enqueue_event_buffer(&buf_token, &data, sizeof(data), 0);
6881 AIL_enqueue_event_end_named(buf_token, "mybank/myevent");
6882 $}
6883
6884 As noted in $AIL_enqueue_event_start(), there's only 512 bytes available to an enqueue, so that
6885 places an upper limit on the amount of data you can pass along. If the data is huge, then you
6886 should use user_buffer_is_ptr.
6887*/
6888
6889DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_variablef(S32* token, char const* name, F32 value);
6890/*
6891 Attaches a variable's value to the event enqueue.
6892
6893 $:token A token created with $AIL_enqueue_event_start
6894 $:name The variable name to set.
6895 $:value The value of the variable to set.
6896 $:return 0 if the enqueue buffer is full
6897
6898 When a sound starts, the given variable will be set to the given value prior to any possible
6899 references being used by presets.
6900*/
6901
6902DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_filter(S32* token, U64 apply_to_ID);
6903/*
6904 Limits the effects of the event to sounds started by the given ID.
6905
6906 $:token A token created with $AIL_enqueue_event_start
6907 $:apply_to_ID The ID to use for filtering. This can be either a sound or event ID. For an
6908 event, it will apply to all sounds started by the event, and any events queued by that event.
6909 $:return 0 if the enqueue buffer is full
6910
6911 IDs are assigned to events and sounds - for events, it is returned via the $AIL_enqueue_event_end_named function
6912 (or any other enqueue function). For sounds, you can access the assigned id during the enumeration process.
6913*/
6914
6915DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_context(S32* token, HEVENTSYSTEM system);
6916/*
6917 Causes the event to run on a separate running event system.
6918
6919 $:token A token created with $AIL_enqueue_event_start
6920 $:system An event system $AIL_add_event_system
6921 $:return 0 if the enqueue buffer is full
6922
6923 If you are running multiple event systems, this is required to get events
6924 to queue on the additional event systems.
6925*/
6926
6927DXDEC EXPAPI S32 AILCALL AIL_enqueue_event_selection(S32* token, U32 selection);
6928/*
6929 Passes in a selection value for start sound events to use for picking sounds.
6930
6931 $:token A token created with $AIL_enqueue_event_start.
6932 $:selection The value to use for selecting the sound to play.
6933 $:return 0 if the enqueue buffer is full
6934
6935 The selection index is used to programatically select a sound from the
6936 loaded banks. The index passed in replaces any numeric value at the end
6937 of the sound name existing in any start sound event step. For example, if
6938 a start sound event plays "mybank/sound1", and the event is queued with
6939 a selection, then the selection will replace the "1" with the number passed in:
6940
6941 ${
6942 // Enqueue with a selection of 5
6943 S32 token = AIL_enqueue_event_start();
6944 AIL_enqueue_event_selection(&token, 50;
6945 AIL_enqueue_event_end_named(token, "mybank/myevent");
6946 $}
6947
6948 Assuming mybank/myevent starts sound "mybank/sound1", the sound
6949 that will actually be played will be "mybank/sound5". If the sound does
6950 not exist, it is treated the same as if any other sound was not found.
6951
6952 The selection process replaces ALL trailing numbers with a representation
6953 of the selection index using the same number of digits, meaning in the above
6954 example, "mybank/sound123" would have become "mybank/sound005".
6955*/
6956
6957DXDEC EXPAPI U64 AILCALL AIL_enqueue_event_end_named(S32 token, char const* event_name);
6958/*
6959 Completes assembling the event and queues it to the command buffer to be run during next tick.
6960
6961 $:token A token created with $AIL_enqueue_event_start.
6962 $:event_name The name of the event to run.
6963 $:return A unique ID for the event that can be used to identify sounds started by this event,
6964 or for filtering future events to the sounds started by this event.
6965
6966 This function takes all of the data accumulated via the various enqueue functions and assembles
6967 it in to the command buffer to be run during the next $AIL_begin_event_queue_processing.
6968
6969 As with all of the enqueue functions it is completely thread-safe.
6970
6971 Upon completion of this function, the enqueue slot is release and available for another
6972 $AIL_enqueue_event_start.
6973*/
6974
6975DXDEC EXPAPI U64 AILCALL AIL_enqueue_event(U8 const * event_or_name, void* user_buffer, S32 user_buffer_len, S32 enqueue_flags, U64 apply_to_ID );
6976/*
6977 Enqueue an event to be processed by the next $AIL_begin_event_queue_processing function.
6978
6979 $:event_or_name Pointer to the event contents to queue, or the name of the event to find and queue.
6980 If an event, the contents must be valid until the next call to $AIL_begin_event_queue_processing.
6981 If a name, the string is copied internally and does not have any lifetime requirements, and MILES_ENQUEUE_BY_NAME must be present in enqueue_flags.
6982 $:user_buffer Pointer to a user buffer. Depending on $(AIL_enqueue_event::enqueue_flags), this pointer can be saved directly, or its contents copied into the sound instance.
6983 This data is then accessible later, when enumerating the instances.
6984 $:user_buffer_len Size of the buffer pointed to by user_buffer.
6985 $:enqueue_flags Optional $MILESEVENTENQUEUEFLAGS logically OR'd together that control how to enqueue this event (default is 0).
6986 $:apply_to_ID Optional value that is used for events that affect sound instances. Normally,
6987 when Miles triggers one of these event steps, it matches the name and labels stored with the event step. However, if
6988 you specify an apply_to_ID value, then event step will only run on sounds that matches this QueuedID,InstanceID,or EventID too. This is how you
6989 execute events only specific sound instances. QueuedIDs are returned from each call $AIL_enqueue_event.
6990 InstanceIDs and EventIDs are returned from $AIL_enumerate_sound_instances.
6991 $:return On success, returns QueuedID value that is unique to this queued event for the rest of this
6992 program run (you can use this ID to uniquely identify sounds triggered from this event).
6993
6994 This function enqueues an event to be triggered - this is how you begin execution of an event. First, you
6995 queue it, and then later (usually once a game frame), you call $AIL_begin_event_queue_processing to
6996 execute an event.
6997
6998 This function is very lightweight. It does nothing more than post the event and data to a
6999 command buffer that gets executed via $AIL_begin_event_queue_processing.
7000
7001 The user_buffer parameter can be used in different ways. If no flags are passed in, then
7002 Miles will copy the data from user_buffer (user_buffer_len bytes long) and store the data with
7003 the queued sound - you can then free the user_buffer data completely! This lets Miles keep track
7004 of all your sound related memory directly and is the normal way to use the system (it is very
7005 convenient once you get used to it).
7006
7007 If you instead pass the MILESEVENT_ENQUEUE_BUFFER_PTR flag, then user_buffer pointer will
7008 simply be associated with each sound that this event may start. In this case, user_buffer_len
7009 is ignored.
7010
7011 In both cases, when you later enumerate the sound instances, you can access your sound data
7012 with the $(MILESEVENTSOUNDINFO::UserBuffer) field.
7013
7014 You can call this function from any number threads - it's designed to be called from anywhere in your game.
7015
7016 If you want events you queue to be captured by Miles Studio, then they have to be passed by name. This can be done
7017 by either using the convenience function $AIL_enqueue_event_by_name, or by using the MILESEVENT_ENQUEUE_BY_NAME flag and
7018 passing the name in event_or_name. For introduction to the auditioning system, see $integrating_events.
7019*/
7020
7021EXPTYPEBEGIN typedef S32 MILESEVENTENQUEUEFLAGS;
7022#define MILESEVENT_ENQUEUE_BUFFER_PTR 0x1
7023#define MILESEVENT_ENQUEUE_FREE_EVENT 0x2
7024#define MILESEVENT_ENQUEUE_BY_NAME 0x4
7025// 0x8 can't be used, internal.
7026EXPTYPEEND
7027/*
7028 The available flags to pass in $AIL_enqueue_event or $AIL_enqueue_event_system.
7029
7030 $:MILESEVENT_ENQUEUE_BUFFER_PTR The user_buffer parameter passed in should not be duplicated, and instead
7031 should just tranparently pass the pointer on to the event, so that the $(MILESEVENTSOUNDINFO::UserBuffer)
7032 during sound iteration is just the same pointer. user_buffer_len is ignored in this case.
7033
7034 $:MILESEVENT_ENQUEUE_FREE_EVENT The ownership of the memory for the event is passed to the event system. If this
7035 is present, once the event completes $AIL_mem_free_lock will be called on the raw pointer passed in to $AIL_enqueue_event or
7036 $AIL_enqueue_event_system. This is rarely used.
7037
7038 $:MILESEVENT_ENQUEUE_BY_NAME The event passed in is actually a string. The event system will then look for this event
7039 in the loaded sound banks during queue processing.
7040*/
7041
7042
7043DXDEC EXPAPI S32 AILCALL AIL_begin_event_queue_processing( void );
7044/*
7045 Begin execution of all of the enqueued events.
7046
7047 $:return Return 0 on failure. The only failures are unrecoverable errors in the queued events
7048 (out of memory, bank file not found, bad data, etc). You can get the specific error by
7049 calling $AIL_last_error.
7050
7051 This function executes all the events currently in the queue. This is where all major
7052 processing takes place in the event system.
7053
7054 Once you execute this functions, then sound instances will be in one of three states:
7055
7056 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_PENDING)[MILESEVENT_SOUND_STATUS_PENDING] - these are new sound instances that were
7057 created by events that had a "Start Sound Step". Note that these instances aren't audible yet,
7058 so that you have a chance to modify game driven properties (like the 3D position)
7059 on the sound before Miles begins to play it.
7060
7061 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_PLAYING)[MILESEVENT_SOUND_STATUS_PLAYING] - these are sound instances that were previously
7062 started and are continuing to play (you might update the 3D position for these, for example).
7063
7064 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_COMPLETE)[MILESEVENT_SOUND_STATUS_COMPLETE] - these are sound instances that finished playing
7065 since the last this frame (you might use this status to free any game related memory, for example).
7066
7067 You will normally enumerate the active sound instances in-between calls to $AIL_begin_event_queue_processing
7068 and $AIL_complete_event_queue_processing with $AIL_enumerate_sound_instances.
7069
7070 $AIL_complete_event_queue_processing must be called after this function to commit
7071 all the changes.
7072
7073 Example usage:
7074${
7075 // enqueue an event
7076 $AIL_enqueue_event( EventThatStartsSounds, game_data_ptr, 0, MILESEVENT_ENQUEUE_BUFFER_PTR, 0 );
7077
7078 // now process that event
7079 $AIL_begin_event_queue_processing( );
7080
7081 // next, enumerate the pending and complete sounds for game processing
7082 MILESEVENTSOUNDINFO Info;
7083
7084 HMSSENUM SoundEnum = MSS_FIRST;
7085 while ( $AIL_enumerate_sound_instances( &SoundEnum, MILESEVENT_SOUND_STATUS_PENDING | MILESEVENT_SOUND_STATUS_COMPLETE, 0, &Info ) )
7086 {
7087 game_type * game_data = (game_type*) Info.UserBuffer; // returns the game_data pointer from the enqueue
7088
7089 if ( Info.Status == MILESEVENT_SOUND_STATUS_PENDING )
7090 {
7091 // setup initial state
7092 AIL_set_sample_3D_position( Info.Sample, game_data->x, game_data->y, game_data->z );
7093 }
7094 else if ( Info.Status == MILESEVENT_SOUND_STATUS_COMPLETE )
7095 {
7096 // Free some state we have associated with the sound now that its done.
7097 game_free( game_data );
7098 }
7099 }
7100
7101 $AIL_complete_event_queue_processing( );
7102 $}
7103
7104 Note that if any event step drastically fails, the rest of the command queue is
7105 skipped, and this function returns 0! For this reason, you shouldn't assume
7106 that a start sound event will always result in a completed sound later.
7107
7108 Therefore, you should allocate memory that you want associated with a sound instance
7109 during the enumeration loop, rather than at enqueue time. Otherwise, you
7110 need to detect that the sound didn't start and then free the memory (which can be complicated).
7111*/
7112
7113// Returned by AIL_enumerate_sound_instances()
7114EXPTYPE typedef struct _MILESEVENTSOUNDINFO
7115{
7116 U64 QueuedID;
7117 U64 InstanceID;
7118 U64 EventID;
7119 HSAMPLE Sample;
7120 HSTREAM Stream;
7121 void* UserBuffer;
7122 S32 UserBufferLen;
7123 S32 Status;
7124 U32 Flags;
7125 S32 UsedDelay;
7126 F32 UsedVolume;
7127 F32 UsedPitch;
7128 char const* UsedSound;
7129 S32 HasCompletionEvent;
7130} MILESEVENTSOUNDINFO;
7131/*
7132 Sound instance data that is associated with each active sound instance.
7133
7134 $:QueuedID A unique ID that identifies the queued event that started this sound. Returned from each call to $AIL_enqueue_event.
7135 $:EventID A unique ID that identifies the actual event that started this sound. This is the same as QueuedID unless the sound
7136 was started by a completion event or a event exec step. In that case, the QueuedID represents the ID returned from
7137 $AIL_enqueue_event, and EventID represents the completion event.
7138 $:InstanceID A unique ID that identified this specific sound instance (note that one QueuedID can trigger multiple InstanceIDs).
7139 $:Sample The $HSAMPLE for this playing sound.
7140 $:Stream The $HSTREAM for this playing sound (if it is being streamed, zero otherwise).
7141 $:UserBuffer A pointer to the user data for this sound instance.
7142 $:UserBufferLen The length in bytes of the user data (if known by Miles).
7143 $:Status One of the $MILESEVENTSOUNDSTATUS status values.
7144 $:Flags One or more of the $MILESEVENTSOUNDFLAG flags.
7145 $:UsedDelay The value actually used as a result of the randomization of delay for this instance
7146 $:UsedVolume The value actually used as a result of the randomization of pitch for this instance
7147 $:UsedPitch The value actually used as a result of the randomization of volume for this instance
7148 $:UsedSound The name of the sound used as a result of randomization. This pointer should NOT be deleted
7149 and is only valid for the until the next call in to Miles.
7150 $:HasCompletionEvent Nonzero if the sound will fire an event upon completion.
7151
7152 This structure is returned by the $AIL_enumerate_sound_instances function. It
7153 returns information about an active sound instance.
7154*/
7155
7156DXDEC EXPAPI void AILCALL AIL_set_variable_int(UINTa context, char const* name, S32 value);
7157/*
7158 Sets a named variable that the designer can reference in the tool.
7159
7160 $:context The context the variable is set for. Can be either a $HEVENTSYSTEM
7161 to set a global variable for a specific system, 0 to set a global variable
7162 for the default system, or an $HMSSENUM from $AIL_enumerate_sound_instances.
7163 $:name The name of the variable to set.
7164 $:value The value of the variable to set.
7165
7166 Variables are tracked per sound instance and globally, and when a variable is needed
7167 by an event, it will check the relevant sound instance first, before falling back to
7168 the global variable list:
7169
7170 ${
7171 $HMSSENUM FirstSound = MSS_FIRST;
7172 $MILESEVENTSOUNDINFO Info;
7173
7174 // Grab the first sound, whatever it is.
7175 $AIL_enumerate_sound_instances(0, &FirstSound, 0, 0, 0, &Info);
7176
7177 // Set a variable on that sound.
7178 $AIL_set_variable_int(FirstSound, "MyVar", 10);
7179
7180 // Set a global variable by the same name.
7181 $AIL_set_variable_int(0, "MyVar", 20);
7182
7183 // A preset referencing "MyVar" for FirstSound will get 10. Any other sound will
7184 // get 20.
7185 $}
7186
7187*/
7188
7189DXDEC EXPAPI void AILCALL AIL_set_variable_float(UINTa context, char const* name, F32 value);
7190/*
7191 Sets a named variable that the designer can reference in the tool.
7192
7193 $:context The context the variable is set for. Can be either a $HEVENTSYSTEM
7194 to set a global variable for a specific system, 0 to set a global variable
7195 for the default system, or an $HMSSENUM from $AIL_enumerate_sound_instances.
7196 $:name The name of the variable to set.
7197 $:value The value of the variable to set.
7198
7199 Variables are tracked per sound instance and globally, and when a variable is needed
7200 by an event, it will check the relevant sound instance first, before falling back to
7201 the global variable list.
7202
7203 ${
7204 $HMSSENUM FirstSound = MSS_FIRST;
7205 $MILESEVENTSOUNDINFO Info;
7206
7207 // Grab the first sound, whatever it is.
7208 $AIL_enumerate_sound_instances(0, &FirstSound, 0, 0, 0, &Info);
7209
7210 // Set a variable on that sound.
7211 $AIL_set_variable_float(FirstSound, "MyVar", 10.0);
7212
7213 // Set a global variable by the same name.
7214 $AIL_set_variable_float(0, "MyVar", 20.0);
7215
7216 // A preset referencing "MyVar" for FirstSound will get 10. Any other sound will
7217 // get 20.
7218 $}
7219*/
7220
7221DXDEC EXPAPI S32 AILCALL AIL_variable_int(UINTa context, char const* name, S32* value);
7222/*
7223 Retrieves a named variable.
7224
7225 $:context The context to start the lookup at, same as $AIL_set_variable_int.
7226 $:name The name to look up.
7227 $:value Pointer to an int to store the value in.
7228 $:return 1 if the variable was found, 0 otherwise.
7229
7230 This function follows the same lookup pattern as the runtime - if the context is a
7231 sound instance, it checks the instance before falling back to global variables.
7232*/
7233
7234DXDEC EXPAPI S32 AILCALL AIL_variable_float(UINTa context, char const* name, F32* value);
7235/*
7236 Retrieves a named variable.
7237
7238 $:context The context to start the lookup at, same as $AIL_set_variable_float.
7239 $:name The name to look up.
7240 $:value Pointer to a float to store the value in.
7241 $:return 1 if the variable was found, 0 otherwise.
7242
7243 This function follows the same lookup pattern as the runtime - if the context is a
7244 sound instance, it checks the instance before falling back to global variables.
7245*/
7246
7247DXDEC EXPAPI void AILCALL AIL_requeue_failed_asyncs();
7248/*
7249 Requeues any failed asynchronous loads for sound sources.
7250
7251 Use this function when a disc error causes a slew of failed caches. Any sound source that
7252 has failed due to asynchronous load will get retried.
7253*/
7254
7255DXDEC EXPAPI void AILCALL AIL_set_sound_start_offset(HMSSENUM sound, S32 offset, S32 isms);
7256/*
7257 Specify the starting position for a pending sound.
7258
7259 $:sound The enumeration from $AIL_enumerate_sound_instances representing the desired sound.
7260 The sound must be in the pending state.
7261 $:offset The offset to use for the starting position of the sound.
7262 $:isms If nonzero, the offset is in milliseconds, otherwise bytes.
7263
7264 Use this function instead of manipulating the sample position directly via low level Miles calls prior to
7265 the sound starting. Generally you don't need to do this manually, since the sound designer should do
7266 this, however if you need to restart a sound that stopped - for example a stream that went to error -
7267 you will have to set the start position via code.
7268
7269 However, since there can be a delay between the time the sound is first seen in the sound iteration and
7270 the time it gets set to the data, start positions set via the low level miles calls can get lost, so
7271 use this.
7272
7273 See the <i>eventstreamerror.cpp</i> example program for usage.
7274*/
7275
7276DXDEC EXPAPI S32 AILCALL AIL_enumerate_sound_instances(HEVENTSYSTEM system, HMSSENUM* next, S32 statuses, char const* label_query, U64 search_for_ID, EXPOUT MILESEVENTSOUNDINFO* info);
7277/*
7278 Enumerated the active sound instances managed by the event system.
7279
7280 $:next Enumeration token - initialize to MSS_FIRST before the first call. You can pass 0 here, if you just want the first instance that matches.
7281 $:statuses Or-ed list of status values to enumerate. Use 0 for all status types.
7282 $:label_query A query to match sound instance labels against. Use 0 to skip label matching.
7283 $:search_for_ID Match only instances that have a QueuedID,InstanceID,or EventID that matches this value. Use 0 to skip ID matching.
7284 $:info Returns the data for each sound instance.
7285 $:return Returns 0 when enumeration is complete.
7286
7287 Enumerates the sound instances. This will generally be used between
7288 calls to $AIL_begin_event_queue_processing and $AIL_complete_event_queue_processing to
7289 manage the sound instances.
7290
7291 The label_query is a list of labels to match, separated by commas. By default, comma-separated
7292 values only have to match at least one label. So, if you used "level1, wind", then all sound instances
7293 that had either "level1" <i>or</i> "wind" would match. If you want to match <i>all</i> labels,
7294 then use the + sign first (for example, "+level1, +wind" would only match sound instances that
7295 had <i>both</i> "level1" and "wind"). You can also use the - sign before a label to <i>not</i>
7296 match that label (so, "level1, -wind" would match all "level1" labeled sound instances that didn't have
7297 a "wind" label). Finally, you can also use * and ? to match wildcard style labels (so, "gun*"
7298 would match any sound instance with a label that starts with "gun").
7299
7300 Valid status flags are:
7301
7302 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_PENDING)[MILESEVENT_SOUND_STATUS_PENDING] - these are new sound instances that were
7303 created by events that had a "Start Sound Step". Note that these instances aren't audible yet,
7304 so that you have a chance to modify game driven properties (like the 3D position)
7305 on the sound before Miles begins to play it.
7306
7307 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_PLAYING)[MILESEVENT_SOUND_STATUS_PLAYING] - these are sound instances that were previously
7308 started and are continuing to play (you might update the 3D position for these, for example).
7309
7310 $(MILESEVENTSOUNDSTATUS::MILESEVENT_SOUND_STATUS_COMPLETE)[MILESEVENT_SOUND_STATUS_COMPLETE] - these are sound instances that finished playing
7311 since the last this frame (you might use this status to free any game related memory, for example).
7312
7313 Example Usage:
7314${
7315 HMSSENUM SoundEnum = MSS_FIRST;
7316 MILESEVENTSOUNDINFO Info;
7317
7318 while ( $AIL_enumerate_sound_instances( &SoundEnum, 0, 0, &Info ) )
7319 {
7320 if ( Info.Status != MILESEVENT_SOUND_STATUS_COMPLETE )
7321 {
7322 game_SoundState* game_data= (game_SoundState*)( Info.UserBuffer );
7323 $AIL_set_sample_is_3D( Info.Sample, 1 );
7324 $AIL_set_sample_3D_position( Info.Sample, game_data->x, game_data->y, game_date->z );
7325 }
7326 }
7327
7328$}
7329*/
7330
7331EXPTYPEBEGIN typedef S32 MILESEVENTSOUNDSTATUS;
7332#define MILESEVENT_SOUND_STATUS_PENDING 0x1
7333#define MILESEVENT_SOUND_STATUS_PLAYING 0x2
7334#define MILESEVENT_SOUND_STATUS_COMPLETE 0x4
7335EXPTYPEEND
7336/*
7337 Specifies the status of a sound instance.
7338
7339 $:MILESEVENT_SOUND_STATUS_PENDING New sound instances that were
7340 created by events that had a "Start Sound Step". Note that these instances aren't audible yet,
7341 so that you have a chance to modify game driven properties (like the 3D position)
7342 on the sound before Miles begins to play it.
7343
7344 $:MILESEVENT_SOUND_STATUS_PLAYING Sound instances that were previously
7345 started and are continuing to play (you might update the 3D position for these, for example).
7346
7347 $:MILESEVENT_SOUND_STATUS_COMPLETE Sound instances that finished playing
7348 since the last this frame (you might use this status to free any game related memory, for example).
7349
7350 These are the status values that each sound instance can have. Use $AIL_enumerate_sound_instances to retrieve them.
7351*/
7352
7353EXPTYPEBEGIN typedef U32 MILESEVENTSOUNDFLAG;
7354#define MILESEVENT_SOUND_FLAG_MISSING_SOUND 0x1
7355#define MILESEVENT_SOUND_FLAG_EVICTED 0x2
7356#define MILESEVENT_SOUND_FLAG_WAITING_ASYNC 0x4
7357#define MILESEVENT_SOUND_FLAG_PENDING_ASYNC 0x8
7358#define MILESEVENT_SOUND_FLAG_FAILED_HITCH 0x10
7359#define MILESEVENT_SOUND_FLAG_FAILED_ASYNC 0x20
7360EXPTYPEEND
7361/*
7362 Specifies the status of a sound instance.
7363
7364 $:MILESEVENT_SOUND_FLAG_MISSING_SOUND The event system tried to look up the sound requested from a Start Sound event
7365 and couldn't find anything in the loaded banks.
7366 $:MILESEVENT_SOUND_FLAG_EVICTED The sound was evicted due to a sound instance limit being hit. Another sound was selected
7367 as being higher priority, and this sound was stopped as a result. This can be the result of either a Label Sound Limit,
7368 or a limit on the sound itself.
7369 $:MILESEVENT_SOUND_FLAG_WAITING_ASYNC The sound is pending because the data for it is currently being loaded.
7370 The sound will start when sufficient data has been loaded to hopefully avoid a skip.
7371 $:MILESEVENT_SONUD_FLAG_PENDING_ASYNC The sound has started playing, but the data still isn't completely loaded, and it's possible
7372 that the sound playback will catch up to the read position under poor I/O conditions.
7373 $:MILESEVENT_SOUND_FLAG_FAILED_HITCH The sound meta data was found, but the sound was not in memory, and the Start Sound event
7374 was marked as "Must Be Cached". To prevent this, either clear the flag in the event, which will cause a start delay as the
7375 sound data is asynchronously loaded, or specify the sound in a Cache Sounds step prior to attempting to start it.
7376 $:MILESEVENT_SOUND_FLAG_FAILED_ASYNC The sound tried to load and the asynchronous I/O operation failed - most likely either the media
7377 was removed during load, or the file was not found.
7378
7379 These are the flag values that each sound instance can have. Use $AIL_enumerate_sound_instances to retrieve them. Instances
7380 may have more than one flag, logically 'or'ed together.
7381*/
7382
7383DXDEC EXPAPI S32 AILCALL AIL_complete_event_queue_processing( void );
7384/*
7385 Completes the queue processing (which is started with $AIL_begin_event_queue_processing ).
7386
7387 $:return Returns 0 on failure.
7388
7389 This function must be called as a pair with $AIL_begin_event_queue_processing.
7390
7391 In $AIL_begin_event_queue_processing, all the new sound instances are queued up, but they haven't
7392 started playing yet. Old sound instances that have finished playing are still valid - they
7393 haven't been freed yet. $AIL_complete_event_queue_processing actually starts the sound instances
7394 and frees the completed ones - it's the 2nd half of the event processing.
7395
7396 Usually you call $AIL_enumerate_sound_instances before this function to manage all the sound
7397 instances.
7398*/
7399
7400DXDEC EXPAPI U64 AILCALL AIL_stop_sound_instances(char const * label_query, U64 apply_to_ID);
7401/*
7402 Allows the programmer to manually enqueue a stop sound event into the event system.
7403
7404 $:label_query A query to match sound instance labels against. Use 0 to skip label matching.
7405 $:apply_to_ID An optional value returned from a previous $AIL_enqueue_event or $AIL_enumerate_sound_instances that
7406 tells Miles to stop only those instances who's QueuedID,InstanceID,or EventID matches this value.
7407 $:return Returns a non-zero queue ID on success.
7408
7409 Enqueues an event to stop all sounds matching the specified label query (see $AIL_enumerate_sound_instances
7410 for a description of the label_query format).
7411
7412 Usually the programmer should trigger a named event that the sound designed can fill out to stop the necessary sounds,
7413 however, if a single sound (for example associated with an enemy that the player just killed) needs to be stopped,
7414 this function accomplishes that, and is captured by the auditioner for replay.
7415*/
7416
7417DXDEC EXPAPI U64 AILCALL AIL_pause_sound_instances(char const * label_query, U64 apply_to_ID);
7418/*
7419 Allows the programmer to manually enqueue a pause sound event into the event system.
7420
7421 $:label_query A query to match sound instance labels against. Use 0 to skip label matching.
7422 $:apply_to_ID An optional value returned from a previous $AIL_enqueue_event or $AIL_enumerate_sound_instances that
7423 tells Miles to pause only those instances who's QueuedID,InstanceID,or EventID matches this value.
7424 $:return Returns a non-zero queue ID on success.
7425
7426 Enqueues an event to pause all sounds matching the specified label query (see $AIL_enumerate_sound_instances
7427 for a description of the label_query format).
7428
7429 Usually the programmer should trigger a named event that the sound designed can fill out to pause the necessary sounds,
7430 however, if a single sound (for example associated with an enemy that has been put in to stasis) needs to be paused,
7431 this function accomplishes that, and is captured by the auditioner for replay.
7432*/
7433
7434DXDEC EXPAPI U64 AILCALL AIL_resume_sound_instances(char const * label_query, U64 apply_to_ID);
7435/*
7436 Allows the programmer to manually enqueue a resume sound event into the event system.
7437
7438 $:label_query A query to match sound instance labels against. Use 0 to skip label matching.
7439 $:apply_to_ID An optional value returned from a previous $AIL_enqueue_event or $AIL_enumerate_sound_instances that
7440 tells Miles to resume only those instances who's QueuedID,InstanceID,or EventID matches this value.
7441 $:return Returns a non-zero enqueue ID on success.
7442
7443 Enqueues an event to resume all sounds matching the specified label query (see $AIL_enumerate_sound_instances
7444 for a description of the label_query format).
7445
7446 Usually the programmer should trigger a named event that the sound designed can fill out to resume the necessary sounds,
7447 however, if a single sound (for example associated with an enemy that has been restored from stasis) needs to be resumed,
7448 this function accomplishes that, and is captured by the auditioner for replay.
7449*/
7450
7451DXDEC EXPAPI U64 AILCALL AIL_start_sound_instance(HMSOUNDBANK bank, char const * sound, U8 loop_count,
7452 S32 should_stream, char const * labels, void* user_buffer, S32 user_buffer_len, S32 enqueue_flags );
7453/*
7454 Allows the programmer to manually enqueue a start sound event into the event system.
7455
7456 $:bank The bank containing the sound to start.
7457 $:sound The name of the sound file to start, including bank name, e.g. "BankName/SoundName"
7458 $:loop_count The loop count to assign to the sound. 0 for infinite, 1 for play once, or just the number of times to loop.
7459 $:stream Non-zero if the sound playback should stream off the disc.
7460 $:labels An optional comma-delimited list of labels to assign to the sound playback.
7461 $:user_buffer See the user_buffer description in $AIL_enqueue_event.
7462 $:user_buffer_len See the user_buffer_len description in $AIL_enqueue_event.
7463 $:enqueue_flags See the enqueue_flags description in $AIL_enqueue_event.
7464 $:return Returns a non-zero EnqueueID on success.
7465
7466 Enqueues an event to start the specified sound asset.
7467
7468 Usually the programmer should trigger an event that the sound designer has specifically
7469 create to start the appropriate sounds, but this function gives the programmer
7470 manual control, if necessary. <b>This function is not captured by the auditioner.</b>
7471*/
7472
7473DXDEC EXPAPI void AILCALL AIL_clear_event_queue( void );
7474/*
7475 Removes all pending events that you have enqueued.
7476
7477 This function will clears the list of all events that you have previously enqueued.
7478*/
7479
7480
7481DXDEC EXPAPI S32 AILCALL AIL_set_sound_label_limits(HEVENTSYSTEM system, char const* sound_limits);
7482/*
7483 Sets the maximum number of sounds that matches a particular label.
7484
7485 $:sound_limits A string that defines one or more limits on a label by label basis. The string should
7486 be of the form "label1name label1count:label2name label2count".
7487 $:return Returns 0 on failure (usually a bad limit string).
7488
7489 Every time an event triggers a sound to be played, the sound limits are checked, and, if exceeded, a sound is dropped (based
7490 on the settings in the event step).
7491
7492 Usually event limits are set by a sound designer via an event, but this lets the programmer override the limits at runtime.
7493 Note that this replaces those events, it does not supplement.
7494*/
7495
7496DXDEC EXPAPI S32 AILCALL AIL_enumerate_preset_persists(HEVENTSYSTEM system, HMSSENUM* next, EXPOUT char const ** name);
7497/*
7498 Enumerates the current persisted presets that active in the system.
7499
7500 $:system The system to enumerate the persists for, or 0 to use the default system.
7501 $:next Enumeration token - initialize to MSS_FIRST before the first call.
7502 $:name Pointer to a char* that receives the name of the persist. NOTE
7503 that this pointer can change frame to frame and should be immediately copied to a client-allocated
7504 buffer if persistence is desired.
7505 $:return Returns 0 when enumeration is complete.
7506
7507 This function lets you enumerate all the persisting presets that are currently active in the system. It
7508 is mostly a debugging aid.
7509*/
7510
7511DXDEC EXPAPI char * AILCALL AIL_text_dump_event_system(void);
7512/*
7513 Returns a big string describing the current state of the event system.
7514
7515 $:return String description of current systems state.
7516
7517 This function is a debugging aid - it can be used to show all of the active allocations,
7518 active sounds, etc.
7519
7520 You must delete the pointer returned from this function with $AIL_mem_free_lock.
7521*/
7522
7523EXPTYPE typedef struct _MILESEVENTSTATE
7524{
7525 S32 CommandBufferSize;
7526 S32 HeapSize;
7527 S32 HeapRemaining;
7528 S32 LoadedSoundCount;
7529 S32 PlayingSoundCount;
7530 S32 LoadedBankCount;
7531 S32 PersistCount;
7532
7533 S32 SoundBankManagementMemory;
7534 S32 SoundDataMemory;
7535} MILESEVENTSTATE;
7536/*
7537 returns the current state of the Miles Event System.
7538
7539 $:CommandBufferSize The size of the command buffer in bytes. See also the $AIL_startup_event_system.
7540 $:HeapSize The total size of memory used by the event system for management structures, and is allocated during startup. This does not include loaded file sizes.
7541 $:HeapRemaining The number of bytes in HeapSize that is remaining.
7542 $:LoadedSoundCount The number of sounds loaded and ready to play via cache event steps.
7543 $:PlayingSoundCount The number of sounds currently playing via start sound event steps.
7544 $:LoadedBankCount The number of sound banks loaded in the system via cache event steps, or AIL_add_soundbank.
7545 $:PersistCount The number of presets persisted via the persist event step.
7546 $:SoundBankManagementMemory The number of bytes used for the management of the loaded sound banks.
7547 $:SoundDataMemory The number of bytes used in file sizes - remember this is not included in HeapSize. Streaming overhead is not included in this number, only fully loaded sounds.
7548
7549 This structure returns debugging info about the event system. It is used with $AIL_event_system_state.
7550*/
7551
7552EXPGROUP(Miles High Level Callbacks)
7553
7554EXPAPI typedef void AILCALLBACK MilesBankFreeAll( void );
7555/*
7556 callback to free all user managed bank memory.
7557*/
7558
7559EXPAPI typedef void * AILCALLBACK MilesBankGetPreset( char const * name );
7560/*
7561 callback to retrieve a sound preset.
7562*/
7563
7564EXPAPI typedef void * AILCALLBACK MilesBankGetEnvironment( char const * name );
7565/*
7566 callback to retrieve an environment preset.
7567*/
7568EXPAPI typedef S32 AILCALLBACK MilesBankGetSound(char const* SoundAssetName, char* SoundFileName, MILESBANKSOUNDINFO* o_SoundInfo );
7569/*
7570 callback to return whether the sound asset is in the bank, and, if so, what the final data filename is.
7571
7572 In order to externally deploy sound files, you will need to register your own GetSound callback. This is detailed in the
7573 eventexternal example program.
7574
7575 This returns the len of the buffer required for the output file name if SoundFileName is zero.
7576*/
7577
7578EXPAPI typedef void * AILCALLBACK MilesBankGetEvent( char const * name );
7579/*
7580 callback to retrieve an event.
7581*/
7582
7583EXPAPI typedef void * AILCALLBACK MilesBankGetMarkerList( char const * name );
7584/*
7585 callback to retrieve a sound marker list.
7586*/
7587
7588EXPAPI typedef S32 AILCALLBACK MilesBankGetLoadedCount( void );
7589/*
7590 callback to retrieve the number of loaded sound banks.
7591*/
7592
7593EXPAPI typedef S32 AILCALLBACK MilesBankGetMemUsage( void );
7594/*
7595 callback to retrieve the total memory in use.
7596*/
7597
7598EXPAPI typedef char const * AILCALLBACK MilesBankGetLoadedName( S32 index );
7599/*
7600 callback to retrieve the file name of a sound index.
7601*/
7602
7603
7604EXPTYPE typedef struct _MILESBANKFUNCTIONS
7605{
7606 MilesBankFreeAll * FreeAll;
7607 MilesBankGetPreset * GetPreset;
7608 MilesBankGetEnvironment * GetEnvironment;
7609 MilesBankGetSound * GetSound;
7610 MilesBankGetEvent * GetEvent;
7611 MilesBankGetMarkerList * GetMarkerList;
7612 MilesBankGetLoadedCount * GetLoadedCount;
7613 MilesBankGetMemUsage * GetMemUsage;
7614 MilesBankGetLoadedName * GetLoadedName;
7615} MILESBANKFUNCTIONS;
7616/*
7617 specifies callbacks for each of the Miles event system.
7618
7619 $:FreeAll Callback that tells you to free all user-side bank memory.
7620 $:GetPreset Callback to retrieve a sound preset.
7621 $:GetEnvironment Callback to retrieve an environment preset.
7622 $:GetSound Callback to return the actual filename of a sound asset.
7623 $:GetEvent Callback to retrieve a sound event.
7624 $:GetMarkerList Callback to retrieve a sound marker list.
7625 $:GetLoadedCount Callback to retrieve a count of loaded sound banks.
7626 $:GetMemUsage Callback to retrieve the amount of memory in use.
7627 $:GetLoadedName Callback to retrieve the filename for a sound asset index.
7628
7629 This structure is used to provide overrides for all of the high-level loading
7630 functionality.
7631*/
7632
7633EXPGROUP(Miles High Level Event System)
7634
7635DXDEC EXPAPI void AILCALL AIL_set_event_sample_functions(HSAMPLE (*CreateSampleCallback)(char const* SoundName, char const* SoundFileName, HDIGDRIVER dig, void* UserBuffer, S32 UserBufferLen), void (*ReleaseSampleCallback)(HSAMPLE));
7636/*
7637 Allows you to manage sound data availability and sample handles.
7638
7639 $:CreateSampleCallback Function that will be called when a sample handle is needed.
7640 $:ReleaseSampleCallback Function that will be called when a sample is no longer needed.
7641
7642 A created sample is required to have all data pointers necessary to play - e.g.
7643 the event system needs to be able to just do a AIL_start_sample() on the returned
7644 handle and have it work.
7645
7646 In the callback, SoundName is the name of the asset in Miles Studio, and SoundFileName
7647 is the value returned from Container_GetSound() (see also $AIL_set_event_bank_functions).
7648
7649*/
7650
7651DXDEC EXPAPI void AILCALL AIL_set_event_bank_functions(MILESBANKFUNCTIONS const * Functions);
7652/*
7653 Allows you to override the internal bank file resource management..
7654
7655 $:Functions A pointer to a structure containing all the callback functions.
7656
7657 This function is used to completely override the high-level resource management system.
7658 It's not for overriding the IO - it's when you need much higher-level of control. Primarily
7659 targeted internally for the Auditioner to use, it also is used when deploying sound files
7660 externally.
7661*/
7662
7663DXDEC EXPAPI MILESBANKFUNCTIONS const* AILCALL AIL_get_event_bank_functions();
7664/*
7665 Returns the current functions used to retrieve and poll bank assets.
7666*/
7667
7668
7669typedef S32 AILCALLBACK AuditionStatus();
7670typedef S32 AILCALLBACK AuditionPump();
7671typedef void* AILCALLBACK AuditionOpenBank(char const* i_FileName);
7672typedef S32 AILCALLBACK AuditionOpenComplete(void* i_Bank);
7673typedef void AILCALLBACK AuditionCloseBank(void* i_Bank);
7674
7675typedef void AILCALLBACK AuditionSuppress(S32 i_IsSuppressed);
7676typedef void AILCALLBACK AuditionFrameStart();
7677typedef void AILCALLBACK AuditionFrameEnd();
7678typedef void AILCALLBACK AuditionDefragStart();
7679typedef void AILCALLBACK AuditionSetBlend(U64 i_EventId, char const* i_Name);
7680typedef void AILCALLBACK AuditionSetPersist(U64 i_EventId, char const* i_Name, char const* i_Preset);
7681typedef void AILCALLBACK AuditionEvent(char const* i_EventName, U64 i_EventId, U64 i_Filter, S32 i_Exists, void* i_InitBlock, S32 i_InitBlockLen);
7682typedef void AILCALLBACK AuditionSound(U64 i_EventId, U64 i_SoundId, char const* i_Sound, char const* i_Labels, float i_Volume, S32 i_Delay, float i_Pitch);
7683typedef void AILCALLBACK AuditionSoundComplete(U64 i_SoundId);
7684typedef void AILCALLBACK AuditionSoundPlaying(U64 i_SoundId);
7685typedef void AILCALLBACK AuditionSoundFlags(U64 i_SoundId, S32 i_Flags);
7686typedef void AILCALLBACK AuditionSoundLimited(U64 i_SoundId, char const* i_Label);
7687typedef void AILCALLBACK AuditionSoundEvicted(U64 i_SoundId, U64 i_ForSound, S32 i_Reason);
7688typedef void AILCALLBACK AuditionControl(U64 i_EventId, char const* i_Labels, U8 i_ControlType, U64 i_Filter);
7689typedef void AILCALLBACK AuditionSoundBus(U64 i_SoundId, U8 i_BusIndex);
7690
7691typedef void AILCALLBACK AuditionError(U64 i_Id, char const* i_Details);
7692
7693typedef void AILCALLBACK AuditionAsyncQueued(U64 i_RelevantId, S32 i_AsyncId, char const* i_Asset);
7694typedef void AILCALLBACK AuditionAsyncLoad(S32 i_AsyncId, S32 i_ExpectedData);
7695typedef void AILCALLBACK AuditionAsyncError(S32 i_AsyncId);
7696typedef void AILCALLBACK AuditionAsyncComplete(S32 i_AsyncId, S32 i_DataLoaded);
7697typedef void AILCALLBACK AuditionAsyncCancel(S32 i_AsyncId);
7698typedef void AILCALLBACK AuditionListenerPosition(float x, float y, float z);
7699typedef void AILCALLBACK AuditionSoundPosition(U64 i_Sound, float x, float y, float z);
7700typedef void AILCALLBACK AuditionSendCPU(HDIGDRIVER i_Driver);
7701typedef void AILCALLBACK AuditionUpdateDataCount(S32 i_CurrentDataLoaded);
7702typedef void AILCALLBACK AuditionSendCount(S32 i_Count);
7703typedef void AILCALLBACK AuditionHandleSystemLoad(S32 i_Avail, S32 i_Total);
7704typedef void AILCALLBACK AuditionVarState(char const* i_Var, U64 i_SoundId, S32 i_Int, void* i_4ByteValue);
7705typedef void AILCALLBACK AuditionRampState(char const* i_Ramp, U64 i_SoundId, S32 i_Type, float i_Current);
7706typedef void AILCALLBACK AuditionSoundState(U64 i_SoundId, float i_FinalVol, float i_3DVol, float i_BlendVol, float i_BlendPitch, float i_RampVol, float i_RampWet, float i_RampLp, float i_RampRate);
7707
7708typedef void AILCALLBACK AuditionClearState();
7709typedef void AILCALLBACK AuditionCompletionEvent(U64 i_CompletionEventId, U64 i_ParentSoundId);
7710typedef void AILCALLBACK AuditionAddRamp(U64 i_ParentSoundId, S32 i_Type, char const* i_Name, char const* i_Query, U64 i_EventId);
7711
7712typedef struct _MILESAUDITIONFUNCTIONS
7713{
7714 AuditionStatus* Status;
7715 AuditionPump* Pump;
7716 AuditionOpenBank* OpenBank;
7717 AuditionOpenComplete* OpenComplete;
7718 AuditionCloseBank* CloseBank;
7719
7720 AuditionSuppress* Suppress;
7721 AuditionFrameStart* FrameStart;
7722 AuditionFrameEnd* FrameEnd;
7723 AuditionDefragStart* DefragStart;
7724 AuditionSetBlend* SetBlend;
7725 AuditionSetPersist* SetPersist;
7726 AuditionEvent* Event;
7727 AuditionSound* Sound;
7728 AuditionSoundComplete* SoundComplete;
7729 AuditionSoundPlaying* SoundPlaying;
7730 AuditionSoundFlags* SoundFlags;
7731 AuditionSoundLimited* SoundLimited;
7732 AuditionSoundEvicted* SoundEvicted;
7733 AuditionControl* Control;
7734 AuditionSoundBus* SoundBus;
7735
7736 AuditionError* Error;
7737
7738 AuditionAsyncQueued* AsyncQueued;
7739 AuditionAsyncLoad* AsyncLoad;
7740 AuditionAsyncError* AsyncError;
7741 AuditionAsyncComplete* AsyncComplete;
7742 AuditionAsyncCancel* AsyncCancel;
7743 AuditionListenerPosition* ListenerPosition;
7744 AuditionSoundPosition* SoundPosition;
7745 AuditionSendCPU* SendCPU;
7746 AuditionSendCount* SendCount;
7747 AuditionUpdateDataCount* UpdateDataCount;
7748 AuditionHandleSystemLoad* HandleSystemLoad;
7749 AuditionVarState* VarState;
7750 AuditionRampState* RampState;
7751 AuditionSoundState* SoundState;
7752
7753 AuditionClearState* ClearState;
7754 AuditionCompletionEvent* CompletionEvent;
7755 AuditionAddRamp* AddRamp;
7756} MILESAUDITIONFUNCTIONS;
7757
7758DXDEC void AILCALL MilesEventSetAuditionFunctions(MILESAUDITIONFUNCTIONS const* i_Functions);
7759
7760// Auditioner lib functions.
7761EXPGROUP(auditioning)
7762
7763EXPTYPEBEGIN typedef S32 MILESAUDITIONCONNECTRESULT;
7764#define MILES_CONNECTED 0
7765#define MILES_CONNECT_FAILED 1
7766#define MILES_HOST_NOT_FOUND 2
7767#define MILES_SERVER_ERROR 3
7768EXPTYPEEND
7769/*
7770 Return values for $AIL_audition_connect.
7771
7772 $:MILES_CONNECTED The Auditioner connected and successfully executed the handshake.
7773 $:MILES_CONNECT_FAILED The Auditioner couldn't connect - either the IP wasn't valid, or Miles Sound Studio wasn't accepting connections.
7774 $:MILES_HOST_NOT_FOUND The given host name could not be resolved to an IP.
7775 $:MILES_SERVER_ERROR We connected, but the server was either another app on the same port, or the server version was incorrect.
7776*/
7777
7778DXDEC EXPAPI S32 AILCALL AIL_audition_connect(char const* i_Address);
7779/*
7780 Connect to a currently running Miles Sound Studio.
7781
7782 $:i_Address The IP or host name of the computer running Miles Sound Studio. Use $AIL_audition_local_host to connect to the same machine as the runtime.
7783 $:return One of $MILESAUDITIONCONNECTRESULT
7784
7785 The is a synchronous connection attempt to Miles Sound Studio - it will not return until it is happy with the connection
7786 and the server, or a failure occurs.
7787
7788 This must be called before any $AIL_add_soundbank calls.
7789*/
7790
7791DXDEC EXPAPI char const* AILCALL AIL_audition_local_host();
7792/*
7793 Return the host name of the local machine.
7794*/
7795
7796// Defines - must match values in studio/Common.h
7797EXPTYPEBEGIN typedef S32 MILESAUDITIONLANG;
7798#define MILES_LANG_ENGLISH 1
7799#define MILES_LANG_FRENCH 2
7800#define MILES_LANG_GERMAN 3
7801#define MILES_LANG_SPANISH 4
7802#define MILES_LANG_ITALIAN 5
7803#define MILES_LANG_JAPANESE 6
7804#define MILES_LANG_KOREAN 7
7805#define MILES_LANG_CHINESE 8
7806#define MILES_LANG_RUSSIAN 9
7807EXPTYPEEND
7808/*
7809 Values representing the various languages the high level tool allows.
7810
7811 $:MILES_LANG_ENGLISH English
7812 $:MILES_LANG_FRENCH French
7813 $:MILES_LANG_GERMAN German
7814 $:MILES_LANG_SPANISH Spanish
7815 $:MILES_LANG_ITALIAN Italian
7816 $:MILES_LANG_JAPANESE Japanese
7817 $:MILES_LANG_KOREAN Korean
7818 $:MILES_LANG_CHINESE Chinese
7819 $:MILES_LANG_RUSSIAN Russian
7820
7821 Values representing the various languages the high level tool allows.
7822*/
7823
7824EXPTYPEBEGIN typedef S32 MILESAUDITIONPLAT;
7825#define MILES_PLAT_WIN 1
7826#define MILES_PLAT_MAC 2
7827#define MILES_PLAT_PS3 3
7828#define MILES_PLAT_360 4
7829#define MILES_PLAT_3DS 5
7830#define MILES_PLAT_PSP 6
7831#define MILES_PLAT_IPHONE 7
7832#define MILES_PLAT_LINUX 8
7833#define MILES_PLAT_WII 9
7834#define MILES_PLAT_PSP2 10
7835#define MILES_PLAT_WIIU 11
7836#define MILES_PLAT_SEKRIT 12
7837#define MILES_PLAT_SEKRIT2 13
7838#define MILES_PLAT_WIN64 14
7839#define MILES_PLAT_LINUX64 15
7840#define MILES_PLAT_MAC64 16
7841#define MILES_PLAT_WINRT32 17
7842#define MILES_PLAT_WINRT64 18
7843#define MILES_PLAT_WINPH32 19
7844#define MILES_PLAT_ANDROID 20
7845
7846EXPTYPEEND
7847/*
7848 Values representing the various platforms the high level tool allows.
7849
7850 $:MILES_PLAT_WIN Microsoft Win32/64
7851 $:MILES_PLAT_MAC Apple OSX
7852 $:MILES_PLAT_PS3 Sony PS3
7853 $:MILES_PLAT_360 Microsoft XBox360
7854 $:MILES_PLAT_3DS Nintendo 3DS
7855 $:MILES_PLAT_PSP Sony PSP
7856 $:MILES_PLAT_IPHONE Apple iDevices
7857 $:MILES_PLAT_LINUX Linux Flavors
7858 $:MILES_PLAT_WII Nintendo Wii
7859 $:MILES_PLAT_PSP2 Sony NGP
7860
7861 Values representing the various platforms the high level tool allows.
7862*/
7863
7864DXDEC EXPAPI S32 AILCALL AIL_audition_startup(S32 i_ProfileOnly, S32 i_Language, S32 i_Platform);
7865/*
7866 Binds the Auditioner to the Miles Event Runtime.
7867
7868 $:i_ProfileOnly Specify 0 to use assets from the connected Miles Sound Studio, and 1 to use assets from disc.
7869 $:i_Language One of $MILESAUDITIONLANG, or zero to use Default assets. See comments below.
7870 $:i_Platform One of $MILESAUDITIONPLAT, or zero to use the current platform. See comments below.
7871
7872 The Auditioner can run in one of two modes - the first is standard mode, where all assets
7873 are loaded from the server, and profiling data is sent back to the server. The second is
7874 Profiling mode, where the assets are loaded exactly as they would be under normal execution,
7875 but all of the profiling data is sent to the server.
7876
7877 The $(AIL_audition_startup::i_Language) and the $(AIL_audition_startup::i_Platform) are used to determine what assets Miles Sound Studio sends
7878 the Auditioner, and as a result are not used in Profiling Mode. Otherwise these are equivalent to
7879 the options selected for compiling banks.
7880
7881 This must be called before any $AIL_add_soundbank calls.
7882*/
7883
7884DXDEC EXPAPI void AILCALL AIL_audition_shutdown();
7885/*
7886 Removes the Auditioner from the Miles Event Runtime.
7887*/
7888
7889EXPGROUP(Miles High Level Event System)
7890
7891DXDEC EXPAPI void AILCALL AIL_event_system_state(HEVENTSYSTEM system, MILESEVENTSTATE* state);
7892/*
7893 Returns an information structure about the current state of the Miles Event System.
7894
7895 $:system The system to retrieve information for, or zero for the default system.
7896 $:state A pointer to a structure to receive the state information.
7897
7898 This function is a debugging aid - it returns information for the event system.
7899*/
7900
7901DXDEC EXPAPI U32 AILCALL AIL_event_system_command_queue_remaining();
7902/*
7903 Returns the number of bytes remaining in the command buffer.
7904
7905 This can be invalid for a number of reasons - first, if the
7906 command buffer will need to wrap for the next queue, the effective
7907 bytes remaining will be lower. Second, if an enqueue occurs on another
7908 thread in the interim, the value will be outdated.
7909*/
7910
7911DXDEC EXPAPI S32 AILCALL AIL_get_event_length(char const* i_EventName);
7912/*
7913 Returns the length of the first sound referenced in the named event, in milliseconds.
7914
7915 $:i_EventName The name of an event that starts a sound.
7916 $:return The length in milliseconds, or 0 if there is an error, or the event has no sound references, or the sound was not found.
7917
7918 This looks up the given event and searches for the first Start Sound event step, then
7919 uses the first sound name in its list to look up the length. As such, if the start sound
7920 step has multiple sounds, the rest will be ignored.
7921*/
7922
7923// Callback for the error handler.
7924EXPAPI typedef void AILCALLBACK AILEVENTERRORCB(S64 i_RelevantId, char const* i_Resource);
7925/*
7926 The function prototype to use for a callback that will be made when the event system
7927 encounters an unrecoverable error.
7928
7929 $:i_RelevantId The ID of the asset that encountered the error, as best known. EventID or SoundID.
7930 $:i_Resource A string representing the name of the resource the error is in regards to, or 0 if unknown.
7931
7932 The error description can be retrieved via $AIL_last_error.
7933*/
7934
7935
7936
7937EXPAPI typedef S32 AILCALLBACK MSS_USER_RAND( void );
7938/*
7939 The function definition to use when defining your own random function.
7940
7941 You can define a function with this prototype and pass it to $AIL_register_random
7942 if you want to tie the Miles random calls in with your game's (for logging and such).
7943*/
7944
7945DXDEC EXPAPI void AILCALL AIL_set_event_error_callback(AILEVENTERRORCB * i_ErrorCallback);
7946/*
7947 Set the error handler for the event system.
7948
7949 $:i_ErrorHandler The function to call when an error is encountered.
7950
7951 Generally the event system handles errors gracefully - the only noticeable effect
7952 is that a given sound won't play, or a preset doesn't get set. As a result, the errors
7953 can sometimes be somewhat invisible. This function allows you to see what went wrong,
7954 when it went wrong.
7955
7956 The basic usage is to have the callback check $AIL_last_error() for the overall category of
7957 failure. The parameter passed to the callback might provide some context, but it can and will
7958 be zero on occasion. Generally it will represent the resource string that is being worked on when the error
7959 occurred.
7960
7961 Note that there are two out of memory errors - one is the event system ran out of memory - meaning
7962 the value passed in to $AIL_startup_event_system was insufficient for the current load, and
7963 the other is the memory used for sound data - allocated via $AIL_mem_alloc_lock - ran out.
7964*/
7965
7966
7967DXDEC EXPAPI void AILCALL AIL_register_random(MSS_USER_RAND * rand_func);
7968/*
7969 Sets the function that Miles will call to obtain a random number.
7970
7971 Use this function to set your own random function that the Miles Event System will call when it needs a random number.
7972 This lets you control the determinism of the event system.
7973*/
7974
7975
7976
7977
7978#ifdef MSS_FLT_SUPPORTED
7979
7980//
7981// Filter result codes
7982//
7983
7984typedef SINTa FLTRESULT;
7985
7986#define FLT_NOERR 0 // Success -- no error
7987#define FLT_NOT_ENABLED 1 // FLT not enabled
7988#define FLT_ALREADY_STARTED 2 // FLT already started
7989#define FLT_INVALID_PARAM 3 // Invalid parameters used
7990#define FLT_INTERNAL_ERR 4 // Internal error in FLT driver
7991#define FLT_OUT_OF_MEM 5 // Out of system RAM
7992#define FLT_ERR_NOT_IMPLEMENTED 6 // Feature not implemented
7993#define FLT_NOT_FOUND 7 // FLT supported device not found
7994#define FLT_NOT_INIT 8 // FLT not initialized
7995#define FLT_CLOSE_ERR 9 // FLT not closed correctly
7996
7997//############################################################################
7998//## ##
7999//## Interface "MSS pipeline filter" (some functions shared by ##
8000//## "MSS voice filter") ##
8001//## ##
8002//############################################################################
8003
8004typedef FLTRESULT (AILCALL *FLT_STARTUP)(void);
8005
8006typedef FLTRESULT (AILCALL *FLT_SHUTDOWN)(void);
8007
8008typedef C8 * (AILCALL *FLT_ERROR)(void);
8009
8010typedef HDRIVERSTATE (AILCALL *FLT_OPEN_DRIVER) (MSS_ALLOC_TYPE * palloc,
8011 MSS_FREE_TYPE * pfree,
8012 UINTa user,
8013 HDIGDRIVER dig, void * memory);
8014
8015typedef FLTRESULT (AILCALL *FLT_CLOSE_DRIVER) (HDRIVERSTATE state);
8016
8017typedef void (AILCALL *FLT_PREMIX_PROCESS) (HDRIVERSTATE driver);
8018
8019typedef S32 (AILCALL *FLT_POSTMIX_PROCESS) (HDRIVERSTATE driver, void *output_buffer);
8020
8021//############################################################################
8022//## ##
8023//## Interface "Pipeline filter sample services" ##
8024//## ##
8025//############################################################################
8026
8027typedef HSAMPLESTATE (AILCALL * FLTSMP_OPEN_SAMPLE) (HDRIVERSTATE driver,
8028 HSAMPLE S,
8029 void * memory);
8030
8031typedef FLTRESULT (AILCALL * FLTSMP_CLOSE_SAMPLE) (HSAMPLESTATE state);
8032
8033typedef void (AILCALL * FLTSMP_SAMPLE_PROCESS) (HSAMPLESTATE state,
8034 void * source_buffer,
8035 void * dest_buffer, // may be the same as src
8036 S32 n_samples,
8037 S32 is_stereo );
8038
8039typedef S32 (AILCALL * FLTSMP_SAMPLE_PROPERTY) (HSAMPLESTATE state,
8040 HPROPERTY property,
8041 void* before_value,
8042 void const* new_value,
8043 void* after_value
8044 );
8045
8046//############################################################################
8047//## ##
8048//## Interface "MSS output filter" ##
8049//## ##
8050//############################################################################
8051
8052typedef S32 (AILCALL * VFLT_ASSIGN_SAMPLE_VOICE) (HDRIVERSTATE driver,
8053 HSAMPLE S);
8054
8055typedef void (AILCALL * VFLT_RELEASE_SAMPLE_VOICE) (HDRIVERSTATE driver,
8056 HSAMPLE S);
8057
8058typedef S32 (AILCALL * VFLT_START_SAMPLE_VOICE) (HDRIVERSTATE driver,
8059 HSAMPLE S);
8060
8061//############################################################################
8062//## ##
8063//## Interface "Voice filter driver services" ##
8064//## ##
8065//############################################################################
8066
8067typedef S32 (AILCALL * VDRV_DRIVER_PROPERTY) (HDRIVERSTATE driver,
8068 HPROPERTY property,
8069 void* before_value,
8070 void const* new_value,
8071 void* after_value
8072 );
8073
8074typedef S32 (AILCALL * VDRV_FORCE_UPDATE) (HDRIVERSTATE driver);
8075
8076//############################################################################
8077//## ##
8078//## Interface "Voice filter sample services" ##
8079//## ##
8080//############################################################################
8081
8082typedef S32 (AILCALL * VSMP_SAMPLE_PROPERTY) (HSAMPLE S,
8083 HPROPERTY property,
8084 void* before_value,
8085 void const* new_value,
8086 void* after_value
8087 );
8088
8089//
8090// Pipeline filter calls
8091//
8092
8093DXDEC HPROVIDER AILCALL AIL_digital_output_filter (HDIGDRIVER dig);
8094
8095DXDEC S32 AILCALL AIL_enumerate_filters (HMSSENUM *next,
8096 HPROVIDER *dest,
8097 C8 * *name);
8098DXDEC HDRIVERSTATE
8099 AILCALL AIL_open_filter (HPROVIDER lib,
8100 HDIGDRIVER dig);
8101
8102DXDEC void AILCALL AIL_close_filter (HDRIVERSTATE filter);
8103
8104DXDEC S32 AILCALL AIL_find_filter (C8 const *name,
8105 HPROVIDER *ret);
8106
8107DXDEC S32 AILCALL AIL_enumerate_filter_properties
8108 (HPROVIDER lib,
8109 HMSSENUM * next,
8110 RIB_INTERFACE_ENTRY * dest);
8111
8112DXDEC S32 AILCALL AIL_filter_property (HPROVIDER lib,
8113 C8 const* name,
8114 void* before_value,
8115 void const* new_value,
8116 void* after_value
8117 );
8118
8119DXDEC S32 AILCALL AIL_enumerate_output_filter_driver_properties
8120 (HPROVIDER lib,
8121 HMSSENUM * next,
8122 RIB_INTERFACE_ENTRY * dest);
8123
8124DXDEC S32 AILCALL AIL_output_filter_driver_property
8125 (HDIGDRIVER dig,
8126 C8 const * name,
8127 void* before_value,
8128 void const* new_value,
8129 void* after_value
8130 );
8131
8132DXDEC S32 AILCALL AIL_enumerate_output_filter_sample_properties
8133 (HPROVIDER lib,
8134 HMSSENUM * next,
8135 RIB_INTERFACE_ENTRY * dest);
8136
8137DXDEC S32 AILCALL AIL_enumerate_filter_sample_properties
8138 (HPROVIDER lib,
8139 HMSSENUM * next,
8140 RIB_INTERFACE_ENTRY * dest);
8141
8142DXDEC S32 AILCALL AIL_enumerate_sample_stage_properties
8143 (HSAMPLE S,
8144 SAMPLESTAGE stage,
8145 HMSSENUM * next,
8146 RIB_INTERFACE_ENTRY * dest);
8147
8148DXDEC S32 AILCALL AIL_sample_stage_property
8149 (HSAMPLE S,
8150 SAMPLESTAGE stage,
8151 C8 const * name,
8152 S32 channel,
8153 void* before_value,
8154 void const* new_value,
8155 void* after_value
8156 );
8157
8158#define AIL_filter_sample_property(S,name,beforev,newv,afterv) AIL_sample_stage_property((S),SP_FILTER_0,(name),-1,(beforev),(newv),(afterv))
8159
8160typedef struct _FLTPROVIDER
8161{
8162 S32 provider_flags;
8163 S32 driver_size;
8164 S32 sample_size;
8165
8166 PROVIDER_PROPERTY PROVIDER_property;
8167
8168 FLT_STARTUP startup;
8169 FLT_ERROR error;
8170 FLT_SHUTDOWN shutdown;
8171 FLT_OPEN_DRIVER open_driver;
8172 FLT_CLOSE_DRIVER close_driver;
8173 FLT_PREMIX_PROCESS premix_process;
8174 FLT_POSTMIX_PROCESS postmix_process;
8175
8176 FLTSMP_OPEN_SAMPLE open_sample;
8177 FLTSMP_CLOSE_SAMPLE close_sample;
8178 FLTSMP_SAMPLE_PROCESS sample_process;
8179 FLTSMP_SAMPLE_PROPERTY sample_property;
8180
8181 VFLT_ASSIGN_SAMPLE_VOICE assign_sample_voice;
8182 VFLT_RELEASE_SAMPLE_VOICE release_sample_voice;
8183 VFLT_START_SAMPLE_VOICE start_sample_voice;
8184
8185 VDRV_DRIVER_PROPERTY driver_property;
8186 VDRV_FORCE_UPDATE force_update;
8187
8188 VSMP_SAMPLE_PROPERTY output_sample_property;
8189
8190 HDIGDRIVER dig;
8191 HPROVIDER provider;
8192 HDRIVERSTATE driver_state;
8193
8194 struct _FLTPROVIDER *next;
8195} FLTPROVIDER;
8196
8197//
8198// Values for "Flags" property exported by all MSS Pipeline Filter and MSS Output Filter
8199// providers
8200//
8201
8202#define FPROV_ON_SAMPLES 0x0001 // Pipeline filter that operates on input samples (and is enumerated by AIL_enumerate_filters)
8203#define FPROV_ON_POSTMIX 0x0002 // Pipeline filter that operates on the post mixed output (capture filter)
8204#define FPROV_MATRIX 0x0004 // This is a matrix output filter (e.g., SRS/Dolby)
8205#define FPROV_VOICE 0x0008 // This is a per-voice output filter (e.g., DirectSound 3D)
8206#define FPROV_3D 0x0010 // Output filter uses S3D substructure for positioning
8207#define FPROV_OCCLUSION 0x0020 // Output filter supports occlusion (doesn't need per-sample lowpass)
8208#define FPROV_EAX 0x0040 // Output filter supports EAX-compatible environmental reverb
8209#define FPROV_SIDECHAIN 0x0080 // Filter has an "Input" property on the 3rd index for side chaining.
8210
8211#define FPROV_SPU_MASK 0xff0000 // Mask here the SPU INDEX STARTS
8212#define FPROV_SPU_INDEX( val ) ( ( val >> 16 ) & 0xff )
8213#define FPROV_MAKE_SPU_INDEX( val ) ( val << 16 )
8214
8215
8216
8217#ifdef IS_WIN32
8218
8219#define MSS_EAX_AUTO_GAIN 1
8220#define MSS_EAX_AUTOWAH 2
8221#define MSS_EAX_CHORUS 3
8222#define MSS_EAX_DISTORTION 4
8223#define MSS_EAX_ECHO 5
8224#define MSS_EAX_EQUALIZER 6
8225#define MSS_EAX_FLANGER 7
8226#define MSS_EAX_FSHIFTER 8
8227#define MSS_EAX_VMORPHER 9
8228#define MSS_EAX_PSHIFTER 10
8229#define MSS_EAX_RMODULATOR 11
8230#define MSS_EAX_REVERB 12
8231
8232typedef struct EAX_SAMPLE_SLOT_VOLUME
8233{
8234 S32 Slot; // 0, 1, 2, 3
8235 S32 Send;
8236 S32 SendHF;
8237 S32 Occlusion;
8238 F32 OcclusionLFRatio;
8239 F32 OcclusionRoomRatio;
8240 F32 OcclusionDirectRatio;
8241} EAX_SAMPLE_SLOT_VOLUME;
8242
8243typedef struct EAX_SAMPLE_SLOT_VOLUMES
8244{
8245 U32 NumVolumes; // 0, 1, or 2
8246 EAX_SAMPLE_SLOT_VOLUME volumes[ 2 ];
8247} EAX_SAMPLE_SLOT_VOLUMES;
8248
8249// Use this structure for EAX REVERB
8250typedef struct EAX_REVERB
8251{
8252 S32 Effect; // set to MSS_EAX_REVERB
8253 S32 Volume; // -10000 to 0
8254 U32 Environment; // one of the ENVIRONMENT_ enums
8255 F32 EnvironmentSize; // environment size in meters
8256 F32 EnvironmentDiffusion; // environment diffusion
8257 S32 Room; // room effect level (at mid frequencies)
8258 S32 RoomHF; // relative room effect level at high frequencies
8259 S32 RoomLF; // relative room effect level at low frequencies
8260 F32 DecayTime; // reverberation decay time at mid frequencies
8261 F32 DecayHFRatio; // high-frequency to mid-frequency decay time ratio
8262 F32 DecayLFRatio; // low-frequency to mid-frequency decay time ratio
8263 S32 Reflections; // early reflections level relative to room effect
8264 F32 ReflectionsDelay; // initial reflection delay time
8265 F32 ReflectionsPanX; // early reflections panning vector
8266 F32 ReflectionsPanY; // early reflections panning vector
8267 F32 ReflectionsPanZ; // early reflections panning vector
8268 S32 Reverb; // late reverberation level relative to room effect
8269 F32 ReverbDelay; // late reverberation delay time relative to initial reflection
8270 F32 ReverbPanX; // late reverberation panning vector
8271 F32 ReverbPanY; // late reverberation panning vector
8272 F32 ReverbPanZ; // late reverberation panning vector
8273 F32 EchoTime; // echo time
8274 F32 EchoDepth; // echo depth
8275 F32 ModulationTime; // modulation time
8276 F32 ModulationDepth; // modulation depth
8277 F32 AirAbsorptionHF; // change in level per meter at high frequencies
8278 F32 HFReference; // reference high frequency
8279 F32 LFReference; // reference low frequency
8280 F32 RoomRolloffFactor; // like DS3D flRolloffFactor but for room effect
8281 U32 Flags; // modifies the behavior of properties
8282} EAX_REVERB;
8283
8284// Use this structure for EAX AUTOGAIN
8285typedef struct EAX_AUTOGAIN
8286{
8287 S32 Effect; // set to MSS_EAX_AUTO_GAIN
8288 S32 Volume; // -10000 to 0
8289 U32 OnOff; // Switch Compressor on or off (1 or 0)
8290} EAX_AUTOGAIN;
8291
8292// Use this structure for EAX AUTOWAH
8293typedef struct EAX_AUTOWAH
8294{
8295 S32 Effect; // set to MSS_EAX_AUTOWAH
8296 S32 Volume; // -10000 to 0
8297 F32 AttackTime; // Attack time (seconds)
8298 F32 ReleaseTime; // Release time (seconds)
8299 S32 Resonance; // Resonance (mB)
8300 S32 PeakLevel; // Peak level (mB)
8301} EAX_AUTOWAH;
8302
8303// Use this structure for EAX CHORUS
8304typedef struct EAX_CHORUS
8305{
8306 S32 Effect; // set to MSS_EAX_CHORUS
8307 S32 Volume; // -10000 to 0
8308 U32 Waveform; // Waveform selector - 0 = sinusoid, 1 = triangle
8309 S32 Phase; // Phase (Degrees)
8310 F32 Rate; // Rate (Hz)
8311 F32 Depth; // Depth (0 to 1)
8312 F32 Feedback; // Feedback (-1 to 1)
8313 F32 Delay; // Delay (seconds)
8314} EAX_CHORUS;
8315
8316// Use this structure for EAX DISTORTION
8317typedef struct EAX_DISTORTION
8318{
8319 S32 Effect; // set to MSS_EAX_DISTORTION
8320 S32 Volume; // -10000 to 0
8321 F32 Edge; // Controls the shape of the distortion (0 to 1)
8322 S32 Gain; // Controls the post distortion gain (mB)
8323 F32 LowPassCutOff; // Controls the cut-off of the filter pre-distortion (Hz)
8324 F32 EQCenter; // Controls the center frequency of the EQ post-distortion (Hz)
8325 F32 EQBandwidth; // Controls the bandwidth of the EQ post-distortion (Hz)
8326} EAX_DISTORTION;
8327
8328// Use this structure for EAX ECHO
8329typedef struct EAX_ECHO
8330{
8331 S32 Effect; // set to MSS_EAX_ECHO
8332 S32 Volume; // -10000 to 0
8333 F32 Delay; // Controls the initial delay time (seconds)
8334 F32 LRDelay; // Controls the delay time between the first and second taps (seconds)
8335 F32 Damping; // Controls a low-pass filter that dampens the echoes (0 to 1)
8336 F32 Feedback; // Controls the duration of echo repetition (0 to 1)
8337 F32 Spread; // Controls the left-right spread of the echoes
8338} EAX_ECHO;
8339
8340// Use this structure for EAXEQUALIZER_ALLPARAMETERS
8341typedef struct EAX_EQUALIZER
8342{
8343 S32 Effect; // set to MSS_EAX_EQUALIZER
8344 S32 Volume; // -10000 to 0
8345 S32 LowGain; // (mB)
8346 F32 LowCutOff; // (Hz)
8347 S32 Mid1Gain; // (mB)
8348 F32 Mid1Center; // (Hz)
8349 F32 Mid1Width; // (octaves)
8350 F32 Mid2Gain; // (mB)
8351 F32 Mid2Center; // (Hz)
8352 F32 Mid2Width; // (octaves)
8353 S32 HighGain; // (mB)
8354 F32 HighCutOff; // (Hz)
8355} EAX_EQUALIZER;
8356
8357// Use this structure for EAX FLANGER
8358typedef struct EAX_FLANGER
8359{
8360 S32 Effect; // set to MSS_EAX_FLANGER
8361 S32 Volume; // -10000 to 0
8362 U32 Waveform; // Waveform selector - 0 = sinusoid, 1 = triangle
8363 S32 Phase; // Phase (Degrees)
8364 F32 Rate; // Rate (Hz)
8365 F32 Depth; // Depth (0 to 1)
8366 F32 Feedback; // Feedback (0 to 1)
8367 F32 Delay; // Delay (seconds)
8368} EAX_FLANGER;
8369
8370
8371// Use this structure for EAX FREQUENCY SHIFTER
8372typedef struct EAX_FSHIFTER
8373{
8374 S32 Effect; // set to MSS_EAX_FSHIFTER
8375 S32 Volume; // -10000 to 0
8376 F32 Frequency; // (Hz)
8377 U32 LeftDirection; // direction - 0 = down, 1 = up, 2 = off
8378 U32 RightDirection; // direction - 0 = down, 1 = up, 2 = off
8379} EAX_FSHIFTER;
8380
8381// Use this structure for EAX VOCAL MORPHER
8382typedef struct EAX_VMORPHER
8383{
8384 S32 Effect; // set to MSS_EAX_VMORPHER
8385 S32 Volume; // -10000 to 0
8386 U32 PhonemeA; // phoneme: 0 to 29 - A E I O U AA AE AH AO EH ER IH IY UH UW B D G J K L M N P R S T V Z
8387 S32 PhonemeACoarseTuning; // (semitones)
8388 U32 PhonemeB; // phoneme: 0 to 29 - A E I O U AA AE AH AO EH ER IH IY UH UW B D G J K L M N P R S T V Z
8389 S32 PhonemeBCoarseTuning; // (semitones)
8390 U32 Waveform; // Waveform selector - 0 = sinusoid, 1 = triangle, 2 = sawtooth
8391 F32 Rate; // (Hz)
8392} EAX_VMORPHER;
8393
8394
8395// Use this structure for EAX PITCH SHIFTER
8396typedef struct EAX_PSHIFTER
8397{
8398 S32 Effect; // set to MSS_EAX_PSHIFTER
8399 S32 Volume; // -10000 to 0
8400 S32 CoarseTune; // Amount of pitch shift (semitones)
8401 S32 FineTune; // Amount of pitch shift (cents)
8402} EAX_PSHIFTER;
8403
8404// Use this structure for EAX RING MODULATOR
8405typedef struct EAX_RMODULATOR
8406{
8407 S32 Effect; // set to MSS_EAX_RMODULATOR
8408 S32 Volume; // -10000 to 0
8409 F32 Frequency; // Frequency of modulation (Hz)
8410 F32 HighPassCutOff; // Cut-off frequency of high-pass filter (Hz)
8411 U32 Waveform; // Waveform selector - 0 = sinusoid, 1 = triangle, 2 = sawtooth
8412} EAX_RMODULATOR;
8413
8414#endif
8415
8416#else // MSS_FLT_SUPPORTED
8417
8418typedef struct _FLTPROVIDER
8419{
8420 U32 junk;
8421} FLTPROVIDER;
8422
8423#endif // MSS_FLT_SUPPORTED
8424
8425#endif // MSS_BASIC
8426
8427RADDEFEND
8428
8429#endif // MSS_H