wessapi.h (18577B)
1 /*------------------------------------------------------------------*/ 2 /* 3 The Williams Entertainment Sound System 4 Application Programming Interface Routines 5 by Scott Patterson 6 */ 7 /*------------------------------------------------------------------*/ 8 9 #ifndef _WESSAPI_H 10 #define _WESSAPI_H 11 12 #include <ultra64.h> 13 14 /*------------------------------------------------------------------*/ 15 /* 16 Enumerated types. 17 */ 18 /*------------------------------------------------------------------*/ 19 20 /* used by wess_seq_pause and wess_seq_pauseall functions */ 21 enum MuteFlag { NoMute, YesMute }; 22 23 /* used by wess_seq_restartall function */ 24 enum VoiceRestartFlag { NoVoiceRestart, YesVoiceRestart }; 25 26 /* used by wess_sequence_status function */ 27 enum SequenceStatus { SEQUENCE_INVALID, 28 SEQUENCE_INACTIVE, 29 SEQUENCE_STOPPED, 30 SEQUENCE_PLAYING }; 31 32 /*------------------------------------------------------------------*/ 33 /*------------------------------------------------------------------*/ 34 /* 35 System Setup and Shutdown Functions. 36 */ 37 /*------------------------------------------------------------------*/ 38 /*------------------------------------------------------------------*/ 39 40 41 /* 42 wess_set_error_callback - set a callback for runtime audio errors 43 44 passing NULL removes the callback 45 46 the errstring passed to the callback is guaranteed to be less than 12 47 uppercase letter characters only, thus you can print the errors 48 with a very simple print routine. 49 50 the errnum1 and errnum2 ints passed to the callback may or may not 51 have meaning based on the errstring 52 */ 53 54 typedef void (*WessErrorCallbackProc)( char *errstring, int errnum1, int errnum2 ); 55 56 extern void wess_set_error_callback( WessErrorCallbackProc errcall ); 57 58 /* 59 wess_set_decompression_callback - set a callback for runtime decompression 60 61 passing NULL removes the callback 62 63 If the sound system source files are compressed, this callback will happen 64 inside the following functions: 65 66 wess_load_module 67 68 wess_seq_loader_init 69 70 wess_seq_load, wess_seq_range_load, or wess_seq_list_load 71 72 when the callback occurs you must run the decompression type 73 that matches the decomp_type parameter from the source file at a given 74 offset into memory. 75 76 if the decompression is not available or something goes wrong, then return 77 a negative number and the sound system call that issued the callback will 78 abort. 79 */ 80 81 #define NO_DECOMPRESSION 0 /* you will never actually get this as a decomp type */ 82 #define MARKG_INFLATE_DECOMPRESSION 1 83 84 typedef int (*WessDecompCallbackProc)( unsigned char decomp_type, 85 char *fileref, 86 unsigned long file_offset, 87 char *ramdest, 88 unsigned long uncompressed_size ); 89 90 extern void wess_set_decomp_callback( WessDecompCallbackProc decompcall ); 91 92 /* 93 wess_set_tweak - set the tweak parameters for the audio engine 94 95 If you need to change audio system parameters, wess_tweak allows this. 96 97 If you don't know what these parameters do, don't change them! 98 99 This call must be made before wess_init to have any effect. 100 101 Use the mask to set particlar parameters. 102 */ 103 104 #define TWEAK_DMA_BUFFERS (0x1L<< 0) 105 #define TWEAK_DMA_MESSAGES (0x1L<< 1) 106 #define TWEAK_DMA_BUFFER_LENGTH (0x1L<< 2) 107 #define TWEAK_EXTRA_SAMPLES (0x1L<< 3) 108 #define TWEAK_FRAME_LAG (0x1L<< 4) 109 #define TWEAK_VOICES (0x1L<< 5) 110 #define TWEAK_UPDATES (0x1L<< 6) 111 #define TWEAK_SEQUENCES (0x1L<< 7) 112 #define TWEAK_TRACKS (0x1L<< 8) 113 #define TWEAK_GATES (0x1L<< 9) 114 #define TWEAK_ITERS (0x1L<< 10) 115 #define TWEAK_CALLBACKS (0x1L<< 11) 116 #define TWEAK_MAX_TRKS_PER_SEQ (0x1L<< 12) 117 #define TWEAK_MAX_SUBS_PER_TRK (0x1L<< 13) 118 119 typedef struct { 120 unsigned long mask; 121 unsigned long dma_buffers; /* default is 24 */ 122 unsigned long dma_messages; /* default is 32 */ 123 unsigned long dma_buffer_length; /* default is 0x800 */ 124 unsigned long extra_samples; /* default is 80 */ 125 unsigned long frame_lag; /* default is 1 */ 126 unsigned long voices; /* default is 24 */ 127 unsigned long updates; /* default is 48 */ 128 unsigned long sequences; /* default is 26 */ 129 unsigned long tracks; /* default is 25 */ 130 unsigned long gates; /* default is 0 */ 131 unsigned long iters; /* default is 0 */ 132 unsigned long callbacks; /* default is 0 */ 133 unsigned long max_trks_per_seq; /* default is 16 */ 134 unsigned long max_subs_per_trk; /* default is 0 */ 135 } WessTweakAttr; 136 137 extern void wess_set_tweaks(WessTweakAttr *attr); 138 139 /* 140 wess_get_tweak - get the tweak parameters for the audio engine 141 142 The given WessTweakAttr structure will updated to the current parameters. 143 144 This function simply fills the WessTweakAttr structure and sets mask = 0. 145 */ 146 147 extern void wess_get_tweaks(WessTweakAttr *attr); 148 149 150 /* 151 wess_init - Initializes the Williams Entertainment Sound System. 152 153 config is a pointer to the WessConfig structure that holds the 154 following information: 155 156 audioframerate - the frequency (number of times per second) the 157 wess_work function will be called. Typically this 158 will be 30 (30fps) or 60 (60fps). 159 160 outputsamplerate - this is the output sample rate of the audio data 161 the higher this number, the higher the possible 162 frequency response of the audio, but the more data 163 that the RSP must calculate. 164 165 maxACMDSize - the number of commands allowed for the audio 166 command list sent to the RSP. If this number is 167 too small, memory will be trashed. Typical values 168 are 3072 (for 30fps) or 2048 (for 60fps) 169 170 heap_ptr - pointer to an audio heap pointer set up with the 171 alHeapInit call. 172 173 revtbl_ptr - pointer to a reverb settings table for effects initialization. 174 this MUST be set to zero if no effects are to be turned on. 175 */ 176 177 #define WESS_REVERB_NONE 0 178 #define WESS_REVERB_SMALLROOM 1 179 #define WESS_REVERB_BIGROOM 2 180 #define WESS_REVERB_CHORUS 3 181 #define WESS_REVERB_FLANGE 4 182 #define WESS_REVERB_ECHO 5 183 #define WESS_REVERB_CUSTOM 6 184 185 typedef struct WessConfig { /* see wess_init function for more info */ 186 f32 audioframerate; /* the number of times per second that wesswork is called */ 187 u32 outputsamplerate; /* the output samplerate to calculate */ 188 u32 maxACMDSize; /* the size of the audio command list buffers */ 189 ALHeap *heap_ptr; /* audio heap pointer */ 190 char *wdd_location; /* cart location of wdd file */ 191 s32 reverb_id; /* choose from WESS_REVERB defines */ 192 s32 *revtbl_ptr; /* reverb table pointer (used if reverb_id == WESS_REVERB_CUSTOM */ 193 } WessConfig; 194 195 extern void wess_init(WessConfig *wessconfig); 196 197 /* 198 wess_rom_copy - U64 rom copy 199 200 after wess_init has been called, you can call wess_rom_copy 201 202 - this is a blocking rom copy 203 204 - returns 0 and copies nothing if the request was for zero bytes or if 205 the wess_init call has not been made 206 - returns length copied if length is non zero 207 */ 208 209 extern int wess_rom_copy(char *src, char *dest, int len); 210 211 /* 212 wess_exit - call this to shutdown the audio system 213 */ 214 215 extern void wess_exit(void); 216 217 /* 218 wess_work - performs ALL CPU audio work for application 219 220 This function must be called at a constant frequency, as set up 221 by the WessConfig.audioframerate parameter in the wess_init function. 222 It handles all audio work processing and returns a pointer to an RSP 223 audio task, or 0 if no RSP processing is required. 224 225 The task returned by wess_work must be given to the RSP as quickly 226 as possible so that the RSP audio microcode has completed building 227 the audio frame buffer in time for the next call to wess_work. 228 Typically this requires that an in-progress RSP graphics task must 229 yield, and will resume when the RSP completes the audio task. 230 */ 231 232 extern OSTask * wess_work(void); 233 234 /* 235 wess_master_fade - Master volume fade. 236 237 This function smoothly fades the master volume of all sound 238 effects and music channels from the current volume to dest_vol. 239 The transition will complete in millisec milliseconds. Returns the 240 current master volume level prior to the call. 241 242 dest_vol should be 0 - 127 243 */ 244 245 extern int wess_master_fade(char dest_vol, int millisec); 246 247 /* 248 routine: wess_load_module() 249 250 - loads master table of sounds and sequences 251 - returns 0 for failure, 1 for success 252 - NULL for memory_pointer results in internal memory allocation 253 of memory_allowance bytes 254 - if memory_pointer!=NULL then it is assumed to be a pointer 255 to memory_allocation bytes of memory for use by the sound system 256 - enables sequencer engine 257 */ 258 259 extern int wess_size_module (char *wmd_filename); 260 261 extern int wess_load_module (char *wmd_filename, 262 char *memory_pointer, 263 int memory_allowance); 264 265 /* 266 routine: wess_unload_module() 267 268 - disables sequencer engine 269 - frees any allocated memory 270 */ 271 272 extern void wess_unload_module (void); 273 274 /* 275 routine: wess_get_wmd_start() 276 277 - after call to wess_load_module is successful, this 278 gets the pointer to beginning of module block 279 */ 280 281 extern char *wess_get_wmd_start (void); 282 283 /* 284 routine: wess_get_wmd_end() 285 286 - after call to wess_load_module is successful, this 287 gets the pointer past end of module block 288 */ 289 290 extern char *wess_get_wmd_end (void); 291 292 /*------------------------------------------------------------------*/ 293 /*------------------------------------------------------------------*/ 294 /* 295 Sequencer calls. 296 */ 297 /*------------------------------------------------------------------*/ 298 /*------------------------------------------------------------------*/ 299 300 /* 301 routine: wess_seq_trigger() 302 303 - a sequence is everything from a single sound to a music sequence. 304 - multiple sequences can be called simultaneously 305 - dynamic sequence, track, and voice allocation is managed 306 by the sequencer 307 - tracks have priorty assignments and voices triggered by a 308 track inheirit its priority 309 - you can trigger multiple instances of a sequence with multiple 310 trigger calls 311 */ 312 313 #define TRIGGER_VOLUME (0x1L<< 0) 314 #define TRIGGER_PAN (0x1L<< 1) 315 #define TRIGGER_PATCH (0x1L<< 2) 316 #define TRIGGER_PITCH (0x1L<< 3) 317 #define TRIGGER_MUTEMODE (0x1L<< 4) 318 #define TRIGGER_TEMPO (0x1L<< 5) 319 #define TRIGGER_TIMED (0x1L<< 6) 320 #define TRIGGER_LOOPED (0x1L<< 7) 321 #define TRIGGER_REVERB (0x1L<< 8) 322 323 typedef struct { 324 unsigned long mask; 325 unsigned char volume; /* 0-127 */ 326 unsigned char pan; /* 0-127, 64 center */ 327 short patch; /* 0-32767 */ 328 short pitch; /* -8192 to 8191 */ 329 unsigned char mutemode; /* 0-7 */ 330 unsigned char reverb; 331 unsigned short tempo; 332 unsigned long timeppq; 333 } TriggerPlayAttr; 334 335 /* the basic sequence trigger call */ 336 337 extern void wess_seq_trigger (int seq_num); 338 339 /* override masked sequence parameters */ 340 341 extern void wess_seq_trigger_special (int seq_num, 342 TriggerPlayAttr *attr); 343 344 /* set your own type number to the sequence */ 345 346 extern void wess_seq_trigger_type (int seq_num, 347 unsigned long seq_type); 348 349 /* set your own type number to the sequence and 350 override masked sequence parameters */ 351 352 extern void wess_seq_trigger_type_special (int seq_num, 353 unsigned long seq_type, 354 TriggerPlayAttr *attr); 355 356 extern void wess_seq_update_type_special (unsigned long seq_type, 357 TriggerPlayAttr *attr); 358 359 /* 360 routine: wess_seq_status() 361 362 - find out status of any instances of sequences_number 363 - returns SEQUENCE_INVALID for no such sequence 364 SEQUENCE_INACTIVE for is not being processed 365 SEQUENCE_STOPPED for sequence is stopped 366 SEQUENCE_PLAYING for sequence is playing 367 */ 368 369 extern int wess_seq_status (int sequence_number); 370 371 /* 372 routine: wess_seq_type_status() 373 374 - find out status of any instances of sequence_type 375 - returns SEQUENCE_INACTIVE for no sequence of this type is being processed 376 SEQUENCE_STOPPED for a sequence of this type is stopped 377 SEQUENCE_PLAYING for a sequence is this type is playing 378 */ 379 380 extern int wess_seq_type_status (unsigned long sequence_type); 381 382 /* 383 routine: wess_seq_stop() 384 385 - stops all instances of a specified sequence 386 */ 387 388 extern void wess_seq_stop (int sequence_number); 389 390 extern void wess_seq_stop_and_voiceramp (int sequence_number,int millisec); 391 392 /* 393 routine: wess_seq_stoptype() 394 395 - immediate stop of all sequences that were registered as a certain 396 type by wess_seq_trigger_type 397 */ 398 399 extern void wess_seq_stoptype (unsigned long sequence_type); 400 401 extern void wess_seq_stoptype_and_voiceramp (unsigned long sequence_type,int millisec); 402 403 /* 404 routine: wess_seq_stopall() 405 406 - immediate stop of all sequences 407 */ 408 409 extern void wess_seq_stopall (void); 410 411 extern void wess_seq_stopall_and_voiceramp (int millisec); 412 413 /* 414 routine: wess_seq_pause() 415 416 - immediately pause a sequence 417 - if MuteFlag is YesMute, all playing voices are muted 418 - if MuteFlag is NoMute, all playing voices do note decay 419 */ 420 421 extern void wess_seq_pause (int sequence_number, 422 enum MuteFlag mflag); 423 424 /* 425 routine: wess_seq_restart() 426 427 - restarts a paused sequence 428 */ 429 430 extern void wess_seq_restart (int sequence_number); 431 432 /* 433 routine: wess_seq_stopall() 434 435 - immediate pause of all sequences 436 - if mflag is YesMute, all playing voices are muted 437 - if mflag is NoMute, all playing voices remain on 438 - if remember bits are set then corrosponding voices 439 will restore when wess_seq_restartall is called 440 */ 441 442 #define REMEMBER_MUSIC (0x1L<< 0) 443 #define REMEMBER_SNDFX (0x1L<< 1) 444 445 extern void wess_seq_pauseall (enum MuteFlag mflag, int remember); 446 447 /* 448 routine: wess_seq_restartall() 449 450 - restart all paused sequences 451 - if restart_remembered voices is YesVoiceRestart, all the 452 voices remembered at pauseall time will restart 453 */ 454 455 extern void wess_seq_restartall (enum VoiceRestartFlag restart_remembered_voices); 456 457 /* 458 routine: wess_register_callback() 459 460 - callbacks are useful for video and program flow synchronization 461 with audio. 462 - callbacks are called when any track of a playing sequence 463 encounters a StatusMark with a registered marker_ID 464 - the first parameter of the callback is the marker_ID encountered 465 - the second parameter is the StatusMark's data field 466 */ 467 468 extern void wess_register_callback (char marker_ID, 469 void (*function_pointer)(char,short)); 470 471 /* 472 routine: wess_delete_callback() 473 474 - stop any callbacks from a particular marker_ID 475 */ 476 477 extern void wess_delete_callback (char marker_ID); 478 479 /*------------------------------------------------------------------*/ 480 /*------------------------------------------------------------------*/ 481 /* 482 Master functions get and set global sound parameters. 483 */ 484 /*------------------------------------------------------------------*/ 485 /*------------------------------------------------------------------*/ 486 487 /* 488 routine: wess_master_sfx_volume_get() 489 routine: wess_master_mus_volume_get() 490 491 - gets the master volume 492 */ 493 494 extern char wess_master_sfx_volume_get (void); 495 extern char wess_master_mus_volume_get (void); 496 497 /* 498 routine: wess_master_sfx_vol_set() 499 routine: wess_master_mus_vol_set() 500 501 - sets the master volume 502 */ 503 504 extern void wess_master_sfx_vol_set (char volume); 505 extern void wess_master_mus_vol_set (char volume); 506 507 /* 508 routine: wess_pan_mode_get() 509 510 - gets the pan mode where 0=off, 1=normal, 2=switchLR 511 */ 512 513 extern char wess_pan_mode_get (void); 514 515 /* 516 routine: wess_pan_mode_set() 517 518 - sets the pan mode where 0=off, 1=normal, 2=switchLR 519 */ 520 521 extern void wess_pan_mode_set (char mode); 522 523 /* 524 routine: wess_set_mute_release(millisec) 525 526 - sets the stop/mute release time given milliseconds 527 */ 528 529 extern void wess_set_mute_release(int millisec); 530 531 /* 532 routine: wess_get_mute_release(millisec) 533 534 - gets the stop/mute release time given milliseconds 535 */ 536 537 extern int wess_get_mute_release(void); 538 539 /* 540 routine: wess_master_status() 541 542 - this returns a pointer to low level data structures 543 - some function calls need this pointer 544 */ 545 546 extern void * wess_get_master_status (void); 547 548 #endif 549 550 551 552