XAudio2 APIs

Overview of the XAudio2 APIs technology.

To develop XAudio2 APIs, you need these headers:

For programming guidance for this technology, see:

Class

 
CXAPOBase

Default implementation of the IXAPO interface.
CXAPOParametersBase

Default implementation of the IXAPOParameters interface.

Enumerations

 
HrtfDirectivityType

Indicates one of several stock directivity patterns.
HrtfDistanceDecayType

Indicates a distance-based decay type applied to a sound.
HrtfEnvironment

Indicates one of several stock environment types.
XAPO_BUFFER_FLAGS

Describes the contents of a stream buffer.
XAUDIO2_FILTER_TYPE

Indicates the filter type.

Functions

 
AddRef

Adds a reference to the XAudio2 object.
BeginProcess

Returns the current process parameters.
CalcInputFrames

Returns the number of input frames required to generate the given number of output frames.
CalcOutputFrames

Returns the number of output frames that will be generated from a given number of input frames.
CommitChanges

Atomically applies a set of operations that are tagged with a given identifier.
CreateFX

Creates an instance of the requested XAPOFX effect.
CreateHrtfApo

Creates an instance of the IXAPO interface for head-related transfer function (HRTF) processing.
CreateMasteringVoice

Creates and configures a mastering voice.
CreateSourceVoice

Creates and configures a source voice.
CreateSubmixVoice

Creates and configures a submix voice.
CXAPOBase

Creates an instance of the CXAPOBase class.
CXAPOParametersBase

Creates an instance of the CXAPOParametersBase class.
DestroyVoice

Destroys the voice. If necessary, stops the voice and removes it from the XAudio2 graph.
DisableEffect

Disables the effect at a given position in the effect chain of the voice.
Discontinuity

Notifies an XAudio2 voice that no more buffers are coming after the last one that is currently in its queue.
EnableEffect

Enables the effect at a given position in the effect chain of the voice.
EndProcess

Notifies CXAPOParametersBase that the XAPO has finished accessing the current process parameters.
ExitLoop

Stops looping the voice when it reaches the end of the current loop region.
FlushSourceBuffers

Removes all pending audio buffers from the voice queue.
GetChannelMask

Returns the channel mask for this voice.
GetChannelVolumes

Returns the volume levels for the voice, per channel.
GetEffectParameters

Returns the current effect-specific parameters of a given effect in the voice's effect chain.
GetEffectState

Returns the running state of the effect at a specified position in the effect chain of the voice.
GetFilterParameters

Gets the voice's filter parameters.
GetFrequencyRatio

Returns the frequency adjustment ratio of the voice.
GetOutputFilterParameters

Returns the filter parameters from one of this voice's sends.
GetOutputMatrix

Gets the volume level of each channel of the final output for the voice. These channels are mapped to the input channels of a specified destination voice.
GetParameters

Gets the current values for any effect-specific parameters.
GetPerformanceData

Returns current resource usage details, such as available memory or CPU usage.
GetRegistrationProperties

Returns the registration properties of an XAPO.
GetRegistrationPropertiesInternal

Returns a pointer to the XAPO_REGISTRATION_PROPERTIES structure containing the registration properties the XAPO was created with.
GetState

Returns the voice's current cursor position data.
GetVoiceDetails

Returns information about the creation flags, input channels, and sample rate of a voice.
GetVolume

Gets the current overall volume level of the voice.
Initialize

Performs any effect-specific initialization.
IsInputFormatSupported

Queries if a specific input format is supported for a given output format.
IsLocked

Queries whether the XAPO is locked.
IsOutputFormatSupported

Queries if a specific output format is supported for a given input format.
LockForProcess

Called by XAudio2 to lock the input and output configurations of an XAPO allowing it to do any final initialization before Process is called on the realtime thread.
OnBufferEnd

Called when the voice finishes processing a buffer.
OnBufferStart

Called when the voice is about to start processing a new audio buffer.
OnCriticalError

Called if a critical system error occurs that requires XAudio2 to be closed down and restarted.
OnLoopEnd

Called when the voice reaches the end position of a loop.
OnProcessingPassEnd

Called by XAudio2 just after an audio processing pass ends.
OnProcessingPassStart

Called by XAudio2 just before an audio processing pass begins.
OnSetParameters

Called by IXAPOParameters::SetParameters to allow for user-defined parameter validation.
OnStreamEnd

Called when the voice has just finished playing a contiguous audio stream.
OnVoiceError

Called when a critical error occurs during voice processing.
OnVoiceProcessingPassEnd

Called just after the processing pass for the voice ends.
OnVoiceProcessingPassStart

Called during each processing pass for each voice, just before XAudio2 reads data from the voice's buffer queue.
ParametersChanged

Indicates if IXAPOParameters::SetParameters has been called since the last processing pass.
Process

