Up until now, all the explanations we have given have involved the use of only one Sound Effect Bank and Sample Bank. However, in actual practice, sometimes sample banks are divided into files for songs and files for sound effects, and sometimes sound-effect banks are switched depending on the circumstances. In this chapter we explain several ways to use bank files.

In this section we explain how to use a number of sample banks.

As explained in "Section 1.5, Preparations for Audio Playback," all of the sample banks must be initialized ahead of time. It does not matter how many sample banks are going to be initialized with MusPtrBankInitialize. At the time of initialization, the sample bank specified the first time by MusPtrBankInitialize is automatically set as the default sample bank. Sample banks initialized on the second and subsequent times are not set as the default, but this can be changed and one of these sample banks can be set as the default using MusPtrBankSetCurrent. When a bank is set as the default, any song or sound effect started after that point will make use of that bank.

Set initialized sample bank as the default

Function name:	MusPtrBankSetCurrent
Syntax:	void MusPtrBankSetCurrent(void *ipbank)
Arguments:	ipbank	Address of the initialized sample bank
Return value:	None

You can make use of a number of sample banks with just MusPtrBankSetCurrent, but there is another function with different characteristics called, MusPtrBankSetSingle, that you can also use. This function sets an override that is different from the default. The override has higher priority than the default, but it is cleared after one use. Thus, you can utilize this function to make temporary use of a different sample bank when the need arises.

Temporarily set the next sample bank to use

Function name:	MusPtrBankSetSingle
Syntax:	void MusPtrBankSetSingle(void *ipbank)
Arguments:	ipbank	Address of an initialized sample pointer bank
Return value:	None

The following is an example of how these two functions can be combined to make use of multiple sample banks.

MusPtrBankInitialize(A_ptr,A_wbk);  // Initialize A and set as default
MusPtrBankInitialize(B_ptr,B_wbk);   // Initialize B
MusPtrBankInitialize(C_ptr,C_wbk);  // Initialize C

MusStartSong(song1);            // Use the default, A  (there is no override)

MusPtrBankSetCurrent(B_ptr);    // Change the default to B
MusStartSong(song2);            // Use the default, B (there is no override)

MusPtrBankSetSingle(C_ptr);    // Set the override to C
MusStartSong(song3);           // Use the override, C (override gets cleared)

MusStartSong(song4);           // Use the default, B (there is no override)

There is one point you need to be careful about, as the next example demonstrates:

MusPtrBankInitialize(A_ptr,A_wbk);   // Initialize A and set as default
MusPtrBankInitialize(B_ptr,B_wbk);   // Initialize B
MusPtrBankInitialize(C_ptr,C_wbk);   // Initialize C

MusStartSong(song1);            // Use the default, A (there is no override)

MusPtrBankSetSingle(C_ptr);    // Set the override to C 

MusPtrBankSetCurrent(B_ptr);   // Change the default to B
MusStartSong(song2);           // Use the override, C (override gets cleared)

The override is released when the song or sound effect begins, but not if the only function that is executed is MusPtrBankSetCurrent. For this reason, you should execute MusPtrBankSetSingle immediately before starting the song or sound effect. You can forcefully clear the override by setting NULL in the argument of MusPtrBankSetSingle.