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<h2>Syntax</h2> 17<dl><dd><pre class="construction"> 18#include <revolution/ax.h> 19 20#define AX_PRIORITY_NODROP 31 21#define AX_PRIORITY_LOWEST 1 22 23typedef void(*AXVoiceCallback)(void *p); 24 25AXVPB* AXAcquireVoice(u32 priority, AXVoiceCallback callback, u32 userContext); 26</pre></dd></dl> 27 28<h2>Arguments</h2> 29<TABLE class="arguments" border="1" > 30 <tr> 31<th>priority</th> 32<td>Application-assigned priority. Set from 1 (minimum) to 31 (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 of 0 means that the voice is empty.</td> 33 </tr> 34 <tr> 35<th>callback</th> 36<td>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 <SPAN class="argument">p</SPAN>. If the callback does not need to be called, specify <code>NULL</code>.</td> 37 </tr> 38 <tr> 39<th>userContext</th> 40<td>An application-defined utility variable. This replaces the AXVPB member <SPAN class="argument">userContext</SPAN> 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<p>Pointer to <CODE>AXVPB</CODE> associated with the voice. <code>NULL</code> if acquisition failed.</p> 46 47<h2>Description</h2> 48<p>The <code>AXAcquireVoice</code> function 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 with the <code>AX_PRIORITY_NODROP</code> priority cannot be reacquired by this method.) Voices reacquired with the <code>AX_PRIORITY_NODROP</code> priority 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> 49 50<h2>See Also</h2> 51<p class="reference"> 52<a href="AXFreeVoice.html"><CODE>AXFreeVoice</CODE></a>, <a href="AXSetVoicePriority.html"><CODE>AXSetVoicePriority</CODE></a> 53</p> 54 55<h2>Revision History</h2> 56<P> 572006/10/17 Added and corrected argument descriptions.<br>2006/03/01 Initial version.<br> 58</P> 59 60<hr><p>CONFIDENTIAL</p></body> 61</html> 62