libnds: maxmod9.h ソースファイル

00001 /****************************************************************************
00002  *                                                          __              *
00003  *                ____ ___  ____ __  ______ ___  ____  ____/ /              *
00004  *               / __ `__ \/ __ `/ |/ / __ `__ \/ __ \/ __  /               *
00005  *              / / / / / / /_/ />  </ / / / / / /_/ / /_/ /                *
00006  *             /_/ /_/ /_/\__,_/_/|_/_/ /_/ /_/\____/\__,_/                 *
00007  *                                                                          *
00008  *                            ARM9 Definitions                              *
00009  *                                                                          *
00010  *         Copyright (c) 2008, Mukunda Johnson (mukunda@maxmod.org)         *
00011  *                                                                          *
00012  * Permission to use, copy, modify, and/or distribute this software for any *
00013  * purpose with or without fee is hereby granted, provided that the above   *
00014  * copyright notice and this permission notice appear in all copies.        *
00015  *                                                                          *
00016  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES *
00017  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF         *
00018  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR  *
00019  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES   *
00020  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN    *
00021  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  *
00022  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.           *
00023  ****************************************************************************/
00024 
00025 #ifdef ARM7
00026 #error "maxmod9.h is for ARM9!"
00027 #endif
00028 
00029 //----------------------------------------------------------------
00030 #ifndef MAXMOD_H
00031 //----------------------------------------------------------------
00032 
00033 #define MAXMOD_H
00034 
00035 #include <mm_types.h>
00036 
00037 //----------------------------------------------------------------
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif
00041 //----------------------------------------------------------------
00042 
00043 /*****************************************************************
00044  * mmInitDefault( char* soundbank_file )
00045  *
00046  * Initialize Maxmod using default settings.
00047  *
00048  * soundbank_file : Filename of the soundbank to use.
00049  *****************************************************************/
00050  
00051 void mmInitDefault( char* soundbank_file );
00052 
00053 /*****************************************************************
00054  * mmInitDefaultMem( mm_addr soundbank )
00055  *
00056  * Initialize Maxmod using default settings.
00057  * Use this when you have the entire soundbank loaded into memory.
00058  * 
00059  * soundbank : Address of soundbank data.
00060  *****************************************************************/
00061  
00062 void mmInitDefaultMem( mm_addr soundbank );
00063 
00064 /*****************************************************************
00065  * mmInit( mm_ds_system* system )
00066  *
00067  * Initialize Maxmod
00068  *
00069  * system : Configuration info.
00070  *****************************************************************/
00071  
00072 void mmInit( mm_ds_system* system );
00073 
00074 /*****************************************************************
00075  * mmSelectMode( mm_mode_enum mode )
00076  *
00077  * Select audio mode
00078  *
00079  * mode:
00080  *   MM_MODE_A : Hardware Mixing
00081  *   MM_MODE_B : Interpolated Mixing
00082  *   MM_MODE_C : Extended Mixing
00083  *****************************************************************/
00084  
00085 void mmSelectMode( mm_mode_enum mode );
00086 
00087 /*****************************************************************
00088  * mmLoad( mm_word module_ID )
00089  *
00090  * Load a module into memory. Must be used before starting
00091  * a module.
00092  *
00093  * module_ID : ID of module. (defined in soundbank header)
00094  *****************************************************************/
00095  
00096 void mmLoad( mm_word module_ID );
00097 
00098 /*****************************************************************
00099  * mmUnload( mm_word module_ID )
00100  *
00101  * Unload a module from memory.
00102  *
00103  * module_ID : ID of module. (defined in soundbank header)
00104  *****************************************************************/
00105 
00106 void mmUnload( mm_word module_ID );
00107 
00108 /*****************************************************************
00109  * mmLoadEffect( mm_word sample_ID )
00110  *
00111  * Load a sound effect into memory. Use before mmEffect.
00112  *
00113  * sample_ID : ID of sample. (defined in soundbank header)
00114  *****************************************************************/
00115  
00116 void mmLoadEffect( mm_word sample_ID );
00117 
00118 /*****************************************************************
00119  * mmUnloadEffect( mm_word sample_ID )
00120  *
00121  * Unload sound effect from memory.
00122  *
00123  * sample_ID : ID of sample. (defined in soundbank header)
00124  *****************************************************************/
00125  
00126 void mmUnloadEffect( mm_word sample_ID );
00127 
00128 /*****************************************************************
00129  * mmLockChannels( mm_word bitmask )
00130  *
00131  * Lock audio channels from being used by Maxmod.
00132  *
00133  * bitmask : Bitmask of which channels should be locked.
00134  * (&1 = ch0, &2 = ch1, &4 = ch2, &8 = ch4, etc...)
00135  *****************************************************************/
00136  
00137 void mmLockChannels( mm_word bitmask );
00138 
00139 /*****************************************************************
00140  * mmUnlockChannels( mm_word bitmask )
00141  *
00142  * Unlock audio channels so Maxmod can use them.
00143  *
00144  * bitmask : Bitmask of which channels should be unlocked.
00145  * (&1 = ch0, &2 = ch1, &4 = ch2, &8 = ch4, etc...)
00146  *****************************************************************/
00147  
00148 void mmUnlockChannels( mm_word bitmask );
00149 
00150 /*****************************************************************
00151  * mmSetEventHandler( mm_callback handler )
00152  *
00153  * Setup handler to receive playback events.
00154  *
00155  * handler : Pointer to your function.
00156  *****************************************************************/
00157 
00158 void mmSetEventHandler( mm_callback handler );
00159 
00160 /*****************************************************************
00161  * mmSoundBankInMemory( mm_addr address )
00162  * mmSoundBankInFiles( char* filename )
00163  * mmSetCustomSoundBankHandler( mm_callback p_loader )
00164  *
00165  * Setup soundbank interface.
00166  * This is automatically done by mmInitDefault/mmInitDefaultMem.
00167  *****************************************************************/
00168 
00169 void mmSoundBankInMemory( mm_addr address );
00170 void mmSoundBankInFiles( char* filename );
00171 void mmSetCustomSoundBankHandler( mm_callback p_loader );
00172 
00173 
00174 
00175 /*****************************************************************
00176  * 
00177  * Module Playback
00178  *
00179  *****************************************************************/
00180 
00181 
00182 
00183 /*****************************************************************
00184  * mmStart( mm_word module_ID, mm_pmode mode )
00185  *
00186  * Start module playback.
00187  *
00188  * module_ID : ID of module to play (defined in soundbank header)
00189  *             Make sure the module is loaded via mmLoad
00190  *
00191  * mode : Mode of playback: MM_PLAY_ONCE or MM_PLAY_LOOP
00192  *****************************************************************/
00193 
00194 void mmStart( mm_word module_ID, mm_pmode mode );
00195 
00196 /*****************************************************************
00197  * mmPause()
00198  *
00199  * Pause module playback. Resume with mmResume().
00200  *****************************************************************/
00201  
00202 void mmPause( void );
00203 
00204 /*****************************************************************
00205  * mmResume()
00206  *
00207  * Resume module playback. Pause with mmPause().
00208  *****************************************************************/
00209  
00210 void mmResume( void );
00211 
00212 /*****************************************************************
00213  * mmStop()
00214  *
00215  * Stop module playback. Start again (from the beginning)
00216  * with mmStart().
00217  *****************************************************************/
00218 
00219 void mmStop( void );
00220 
00221 /*****************************************************************
00222  * mmPosition( mm_word position )
00223  *
00224  * Set playback position.
00225  *
00226  * position : New position in module sequence.
00227  *****************************************************************/
00228 
00229 void mmPosition( mm_word position );
00230 
00231 /*****************************************************************
00232  * mmJingle( mm_word module_ID )
00233  *
00234  * Play module as jingle. Jingles are limited to 4 channels only.
00235  *
00236  * module_ID : ID of module
00237  *****************************************************************/
00238 
00239 void mmJingle( mm_word module_ID );
00240 
00241 /*****************************************************************
00242  * mmSetModuleVolume( mm_word volume )
00243  * mmSetJingleVolume( mm_word volume )
00244  *
00245  * Set master volume scale for music/jingle playback.
00246  *
00247  * volume : 0->1024 representing 0%->100% volume
00248  *****************************************************************/
00249 
00250 void mmSetModuleVolume( mm_word volume );
00251 void mmSetJingleVolume( mm_word volume );
00252 
00253 /*****************************************************************
00254  * mmSetModuleTempo( mm_word tempo )
00255  *
00256  * Set tempo of playback.
00257  *
00258  * tempo : Fixed point (Q10) value representing tempo.
00259  *         Range = 0x200 -> 0x800 = 0.5 -> 2.0
00260  *****************************************************************/
00261 
00262 void mmSetModuleTempo( mm_word tempo );
00263 
00264 /*****************************************************************
00265  * mmSetModulePitch( mm_word pitch )
00266  *
00267  * Set pitch of playback.
00268  *
00269  * pitch : Range = 0x200 -> 0x800 = 0.5 -> 2.0
00270  *****************************************************************/
00271  
00272 void mmSetModulePitch( mm_word pitch );
00273 
00274 /*****************************************************************
00275  * mmActive()
00276  *
00277  * Returns nonzero if module is playing.
00278  *****************************************************************/
00279 
00280 mm_bool mmActive( void );
00281 
00282  
00283  
00284 /*****************************************************************
00285  *
00286  * Sound Effects
00287  *
00288  *****************************************************************/
00289  
00290  
00291  
00292 /*****************************************************************
00293  * mmEffect( mm_word sample_ID )
00294  *
00295  * Play a sound effect at its default rate with full volume
00296  * and centered panning.
00297  * Remember to load the effect via mmLoadEffect first.
00298  *
00299  * sample_ID : ID of sample to play (defined in soundbank header)
00300  *
00301  * Returns mm_sfxhand which may be used to modify the sound later.
00302  *****************************************************************/
00303 
00304 mm_sfxhand mmEffect( mm_word sample_ID );
00305 
00306 /*****************************************************************
00307  * mmEffectEx( mm_sound_effect* sound )
00308  *
00309  * Play a sound effect with rate/volume/panning specified.
00310  * Remember to load the effect via mmLoadEffect first.
00311  *
00312  * sound : sound effect info
00313  *****************************************************************/
00314  
00315 mm_sfxhand mmEffectEx( mm_sound_effect* sound );
00316 
00317 /*****************************************************************
00318  * mmEffectVolume( mm_sfxhand handle, mm_byte volume )
00319  *
00320  * Set effect volume.
00321  *
00322  * handle : Sound effect handle (returned from mmEffect/Ex)
00323  * volume : 0..255 = silent..normal
00324  *****************************************************************/
00325 
00326 void mmEffectVolume( mm_sfxhand handle, mm_word volume );
00327 
00328 /*****************************************************************
00329  * mmEffectPanning( mm_sfxhand handle, mm_byte panning )
00330  *
00331  * Set effect panning.
00332  *
00333  * handle : Sound effect handle (returned from mmEffect/Ex)
00334  * panning : 0..255 = hard left..hard right
00335  *****************************************************************/
00336  
00337 void mmEffectPanning( mm_sfxhand handle, mm_byte panning );
00338 
00339 /*****************************************************************
00340  * mmEffectRate( mm_sfxhandle, mm_word rate )
00341  *
00342  * Set effect playback rate.
00343  *
00344  * handle : Sound effect handle (returned from mmEffect/Ex)
00345  * rate : 6.10 fixed point value representing rate. A value of
00346  *        2048 will make the pitch one octave higher than the
00347  *        default setting
00348  *****************************************************************/
00349  
00350 void mmEffectRate( mm_sfxhand handle, mm_word rate );
00351 
00352 /*****************************************************************
00353  * mmEffectScaleRate( mm_sfxhandle, mm_word factor )
00354  *
00355  * Scale effect playback rate.
00356  *
00357  * handle : Sound effect handle (returned from mmEffect/Ex)
00358  * factor : 6.10 fixed point value to multiply the rate by.
00359  *****************************************************************/
00360 
00361 void mmEffectScaleRate( mm_sfxhand handle, mm_word factor );
00362 
00363 /*****************************************************************
00364  * mmEffectCancel( mm_sfx_handle handle )
00365  *
00366  * Stop sound effect.
00367  *
00368  * handle : Sound effect handle (returned from mmEffect/Ex)
00369  *****************************************************************/
00370  
00371 void mmEffectCancel( mm_sfxhand handle );
00372 
00373 /*****************************************************************
00374  * mmEffectRelease( mm_sfxhand handle )
00375  *
00376  * Release sound effect. This discards the handle and allows the
00377  * effect to be overidden by music/other effects.
00378  *****************************************************************/
00379  
00380 void mmEffectRelease( mm_sfxhand handle );
00381 
00382 /*****************************************************************
00383  * mmEffectExt( mm_sound_effect* sound, mm_sample* sample )
00384  *
00385  * Play external sound.
00386  *
00387  * sound : Pointer to sound effect info
00388  * sample : Pointer to external sample
00389  *****************************************************************/
00390 
00391 mm_sfxhand mmEffectExt( mm_sound_effect* sound, mm_ds_sample* sample );
00392 
00393 /*****************************************************************
00394  * mmSetEffectsVolume( mm_word volume )
00395  *
00396  * Set master volume scale for effect playback.
00397  *
00398  * volume : 0->1024 representing 0%->100% volume
00399  *****************************************************************/
00400 
00401 void mmSetEffectsVolume( mm_word volume );
00402 
00403 /*****************************************************************
00404  * mmEffectCancelAll()
00405  *
00406  * Stop all sound effects
00407  *****************************************************************/
00408  
00409 void mmEffectCancelAll();
00410 
00411 
00412 
00413 /*****************************************************************
00414  *
00415  * Streaming
00416  *
00417  *****************************************************************/
00418 
00419 
00420 
00421 /*****************************************************************
00422  * mmStreamOpen( mm_stream_info* info )
00423  *
00424  * Open audio stream.
00425  *
00426  * stream : Configuration struct
00427  *****************************************************************/
00428 
00429 void mmStreamOpen( mm_stream* stream );
00430 
00431 /*****************************************************************
00432  * mmStreamUpdate()
00433  *
00434  * Fill audio stream with data. This needs to be called
00435  * in 'manual' mode. This is called automatically in 'auto' mode.
00436  *****************************************************************/
00437  
00438 void mmStreamUpdate( void );
00439 
00440 /*****************************************************************
00441  * mmStreamClose()
00442  *
00443  * Close audio stream.
00444  *****************************************************************/
00445  
00446 void mmStreamClose( void );
00447 
00448 /*****************************************************************
00449  * mmStreamGetPosition()
00450  *
00451  * Get number of samples elapsed since the stream was opened.
00452  * The 32-bit value will wrap every 36 hours or so (at 32khz)
00453  *****************************************************************/
00454  
00455 mm_word mmStreamGetPosition();
00456 
00457 
00458 
00459 /*****************************************************************
00460  *
00461  * Reverb
00462  *
00463  *****************************************************************/
00464  
00465  
00466 
00467 /*****************************************************************
00468  * mmReverbEnable()
00469  *
00470  * Enable reverb system. (use before configuring!)
00471  *****************************************************************/
00472  
00473 void mmReverbEnable( void );
00474  
00475 /*****************************************************************
00476  * mmReverbConfigure( mm_reverb_cfg* config )
00477  *
00478  * Configure reverb parameters.
00479  * config : Configuration data.
00480  *****************************************************************/
00481  
00482 void mmReverbConfigure( mm_reverb_cfg* config );
00483 
00484 /*****************************************************************
00485  * mmReverbStart( mm_reverbch channels )
00486  *
00487  * Start reverb output.
00488  *****************************************************************/
00489 
00490 void mmReverbStart( mm_reverbch channels );
00491 
00492 /*****************************************************************
00493  * mmReverbStop( mm_reverch channels )
00494  *
00495  * Stop reverb output.
00496  *****************************************************************/
00497 
00498 void mmReverbStop( mm_reverbch channels );
00499 
00500 /*****************************************************************
00501  * mmReverbBufferSize( mm_word bit_depth, mm_word sampling_rate,
00502  *                     mm_word delay )
00503  *
00504  * Calculate reverb buffer size based on bit depth, delay
00505  * and sampling rate.
00506  *
00507  * bit_depth : Pass 8 or 16 for 8-bit/16-bit
00508  * sampling_rate :
00509  * delay : In milliseconds
00510  *
00511  * Returns size in WORDS.
00512  *****************************************************************/
00513 
00514 static inline mm_word mmReverbBufferSize( mm_word bit_depth, mm_word sampling_rate, mm_word delay )
00515 {
00516         if( bit_depth == 16 )
00517         {
00518                 return ((((sampling_rate * delay * 2) / 1000) + 3) & (~3)) / 4;
00519         }
00520         else
00521         {
00522                 return ((((sampling_rate * delay) / 1000) + 3) & (~3)) / 4;
00523         }
00524 }
00525 
00526 /*****************************************************************
00527  * mmReverbDisable()
00528  *
00529  * Disable reverb system.
00530  *****************************************************************/
00531 
00532 void mmReverbDisable( void );
00533 
00534 
00535 
00536 //----------------------------------------------------------------
00537 #ifdef __cplusplus
00538 }
00539 #endif
00540 //----------------------------------------------------------------
00541 
00542 /*****************************************************************
00543  * Soundbank interface messages
00544  *****************************************************************/
00545  
00546 #define MMCB_SONGREQUEST        0x1A
00547 #define MMCB_SAMPREQUEST        0x1B
00548 #define MMCB_DELETESONG         0x1C
00549 #define MMCB_DELETESAMPLE       0x1D
00550 
00551 /*****************************************************************
00552  * Playback events
00553  *****************************************************************/
00554 
00555 //----------------------------------------------------------------
00556 // This happens when Maxmod reads an SFx (or mod/xm EFx) effect
00557 // from a module. It will pass 'x' in param.
00558 //----------------------------------------------------------------
00559 #define MMCB_SONGMESSAGE        0x2A
00560 //----------------------------------------------------------------
00561 
00562 //----------------------------------------------------------------
00563 // A module has finished playing.
00564 // param == 0 if main module, ==1 otherwise
00565 //----------------------------------------------------------------
00566 #define MMCB_SONGFINISHED       0x2B
00567 //----------------------------------------------------------------
00568 
00569 //----------------------------------------------------------------
00570 #endif
00571 //----------------------------------------------------------------