gc/asndlib.h

   1 /* ASNDLIB -> accelerated sound lib using the DSP
   2
   3 Copyright (c) 2008 Hermes <www.entuwii.net>
   4 All rights reserved.
   5
   6 Redistribution and use in source and binary forms, with or without modification, are
   7 permitted provided that the following conditions are met:
   8
   9 - Redistributions of source code must retain the above copyright notice, this list of
  10   conditions and the following disclaimer.
  11 - Redistributions in binary form must reproduce the above copyright notice, this list
  12   of conditions and the following disclaimer in the documentation and/or other
  13   materials provided with the distribution.
  14 - The names of the contributors may not be used to endorse or promote products derived
  15   from this software without specific prior written permission.
  16
  17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
  18 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
  20 THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  24 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
  25 THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26
  27 */
  28
  29
  30 #ifndef __ASNDLIB_H__
  31 #define __ASNDLIB_H__
  32
  33 #define __SNDLIB_H__
  34
  35 #define ASND_LIB 0x100
  36 #define SND_LIB  (ASND_LIB+2)
  37
  38 #include <gctypes.h>
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 // SND return values
  45
  46 #define SND_OK               0
  47 #define SND_INVALID         -1
  48 #define SND_ISNOTASONGVOICE -2
  49 #define SND_BUSY             1
  50
  51 // SND_IsActiveVoice additional return values
  52
  53 #define SND_UNUSED   0   // you can use this voice
  54 #define SND_WORKING  1   // this voice is in progress
  55 #define SND_WAITING  2   // this voice is in progress and waiting to one SND_AddVoice function (the voice handler is called continuously)
  56
  57 // SND_SetVoice format
  58 #define VOICE_MONO_8BIT    0
  59 #define VOICE_MONO_16BIT   1
  60 #define VOICE_STEREO_8BIT  2
  61 #define VOICE_STEREO_16BIT 3
  62
  63
  64 // Voice volume Range
  65
  66 #define MIN_VOLUME 0
  67 #define MID_VOLUME 127
  68 #define MAX_VOLUME 255
  69
  70 // Pitch Range
  71
  72 #define MIN_PITCH      1      // 1 Hz
  73
  74 #define F44100HZ_PITCH 44100  // 44100Hz
  75
  76 #define MAX_PITCH      144000 // 144000Hz (more process time for pitch>48000)
  77
  78 #define INIT_RATE_48000
  79
  80 // note codification
  81
  82 enum
  83 {
  84 NOTE_DO=0,
  85 NOTE_DOs,
  86 NOTE_REb=NOTE_DOs,
  87 NOTE_RE,
  88 NOTE_REs,
  89 NOTE_MIb=NOTE_REs,
  90 NOTE_MI,
  91 NOTE_FA,
  92 NOTE_FAs,
  93 NOTE_SOLb=NOTE_FAs,
  94 NOTE_SOL,
  95 NOTE_SOLs,
  96 NOTE_LAb=NOTE_SOLs,
  97 NOTE_LA,
  98 NOTE_LAs,
  99 NOTE_SIb=NOTE_LAs,
 100 NOTE_SI
 101 };
 102
 103 enum
 104 {
 105 NOTE_C=0,
 106 NOTE_Cs,
 107 NOTE_Db=NOTE_Cs,
 108 NOTE_D,
 109 NOTE_Ds,
 110 NOTE_Eb=NOTE_Ds,
 111 NOTE_E,
 112 NOTE_F,
 113 NOTE_Fs,
 114 NOTE_Gb=NOTE_Fs,
 115 NOTE_G,
 116 NOTE_Gs,
 117 NOTE_Ab=NOTE_Gs,
 118 NOTE_A,
 119 NOTE_As,
 120 NOTE_Bb=NOTE_As,
 121 NOTE_B
 122 };
 123
 124 #define NOTE(note,octave) (note+(octave<<3)+(octave<<2)) // final note codification. Used in Note2Freq()
 125
 126 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 127
 128 // compat with SNDLIB
 129
 130 #define Note2Freq               ANote2Freq
 131 #define SND_Init                ASND_Init
 132 #define SND_End                 ASND_End
 133 #define SND_Pause               ASND_Pause
 134 #define SND_Is_Paused           ASND_Is_Paused
 135 #define SND_GetTime             ASND_GetTime
 136 #define SND_GetSampleCounter    ASND_GetSampleCounter
 137 #define SND_GetSamplesPerTick   ASND_GetSamplesPerTick
 138 #define SND_SetTime             ASND_SetTime
 139 #define SND_SetCallback         ASND_SetCallback
 140 #define SND_GetAudioRate        ASND_GetAudioRate
 141 #define SND_SetVoice            ASND_SetVoice
 142 #define SND_AddVoice            ASND_AddVoice
 143 #define SND_StopVoice           ASND_StopVoice
 144 #define SND_PauseVoice          ASND_PauseVoice
 145 #define SND_StatusVoice         ASND_StatusVoice
 146 #define SND_GetFirstUnusedVoice ASND_GetFirstUnusedVoice
 147 #define SND_ChangePitchVoice    ASND_ChangePitchVoice
 148 #define SND_ChangeVolumeVoice   ASND_ChangeVolumeVoice
 149 #define SND_ChangeVolumeVoice   ASND_ChangeVolumeVoice
 150 #define SND_GetTickCounterVoice ASND_GetTickCounterVoice
 151 #define SND_GetTimerVoice       ASND_GetTimerVoice
 152 #define SND_TestPointer         ASND_TestPointer
 153
 154 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 155
 156 typedef void (*ASNDVoiceCallback)(s32 voice);
 157
 158 /* int ANote2Freq(int note, int freq_base,int note_base);
 159
 160 Initializes the SND lib and fix the hardware sample rate.
 161
 162 -- Params ---
 163
 164 note: Note codified to play. For example: NOTE(C,4) for note C and octave 4
 165
 166 freq_base: Frequency base of the sample. For example 8000Hz
 167
 168 note_base: Note codified of the sample. For example: NOTE(L,3) for note L and octave 3 (LA 3)
 169
 170 return: frequency (in Hz)
 171
 172 */
 173
 174 int ANote2Freq(int note, int freq_base,int note_base);
 175
 176 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 177 /* General Sound Functions                                                                                                                              */
 178 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 179
 180 /* void ASND_Init();
 181
 182 Initializes the ASND lib and fix the hardware sample rate to 48000.
 183
 184 -- Params ---
 185
 186
 187 return: nothing
 188
 189 */
 190
 191 void ASND_Init();
 192
 193 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 194
 195 /* void ASND_End();
 196
 197 De-initializes the ASND lib.
 198
 199 return: nothing
 200
 201 */
 202
 203 void ASND_End();
 204
 205 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 206
 207 /* void ASND_Pause(s32 paused);
 208
 209 Used to pause (or not) the sound. When you call to the ASND_Init() function, the sound is paused.
 210
 211
 212 -- Params ---
 213
 214 paused: use 0 to run or 1 to pause
 215
 216 return: nothing
 217
 218 */
 219
 220 void ASND_Pause(s32 paused);
 221
 222 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 223
 224 /* s32 ASND_Is_Paused();
 225
 226 Return if the sound is paused or not
 227
 228 -- Params ---
 229
 230 return: 0-> running 1-> paused
 231
 232 */
 233
 234
 235 s32 ASND_Is_Paused();
 236
 237 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 238
 239 /* u32 ASND_GetTime();
 240
 241 Get the global time (in milliseconds). This time is updated from the IRQ
 242
 243 -- Params ---
 244
 245
 246 return: current time (in ms)
 247
 248 */
 249
 250 u32 ASND_GetTime();
 251
 252 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 253
 254 /* u32 ASND_GetSampleCounter();
 255
 256 Get the global sample counter. This counter is updated from the IRQ in steps of ASND_GetSamplesPerTick()
 257
 258 NOTE: you can use this to implement one timer with high precision
 259
 260 -- Params ---
 261
 262
 263 return: current sample
 264
 265 */
 266
 267
 268 u32 ASND_GetSampleCounter();
 269
 270 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 271
 272 /* u32 ASND_GetSamplesPerTick();
 273
 274 Get the samples sended from the IRQ in one tick
 275
 276 -- Params ---
 277
 278
 279 return: samples per tick
 280
 281 */
 282
 283
 284 u32 ASND_GetSamplesPerTick();
 285
 286 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 287
 288 /* void ASND_SetTime(u32 time);
 289
 290 Set the global time (in milliseconds). This time is updated from the IRQ
 291
 292 -- Params ---
 293
 294 time: fix the current time (in ms)
 295
 296 return: nothing
 297
 298 */
 299
 300 void ASND_SetTime(u32 time);
 301
 302 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 303
 304 /* void ASND_SetCallback(void (*callback)());
 305
 306 Set a global callback for general pourpose. This callback is called from the IRQ
 307
 308 -- Params ---
 309
 310 callback: function callback
 311
 312 return: nothing
 313
 314 */
 315
 316 void ASND_SetCallback(void (*callback)());
 317
 318 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 319
 320 /* s32 ASND_GetAudioRate();
 321
 322 return: Audio rate (48000)
 323
 324 Note: for compatibility with SND_lib
 325
 326 */
 327
 328 s32 ASND_GetAudioRate();
 329
 330 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 331 /* Voice Functions                                                                                                                                      */
 332 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 333
 334 /* s32 ASND_SetVoice(s32 voice, s32 format, s32 pitch,s32 delay, void *snd, s32 size_snd, s32 volume_l, s32 volume_r, void (*callback) (s32 voice));
 335
 336 Set a PCM voice to play. This function stops one previously voice. Use the ASND_StatusVoice() to test the status condition
 337
 338 NOTE: The voices are played in stereo and 16 bits independently of the source format.
 339
 340 -- Params ---
 341
 342 voice: use one from 0 to (MAX_SND_VOICES-1)
 343
 344 format: PCM format from VOICE_MONO_8BIT to VOICE_STEREO_16BIT
 345
 346 pitch: pitch frequency (in Hz)
 347
 348 delay: delay time in milliseconds (ms). Time to wait before to play the voice
 349
 350 snd: buffer containing the samples (aligned and padded to 32 bytes!!!)
 351
 352 size_snd: size (in bytes) of the buffer samples
 353
 354 volume_l: volume to the left channel from 0 to 255
 355
 356 volume_r: volume to the right channel from 0 to 255
 357
 358 callback: can be NULL or one callback function is used to implement a double buffer use. When the second buffer is empty, the callback is called sending
 359           the voice number as parameter. You can use "void callback(s32 voice)" function to call ASND_AddVoice() and add one voice to the second buffer.
 360                   NOTE: When callback is fixed the voice never stops and it turn in SND_WAITING status if success one timeout condition.
 361
 362 return: SND_OK or SND_INVALID
 363
 364 */
 365
 366 s32 ASND_SetVoice(s32 voice, s32 format, s32 pitch,s32 delay, void *snd, s32 size_snd, s32 volume_l, s32 volume_r, ASNDVoiceCallback callback);
 367 s32 ASND_SetInfiniteVoice(s32 voice, s32 format, s32 pitch,s32 delay, void *snd, s32 size_snd, s32 volume_l, s32 volume_r);
 368
 369 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 370
 371 /* s32 ASND_AddVoice(s32 voice, void *snd, s32 size_snd);
 372
 373 Add a PCM voice in the second buffer to play. This function requires one previously call to ASND_SetVoice() and one condition status different
 374         of 'SND_UNUSED'
 375
 376 -- Params ---
 377
 378 voice: use one from 0 to (MAX_SND_VOICES-1)
 379
 380 snd: buffer containing the samples (aligned and padded to 32 bytes!) in the same format of the previously ASND_SetVoice() use
 381
 382 size_snd: size (in bytes) of the buffer samples
 383
 384 return: SND_OK, SND_INVALID or SND_BUSY if the second buffer is not empty and de voice cannot be add
 385
 386 */
 387
 388 s32 ASND_AddVoice(s32 voice, void *snd, s32 size_snd);
 389
 390
 391 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 392
 393 /* s32 ASND_StopVoice(s32 voice);
 394
 395 Stops the voice selected.
 396
 397 If the voice is used in song mode, you need to assign the samples with ASND_SetSongSampleVoice() again. Use ASND_PauseSongVoice() in this case to stops
 398         the voice without lose the samples.
 399
 400 -- Params ---
 401
 402 voice: use one from 0 to (MAX_SND_VOICES-1)
 403
 404 return: SND_OK, SND_INVALID
 405
 406 */
 407
 408 s32 ASND_StopVoice(s32 voice);
 409
 410 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 411
 412 /* s32 ASND_PauseVoice(s32 voice, s32 pause);
 413
 414 Pause the voice selected.
 415
 416
 417
 418 -- Params ---
 419
 420 voice: use one from 0 to (MAX_SND_VOICES-1)
 421
 422 return: SND_OK, SND_INVALID
 423
 424 */
 425
 426 s32 ASND_PauseVoice(s32 voice, s32 pause);
 427
 428 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 429
 430 /* s32 ASND_StatusVoice(s32 voice);
 431
 432 Return the status of the voice selected
 433
 434 -- Params ---
 435
 436 voice: use one from 0 to (MAX_SND_VOICES-1)
 437
 438 return: SND_INVALID
 439         SND_UNUSED   you can use this voice
 440         SND_WORKING  this voice is in progress
 441         SND_WAITING  this voice is in progress and waiting to one SND_AddVoice function (the voice handler is called continuously)
 442
 443 */
 444
 445 s32 ASND_StatusVoice(s32 voice);
 446
 447 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 448
 449 /* s32 ASND_GetFirstUnusedVoice();
 450
 451 Get the first unused voice. The voice 0 is tried especially and it is the last possible result. The idea is to reserve that voice for a Mod/Ogg/MP3
 452        Player or similar. So if the function return a value <1 you can be sure the rest of the voices are working.
 453
 454 -- Params ---
 455
 456 None
 457
 458 return: SND_INVALID or the first free voice (from 0 to (MAX_SND_VOICES-1))
 459
 460 */
 461
 462 s32 ASND_GetFirstUnusedVoice();
 463
 464 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 465
 466 /* s32 ASND_ChangePitchVoice(s32 voice, s32 pitch);
 467
 468 Use this function to change the voice pitch in real-time. You can use this to create audio effects.
 469
 470 -- Params ---
 471
 472 voice: use one from 0 to (MAX_SND_VOICES-1)
 473
 474 return: SND_OK, SND_INVALID
 475
 476 */
 477
 478 s32 ASND_ChangePitchVoice(s32 voice, s32 pitch);
 479
 480 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 481
 482 /* s32 SND_ChangeVolumeVoice(s32 voice, s32 volume_l, s32 volume_r);
 483
 484 Use this function to change the voice volume in real-time. You can use this to create audio effects.
 485
 486 -- Params ---
 487
 488 voice: use one from 0 to (MAX_SND_VOICES-1)
 489
 490 volume_l: volume to the left channel from 0 to 255
 491
 492 volume_r: volume to the right channel from 0 to 255
 493
 494 return: SND_OK, SND_INVALID
 495
 496 */
 497
 498 s32 ASND_ChangeVolumeVoice(s32 voice, s32 volume_l, s32 volume_r);
 499
 500 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 501
 502 /* u32 SND_GetTickCounterVoice(s32 voice);
 503
 504 Get the tick counter from the voice starts to play (without the delay time). This counter uses the same resolution of the internal sound buffer.
 505        For example if the lib is initilized with INIT_RATE_48000 a return value of 24000 are equal to 0.5 seconds played
 506
 507 USES: you can use this value to synchronize audio & video
 508
 509
 510 -- Params ---
 511
 512 voice: use one from 0 to (MAX_SND_VOICES-1)
 513
 514 return: Number of ticks. No error condition for this function
 515
 516 */
 517
 518 u32 ASND_GetTickCounterVoice(s32 voice);
 519
 520 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 521
 522 /* u32 ASND_GetTimerVoice(s32 voice);
 523
 524 Get the time (in milliseconds) from the voice starts to play (without the delay time).
 525
 526 USES: you can use this value to synchronize audio & video
 527
 528 -- Params ---
 529
 530 voice: use one from 0 to (MAX_SND_VOICES-1)
 531
 532 return: time (in ms). No error condition for this function
 533
 534 */
 535
 536 u32 ASND_GetTimerVoice(s32 voice);
 537
 538 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 539
 540 /* s32 SND_TestPointer(s32 voice, void *pointer);
 541
 542 Test if the pointer is in use by the voice (as buffer).
 543
 544 -- Params ---
 545
 546 voice: use one from 0 to (MAX_SND_VOICES-1)
 547
 548 pointer: address to test It must be the same pointer passed to the ASND_AddVoice() or ASND_SetVoice() functions
 549
 550 return: SND_INVALID, 0-> Unused, 1-> Used as buffer
 551
 552 */
 553
 554
 555 s32 ASND_TestPointer(s32 voice, void *pointer);
 556
 557 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 558
 559 /* s32 ASND_TestVoiceBufferReady(s32 voice);
 560
 561 Test if the Voice is Ready to receive a new buffer sample with ASND_AddVoice(). You can use this function to block a reader when you use double buffering
 562 as similar form of the ASND_TestPointer() function without passing one address to test
 563
 564 -- Params ---
 565
 566 voice: use one from 0 to (MAX_SND_VOICES-1)
 567
 568 return: SND_INVALID, 0-> not ready to receive a new AddVoice(), 1->ready to receive a new AddVoice()
 569
 570 */
 571
 572 s32 ASND_TestVoiceBufferReady(s32 voice);
 573
 574 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 575 /* DSP FUNCTIONS                                                                                                                                                    */
 576 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 577
 578 /* u32 ASND_GetDSP_PercentUse();
 579
 580 Get the Percent use of the DSP
 581
 582 -- Params ---
 583
 584 None
 585
 586 return: percent use
 587
 588 */
 589
 590 u32 ASND_GetDSP_PercentUse();
 591
 592
 593 /*------------------------------------------------------------------------------------------------------------------------------------------------------*/
 594
 595
 596 #ifdef __cplusplus
 597   }
 598 #endif
 599
 600 #endif
 601