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. When a voice is reacquired (takeover), AX will call this callback. A pointer to the reacquired AXVPB is passed to the callback argument <code>p</code>. If the callback does not need to be called, specify <code>NULL</code>.</td>
37  </tr>
38  <tr>
39<td width="120" bgcolor="#ffffe8"><em><strong><code>userContext</code></strong></em></td>
40<td width="520">An application-defined utility variable. This replaces the AXVPB member userContext at voice acquisition. The application will be able to obtain this variable during voice reacquisition (takeover) through the callback argument (AXVPB pointer) specified above.</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>
612006/03/01 Initial version. <BR>2006/10/17 Added/revised the descriptions for the arguments.
62</P>
63
64<hr>
65<P>CONFIDENTIAL</p>
66</BODY>
67</HTML>
68