XAudio2 audio data is interleaved, data from each channel is adjacent for a particular sample number. For example if there was a 4 channel wave playing into an XAudio2 source voice, the audio data would be a sample of channel 0, a sample of channel 1, a sample of channel 2, a sample of channel 3, and then the next sample of channels 0, 1, 2, 3, etc.

The AudioBytes and pAudioData members of correspond to the size in bytes and contents of the 'data' RIFF chunk of the file being played. The contents of the chunk may need to be byte swapped when loading the file on Xbox 360.

Memory allocated to hold a or structure can be freed as soon as the call it is passed to returns. The data the structure points to (pAudioData and pDecodedPacketCumulativeBytes, respectively) can't be freed until the buffer completes (as signaled by the callback) or the voice is stopped or destroyed.

XAPO instances are passed to XAudio2 as interfaces and XAudio2 uses IXAPO::QueryInterface to acquire an interface and to detect whether the XAPO implements the interface.

For additional information on using XAPOs with XAudio2 see How to: Create an Effect Chain and How to: Use an XAPO in XAudio2.

There are many preset values defined for the structure. For more information, see XAUDIO2FX_I3DL2_PRESET.

All parameters related to sampling rate or time are relative to a 48kHz voice and must be scaled for use with other sampling rates. For example, setting ReflectionsDelay to 300ms gives a true 300ms delay when the reverb is hosted in a 48kHz voice, but becomes a 150ms delay when hosted in a 24kHz voice.

This structure is used with the XAudio2 method.

pPeakLevels and pRMSLevels are not returned by , the arrays are only filled out if they are present. If pPeakLevels and pRMSLevels are used they must be allocated by the application. The application is responsible for freeing the arrays when they are no longer needed.

ChannelCount must be set by the application to match the number of channels in the voice the effect is applied to.

XAudio2 audio data is interleaved, data from each channel is adjacent for a particular sample number. For example if there was a 4 channel wave playing into an XAudio2 source voice, the audio data would be a sample of channel 0, a sample of channel 1, a sample of channel 2, a sample of channel 3, and then the next sample of channels 0, 1, 2, 3, etc.

The AudioBytes and pAudioData members of correspond to the size in bytes and contents of the 'data' RIFF chunk of the file being played. The contents of the chunk may need to be byte swapped when loading the file on Xbox 360.

Memory allocated to hold a or structure can be freed as soon as the call it is passed to returns. The data the structure points to (pAudioData and pDecodedPacketCumulativeBytes, respectively) can't be freed until the buffer completes (as signaled by the callback) or the voice is stopped or destroyed.

Note the DirectX SDK versions of XAUDIO2 do not support the ActiveFlags member.

The pChannelMask argument is a bit-mask of the various channels in the speaker geometry reported by the audio system. This information is needed for the X3DAudioInitialize SpeakerChannelMask parameter.

The X3DAUDIO.H header declares a number of SPEAKER_ positional defines to decode these channels masks.

Examples include:

 //  (0x1) |  (0x2)   //  (0x1) |  (0x2) // |  (0x4) // |  (0x8) // |  (0x10) |  (0x20)

The pChannelMask argument is a bit-mask of the various channels in the speaker geometry reported by the audio system. This information is needed for the SpeakerChannelMask parameter.

The X3DAUDIO.H header declares a number of SPEAKER_ positional defines to decode these channels masks.

Examples include:

 //  (0x1) |  (0x2)   //  (0x1) |  (0x2) // |  (0x4) // |  (0x8) // |  (0x10) |  (0x20)

Note??For the DirectX SDK versions of XAUDIO, the channel mask for the output device was obtained via the IXAudio2::GetDeviceDetails method, which doesn't exist in Windows?8 and later.

GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent call: the actual ratio is only changed the next time the audio engine runs after the call (or after the corresponding call, if was called with a deferred operation ID).

For information on frequency ratios, see .

The SetSourceSampleRate method supports reuse of XAudio2 voices by allowing a voice to play sounds with a variety of sample rates. To use SetSourceSampleRate the voice must have been created without the or flags and must not have any buffers currently queued.

The typical use of SetSourceSampleRate is to support voice pooling. For example to support voice pooling an application would precreate all the voices it expects to use. Whenever a new sound will be played the application chooses an inactive voice or ,if all voices are busy, picks the least important voice and calls SetSourceSampleRate on the voice with the new sound's sample rate. After SetSourceSampleRate has been called on the voice, the application can immediately start submitting and playing buffers with the new sample rate. This allows the application to avoid the overhead of creating and destroying voices frequently during gameplay.

If the XAudio2 engine is stopped, the voice stops running. However, it remains in the started state, so that it starts running again as soon as the engine starts.

When first created, source voices are in the stopped state. Submix and mastering voices are in the started state.

After Start is called it has no further effect if called again before is called. In addition multiple calls to Start without matching calls to will result in warning messages in debug builds.

All source buffers that are queued on the voice and the current cursor position are preserved. This allows the voice to continue from where it left off, when it is restarted. The method can be used to flush queued source buffers.

By default, any pending output from voice effects?for example, reverb tails?is not played. Instead, the voice is immediately rendered silent. The flag can be used to continue emitting effect output after the voice stops running.

