1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3
4<head>
5<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css">
6<title>AXAcquireVoice</title>
7<META http-equiv="Content-Type" content="text/html; charset=windows-1252">
8<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 6.5.0.0 for Windows">
9<META http-equiv="Content-Style-Type" content="text/css">
10</head>
11
12<body>
13
14<h1 align="left">AXAcquireVoice</h1>
15
16
17<h2>C Specification</h2>
18<BLOCKQUOTE>
19<pre><code>#include &lt;revolution.h&gt;
20
21#define AX_PRIORITY_NODROP  31
22#define AX_PRIORITY_LOWEST  1
23
24typedef void(*AXVoiceCallback)(void *p);
25AXVPB* AXAcquireVoice(u32 priority, AXVoiceCallback callback, u32 userContext);</CODE></pre>
26</BLOCKQUOTE>
27<h2>Arguments</h2>
28
29<table border="1" cellpadding="3" cellspacing="0.1">
30  <tr>
31<td width="120" bgcolor="#ffffe8"><em><strong><code>priority</code></strong></em></td>
32<td width="520">Application-assigned priority. Set from <code>1</code> (minimum) - <code>31</code> (maximum). 31 is the highest priority. <code>AX_PRIORITY_NODROP</code> is defined as 31. <code>AX_PRIORITY_LOWEST</code> is defined as 1. Voices acquired with <code>AX_PRIORITY_NODROP</code> will not be eligible for reacquisition. Priority 0 means that the voice is empty.</td>
33  </tr>
34  <tr>
35<td width="120" bgcolor="#ffffe8"><em><strong><code>callback</code></strong></em></td>
36<td width="520">Application callback. AX invokes this callback if a voice is reacquired (&quot;dropped&quot;). <code>NULL</code> means no callback is to be invoked.</td>
37  </tr>
38  <tr>
39<td width="120" bgcolor="#ffffe8"><em><strong><code>userContext</code></strong></em></td>
40<td width="520">Application-defined &quot;utility&quot; variable. Passed as an argument to the callback.</td>
41  </tr>
42</table>
43
44<h2>Return Values</h2>
45
46<p>Pointer to the voice's associated <code>AXVPB</code>. <code>NULL</code> if acquisition failed.</p>
47
48<h2>Description</h2>
49
50<p><code>AXAcquireVoice()</code> attempts to acquire a voice from AX. Voice acquisition is priority-based. If a free voice is not available, the oldest voice of lowest priority (and lower than the requested priority) will be forcibly reacquired to fulfill the request. (Voices having priority <code>AX_PRIORITY_NODROP</code> cannot be reacquired by this method.) However, such voices may still be dropped by the AX if DSP resources are exceeded for an audio frame. Priority for a voice may be reassigned after acquisition by using <code>AXSetVoicePriority()</code>.</p>
51
52<h2>See Also</h2>
53
54<p>
55<code><a href="AXFreeVoice.html">AXFreeVoice</a><br> <a href="AXSetVoicePriority.html">AXSetVoicePriority</a></code>
56</p>
57
58<h2>Revision History</h2>
59
60<P>03/01/2006 Initial version.</P>
61</body>
62</html>
63