XAudio2 APIs

Overview of the XAudio2 APIs technology.

To develop XAudio2 APIs, you need these headers:

• hrtfapoapi.h
• x3daudio.h
• xapo.h
• xapobase.h
• xapofx.h
• xaudio2.h
• xaudio2fx.h

For programming guidance for this technology, see:

• XAudio2 APIs

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_PERFORMANCE_DATA)
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.