A voice stopped with the flag stops consuming source buffers, but continues to process its effects and send audio to its destination voices. A voice in this state can later be stopped completely by calling Stop again with the Flags argument set to 0. This enables stopping a voice with , waiting sufficient time for any audio being produced by its effects to finish, and then fully stopping the voice by calling Stop again without . This technique allows voices with effects to be stopped gracefully while ensuring idle voices will not continue to be processed after they have finished producing audio.

Stop is always asynchronous, even if called within a callback.

The voice processes and plays back the buffers in its queue in the order that they were submitted.

The structure includes details about the audio buffer's location and size, the part of the buffer that should actually be played, the loop region (if any) and loop count, the context reference to be used in any callbacks relating to this buffer, and an optional flag that indicates that it is the last buffer of a contiguous sound.

If the voice is started and has no buffers queued, the new buffer will start playing immediately. If the voice is stopped, the buffer is added to the voice's queue and will be played when the voice starts.

If only part of the given buffer should be played, the PlayBegin and PlayLength fields in the can be used to specify the region to be played. A PlayLength value of 0 means to play the entire buffer (and in this case PlayBegin must be 0 as well).

If all or part of the buffer should be played in a continuous loop, the LoopBegin, LoopLength and LoopCount fields in can be used to specify the characteristics of the loop region. A LoopBegin value of means that no looping should be performed, and in this case LoopLength and LoopCount must be given as 0. If a loop region is specified, it must be non-empty (LoopLength > 0), and the loop count must be between 1 and inclusive (or to specify an endless loop which will only end when is called). A loop count of N means to skip backwards N times, i.e. to play the loop region N+1 times.

If an explicit play region is specified, it must begin and end within the given audio buffer (or, in the compressed case, within the set of samples that the buffer will decode to). In addition, the loop region cannot end past the end of the play region.

?

The pBuffer reference can be reused or freed immediately after calling this method, but the actual audio data referenced by pBuffer must remain valid until the buffer has been fully consumed by XAudio2 (which is indicated by the callback).

Up to buffers can be queued on a voice at any one time.

SubmitSourceBuffer takes effect immediately when called from an XAudio2 callback with an OperationSet of .

?

If the voice is started, the buffer that is currently playing is not removed from the queue.

FlushSourceBuffers can be called regardless of whether the voice is currently started or stopped.

For every buffer removed, an OnBufferEnd callback will be made, but none of the other per-buffer callbacks (OnBufferStart, OnStreamEnd or OnLoopEnd) will be made.

FlushSourceBuffers does not change a the voice's running state, so if the voice was playing a buffer prior to the call, it will continue to do so, and will deliver all the callbacks for the buffer normally. This means that the OnBufferEnd callback for this buffer will take place after the OnBufferEnd callbacks for the buffers that were removed. Thus, an XAudio2 client that calls FlushSourceBuffers cannot expect to receive OnBufferEnd callbacks in the order in which the buffers were submitted.

No warnings for starvation of the buffer queue will be emitted when the currently playing buffer completes; it is assumed that the client has intentionally removed the buffers that followed it. However, there may be an audio pop if this buffer does not end at a zero crossing. If the application must ensure that the flush operation takes place while a specific buffer is playing?perhaps because the buffer ends with a zero crossing?it must call FlushSourceBuffers from a callback, so that it executes synchronously.

Calling FlushSourceBuffers after a voice is stopped and then submitting new data to the voice resets all of the voice's internal counters.

A voice's state is not considered reset after calling FlushSourceBuffers until the OnBufferEnd callback occurs (if a buffer was previously submitted) or returns with . BuffersQueued == 0. For example, if you stop a voice and call FlushSourceBuffers, it's still not legal to immediately call (which requires the voice to not have any buffers currently queued), until either of the previously mentioned conditions are met.

Discontinuity suppresses the warnings that normally occur in the debug build of XAudio2 when a voice runs out of audio buffers to play. It is preferable to mark the final buffer of a stream by tagging it with the flag, but in some cases the client may not know that a buffer is the end of a stream until after the buffer has been submitted.

Because calling Discontinuity is equivalent to applying the flag retroactively to the last buffer submitted, an OnStreamEnd callback will be made when this buffer completes.

If the cursor for the voice is not in a loop region, ExitLoop does nothing.

For all encoded formats, including constant bit rate (CBR) formats such as adaptive differential pulse code modulation (ADPCM), SamplesPlayed is expressed in terms of decoded samples. For pulse code modulation (PCM) formats, SamplesPlayed is expressed in terms of either input or output samples. There is a one-to-one mapping from input to output for PCM formats.

If a client needs to get the correlated positions of several voices?that is, to know exactly which sample of a particular voice is playing when a specified sample of another voice is playing?it must make the calls in an XAudio2 engine callback. Doing this ensures that none of the voices advance while the calls are made.

Frequency adjustment is expressed as source frequency / target frequency. Changing the frequency ratio changes the rate audio is played on the voice. A ratio greater than 1.0 will cause the audio to play faster and a ratio less than 1.0 will cause the audio to play slower. Additionally, the frequency ratio affects the pitch of audio on the voice. As an example, a value of 1.0 has no effect on the audio, whereas a value of 2.0 raises pitch by one octave and 0.5 lowers it by one octave.