Runs the XAPO's digital signal processing (DSP) code on the given input and output buffers.
ProcessThru

Called by an IXAPO::Process implementation when an XAPO is disabled for thru processing.
QueryInterface

Queries for a given COM interface on the XAudio2 object.
RegisterForCallbacks

Adds an IXAudio2EngineCallback pointer to the XAudio2 engine callback list.
Release

Releases a reference to the XAudio2 object.
Reset

Resets variables dependent on frame history.
ReverbConvertI3DL2ToNative

Inline function that converts I3DL2 (Interactive 3D Audio Rendering Guidelines Level 2.0) parameters to native XAudio2 parameters.
SetChannelVolumes

Sets the volume levels for the voice, per channel.
SetDebugConfiguration

Changes global debug logging options for XAudio2.
SetEffectChain

Replaces the effect chain of the voice.
SetEffectParameters

Sets parameters for a given effect in the voice's effect chain.
SetEnvironment

Selects the acoustic environment to simulate.
SetFilterParameters

Sets the voice's filter parameters.
SetFrequencyRatio

Sets the frequency adjustment ratio of the voice.
SetOutputFilterParameters

Sets the filter parameters on one of this voice's sends.
SetOutputMatrix

Sets the volume level of each channel of the final output for the voice. These channels are mapped to the input channels of a specified destination voice.
SetOutputVoices

Designates a new set of submix or mastering voices to receive the output of the voice.
SetParameters

Sets effect-specific parameters.
SetSourceGain

Sets the custom direct-path gain value for the current source position. Valid only for sounds played with the HrtfDistanceDecayType custom decay type.
SetSourceOrientation

Set the rotation matrix for the source orientation, with respect to the listener's coordinate system.
SetSourcePosition

Sets the position of the sound relative to the listener.
SetSourceSampleRate

Reconfigures the voice to consume source data at a different sample rate than the rate specified when the voice was created.
SetVolume

Sets the overall volume level for the voice.
Start

Starts consumption and processing of audio by the voice. Delivers the result to any connected submix or mastering voices, or to the output device.
StartEngine

Starts the audio processing thread.
Stop

Stops consumption of audio by the current voice.
StopEngine

Stops the audio processing thread.
SubmitSourceBuffer

Adds a new audio buffer to the voice queue.
UnlockForProcess

Deallocates variables that were allocated with the LockForProcess method.
UnregisterForCallbacks

Removes an IXAudio2EngineCallback pointer from the XAudio2 engine callback list.
ValidateFormatDefault

Verifies that an audio format falls within the default ranges supported.
ValidateFormatPair

Verifies that an input and output format pair configuration is supported by the XAPO.
X3DAudioCalculate

Calculates DSP settings with respect to 3D parameters.
X3DAudioInitialize

Sets all global 3D audio constants.
XAPOAlloc

Memory allocation macro used by IXAPO methods that must allocate arbitrary sized structures that are subsequently returned to the application.
XAPOFree

Macro used to free memory allocated with the XAPOAlloc macro.
XAudio2AmplitudeRatioToDecibels

Inline function that converts an amplitude ratio value to a decibel value.
XAudio2Create

Creates a new XAudio2 object and returns a pointer to its IXAudio2 interface.
XAudio2CreateReverb

Creates a new reverb audio processing object (APO), and returns a pointer to it.
XAudio2CreateVolumeMeter

Creates a new volume meter audio processing object (APO) and returns a pointer to it.
XAudio2CutoffFrequencyToOnePoleCoefficient

Inline function that converts from filter cutoff frequencies expressed in hertz to the filter coefficients used with the Frequency member of the XAUDIO2_FILTER_PARAMETERS structure.
XAudio2CutoffFrequencyToRadians

Inline function that converts from filter cutoff frequencies expressed in hertz to the radian frequency values used in the Frequency member of the XAUDIO2_FILTER_PARAMETERS structure.
XAudio2DecibelsToAmplitudeRatio

Inline function that converts a decibel value to an amplitude ratio value.
XAudio2FrequencyRatioToSemitones

Inline function that converts a frequency ratio value to a semitone value.
XAudio2RadiansToCutoffFrequency

Inline function that converts from the radian frequencies used in XAUDIO2_FILTER_PARAMETERS back to absolute frequencies in hertz.
XAudio2SemitonesToFrequencyRatio

Inline function that converts a semitone value to a frequency ratio value.

Interfaces

 
IXAPO

The interface for an Audio Processing Object which be used in an XAudio2 effect chain.
IXAPOHrtfParameters

The interface used to set parameters that control how head-related transfer function (HRTF) is applied to a sound.
IXAPOParameters

An optional interface that allows an XAPO to use effect-specific parameters.
IXAudio2

