AXAcquireVoice

Syntax

#include <cafe/ax.h>

#define AX_PRIORITY_NODROP  31
#define AX_PRIORITY_LOWEST  1

typedef void(*AXVoiceCallback)(void *p);

AXVPB* AXAcquireVoice(u32 priority, AXVoiceCallback callback, u32 userContext);

Parameters

priority Application-assigned priority. Set from 1 (minimum) to 31 (maximum). 31 is the highest priority. AX_PRIORITY_NODROP is defined as 31. AX_PRIORITY_LOWEST is defined as 1. Voices acquired with AX_PRIORITY_NODROP will not be eligible for reacquisition. Priority of 0 indicates that the voice is not used.
callback Application callback. When a voice is reacquired, AX will call this callback. A pointer to the reacquired AXVPB is passed via the callback argument p. If the callback does not need to be called, specify NULL.
userContext An application-defined utility variable.

Return Values

Pointer to AXVPB associated with the voice. NULL if acquisition failed.

Description

Acquire a voice from AX. Voice acquisition is priority-based. If a voice is unavailable, the oldest voice of lowest priority (and lower than the requested priority) will be forcibly reacquired to fulfill the request.

Voices having priority AX_PRIORITY_NODROP cannot be reacquired by this method.

Voices having priority AX_PRIORITY_NODROP may still be dropped by AX if rendering resources are exceeded for an audio frame.

Priority for a voice may be reassigned after acquisition by using AXSetVoicePriority

Availability

Library Version Availability
Sound 2.0 Yes
Sound 1.0 Yes

Do Not Call From

None.

See Also

AXFreeVoice
AXSetVoicePriority

Revision History

2013/05/08 Automated cleanup pass.
2012/01/26 Update to Audio API v2.0.
2011/02/21 Initial Version


CONFIDENTIAL