If SetFrequencyRatio is called specifying a Ratio value outside the valid range, the method will set the frequency ratio to the nearest valid value. A warning also will be generated for debug builds.

GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent call: the actual ratio is only changed the next time the audio engine runs after the call (or after the corresponding call, if was called with a deferred operation ID).

For information on frequency ratios, see .

The SetSourceSampleRate method supports reuse of XAudio2 voices by allowing a voice to play sounds with a variety of sample rates. To use SetSourceSampleRate the voice must have been created without the or flags and must not have any buffers currently queued.

The typical use of SetSourceSampleRate is to support voice pooling. For example to support voice pooling an application would precreate all the voices it expects to use. Whenever a new sound will be played the application chooses an inactive voice or ,if all voices are busy, picks the least important voice and calls SetSourceSampleRate on the voice with the new sound's sample rate. After SetSourceSampleRate has been called on the voice, the application can immediately start submitting and playing buffers with the new sample rate. This allows the application to avoid the overhead of creating and destroying voices frequently during gameplay.

Data buffers cannot be submitted directly to submix voices and will not be audible unless submitted to a mastering voice. A submix voice can be used to ensure that a particular set of voice data is converted to the same format and/or to have a particular effect chain processed on the collective result.

inherits directly from , but does not implement methods specific to submix voices. The interface type exists solely because some of the base class methods are implemented differently for submix voices. Having a separate type for these voices helps client code to distinguish the different voice types and to benefit from C++ type safety.

This method is only valid for source and submix voices. Mastering voices can not send audio to another voice.

After calling SetOutputVoices a voice's current send levels will be replaced by a default send matrix. The method must be called to set a custom matrix for the new sendlist.

It is invalid to call SetOutputVoices from within a callback (that is, or ). If SetOutputVoices is called within a callback, it returns .

GetFilterParameters will fail if the voice was not created with the flag.

GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent call: the actual parameters are only changed the next time the audio engine runs after the call (or after the corresponding call, if was called with a deferred operation ID).

SetVolume controls a voice's master input volume level. The master volume level is applied at different times depending on the type of voice. For submix and mastering voices the volume level is applied just before the voice's built in filter and effect chain is applied. For source voices the master volume level is applied after the voice's filter and effect chain is applied.

Volume levels are expressed as floating-point amplitude multipliers between - and (-2?? to 2??), with a maximum gain of 144.5 dB. A volume level of 1.0 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

This method is only valid for source and submix voices. Mastering voices can not send audio to another voice.

After calling SetOutputVoices a voice's current send levels will be replaced by a default send matrix. The method must be called to set a custom matrix for the new sendlist.

It is invalid to call SetOutputVoices from within a callback (that is, or ). If SetOutputVoices is called within a callback, it returns .

The number of output channels allowed for a voice's effect chain is locked at creation of the voice. If you create the voice with an effect chain, any new effect chain passed to SetEffectChain must have the same number of input and output channels as the original effect chain. If you create the voice without an effect chain, the number of output channels allowed for the effect chain will default to the number of input channels for the voice. If any part of effect chain creation fails, none of it is applied.

After you attach an effect to an XAudio2 voice, XAudio2 takes control of the effect, and the client should not make any further calls to it. The simplest way to ensure this is to release all references to the effect.

It is invalid to call SetEffectChain from within a callback (that is, or ). If you call SetEffectChain within a callback, it returns .

The that is passed in as the pEffectChain argument and any information contained within it are no longer needed after SetEffectChain successfully completes, and may be deleted immediately after SetEffectChain is called.

Be careful when you enable an effect while the voice that hosts it is running. Such an action can result in a problem if the effect significantly changes the audio's pitch or volume.

The effects in a given XAudio2 voice's effect chain must consume and produce audio at that voice's processing sample rate. The only aspect of the audio format they can change is the channel count. For example a reverb effect can convert mono data to 5.1. The client can use the structure's OutputChannels field to specify the number of channels it wants each effect to produce. Each effect in an effect chain must produce a number of channels that the next effect can consume. Any calls to or that would make the effect chain stop fulfilling these requirements will fail.

EnableEffect takes effect immediately when you call it from an XAudio2 callback with an OperationSet of .

The effects in a given XAudio2 voice's effect chain must consume and produce audio at that voice's processing sample rate. The only aspect of the audio format they can change is the channel count. For example a reverb effect can convert mono data to 5.1. The client can use the structure's OutputChannels field to specify the number of channels it wants each effect to produce. Each effect in an effect chain must produce a number of channels that the next effect can consume. Any calls to or that would make the effect chain stop fulfilling these requirements will fail.

Disabling an effect immediately removes it from the processing graph. Any pending audio in the effect?such as a reverb tail?is not played. Be careful disabling an effect while the voice that hosts it is running. This can result in an audible artifact if the effect significantly changes the audio's pitch or volume.

DisableEffect takes effect immediately when called from an XAudio2 callback with an OperationSet of .

GetEffectState always returns the effect's actual current state. However, this may not be the state set by the most recent or call: the actual state is only changed the next time the audio engine runs after the or call (or after the corresponding call, if EnableEffect/DisableEffect was called with a deferred operation ID).

