1.3 Initializing the Library
Before initializing the library you set the external Scheduler. Like with NuSystem, when using your own Scheduler you need to call the MusSetScheduler function and register it in the MUS library. After that you initialize the library with the MusInitialize function. In NuSystem, there is a special initialization function called nuAuStlMgrInit, and by simply calling this function the Scheduler is registered and the library is initialized (the MusSetScheduler and MusInitialize functions are called internally, so they do not need to be explicitly called.)
| Function name: |
MusSetScheduler |
| Syntax: |
void MusSetScheduler(musSched *sched_list) |
| Arguments: |
sched_lsit |
Address of the Scheduler function list |
| Return value: |
None |
| Function name: |
MusInitialize |
| Syntax: |
s32 MusInitialize(musConfig *c) |
| Arguments: |
c |
Address of the Configuration structure |
| Return value: |
Size of audio heap used by MusInitialize |
| Function name: |
nuAuStlMgrInit |
| Syntax: |
s32 nuAuStlMgrInit(musConfig *c) |
| Arguments: |
c |
Address of the Configuration structure |
| Return value: |
Size of audio heap used by MusInitialize |
Below is an example of the Configuration structure:
| |
#define AUDIO_HEAP_SIZE 0x40000 |
| |
|
| |
musConfig init; |
| |
|
| |
init.control_flag |
= 0 |
| |
init.channels |
= 16; |
| |
init.sched |
= NULL; |
| |
init.thread_priority |
= NU_AU_MGR_THREAD_PRI; |
| |
init.heap |
= (u8 *)(NU_GFX_FRAMEBUFFER_ADDR-AUDIO_HEAP_SIZE); |
| |
init.heap_length |
= AUDIO_HEAP_SIZE; |
| |
init.ptr |
= NULL; |
| |
init.wbk |
= NULL; |
| |
init.default_fxbank |
= NULL; |
| |
init.fifo_length |
= 64; |
| |
init.syn_updates |
= 128; |
| |
init.syn_output_rate |
= 32000; |
| |
init.syn_rsp_cmds |
= 0x800; |
| |
init.syn_retraceCount |
= 1; |
| |
init.syn_num_dma_bufs |
= 64; |
| |
init.syn_dma_buf_size |
= 0x400; |
| |
|
| |
inuAuStlMgrInit(&init); |
Here we explain the various parameters of the Configuration structure:
| control_flag : |
The library control flag |
| |
Specifies where to place sample wave bank (wbk file). |
| |
0 |
: |
DMA transfer from ROM whenever needed. |
| |
MUSCONTROL_RAM |
: |
Put in RAM ahead of time and use without DMA transferring. |
| |
0 is usually specified.
You would specify MUSCONTROL_RAM in cases where you cannot DMA whenever needed, such as when the sample wave bank data is on a 64DD disk. You could also use this specification when you cannot secure enough DMA time for audio because of graphics DMAs, but this requires a large amount of memory space.
The explanations in this tutorial manual are based on the assumption that the sample wave bank data is located in ROM.
|
| channels : |
The maximum number of channels |
| |
Specifies a maximum value for the number of channels that can be secured by the Music Player. When songs and sound effects start, the maximum number of channels is secured for use by each. This parameter specifies a maximum value for the total number of channels secured for both. If the number of channels actually needed is greater than this value, then some of the sounds will not be produced.
|
| sched : |
The address of the Scheduler structure |
| |
When the default Scheduler is used (when MusSetScheduler is not used), the address of that Scheduler is passed. NuSystem uses a special Scheduler, so in this case this parameter is set to NULL.
|
| thread_priority : |
The priority of the Music Player thread. |
| |
Specifies the priority of the audio task thread. In NuSystem, it is set with NU_AU_MGR_THREAD_PRI.
|
| heap : |
The address of the audio heap |
| |
Specifies the address of the audio heap area. With the MUS library, the synthesizers and the players are secured from this heap area. With NuSystem, the areas for the sample pointer bank (ptr file), song (bin file) and sound effect bank (bfx file) are also secured from this audio heap. NuSystem specifies either (u8 *)NU_AU_HEAP_ADDR or the recalculated value (u8 *)(NU_GFX_FRAMEBUFFER_ADDR - the size of the secured audio heap). |
| heap_length : |
The size of the audio heap |
| |
Specifies the size in bytes of the audio heap area. The required size is equal to the value returned by the nuAuStlMgrInit function plus the size explicitly set aside by the programmer for the data area.
|
| ptr : |
The default address of the sample pointer bank |
| |
Specifies the default address of the sample pointer bank (ptr file) in RAM. In order to make the specification in this parameter, no transfer of data to RAM must take place at this time. The default address cannot be specified here if the data area is to be secured from the audio heap. You can specify the address later with MusPtrBankInitialize, so this is set to NULL.
|
| wbk : |
The default address of the sample wave bank |
| |
Specifies the default address of the sample wave bank (wbk file) in ROM (or in RAM when MUSCONTROL_RAM is set in control_flag). In order to make the specification in this parameter, no transfer of the companion sample pointer bank data to RAM must take place at this time. The default address cannot be specified here if the data area is to be secured from the audio heap. You can specify the address later with MusPtrBankInitialize, so this is set to NULL.
|
| default_fxbank : |
The address of the sound effect bank |
| |
Specifies the default address of the sound effect bank (bfx file) in RAM. In order to make the specification in this parameter, no transfer of data to RAM must take place at this time. The default address cannot be specified here if the data area is to be secured from the audio heap. You can specify the address later with MusPtrBankInitialize, so this is set to NULL. |
| fifo_length : |
The size of the library's FIFO buffer |
| |
Specifies the size of the FIFO buffer used for pausing (MusHandlePause) and for switching sound effects (MusSetFxType). The value can be specified in the range of 64 to 1024, but 64 is normally sufficient. You should increase the value if numerous commands are used in 1 frame.
|
| syn_updates : |
The number of synthesizer updates |
| |
Specifies the number of updates usable by the synthesizer. It is used up by the volume and pan settings, etc. In general, you should specify a value in the range of 96 to 256.
|
| syn_output_rate : |
The playback rate |
| |
Specifies the playback frequency (Hz). A value of 32000Hz or less is recommended. Lower values are also fine for balance with the graphics. Set at the same rate as the sound data created with Sound Tools. |
| syn_rsp_cmds : |
The number of RSP commands |
| |
The number of RSP commands. In other words, it is the maximum length of the audio command list. A minimum value of around 2048( x syn_retraceCount) is required.
|
| syn_retraceCount : |
The number of frames per retrace message |
| |
Specifies the interval for calling the Audio Manager. If the value is set to 1, the Audio Manager is called on every retrace. If the value is 2, it is called on every other retrace. The parameter is usually set to 1. |
| syn_num_dma_bufs : |
The number of DMA buffers |
| |
Specifies the number of buffers to be used by the Audio Manager for DMA from ROM. Set to be at a minimum, larger than the value of the "channels" parameter. |
| syn_dma_buf_size : |
The length of each DMA buffer |
| |
Specifies the size of each buffer used by the Audio Manager for DMA from ROM. The actual buffer size is equal to (syn_num_dma_bufs x (sun_dma_buf_size - buffer header size)). The required size differs, depending on the values of syn_output_rate and channels. For details, see the next section.
|
| diskrom_handle : |
Information about the hardware settings for the 64DD built-in ROM |
| |
Specifies the value returned by osDriveRomInit when using sample waves stored in the 64DD built-in ROM. This was not set in our example of the Configuration structure. Nothing needs to be set for this parameter when such data is not used. |