git.mutantstargoat.com Git - gbajam21/blob - libs/maxmod/maxmod.h

   1 /****************************************************************************
   2  *                                                          __              *
   3  *                ____ ___  ____ __  ______ ___  ____  ____/ /              *
   4  *               / __ `__ \/ __ `/ |/ / __ `__ \/ __ \/ __  /               *
   5  *              / / / / / / /_/ />  </ / / / / / /_/ / /_/ /                *
   6  *             /_/ /_/ /_/\__,_/_/|_/_/ /_/ /_/\____/\__,_/                 *
   7  *                                                                          *
   8  *                             GBA Definitions                              *
   9  *                                                                          *
  10  *         Copyright (c) 2008, Mukunda Johnson (mukunda@maxmod.org)         *
  11  *                                                                          *
  12  * Permission to use, copy, modify, and/or distribute this software for any *
  13  * purpose with or without fee is hereby granted, provided that the above   *
  14  * copyright notice and this permission notice appear in all copies.        *
  15  *                                                                          *
  16  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES *
  17  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF         *
  18  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR  *
  19  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES   *
  20  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN    *
  21  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  *
  22  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
  23  ****************************************************************************/
  24
  25 #ifndef MAXMOD_H
  26 #define MAXMOD_H
  27
  28 #include <mm_types.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 // precalculated mix buffer lengths (in bytes)
  35 #define MM_MIXLEN_8KHZ          544             // (8121 hz)
  36 #define MM_MIXLEN_10KHZ         704             // (10512 hz)
  37 #define MM_MIXLEN_13KHZ         896             // (13379 hz)
  38 #define MM_MIXLEN_16KHZ         1056    // (15768 hz)
  39 #define MM_MIXLEN_18KHZ         1216    // (18157 hz)
  40 #define MM_MIXLEN_21KHZ         1408    // (21024 hz)
  41 #define MM_MIXLEN_27KHZ         1792    // (26758 hz)
  42 #define MM_MIXLEN_31KHZ         2112    // (31536 hz)
  43
  44 // measurements of channel types (bytes)
  45 #define MM_SIZEOF_MODCH         40
  46 #define MM_SIZEOF_ACTCH         28
  47 #define MM_SIZEOF_MIXCH         24
  48
  49 /****************************************************************************
  50  * mmInitDefault( mm_addr soundbank, mm_word number_of_channels )
  51  *
  52  * Initialize Maxmod with default settings.
  53  ****************************************************************************/
  54
  55 void mmInitDefault( mm_addr soundbank, mm_word number_of_channels );
  56
  57 /****************************************************************************
  58  * mmInit( mm_gba_system* setup )
  59  *
  60  * Initialize system. Call once at startup.
  61  ****************************************************************************/
  62
  63 void mmInit( mm_gba_system* setup );
  64
  65 /****************************************************************************
  66  * mmVBlank()
  67  *
  68  * Must be linked to the VBlank IRQ.
  69  ****************************************************************************/
  70
  71 void mmVBlank( void );
  72
  73 /****************************************************************************
  74  * mmSetVBlankHandler( void* function )
  75  *
  76  * Install user vblank handler
  77  *
  78  * function : Pointer to your VBlank handler.
  79  ****************************************************************************/
  80
  81 void mmSetVBlankHandler( void* function );
  82
  83 /****************************************************************************
  84  * mmSetEventHandler( mm_callback handler )
  85  *
  86  * Install handler to receive song events.
  87  ****************************************************************************/
  88
  89 void mmSetEventHandler( mm_callback handler );
  90
  91 /****************************************************************************
  92  * mmFrame()
  93  *
  94  * Work routine. _Must_ be called every frame.
  95  ****************************************************************************/
  96
  97 void mmFrame( void ) __attribute((long_call));
  98
  99
 100
 101 /****************************************************************************
 102  *
 103  * Module Playback
 104  *
 105  ****************************************************************************/
 106
 107
 108
 109 /****************************************************************************
 110  * mmStart( mm_word id, mm_pmode mode )
 111  *
 112  * Start module playback.
 113  *
 114  * id : ID of module to play.
 115  * mode : Playback mode (loop/once)
 116  ****************************************************************************/
 117
 118 void mmStart( mm_word id, mm_pmode mode );
 119
 120 /****************************************************************************
 121  * mmPause()
 122  *
 123  * Pause module playback, resume with mmResume().
 124  ****************************************************************************/
 125
 126 void mmPause( void );
 127
 128 /****************************************************************************
 129  * mmResume()
 130  *
 131  * Resume module playback, pause with mmPause().
 132  ****************************************************************************/
 133
 134 void mmResume( void );
 135
 136 /****************************************************************************
 137  * mmStop()
 138  *
 139  * Stop module playback. start again with mmStart().
 140  ****************************************************************************/
 141
 142 void mmStop( void );
 143
 144 /****************************************************************************
 145  * mmGetPosition()
 146  *
 147  * Get playback position.
 148  ****************************************************************************/
 149
 150 mm_word mmGetPosition( void );
 151
 152 /****************************************************************************
 153  * mmPosition()
 154  *
 155  * Set playback position.
 156  *
 157  * position: New position in the module sequence.
 158  ****************************************************************************/
 159
 160 void mmPosition( mm_word position );
 161
 162 /****************************************************************************
 163  * mmSetPosition()
 164  *
 165  * Set playback position (alias for mmPosition()).
 166  *
 167  * position: New position in the module sequence.
 168  ****************************************************************************/
 169
 170 inline void mmSetPosition( mm_word position )
 171 {
 172     mmPosition( position );
 173 }
 174
 175 /****************************************************************************
 176  * mmActive()
 177  *
 178  * Returns nonzero if module is playing.
 179  ****************************************************************************/
 180
 181 int  mmActive( void );
 182
 183 /****************************************************************************
 184  * mmJingle( mm_word module_ID )
 185  *
 186  * Play module as jingle. Jingles are limited to 4 channels only.
 187  *
 188  * module_ID : ID of moudle (defined in soundbank header)
 189  ****************************************************************************/
 190
 191 void mmJingle( mm_word module_ID );
 192
 193 /****************************************************************************
 194  * mmActiveSub()
 195  *
 196  * Returns nonzero if a jingle is actively playing.
 197  ****************************************************************************/
 198
 199 int  mmActiveSub( void );
 200
 201 /****************************************************************************
 202  * mmSetModuleVolume( mm_word volume )
 203  * mmSetJingleVolume( mm_word volume )
 204  *
 205  * Set volume scaler for music/jingles.
 206  *
 207  * volume : 0->1024 = silent..normal
 208  ****************************************************************************/
 209
 210 void mmSetModuleVolume( mm_word volume );
 211 void mmSetJingleVolume( mm_word volume );
 212
 213 /*****************************************************************
 214  * mmSetModuleTempo( mm_word tempo )
 215  *
 216  * Set tempo of playback.
 217  *
 218  * tempo : Fixed point (Q10) value representing tempo.
 219  *         Range = 0x200 -> 0x800 = 0.5 -> 2.0
 220  *****************************************************************/
 221
 222 void mmSetModuleTempo( mm_word tempo );
 223
 224 /*****************************************************************
 225  * mmSetModulePitch( mm_word pitch )
 226  *
 227  * Set pitch of playback.
 228  *
 229  * pitch : Range = 0x200 -> 0x800 = 0.5 -> 2.0
 230  *****************************************************************/
 231
 232 void mmSetModulePitch( mm_word pitch );
 233
 234 /****************************************************************************
 235  * mmPlayModule( mm_word address, mm_word mode, mm_word layer )
 236  *
 237  * Play direct MAS file
 238  ****************************************************************************/
 239
 240 void mmPlayModule( mm_word address, mm_word mode, mm_word layer );
 241
 242
 243
 244 /****************************************************************************
 245  *
 246  * Sound Effects
 247  *
 248  ****************************************************************************/
 249
 250
 251
 252 /****************************************************************************
 253  * mmEffect( mm_word sample_ID )
 254  *
 255  * Play a sound effect at its default frequency with full volume and
 256  * centered panning.
 257  *
 258  * sample_ID : Sound effect ID. (defined in soundbank header)
 259  ****************************************************************************/
 260
 261 mm_sfxhand mmEffect( mm_word sample_ID );
 262
 263 /****************************************************************************
 264  * mmEffectEx( mm_sound_effect* sound )
 265  *
 266  * Play a sound effect with all parameters.
 267  *
 268  * sound : Sound effect attributes.
 269  ****************************************************************************/
 270
 271 mm_sfxhand mmEffectEx( mm_sound_effect* sound );
 272
 273 /****************************************************************************
 274  * mmEffectVolume( mm_sfxhand handle, mm_word volume )
 275  *
 276  * Set the volume of a sound effect.
 277  *
 278  * handle : Sound effect handle.
 279  * volume : 0->65535
 280  ****************************************************************************/
 281
 282 void mmEffectVolume( mm_sfxhand handle, mm_word volume );
 283
 284 /****************************************************************************
 285  * mmEffectPanning( mm_sfxhand handle, mm_word panning )
 286  *
 287  * Set the panning of a sound effect.
 288  *
 289  * handle : Sound effect handle.
 290  * panning : 0->255 = left..right
 291  ****************************************************************************/
 292
 293 void mmEffectPanning( mm_sfxhand handle, mm_byte panning );
 294
 295 /****************************************************************************
 296  * mmEffectRate( mm_sfxhand handle, mm_word rate )
 297  *
 298  * Set the playback rate of an effect.
 299  *
 300  * handle : Sound effect handle.
 301  * rate: 6.10 factor
 302  ****************************************************************************/
 303
 304 void mmEffectRate( mm_sfxhand handle, mm_word rate );
 305
 306 /****************************************************************************
 307  * mmEffectScaleRate( mm_sfxhand handle, mm_word factor )
 308  *
 309  * Scale the playback rate of an effect.
 310  *
 311  * handle : Sound effect handle.
 312  * factor : 6.10 fixed point factor.
 313  ****************************************************************************/
 314
 315 void mmEffectScaleRate( mm_sfxhand handle, mm_word factor );
 316
 317 /****************************************************************************
 318  * mmEffectActive( mm_sfxhand handle )
 319  *
 320  * Indicates if a sound effect is active or not.
 321  *
 322  * handle : Sound effect handle.
 323  ****************************************************************************/
 324
 325 mm_bool mmEffectActive( mm_sfxhand handle );
 326
 327 /****************************************************************************
 328  * mmEffectCancel( mm_sfxhand handle )
 329  *
 330  * Stop sound effect.
 331  *
 332  * handle : Sound effect handle.
 333  ****************************************************************************/
 334
 335 void mmEffectCancel( mm_sfxhand handle );
 336
 337 /****************************************************************************
 338  * mmEffectRelease( mm_sfxhand handle )
 339  *
 340  * Release sound effect (invalidate handle and allow interruption)
 341  *
 342  * handle : Sound effect handle.
 343  ****************************************************************************/
 344
 345 void mmEffectRelease( mm_sfxhand handle );
 346
 347 /****************************************************************************
 348  * mmSetEffectsVolume( mm_word volume )
 349  *
 350  * Set master volume scale for effect playback.
 351  *
 352  * volume : 0->1024 representing 0%->100% volume
 353  ****************************************************************************/
 354
 355 void mmSetEffectsVolume( mm_word volume );
 356
 357 /****************************************************************************
 358  * mmEffectCancelAll()
 359  *
 360  * Stop all sound effects
 361  ****************************************************************************/
 362
 363 void mmEffectCancelAll();
 364
 365
 366
 367 #ifdef __cplusplus
 368 }
 369 #endif
 370
 371 /****************************************************************************
 372  * Playback events
 373  ****************************************************************************/
 374
 375 //---------------------------------------------------------------------------
 376 // This happens when Maxmod reads a SFx (or mod/xm EFx) effect from a module
 377 // It will store 'x' in param_b
 378 //---------------------------------------------------------------------------
 379 #define MMCB_SONGMESSAGE        0x2A
 380 //---------------------------------------------------------------------------
 381
 382 //---------------------------------------------------------------------------
 383 // A module has finished playing
 384 // param == 0 if main module, ==1 otherwise
 385 //---------------------------------------------------------------------------
 386 #define MMCB_SONGFINISHED       0x2B
 387 //---------------------------------------------------------------------------
 388
 389 /****************************************************************************
 390  * etc...
 391  ****************************************************************************/
 392
 393 extern mm_byte  mp_mix_seg;                     // current mixing segment
 394 extern mm_word  mp_writepos;            // mixer's write position
 395
 396 #endif