The specific effect being used determines the valid size and format of the pParameters buffer. The call will fail if pParameters is invalid or if ParametersByteSize is not exactly the size that the effect expects. The client must take care to direct the SetEffectParameters call to the right effect. If this call is directed to a different effect that happens to accept the same parameter block size, the parameters will be interpreted differently. This may lead to unexpected results.

The memory pointed to by pParameters must not be freed immediately, because XAudio2 will need to refer to it later when the parameters actually are applied to the effect. This happens during the next audio processing pass if the OperationSet argument is . Otherwise, the parameters are applied to the effect later, during the first processing pass after the function is called with the same OperationSet argument.

SetEffectParameters takes effect immediately when called from an XAudio2 callback with an OperationSet of .

GetEffectParameters always returns the effect's actual current parameters. However, these may not match the parameters set by the most recent call to : the actual parameters are only changed the next time the audio engine runs after the call (or after the corresponding call, if was called with a deferred operation ID).

SetFilterParameters will fail if the voice was not created with the flag.

This method is usable only on source and submix voices and has no effect on mastering voices.

GetFilterParameters will fail if the voice was not created with the flag.

GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent call: the actual parameters are only changed the next time the audio engine runs after the call (or after the corresponding call, if was called with a deferred operation ID).

SetOutputFilterParameters will fail if the send was not created with the flag. This method is usable only on sends belonging to source and submix voices and has no effect on a mastering voice's sends.

GetOutputFilterParameters will fail if the send was not created with the flag. This method is usable only on sends belonging to source and submix voices and has no effect on mastering voices? sends.

SetVolume controls a voice's master input volume level. The master volume level is applied at different times depending on the type of voice. For submix and mastering voices the volume level is applied just before the voice's built in filter and effect chain is applied. For source voices the master volume level is applied after the voice's filter and effect chain is applied.

Volume levels are expressed as floating-point amplitude multipliers between - and (-2?? to 2??), with a maximum gain of 144.5 dB. A volume level of 1.0 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

SetVolume controls a voice's master input volume level. The master volume level is applied at different times depending on the type of voice. For submix and mastering voices the volume level is applied just before the voice's built in filter and effect chain is applied. For source voices the master volume level is applied after the voice's filter and effect chain is applied.

Volume levels are expressed as floating-point amplitude multipliers between - and (-2?? to 2??), with a maximum gain of 144.5 dB. A volume level of 1.0 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

SetChannelVolumes controls a voice's per-channel output levels and is applied just after the voice's final SRC and before its sends.

This method is valid only for source and submix voices, because mastering voices do not specify volume per channel.

Volume levels are expressed as floating-point amplitude multipliers between - and (-2?? to 2??), with a maximum gain of 144.5 dB. A volume of 1 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

These settings are applied after the effect chain is applied. This method is valid only for source and submix voices, because mastering voices do not specify volume per channel.

Volume levels are expressed as floating-point amplitude multipliers between -2?? to 2??, with a maximum gain of 144.5 dB. A volume of 1 means there is no attenuation or gain, 0 means silence, and negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

This method is valid only for source and submix voices, because mastering voices write directly to the device with no matrix mixing.

Volume levels are expressed as floating-point amplitude multipliers between - and (-2?? to 2??), with a maximum gain of 144.5 dB. A volume level of 1.0 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

The X3DAudio function X3DAudioCalculate can produce an output matrix for use with SetOutputMatrix based on a sound's position and a listener's position.

This method applies only to source and submix voices, because mastering voices write directly to the device with no matrix mixing. Volume levels are expressed as floating-point amplitude multipliers between -2?? to 2??, with a maximum gain of 144.5 dB. A volume level of 1 means there is no attenuation or gain and 0 means silence. Negative levels can be used to invert the audio's phase. See XAudio2 Volume and Pitch Control for additional information on volume control.

See for information on standard channel ordering.

If any other voice is currently sending audio to this voice, the method fails.

DestroyVoice waits for the audio processing thread to be idle, so it can take a little while (typically no more than a couple of milliseconds). This is necessary to guarantee that the voice will no longer make any callbacks or read any audio data, so the application can safely free up these resources as soon as the call returns.

To avoid title thread interruptions from a blocking DestroyVoice call, the application can destroy voices on a separate non-critical thread, or the application can use voice pooling strategies to reuse voices rather than destroying them. Note that voices can only be reused with audio that has the same data format and the same number of channels the voice was created with. A voice can play audio data with different sample rates than that of the voice by calling with an appropriate ratio parameter.

It is invalid to call DestroyVoice from within a callback (that is, or ).

The DirectX SDK versions of XAUDIO2 included three member functions that are not present in the Windows 8 version: GetDeviceCount, GetDeviceDetails, and Initialize. These enumeration methods are no longer provided and standard Windows Audio APIs should be used for device enumeration instead.

For specific information on the statistics returned by GetPerformanceData, see the structure reference.

This method can be called multiple times, allowing different components or layers of the same application to manage their own engine callback implementations separately.

It is invalid to call RegisterForCallbacks from within a callback (that is, or ). If RegisterForCallbacks is called within a callback, it returns .

It is invalid to call UnregisterForCallbacks from within a callback (that is, or ).

Source voices read audio data from the client. They process the data and send it to the XAudio2 processing graph.

