1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../../../css/manpage.css" type="text/css" />
7<title>AllocVoice</title>
8  </head>
9  <body>
10<h1><CODE>nn::snd::CTR::AllocVoice</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14<a href="../../../nn/snd/CTR/Voice/Overview.html">Voice</a> * AllocVoice(
15     s32 priority,
16     <a href="../../../nn/snd/CTR/VoiceDropCallbackFunc.html">VoiceDropCallbackFunc</a> callback,
17     uptr userArg
18);
19</pre>
20    </div>
21<h2>Arguments</h2>
22    <div class="section">
23      <table class="arguments">
24        <thead>
25          <tr>
26            <td width="15" />
27<th>Name</th>
28<td>Description</td>
29          </tr>
30        </thead>
31        <tr>
32<td>in</td>
33<th>priority</th>
34<td>Priority.</td>
35        </tr>
36        <tr>
37<td>in</td>
38<th>callback</th>
39<td>Address of the callback function.</td>
40        </tr>
41        <tr>
42<td>in</td>
43<th>userArg</th>
44<td>User argument.</td>
45        </tr> </table>
46    </div>
47<h2>Return Values</h2>
48<div class="section">Returns the address of a <CODE>Voice</CODE> object on success. Returns <CODE>NULL</CODE> on failure. </div>
49<h2>Description</h2>
50    <div class="section">
51<p>Gets a voice.</p><p>
52Call this function to get a valid <CODE>Voice</CODE> object. This function returns the address of one usable object of the 24 voice objects managed by the library.
53      </p><p>
54<CODE>priority</CODE> 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.
55</p><p><table><tr><th>Normal priority</th><td>
56If 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.
57</td></tr><tr><th><CODE>VOICE_PRIORITY_NODROP</CODE></th><td>
58If the lowest-priority object among the obtained objects is <CODE>VOICE_PRIORITY_NODROP</CODE>, NULL is returned. If the lowest priority is lower than <CODE>VOICE_PRIORITY_NODROP</CODE>, this function behaves as if you specified a normal priority.
59            </td></tr></table></p><p>
60The callback function that is specified by <CODE>callback</CODE> is called when a voice-drop occurs under the following conditions.
61<ul><li>When there is no usable <CODE>Voice</CODE>, and the lowest priority <CODE>Voice</CODE> has been released</li><li>When the lowest priority <CODE>Voice</CODE> has been released to prevent a large increase in processing load within the DSP</li></ul></p><p>
62For the former, the callback function is called from the <CODE>AllocVoice</CODE> function. For the latter, the callback function is called from the <a href="../../../nn/snd/CTR/SendParameterToDsp.html"><CODE>nn::snd::CTR::SendParameterToDsp</CODE></a> function.
63      </p><p>
64When <CODE>VOICE_PRIORITY_NODROP</CODE> is specified, there will be no callback, since that <CODE>Voice</CODE> cannot be the target of a voice-drop. As a result, for example, when all voices have been specified as <CODE>VOICE_PRIORITY_NODROP</CODE> and the processing load within the DSP grows too large, the sound might skip. You need to be aware of this possibility.
65      </p><p>
66Once a callback has been called, you can no longer control that <CODE>Voice</CODE>. The <a href="../../../nn/snd/CTR/FreeVoice.html"><CODE>nn::snd::CTR::FreeVoice</CODE></a> function is also called automatically for the relevant <CODE>Voice</CODE> object.
67      </p></div>
68<h2>Revision History</h2>
69    <div class="section">
70      <dl class="history">
71        <dt>2010/11/05</dt>
72<dd>Added description of how the callback function is called when a voice-drop occurs.
73        </dd>
74        <dt>2010/10/21</dt>
75<dd>Added more information specific to voice-drops.
76        </dd>
77        <dt>2010/07/23</dt>
78<dd>Fixed a typo related to the maximum number of voices.
79        </dd>
80        <dt>2010/01/29</dt>
81<dd>Initial version.<br />
82        </dd>
83      </dl>
84    </div>
85  <hr><p>CONFIDENTIAL</p></body>
86</html>