nn::snd::CTR::AllocVoice Function

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

	Name	Description
in	priority	Priority.
in	callback	The address of the callback function invoked when a voice-drop occurs
in	userArg	The user argument for the callback function invoked when a voice-drop occurs

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 Voice objects that have already been obtained, the lowest-priority voice among them is stopped and 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.

Among voices that are set to the same level of priority, the voice that was set last takes the highest priority. This setting of priority includes the nn::snd::CTR::Voice::SetPriority function.

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.

2011/05/26

Added mention of the ordering of voices set to the same priority level.

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.