A source voice includes a variable-rate sample rate conversion, to convert data from the source format sample rate to the output rate required for the voice send list. If you use a null send list, the target sample rate will be the mastering voice's input sample rate. If you provide a single voice in pSendList, that voice's input sample rate is the target rate. If you provide multiple voices in the pSendList, all the source voice's output voices must be running at the same input sample rate.

You cannot create any source or submix voices until a mastering voice exists, and you cannot destory a mastering voice if any source or submix voices still exist.

Source voices are always processed before any submix or mastering voices. This means that you do not need a ProcessingStage parameter to control the processing order.

When first created, source voices are in the stopped state.

XAudio2 uses an internal memory pooler for voices with the same format. This means memory allocation for voices will occur less frequently as more voices are created and then destroyed. To minimize just-in-time allocations, a title can create the anticipated maximum number of voices needed up front, and then delete them as necessary. Voices will then be reused from the XAudio2 pool. The memory pool is tied to an XAudio2 engine instance. You can reclaim all the memory used by an instance of the XAudio2 engine by destroying the XAudio2 object and recreating it as necessary (forcing the memory pool to grow via preallocation would have to be reapplied as needed).

It is invalid to call CreateSourceVoice from within a callback (that is, or ). If you call CreateSourceVoice within a callback, it returns .

The that is passed in as the pEffectChain argument and any information contained within it are no longer needed after CreateSourceVoice successfully completes, and may be deleted immediately after CreateSourceVoice is called.

Submix voices receive the output of one or more source or submix voices. They process the output, and then send it to another submix voice or to a mastering voice.

A submix voice performs a sample rate conversion from the input sample rate to the input rate of its output voices in pSendList. If you specify multiple voice sends, they must all have the input same sample rate.

You cannot create any source or submix voices until a mastering voice exists, and you cannot destroy a mastering voice if any source or submix voices still exist.

When first created, submix voices are in the started state.

XAudio2 uses an internal memory pooler for voices with the same format. This means that memory allocation for voices will occur less frequently as more voices are created and then destroyed. To minimize just-in-time allocations, a title can create the anticipated maximum number of voices needed up front, and then delete them as necessary. Voices will then be reused from the XAudio2 pool. The memory pool is tied to an XAudio2 engine instance. You can reclaim all the memory used by an instance of the XAudio2 engine by destroying the XAudio2 object and recreating it as necessary (forcing the memory pool to grow via preallocation would have to be reapplied as needed).

It is invalid to call CreateSubmixVoice from within a callback (that is, or ). If you call CreateSubmixVoice within a callback, it returns .

The that is passed in as the pEffectChain argument and any information contained within it are no longer needed after CreateSubmixVoice successfully completes, and may be deleted immediately after CreateSubmixVoice is called.

Mastering voices receive the output of one or more source or submix voices. They process the data, and send it to the audio output device.

Typically, you should create a mastering voice with an input sample rate that will be used by the majority of the title's audio content. The mastering voice performs a sample rate conversion from this input sample rate to the actual device output rate.

You cannot create a source or submix voices until a mastering voice exists. You cannot destroy a mastering voice if any source or submix voices still exist.

Mastering voices are always processed after all source and submix voices. This means that you need not specify a ProcessingStage parameter to control the processing order.

XAudio2 only allows one mastering voice to exist at once. If you attempt to create more than one voice, is returned. If an additional mastering voice is needed, for example for an output device with a different audio category set, you will need to create an additional XAudio2 instance.

When first created, mastering voices are in the started state.

It is invalid to call CreateMasteringVoice from within a callback (that is, or ). If you call CreateMasteringVoice within a callback, it returns .

The that is passed in as the pEffectChain argument and any information contained within it are no longer needed after CreateMasteringVoice successfully completes, and may be deleted immediately after CreateMasteringVoice is called.

Note that the DirectX SDK XAUDIO2 version of CreateMasteringVoice took a DeviceIndex argument instead of a szDeviceId and a StreamCategory argument. This reflects the changes needed for the standard Windows device enumeration model.

After StartEngine is called, all started voices begin to consume audio. All enabled effects start running, and the resulting audio is sent to any connected output devices. When XAudio2 is first initialized, the engine is already in the started state.

It is invalid to call StartEngine from within a callback (that is, or ). If StartEngine is called within a callback, it returns .

When StopEngine is called, all output is stopped immediately. However, the audio graph is left untouched, preserving effect parameters, effect histories (for example, the data stored by a reverb effect in order to emit echoes of a previous sound), voice states, pending source buffers, cursor positions, and so forth. When the engine is restarted, the resulting audio output will be identical?apart from a period of silence?to the output that would have been produced if the engine had never been stopped.

It is invalid to call StopEngine from within a callback (that is, or ).

CommitChanges does nothing if no operations are tagged with the given identifier.

See the XAudio2 Operation Sets overview about working with CommitChanges and XAudio2 interface methods that may be deferred.

For specific information on the statistics returned by GetPerformanceData, see the structure reference.

SetDebugConfiguration sets the debug configuration for the given instance of XAudio2 engine. See Structure for supported debug options. By default, XAudio2 does not log debug output or break on errors.

When streaming an xWMA file a few packets at a time, should be specified on the last packet. Alternatively, the application may call after submitting the last packet.