IXAudio2 is the interface for the XAudio2 object that manages all audio engine states, the audio processing thread, the voice graph, and so forth.
IXAudio2EngineCallback

The IXAudio2EngineCallback interface contains methods that notify the client when certain events happen in the IXAudio2 engine.
IXAudio2MasteringVoice

A mastering voice is used to represent the audio output device.
IXAudio2SourceVoice

Use a source voice to submit audio data to the XAudio2 processing pipeline.
IXAudio2SubmixVoice

A submix voice is used primarily for performance improvements and effects processing.
IXAudio2Voice

IXAudio2Voice represents the base interface from which IXAudio2SourceVoice, IXAudio2SubmixVoice and IXAudio2MasteringVoice are derived. The methods listed below are common to all voice subclasses.
IXAudio2VoiceCallback

The IXAudio2VoiceCallback interface contains methods that notify the client when certain events happen in a given IXAudio2SourceVoice.

Structures

 
FXECHO_INITDATA

Initialization parameters for use with the FXECHO XAPOFX.
FXECHO_PARAMETERS

Parameters for use with the FXECHO XAPOFX.
FXEQ_PARAMETERS

Parameters for use with the FXEQ XAPO.
FXMASTERINGLIMITER_PARAMETERS

Parameters for use with the FXMasteringLimiter XAPO.
FXREVERB_PARAMETERS

Parameters for use with the FXReverb XAPO.
HrtfApoInit

Specifies parameters used to initialize HRTF spatial audio.
HrtfDirectivity

Base directivity pattern descriptor. Describes the type of directivity applied to a sound.
HrtfDirectivityCardioid

Describes a cardioid directivity pattern.
HrtfDirectivityCone

Describes a cone directivity.
HrtfDistanceDecay

Describes a distance-based decay behavior.
HrtfOrientation

Indicates the orientation of an HRTF directivity object.
HrtfPosition

Represents a position in 3D space, using a right-handed coordinate system.
X3DAUDIO_CONE

Specifies directionality for a single-channel non-LFE emitter by scaling DSP behavior with respect to the emitter's orientation.
X3DAUDIO_DISTANCE_CURVE

Defines an explicit piecewise curve made up of linear segments, directly defining DSP behavior with respect to normalized distance.
X3DAUDIO_DISTANCE_CURVE_POINT

Defines a DSP setting at a given normalized distance.
X3DAUDIO_DSP_SETTINGS

Receives the results from a call to X3DAudioCalculate.
X3DAUDIO_EMITTER

Defines a single-point or multiple-point 3D audio source that is used with an arbitrary number of sound channels.
X3DAUDIO_LISTENER

Defines a point of 3D audio reception.
XAPO_LOCKFORPROCESS_PARAMETERS

Defines stream buffer parameters that remain constant while an XAPO is locked. Used with the IXAPO::LockForProcess method.
XAPO_PROCESS_BUFFER_PARAMETERS

Defines stream buffer parameters that may change from one call to the next. Used with the Process method.
XAPO_REGISTRATION_PROPERTIES

Describes general characteristics of an XAPO. Used with IXAPO::GetRegistrationProperties, CXAPOParametersBase::CXAPOParametersBase, and CXAPOBase::CXAPOBase.
XAUDIO2_BUFFER

Represents an audio data buffer, used with IXAudio2SourceVoice::SubmitSourceBuffer.
XAUDIO2_BUFFER_WMA

Used with IXAudio2SourceVoice::SubmitSourceBuffer when submitting xWMA data.
XAUDIO2_DEBUG_CONFIGURATION

Contains the new global debug configuration for XAudio2. Used with the SetDebugConfiguration function.
XAUDIO2_EFFECT_CHAIN

Defines an effect chain.
XAUDIO2_EFFECT_DESCRIPTOR

Contains information about an XAPO for use in an effect chain.
XAUDIO2_FILTER_PARAMETERS

Defines filter parameters for a source voice.
XAUDIO2_PERFORMANCE_DATA

Contains performance information.
XAUDIO2_SEND_DESCRIPTOR

Defines a destination voice that is the target of a send from another voice and specifies whether a filter should be used.
XAUDIO2_VOICE_DETAILS

Contains information about the creation flags, input channels, and sample rate of a voice.
XAUDIO2_VOICE_SENDS

Defines a set of voices to receive data from a single output voice.
XAUDIO2_VOICE_STATE

Returns the voice's current state and cursor position data.
XAUDIO2FX_REVERB_I3DL2_PARAMETERS

Describes I3DL2 (Interactive 3D Audio Rendering Guidelines Level 2.0) parameters for use in the ReverbConvertI3DL2ToNative function.
XAUDIO2FX_REVERB_PARAMETERS

Describes parameters for use in the reverb APO.
XAUDIO2FX_VOLUMEMETER_LEVELS

Describes parameters for use with the volume meter APO.