nn::snd::CTR::AllocVoice Function

Voice * AllocVoice(
     s32 priority,
     VoiceDropCallbackFunc callback,
     uptr userArg
);

	Name	Description
in	priority	Priority.
in	callback	Address of the callback function.
in	userArg	User argument.

Returns the address of a Voice object on success. Returns NULL on failure.

Gets a voice.

Call this function to get a valid Voice object. This function returns the address of one usable object of the 24 voice objects managed by the library.

priority takes a value between 0 (the lowest) and VOICE_PRIORITY_NODROP (the highest). If the maximum number of voice objects (24) have already been obtained, behavior depends on the priority specified as an argument.

Normal priority	If the priority specified as an argument is greater than or equal to the lowest priority in the obtained objects, the lowest-priority voice is stopped, released, and the object's address is returned. The callback function specified by callback is invoked for the voice that is released.
VOICE_PRIORITY_NODROP	If the lowest-priority object among the obtained objects is VOICE_PRIORITY_NODROP, NULL is returned. If the lowest priority is lower than VOICE_PRIORITY_NODROP, this function behaves as if you specified a normal priority.

The callback function that is specified by callback is called when a voice-drop occurs under the following conditions.

• When there is no usable Voice, and the lowest priority Voice has been released
• When the lowest priority Voice has been released to prevent a large increase in processing load within the DSP

For the former, the callback function is called from the AllocVoice function. For the latter, the callback function is called from the nn::snd::CTR::SendParameterToDsp function.

When VOICE_PRIORITY_NODROP is specified, there will be no callback, since that Voice cannot be the target of a voice-drop. As a result, for example, when all voices have been specified as VOICE_PRIORITY_NODROP and the processing load within the DSP grows too large, the sound might skip. You need to be aware of this possibility.

Once a callback has been called, you can no longer control that Voice. The nn::snd::CTR::FreeVoice function is also called automatically for the relevant Voice object.

2010/11/05

Added description of how the callback function is called when a voice-drop occurs.

2010/10/21

Added more information specific to voice-drops.

2010/07/23

Fixed a typo related to the maximum number of voices.

2010/01/29

Initial version.