In addition, when streaming an xWMA file a few packets at a time, the application should subtract pDecodedPacketCumulativeBytes[PacketCount-1] of the previous packet from all the entries of the currently submitted packet.

The members of correspond to values contained in the 'dpds' RIFF chunk of the xWMA file being played. PacketCount will correspond to the size in UINT32s of the chunk. pDecodedPacketCumulativeBytes will correspond to a UINT32 buffer containing the contents of the chunk. The contents of the buffer will need to be byte swapped when loading the buffer on Xbox 360.

Memory allocated to hold a or structure can be freed as soon as the call it is passed to returns. The data the structure points to (pAudioData and pDecodedPacketCumulativeBytes, respectively) can't be freed until the buffer completes (as signaled by the callback) or the voice is stopped and destroyed.

XAUDIO 2.8 in Windows 8.x does not support xWMA decoding. Use Windows Media Foundation APIs to perform the decoding from WMA to PCM instead. This functionality is available in the DirectX SDK versions of XAUDIO and in XAUDIO 2.9 in Windows?10.

Debugging messages can be completely turned off by initializing to all zeroes.

Setting with the following values is acoustically equivalent to the filter being fully bypassed.

 FilterParams;	
            FilterParams.Frequency = 1.0f;    	
            FilterParams.OneOverQ = 1.0f;	
            FilterParams.Type = LowPassFilter;	
            

The following formulas show the relationship between the members of and the per-voice filter.

Yl( n ) = F1 yb( n ) + yl( n - 1 )	
            Yb( n ) = F1 yh( n ) + yb( n - 1 )	
            Yh( n ) = x( n ) - yl( n ) - OneOverQ(yb( n - 1 )	
            Yn( n ) = Yl(n) + Yh(n) 

Where:

Yl = lowpass output	
            Yb = bandpass output	
            Yh = highpass output	
            Yn = notch output	
            F1 = .Frequency	
            OneOverQ = .OneOverQ

CPU cycles are recorded using . Use to convert these values.

Note the DirectX SDK versions of XAUDIO2 do not support the ActiveFlags member.

If pSends is not null all of its elements must be non-null. To send output to the default mastering voice call with the pSendList argument set to null.

Setting SendCount to 0 is useful for certain effects such as volume meters or file writers that don't generate any audio output to pass on to another voice.

If needed, a voice will perform a single sample rate conversion, from the voice's input sample rate to the input sample rate of the voice's output voices. Because only one sample rate conversion will be performed, all the voice's output voices must have the same input sample rate. If the input sample rates of the voice and its output voices are the same, no sample rate conversion is performed.

For all encoded formats, including constant bit rate (CBR) formats such as adaptive differential pulse code modulation (ADPCM), SamplesPlayed is expressed in terms of decoded samples. For pulse code modulation (PCM) formats, SamplesPlayed is expressed in terms of either input or output samples. There is a one-to-one mapping from input to output for PCM formats.

If a client needs to get the correlated positions of several voices?that is, to know exactly which sample of a particular voice is playing when a specified sample of another voice is playing?it must make the calls in an XAudio2 engine callback. Doing this ensures that none of the voices advance while the calls are made.

The DirectX SDK versions of XAUDIO2 supported a flag to select between the release and 'checked' version. This flag is not supported or defined in the Windows 8 version of XAUDIO2.

Note??No versions of the DirectX SDK contain the xaudio2.lib import library. DirectX SDK versions use COM to create a new XAudio2 object.

XAudio2CreateReverb creates an effect performing Princeton Digital Reverb. The XAPO effect library (XAPOFX) includes an alternate reverb effect. Use CreateFX to create this alternate effect.

The reverb APO supports has the following restrictions:

• Input audio data must be FLOAT32.
• Framerate must be within XAUDIO2FX_REVERB_MIN_FRAMERATE (20,000 Hz) and XAUDIO2FX_REVERB_MAX_FRAMERATE (48,000 Hz).
• The input and output channels must be one of the following combinations.
  • Mono input and mono output
  • Mono input and 5.1 output
  • Stereo input and stereo output
  • Stereo input and 5.1 output

For information about creating new effects for use with XAudio2, see the XAPO Overview.

#ifndef _XBOX	
            CoInitializeEx(null, COINIT_MULTITHREADED);	
            #endif	
            * pXAudio2 = null;	
             hr;	
            if ( FAILED(hr = ( &pXAudio2, 0,  ) ) ) return hr;	
            ...	
             * pReverbAPO;	
            XAudio2CreateReverb(&pReverbAPO);	
            

?

The xaudio2fx.h header defines the AudioReverb class as a cross-platform audio processing object (XAPO).

XAudio2CreateReverb returns this object as a reference to a reference to in the ppApo parameter. Although you can query the and interfaces from this , you typically never use these interfaces directly. Instead, you use them when you create a voice to add them as part of the effects chain.

The reverb uses the parameter structure that you access via the .

Note??XAudio2CreateReverb is an inline function in xaudio2fx.h that calls CreateAudioReverb:

For information on creating new effects for use with XAudio2, see the XAPO Overview.

#ifndef _XBOX	
            CoInitializeEx(null, COINIT_MULTITHREADED);	
            #endif	
            * pXAudio2 = null;	
             hr;	
            if ( FAILED(hr = ( &pXAudio2, 0,  ) ) ) return hr;	
            ...	
             * pVolumeMeterAPO;	
            XAudio2CreateVolumeMeter(&pVolumeMeterAPO);	
            

?

The xaudio2fx.h header defines the AudioVolumeMeter class as a cross-platform audio processing object (XAPO).

XAudio2CreateVolumeMeter returns this object as a reference to a reference to in the ppApo parameter. Although you can query the and interfaces from this , you typically never use these interfaces directly. Instead, you use them when you create a voice to add them as part of the effects chain.

The volume meter uses the parameter structure that you access via the method when the XAPO is bound to the audio graph.

Note??XAudio2CreateVolumeMeter is an inline function in xaudio2fx.h that calls CreateAudioVolumeMeter:

For a detailed explanation of sound cones see Sound Cones.

The following members must be initialized before passing this structure to the X3DAudioCalculate function:

• pMatrixCoefficients
• pDelayTimes
• SrcChannelCount
• DstChannelCount

The following members are returned by passing this structure to the X3DAudioCalculate function:

• pMatrixCoefficients
• pDelayTimes
• LPFDirectCoefficient
• LPFReverbCoefficient
• ReverbLevel
• DopplerFactor
• EmitterToListenerAngle
• EmitterToListenerDistance
• EmitterVelocityComponent
• ListenerVelocityComponent

only supports a cone in a single-point emitter. Multi-point emitters are a convenient and efficient way to manage a related group of sound sources. Many properties are shared among all channel points, such as Doppler?the same Doppler shift is applied to all channels in the emitter. Thus, the Doppler value need only be calculated once, not per-point as would be needed with multiple separate single-point emitters. Because only has one orientation vector, a multi-point emitter cone would be of limited usefulness, forcing all channels to behave as if they were facing the same direction. If multiple independent cones are needed, multiple single-point emitters should be used, each with its own orientation.

The parameter type is typed to DirectX::XMFLOAT3, to provide x , y , and z floating-point values.

X3DAudio uses a left-handed Cartesian coordinate system, with values on the x-axis increasing from left to right, on the y-axis from bottom to top, and on the z-axis from near to far. Azimuths are measured clockwise from a given reference direction. To use X3DAudio with right-handed coordinates, you must negate the .z element of OrientFront, OrientTop, Position, and Velocity.

For user-defined distance curves, the distance field of the first point must be 0.0f and the distance field of the last point must be 1.0f.

If an emitter moves beyond a distance of (CurveDistanceScaler ? 1.0f), the last point on the curve is used to compute the volume output level. The last point is determined by the following:

.pPoints[PointCount-1].DSPSetting)

