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><a href="../../../nn/Overview.html">nn</a>::<a href="../../../nn/snd/Overview.html">snd</a>::<a href="../../../nn/snd/CTR/Overview.html">CTR</a>::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>The address of the callback function invoked when a voice-drop occurs</td>
40        </tr>
41        <tr>
42<td>in</td>
43<th>userArg</th>
44<td>The user argument for the callback function invoked when a voice-drop occurs</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 <CODE>Voice</CODE> 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 <SPAN class="argument">callback</SPAN> 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>
60Among 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 <CODE><a href="../../../nn/snd/CTR/Voice/SetPriority.html">nn::snd::CTR::Voice::SetPriority</a></CODE> function.
61      </p><p>
62The callback function that is specified by <CODE>callback</CODE> is called when a voice-drop occurs under the following conditions.
63<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>
64For 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.
65      </p><p>
66When <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.
67      </p><p>
68Once 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.
69      </p></div>
70<h2>Revision History</h2>
71    <div class="section">
72      <dl class="history">
73        <dt>2011/05/26</dt>
74<dd>Added mention of the ordering of voices set to the same priority level.<br />
75        </dd>
76        <dt>2010/11/05</dt>
77<dd>Added description of how the callback function is called when a voice-drop occurs.
78        </dd>
79        <dt>2010/10/21</dt>
80<dd>Added more information specific to voice-drops.
81        </dd>
82        <dt>2010/07/23</dt>
83<dd>Fixed a typo related to the maximum number of voices.
84        </dd>
85        <dt>2010/01/29</dt>
86<dd>Initial version.<br />
87        </dd>
88      </dl>
89    </div>
90  <hr><p>CONFIDENTIAL</p></body>
91</html>
92