X3DAudio uses a left-handed Cartesian coordinate system, with values on the x-axis increasing from left to right, on the y-axis from bottom to top, and on the z-axis from near to far. Azimuths are measured clockwise from a given reference direction. To use X3DAudio with right-handed coordinates, you must negate the .z element of OrientFront, OrientTop, Position, and Velocity.

The parameter type is typed to DirectX::XMFLOAT3, to provide x, y and z floating-point values.

A listener's front and top vectors must be orthonormal. To be considered orthonormal, a pair of vectors must have a magnitude of 1 +- 1x10-5 and a dot product of 0 +- 1x10-5.

You typically call once for each pair of emitting objects and listeners in the scene. After each call, to apply the 3D effects, the app manually applies the calculation results at pDSPSettings to the XAUDIO2 graph. For more info, see How to: Integrate X3DAudio with XAudio2.

Important?? The listener and emitter values must be valid. Floating-point specials (NaN, QNaN, +INF, -INF) can cause the entire audio output to go silent if introduced into a running audio graph.

X3DAUDIO_HANDLE is an opaque data structure. Because the operating system doesn't allocate any additional storage for the 3D audio instance handle, you don't need to free or close it.

You typically call once for each pair of emitting objects and listeners in the scene. After each call, to apply the 3D effects, the app manually applies the calculation results at pDSPSettings to the XAUDIO2 graph. For more info, see How to: Integrate X3DAudio with XAudio2.

Important?? The listener and emitter values must be valid. Floating-point specials (NaN, QNaN, +INF, -INF) can cause the entire audio output to go silent if introduced into a running audio graph.

X3DAUDIO_HANDLE is an opaque data structure. Because the operating system doesn't allocate any additional storage for the 3D audio instance handle, you don't need to free or close it.

This metadata can be used to implement optimizations that require knowledge of a stream buffer's contents. For example, XAPOs that always produce silent output from silent input can check the flag on the input stream buffer to determine if any signal processing is necessary. If silent, the XAPO can simply set the flag on the output stream buffer to silent and return, thus averting the work of processing silent data.

Likewise, XAPOs that receive valid input data, but generate silence (for any reason), may set the output stream buffer's flag accordingly, rather than writing silent samples to the buffer.

These flags represent what should be assumed is in the respective buffer. The flags may not reflect what is actually stored in memory. For example, the indicates that silent data should be assumed, however the respective memory may be uninitialized

Use of this structure is optional. The default MaxDelay is .

Echo only supports FLOAT32 audio formats.

Each band ranges from FrequencyCenterN - (BandwidthN / 2) to FrequencyCenterN + (BandwidthN / 2).

The and IsInputFormatSupported methods allow an XAPO to indicate which audio formats it is capable of processing. If a requested format is not supported, the XAPO should return the closest format that it does support. The closest format should be determined based on frame rate, bit depth, and channel count, in that order of importance. The behavior of IsInputFormatSupported is allowed to change, based on the internal state of the XAPO, but its behavior should remain constant between calls to the and methods.

The and IsOutputFormatSupported methods allow an XAPO to indicate which audio formats it is capable of processing. If a requested format is not supported, the XAPO should return the closest format that it does support. The closest format should be determined based on frame rate, bit depth, and channel count, in that order of importance. The behavior of IsOutputFormatSupported is allowed to change, based on the internal state of the XAPO, but its behavior should remain constant between calls to the and methods.

The contents of pData are defined by a given XAPO. Immutable parameters (constant for the lifetime of the XAPO) should be set in this method. Once initialized, an XAPO cannot be initialized again. An XAPO should be initialized before passing it to XAudio2 as part of an effect chain.

Constant and locked parameters such as the input and output formats remain unchanged. Variables set by remain unchanged.

For example, an effect with delay should zero out its delay line during this method, but should not reallocate anything as the XAPO remains locked with a constant input and output configuration.

XAudio2 only calls this method if the XAPO is locked.

This method is called from the realtime thread and should not block.

Once locked, the input and output configuration and any other locked parameters remain constant until UnLockForProcess is called. After an XAPO is locked, further calls to LockForProcess have no effect until the UnLockForProcess function is called.

An XAPO indicates what specific formats it supports through its implementation of the IsInputFormatSupported and IsOutputFormatSupported methods. An XAPO should assert the input and output configurations are supported and that any required effect-specific initialization is complete. The IsInputFormatSupported, IsOutputFormatSupported, and Initialize methods should be used as necessary before calling this method.

Because Process is a nonblocking method, all internal memory buffers required for Process should be allocated in LockForProcess.

Process is never called before LockForProcess returns successfully.

LockForProcess is called directly by XAudio2 and should not be called by the client code.

Unlocking an XAPO instance allows it to be reused with different input and output formats.

Implementations of this function should not block, as the function is called from the realtime audio processing thread.

All code that could cause a delay, such as format validation and memory allocation, should be put in the method, which is not called from the realtime audio processing thread.

For in-place processing, the pInputProcessParameters parameter will not necessarily be the same as pOutputProcessParameters. Rather, their pBuffer members will point to the same memory.

Multiple input and output buffers may be used with in-place XAPOs, though the input buffer count must equal the output buffer count. For in-place processing when multiple input and output buffers are used, the XAPO may assume the number of input buffers equals the number of output buffers.

In addition to writing to the output buffer, as appropriate, an XAPO is responsible for setting the output stream's buffer flags and valid frame count.

When IsEnabled is , the XAPO should not apply its normal processing to the given input/output buffers during. It should instead pass data from input to output with as little modification possible. Effects that perform format conversion should continue to do so. Effects must ensure transitions between normal and thru processing do not introduce discontinuities into the signal.

When writing a Process method, it is important to note XAudio2 audio data is interleaved, which means data from each channel is adjacent for a particular sample number. For example, if there was a 4-channel wave playing into an XAudio2 source voice, the audio data would be a sample of channel 0, a sample of channel 1, a sample of channel 2, a sample of channel 3, and then the next sample of channels 0, 1, 2, 3, and so on.

XAudio2 calls this method to determine what size input buffer an XAPO requires to generate the given number of output frames. This method only needs to be called once while an XAPO is locked. CalcInputFrames is only called by XAudio2 if the XAPO is locked.

This function should not block, because it may be called from the realtime audio processing thread.

XAudio2 calls this method to determine how large of an output buffer an XAPO will require for a certain number of input frames. CalcOutputFrames is only called by XAudio2 if the XAPO is locked.

This function should not block, because it may be called from the realtime audio processing thread.

The data in pParameters is completely effect-specific and determined by the implementation of the function. The data passed to SetParameters can be used to set the state of the XAPO and control the behavior of the function.

SetParameters can only be called on the real-time audio processing thread; no synchronization between SetParameters and the method is necessary. However, the method may be called from any thread as it adds in the required synchronization to deliver a copy (asynchronously) of the parameters to SetParameters on the real-time thread; no synchronization between and the method is necessary.

The data in pParameters is completely effect-specific and determined by the implementation of the function. The data returned in pParameters can be used to provide information about the current state of the XAPO.

Unlike SetParameters, XAudio2 does not call this method on the realtime audio processing thread. Thus, the XAPO must protect variables shared with or using appropriate synchronization. The CXAPOParametersBase class is an implementation of and its implementation of GetParameters efficiently handles this synchronization for the user.

XAudio2 calls this method from the method.

This method may block and should never be called from the realtime audio processing thread instead get the current parameters from CXAPOParametersBase::BeginProcess.

Although the format and maximum size values of a particular stream buffer are constant, as defined by the structure, the actual memory address of the stream buffer is permitted to change. For constant-bit-rate (CBR) XAPOs, ValidFrameCount is constant and is always equal to the corresponding .MaxFrameCount for this buffer.

The byte size of the respective stream buffer must be at least MaxFrameCount ? (pFormat->nBlockAlign) bytes.