XAPO instances are passed to XAudio2 as
For additional information on using XAPOs with XAudio2 see How to: Create an Effect Chain and How to: Use an XAPO in XAudio2.
-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
Memory allocated to hold a
See XAudio2 Callbacks for restrictions on callback implementation.
-There are many preset values defined for the
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.
-| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| PositionRight is ignored in mono-in/mono-out mode. |
| Note |
|---|
| PositionMatrixRight is ignored in mono-in/mono-out mode. |
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | +1 | +2 | +3 | +4 |
Note that a LowEQGain value of 8 results in the decay time of low frequencies being equal to the decay time at 1 kHz. Permitted range is from 0 to 12 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (Hz) | 50 | 100 | 150 | 200 | 250 | 300 | 350 | 400 | 450 | 500 |
Permitted range is from 0 to 9 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 |
Permitted range is from 0 to 8 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (kHz) | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | 5.5 | 6 | 6.5 | 7 | 7.5 | 8 |
Permitted range is from 0 to 14 (no units).
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
This structure is used with the XAudio2
pPeakLevels and pRMSLevels are not returned by
ChannelCount must be set by the application to match the number of channels in the voice the effect is applied to.
-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 -
The X3DAudio function
| Note |
|---|
Returns
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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
| Note |
|---|
| If pEffectChain is non- |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call SetEffectChain from within a callback. If you call SetEffectChain within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Returns
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
EnableEffect takes effect immediately when you call it from an XAudio2 callback with an OperationSet of
Returns
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
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
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
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
SetEffectParameters takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Note |
|---|
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
GetEffectParameters always returns the effect's actual current parameters. However, these may not match the parameters set by the most recent call to IXAudio2Voice::SetEffectParameters: the actual parameters are only changed the next time the audio engine runs after the
Returns
SetFilterParameters will fail if the voice was not created with the
This method is usable only on source and submix voices and has no effect on mastering voices.
| Note |
|---|
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Returns
SetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on a mastering voice's sends.
| Note |
|---|
GetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on mastering voices? sends.
| Note |
|---|
Returns
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 -
| Note |
|---|
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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 -
| Note |
|---|
| |
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 -224 to 224, 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.
| Note |
|---|
| GetChannelVolumes always returns the volume levels most recently set by |
| Note |
|---|
| If the voice sends to a single target voice then specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
| Output | Left Input [Array Index] | Right Input [Array Index] |
|---|---|---|
| Left | 1.0 [0] | 0.0 [1] |
| Right | 0.0 [2] | 1.0 [3] |
| Front Center | 0.0 [4] | 0.0 [5] |
| LFE | 0.0 [6] | 0.0 [7] |
| Rear Left | 0.8 [8] | 0.0 [9] |
| Rear Right | 0.0 [10] | 0.8 [11] |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
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 -
The X3DAudio function
| Note |
|---|
| Note |
|---|
| If the voice sends to a single target voice then specifying |
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 -224 to 224, 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
| Note |
|---|
| GetOutputMatrix always returns the levels most recently set by |
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
It is illegal to call DestroyVoice from within a callback. If DestroyVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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
| Value | Description |
|---|---|
| Continue emitting effect output after the voice is stopped.? |
Returns
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
By default, any pending output from voice effects?for example, reverb tails?is not played. Instead, the voice is immediately rendered silent. The
A voice stopped with the
Stop is always asynchronous, even if called within a callback.
| Note |
|---|
| XAudio2 never calls any voice callbacks for a voice if the voice is stopped (even if it was stopped with |
Returns
The voice processes and plays back the buffers in its queue in the order that they were submitted.
The
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
If all or part of the buffer should be played in a continuous loop, the LoopBegin, LoopLength and LoopCount fields in
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.
| Xbox 360 |
|---|
For certain audio formats, there may be additional restrictions on the valid endpoints of any play or loop regions; e.g. for XMA buffers, the regions can only begin or end at 128-sample boundaries in the decoded audio. |
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
Up to
SubmitSourceBuffer takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Xbox 360 |
|---|
This method can be called from an Xbox system thread (most other XAudio2 methods cannot). However, a maximum of two source buffers can be submitted from a system thread at a time. |
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
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
Because calling Discontinuity is equivalent to applying the
| Note |
|---|
| XAudio2 may consume its entire buffer queue and emit a warning before the Discontinuity call takes effect, so Discontinuity is not guaranteed to suppress the warnings. |
Returns
If the cursor for the voice is not in a loop region, ExitLoop does nothing.
-Returns the voice's current cursor position data.
-If a client needs to obtain the correlated positions of several voices (i.e. to know exactly which sample of a given voice is playing when a given sample of another voice is playing) it must make GetState calls in an XAudio2 engine callback, to ensure that none of the voices advance while the calls are being made. See the XAudio2 Callbacks overview for information about using XAudio2 callbacks.
-Returns
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.
| Note |
|---|
GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
For information on frequency ratios, see
Returns
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
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.
-GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
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
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.
-See the XAudio2 Callbacks topic for restrictions on callback implementation.
-Returns
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 illegal to call RegisterForCallbacks from within a callback. If RegisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-It is illegal to call UnregisterForCallbacks from within a callback. If UnregisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-XAudio2 supports PCM and ADPCM voice types. XAudio2 supports the following PCM formats.
8-bit (unsigned) integer PCM
16-bit integer PCM (optimal format for XAudio2)
20-bit integer PCM (either in 24 or 32 bit containers)
24-bit integer PCM (either in 24 or 32 bit containers)
32-bit integer PCM
32-bit float PCM (preferred format after 16-bit integer)
The number of channels in a source voice must be less than or equal to
| Note |
|---|
| Data formats such as ADPCM that require more information than provided by |
| Value | Description |
|---|---|
| No pitch control is available on the voice.? | |
| No sample rate conversion is available on the voice. The voice's outputs must have the same sample rate. Note The | |
| The filter effect should be available on this voice.? |
The maximum value for this argument is defined as
If MaxFrequencyRatio is less than 1.0, the voice will use that ratio immediately after being created (rather than the default of 1.0).
| Xbox 360 |
|---|
| For XMA voices, there is one more restriction on the MaxFrequencyRatio argument and the voice's sample rate. The product of these two numbers cannot exceed XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO for one-channel voices or XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL for voices with any other number of channels. If the value specified for MaxFrequencyRatio is too high for the specified format, the call to CreateSourceVoice fails and produces a debug message. |
| Note |
|---|
| You can use the lowest possible MaxFrequencyRatio value to reduce XAudio2's memory usage. |
Returns
See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.
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
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 illegal to call CreateSourceVoice from within a callback. If you call CreateSourceVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
InputChannels must be less than or equal to
| Value | Description |
|---|---|
| The filter effect should be available on this voice.? |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call CreateSubmixVoice from within a callback. If you call CreateSubmixVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Creates and configures a mastering voice.
-InputChannels must be less than or equal to
InputChannels can be set to
| Windows |
|---|
| Attempts to detect the system speaker configuration setup. |
| Xbox 360 |
|---|
| Defaults to 5.1 surround. |
InputSampleRate must be between
InputSampleRate can be set to
| Windows |
|---|
| Windows XP defaults to 44100. Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver). |
| Xbox 360 |
|---|
| Defaults to 48000. |
Returns
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, a mastering voice should be created 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. Alternatively, IXAudio2::GetDeviceDetails can be used to find the native audio rate, and that can be used throughout the majority of the title's audio graph.
No source or submix voices can be created until a mastering voice exists, and a mastering voice cannot be destroyed 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.
Several mastering voices can exist at once, but only one of them can be started. Only one device can be used by XAudio2 at a time.
When first created, mastering voices are in the started state.
It is illegal to call CreateMasteringVoice from within a callback. If CreateMasteringVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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 illegal to call StartEngine from within a callback. If StartEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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 illegal to call StopEngine from within a callback. If StopEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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
| Note |
|---|
| This function has no effect in this version of XAudio2. |
This function only has an effect in debug versions of the XAudio2 library. SetDebugConfiguration sets the debug configuration for all instances of XAudio2 in the current process, not just the one interface on which the call was made.
The default debug level produces only ERROR and WARNING messages. See
For specific information on the statistics returned by GetPerformanceData, see the
When streaming an xWMA file a few packets at a time,
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
Memory allocated to hold a
Debugging messages can be completely turned off by initializing
Setting
FilterParams; FilterParams.Frequency = 1.0f; FilterParams.OneOverQ = 1.0f; FilterParams.Type = LowPassFilter;
The following formulas show the relationship between the members of
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 -
If XAUDIO2_HELPER_FUNCTIONS is defined, XAudio2.h will include the XAudio2RadiansToCutoffFrequency and XAudio2CutoffFrequencyToRadians helper functions for converting between hertz and radian frequencies.
CPU cycles are recorded using . Use to convert these values.
-| Note |
|---|
| This only counts cycles on the CPU on which XAudio2 is running. |
| Windows |
|---|
| The delay reported is a variable value equal to the rough distance between the last sample submitted to the driver by XAudio2 and the sample currently playing. The following factors can affect the delay: playing multichannel audio on a hardware-accelerated device; the type of audio device (WavePci, WaveCyclic, or WaveRT); and, to a lesser extent, audio hardware implementation. |
| Xbox 360 |
|---|
| The delay reported is a fixed value, which is normally 1,024 samples (21.333 ms at 48 kHz). If XOverrideSpeakerConfig has been called using the XAUDIOSPEAKERCONFIG_LOW_LATENCY flag, the delay reported is 512 samples (10.667 ms at 48 kHz). |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| Number of source voices decoding XMA data. |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| A voice can use more than one XMA stream. |
If pSends is not
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
| Value | Description |
|---|---|
| Enables matrix coefficient table calculation.? | |
| Enables delay time array calculation (stereo only).? | |
| Enables low pass filter (LPF) direct-path coefficient calculation.? | |
| Enables LPF reverb-path coefficient calculation.? | |
| Enables reverb send level calculation.? | |
| Enables Doppler shift factor calculation.? | |
| Enables emitter-to-listener interior angle calculation.? | |
| Fills the center channel with silence. This flag allows you to keep a 6-channel matrix so you do not have to remap the channels, but the center channel will be silent. This flag is only valid if you also set | |
| Applies an equal mix of all source channels to a low frequency effect (LFE) destination channel. It only applies to matrix calculations with a source that does not have an LFE channel and a destination that does have an LFE channel. This flag is only valid if you also set |
For a detailed explanation of sound cones see Sound Cones.
-The following members must be initialized before passing this structure to the
pMatrixCoefficients
pDelayTimes
SrcChannelCount
DstChannelCount
The following members are returned by passing this structure to the
pMatrixCoefficients
pDelayTimes
LPFDirectCoefficient
LPFReverbCoefficient
ReverbLevel
DopplerFactor
EmitterToListenerAngle
EmitterToListenerDistance
EmitterVelocityComponent
ListenerVelocityComponent
| Note |
|---|
| For pMatrixCoefficients and pDelayTimes, |
The parameter type
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.
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:
Inner Radius and Inner Radius Angle.pPoints[PointCount-1].DSPSetting)
InnerRadius is used to specify an area of smooth transition around the origin point as a sound travels directly through, above or below the listener. Elevation is accounted for by specifying an InnerRadiusAngle, whereby a sound whose elevation increases or decreases, will eventually start to bleed the sound into more than just two speakers.
When Inner Radius and Inner Radius Angle are not used, emitters are audible in the two closest speakers to their current position/orientation (or, if directly on a line with one speaker's defined angle, solely from that one speaker).
Inner Radius and Inner Radius Angle have no effect on emitters positioned outside of the cones they describe. Inside of the cone, they will gradually cause the sound to bleed into the opposite speakers, until the sound will be equally heard in all speakers when the emitter is at the same position as (or directly above or below) the listener.
-When distance is greater than CurveDistanceScaler ? 1.0f, the amplification factor is (CurveDistanceScaler ? 1.0f)/distance. At a distance of CurveDistanceScaler ? 2.0f, the sound will be at half volume or -6 dB, at a distance of CurveDistanceScaler ? 4.0f, the sound will be at one quarter volume or -12 dB, and so on.
pVolumeCurve and pLFECurve are independent of each other. pVolumeCurve does not affect LFE channel volume.
pVolumeCurve and pLFECurve are independent of each other. pLFECurve does not affect non LFE channel volume.
The parameter type
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.
-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
The created XAPO will have a reference count of 1. Client code should call IUnknown::Release after passing the XAPO to XAudio2 to allow XAudio2 to dispose of the XAPO when it is no longer needed. Use
Echo only supports FLOAT32 audio formats.
-Each band ranges from FrequencyCenterN - (BandwidthN / 2) to FrequencyCenterN + (BandwidthN / 2).
-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.
-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.
-Returns
Returns
The
Returns
The
Returns
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.
| Note |
|---|
| XAudio2 does not call this method, it should be called by the client before passing the XAPO to XAudio2. |
Constant and locked parameters such as the input and output formats remain unchanged. Variables set by
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.
-Returns
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. -
-| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
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
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
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.
-Returns the number of input frames required.
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.
-Returns the number of output frames that will be produced.
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.
- XAPO instances are passed to XAudio2 as
XAPO instances are passed to XAudio2 as
The data in pParameters is completely effect-specific and determined by the implementation of the
SetParameters can only be called on the real-time audio processing thread; no synchronization between SetParameters and the
The data in pParameters is completely effect-specific and determined by the implementation of the
Unlike SetParameters, XAudio2 does not call this method on the realtime audio processing thread. Thus, the XAPO must protect variables shared with
XAudio2 calls this method from the
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 XAPO_LOCKFORPROCESS_PARAMETERS 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 XAPO_LOCKFORPROCESS_PARAMETERS.MaxFrameCount for this buffer.
| Note |
|---|
| Only constant-bit-rate XAPOs are currently supported. |
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Targets features supported by Direct3D 11.1 including Direct3D device sharing. Device sharing enables Direct3D 10 and Direct3D 11 APIs to use one underlying rendering device. For more information about device sharing, see
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
The IAudioClient::Initialize and IAudioClient::IsFormatSupported methods use the constants defined in the
In shared mode, the client can share the audio endpoint device with clients that run in other user-mode processes. The audio engine always supports formats for client streams that match the engine's mix format. In addition, the audio engine might support another format if the Windows audio service can insert system effects into the client stream to convert the client format to the mix format.
In exclusive mode, the Windows audio service attempts to establish a connection in which the client has exclusive access to the audio endpoint device. In this mode, the audio engine inserts no system effects into the local stream to aid in the creation of the connection point. Either the audio device can handle the specified format directly or the method fails.
For more information about shared-mode and exclusive-mode streams, see User-Mode Audio Components.
-The audio stream will run in shared mode. For more information, see Remarks.
The audio stream will run in exclusive mode. For more information, see Remarks.
The AudioSessionState enumeration defines constants that indicate the current state of an audio session.
-When a client opens a session by assigning the first stream to the session (by calling the IAudioClient::Initialize method), the initial session state is inactive. The session state changes from inactive to active when a stream in the session begins running (because the client has called the IAudioClient::Start method). The session changes from active to inactive when the client stops the last running stream in the session (by calling the IAudioClient::Stop method). The session state changes to expired when the client destroys the last stream in the session by releasing all references to the stream object.
The system volume-control program, Sndvol, displays volume controls for both active and inactive sessions. Sndvol stops displaying the volume control for a session when the session state changes to expired. For more information about Sndvol, see Audio Sessions.
The IAudioSessionControl::GetState and IAudioSessionEvents::OnStateChanged methods use the constants defined in the AudioSessionState enumeration.
For more information about session states, see Audio Sessions.
-The audio session is inactive. (It contains at least one stream, but none of the streams in the session is currently running.)
The audio session is active. (At least one of the streams in the session is running.)
The audio session has expired. (It contains no streams.)
[This documentation is preliminary and is subject to change.]
Specifies the category of an audio stream.
-Media, such as music or streaming audio.
Real-time communications, such as VOIP or chat.
Voice narration, such as a screen reader or ebook reader.
Alert sounds.
Sound effects.
Game sound effects.
Background audio for games.
Other audio stream.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing XAPO instances are passed to XAudio2 as
For additional information on using XAPOs with XAudio2 see How to: Create an Effect Chain and How to: Use an XAPO in XAudio2.
-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
Memory allocated to hold a
See XAudio2 Callbacks for restrictions on callback implementation.
-There are many preset values defined for the
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.
-| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| PositionRight is ignored in mono-in/mono-out mode. |
| Note |
|---|
| PositionMatrixRight is ignored in mono-in/mono-out mode. |
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | +1 | +2 | +3 | +4 |
Note that a LowEQGain value of 8 results in the decay time of low frequencies being equal to the decay time at 1 kHz. Permitted range is from 0 to 12 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (Hz) | 50 | 100 | 150 | 200 | 250 | 300 | 350 | 400 | 450 | 500 |
Permitted range is from 0 to 9 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 |
Permitted range is from 0 to 8 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (kHz) | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | 5.5 | 6 | 6.5 | 7 | 7.5 | 8 |
Permitted range is from 0 to 14 (no units).
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
This structure is used with the XAudio2
pPeakLevels and pRMSLevels are not returned by
ChannelCount must be set by the application to match the number of channels in the voice the effect is applied to.
-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 -
The X3DAudio function
| Note |
|---|
Returns
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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
| Note |
|---|
| If pEffectChain is non- |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call SetEffectChain from within a callback. If you call SetEffectChain within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Returns
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
EnableEffect takes effect immediately when you call it from an XAudio2 callback with an OperationSet of
Returns
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
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
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
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
SetEffectParameters takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Note |
|---|
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
GetEffectParameters always returns the effect's actual current parameters. However, these may not match the parameters set by the most recent call to IXAudio2Voice::SetEffectParameters: the actual parameters are only changed the next time the audio engine runs after the
Returns
SetFilterParameters will fail if the voice was not created with the
This method is usable only on source and submix voices and has no effect on mastering voices.
| Note |
|---|
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Returns
SetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on a mastering voice's sends.
| Note |
|---|
GetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on mastering voices? sends.
| Note |
|---|
Returns
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 -
| Note |
|---|
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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 -
| Note |
|---|
| |
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 -224 to 224, 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.
| Note |
|---|
| GetChannelVolumes always returns the volume levels most recently set by |
| Note |
|---|
| If the voice sends to a single target voice then specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
| Output | Left Input [Array Index] | Right Input [Array Index] |
|---|---|---|
| Left | 1.0 [0] | 0.0 [1] |
| Right | 0.0 [2] | 1.0 [3] |
| Front Center | 0.0 [4] | 0.0 [5] |
| LFE | 0.0 [6] | 0.0 [7] |
| Rear Left | 0.8 [8] | 0.0 [9] |
| Rear Right | 0.0 [10] | 0.8 [11] |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
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 -
The X3DAudio function
| Note |
|---|
| Note |
|---|
| If the voice sends to a single target voice then specifying |
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 -224 to 224, 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
| Note |
|---|
| GetOutputMatrix always returns the levels most recently set by |
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
It is illegal to call DestroyVoice from within a callback. If DestroyVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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
| Value | Description |
|---|---|
| Continue emitting effect output after the voice is stopped.? |
Returns
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
By default, any pending output from voice effects?for example, reverb tails?is not played. Instead, the voice is immediately rendered silent. The
A voice stopped with the
Stop is always asynchronous, even if called within a callback.
| Note |
|---|
| XAudio2 never calls any voice callbacks for a voice if the voice is stopped (even if it was stopped with |
Returns
The voice processes and plays back the buffers in its queue in the order that they were submitted.
The
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
If all or part of the buffer should be played in a continuous loop, the LoopBegin, LoopLength and LoopCount fields in
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.
| Xbox 360 |
|---|
For certain audio formats, there may be additional restrictions on the valid endpoints of any play or loop regions; e.g. for XMA buffers, the regions can only begin or end at 128-sample boundaries in the decoded audio. |
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
Up to
SubmitSourceBuffer takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Xbox 360 |
|---|
This method can be called from an Xbox system thread (most other XAudio2 methods cannot). However, a maximum of two source buffers can be submitted from a system thread at a time. |
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
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
Because calling Discontinuity is equivalent to applying the
| Note |
|---|
| XAudio2 may consume its entire buffer queue and emit a warning before the Discontinuity call takes effect, so Discontinuity is not guaranteed to suppress the warnings. |
Returns
If the cursor for the voice is not in a loop region, ExitLoop does nothing.
-Returns the voice's current cursor position data.
-If a client needs to obtain the correlated positions of several voices (i.e. to know exactly which sample of a given voice is playing when a given sample of another voice is playing) it must make GetState calls in an XAudio2 engine callback, to ensure that none of the voices advance while the calls are being made. See the XAudio2 Callbacks overview for information about using XAudio2 callbacks.
-Returns
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.
| Note |
|---|
GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
For information on frequency ratios, see
Returns
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
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.
-GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
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
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.
-See the XAudio2 Callbacks topic for restrictions on callback implementation.
-Returns
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 illegal to call RegisterForCallbacks from within a callback. If RegisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-It is illegal to call UnregisterForCallbacks from within a callback. If UnregisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-XAudio2 supports PCM and ADPCM voice types. XAudio2 supports the following PCM formats.
8-bit (unsigned) integer PCM
16-bit integer PCM (optimal format for XAudio2)
20-bit integer PCM (either in 24 or 32 bit containers)
24-bit integer PCM (either in 24 or 32 bit containers)
32-bit integer PCM
32-bit float PCM (preferred format after 16-bit integer)
The number of channels in a source voice must be less than or equal to
| Note |
|---|
| Data formats such as ADPCM that require more information than provided by |
| Value | Description |
|---|---|
| No pitch control is available on the voice.? | |
| No sample rate conversion is available on the voice. The voice's outputs must have the same sample rate. Note The | |
| The filter effect should be available on this voice.? |
The maximum value for this argument is defined as
If MaxFrequencyRatio is less than 1.0, the voice will use that ratio immediately after being created (rather than the default of 1.0).
| Xbox 360 |
|---|
| For XMA voices, there is one more restriction on the MaxFrequencyRatio argument and the voice's sample rate. The product of these two numbers cannot exceed XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO for one-channel voices or XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL for voices with any other number of channels. If the value specified for MaxFrequencyRatio is too high for the specified format, the call to CreateSourceVoice fails and produces a debug message. |
| Note |
|---|
| You can use the lowest possible MaxFrequencyRatio value to reduce XAudio2's memory usage. |
Returns
See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.
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
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 illegal to call CreateSourceVoice from within a callback. If you call CreateSourceVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
InputChannels must be less than or equal to
| Value | Description |
|---|---|
| The filter effect should be available on this voice.? |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call CreateSubmixVoice from within a callback. If you call CreateSubmixVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Creates and configures a mastering voice.
-InputChannels must be less than or equal to
InputChannels can be set to
| Windows |
|---|
| Attempts to detect the system speaker configuration setup. |
| Xbox 360 |
|---|
| Defaults to 5.1 surround. |
InputSampleRate must be between
InputSampleRate can be set to
| Windows |
|---|
| Windows XP defaults to 44100. Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver). |
| Xbox 360 |
|---|
| Defaults to 48000. |
Returns
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, a mastering voice should be created 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. Alternatively, IXAudio2::GetDeviceDetails can be used to find the native audio rate, and that can be used throughout the majority of the title's audio graph.
No source or submix voices can be created until a mastering voice exists, and a mastering voice cannot be destroyed 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.
Several mastering voices can exist at once, but only one of them can be started. Only one device can be used by XAudio2 at a time.
When first created, mastering voices are in the started state.
It is illegal to call CreateMasteringVoice from within a callback. If CreateMasteringVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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 illegal to call StartEngine from within a callback. If StartEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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 illegal to call StopEngine from within a callback. If StopEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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
| Note |
|---|
| This function has no effect in this version of XAudio2. |
This function only has an effect in debug versions of the XAudio2 library. SetDebugConfiguration sets the debug configuration for all instances of XAudio2 in the current process, not just the one interface on which the call was made.
The default debug level produces only ERROR and WARNING messages. See
For specific information on the statistics returned by GetPerformanceData, see the
When streaming an xWMA file a few packets at a time,
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
Memory allocated to hold a
Debugging messages can be completely turned off by initializing
Setting
FilterParams; FilterParams.Frequency = 1.0f; FilterParams.OneOverQ = 1.0f; FilterParams.Type = LowPassFilter;
The following formulas show the relationship between the members of
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 -
If XAUDIO2_HELPER_FUNCTIONS is defined, XAudio2.h will include the XAudio2RadiansToCutoffFrequency and XAudio2CutoffFrequencyToRadians helper functions for converting between hertz and radian frequencies.
CPU cycles are recorded using . Use to convert these values.
-| Note |
|---|
| This only counts cycles on the CPU on which XAudio2 is running. |
| Windows |
|---|
| The delay reported is a variable value equal to the rough distance between the last sample submitted to the driver by XAudio2 and the sample currently playing. The following factors can affect the delay: playing multichannel audio on a hardware-accelerated device; the type of audio device (WavePci, WaveCyclic, or WaveRT); and, to a lesser extent, audio hardware implementation. |
| Xbox 360 |
|---|
| The delay reported is a fixed value, which is normally 1,024 samples (21.333 ms at 48 kHz). If XOverrideSpeakerConfig has been called using the XAUDIOSPEAKERCONFIG_LOW_LATENCY flag, the delay reported is 512 samples (10.667 ms at 48 kHz). |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| Number of source voices decoding XMA data. |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| A voice can use more than one XMA stream. |
If pSends is not
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
| Value | Description |
|---|---|
| Enables matrix coefficient table calculation.? | |
| Enables delay time array calculation (stereo only).? | |
| Enables low pass filter (LPF) direct-path coefficient calculation.? | |
| Enables LPF reverb-path coefficient calculation.? | |
| Enables reverb send level calculation.? | |
| Enables Doppler shift factor calculation.? | |
| Enables emitter-to-listener interior angle calculation.? | |
| Fills the center channel with silence. This flag allows you to keep a 6-channel matrix so you do not have to remap the channels, but the center channel will be silent. This flag is only valid if you also set | |
| Applies an equal mix of all source channels to a low frequency effect (LFE) destination channel. It only applies to matrix calculations with a source that does not have an LFE channel and a destination that does have an LFE channel. This flag is only valid if you also set |
For a detailed explanation of sound cones see Sound Cones.
-The following members must be initialized before passing this structure to the
pMatrixCoefficients
pDelayTimes
SrcChannelCount
DstChannelCount
The following members are returned by passing this structure to the
pMatrixCoefficients
pDelayTimes
LPFDirectCoefficient
LPFReverbCoefficient
ReverbLevel
DopplerFactor
EmitterToListenerAngle
EmitterToListenerDistance
EmitterVelocityComponent
ListenerVelocityComponent
| Note |
|---|
| For pMatrixCoefficients and pDelayTimes, |
The parameter type
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.
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:
Inner Radius and Inner Radius Angle.pPoints[PointCount-1].DSPSetting)
InnerRadius is used to specify an area of smooth transition around the origin point as a sound travels directly through, above or below the listener. Elevation is accounted for by specifying an InnerRadiusAngle, whereby a sound whose elevation increases or decreases, will eventually start to bleed the sound into more than just two speakers.
When Inner Radius and Inner Radius Angle are not used, emitters are audible in the two closest speakers to their current position/orientation (or, if directly on a line with one speaker's defined angle, solely from that one speaker).
Inner Radius and Inner Radius Angle have no effect on emitters positioned outside of the cones they describe. Inside of the cone, they will gradually cause the sound to bleed into the opposite speakers, until the sound will be equally heard in all speakers when the emitter is at the same position as (or directly above or below) the listener.
-When distance is greater than CurveDistanceScaler ? 1.0f, the amplification factor is (CurveDistanceScaler ? 1.0f)/distance. At a distance of CurveDistanceScaler ? 2.0f, the sound will be at half volume or -6 dB, at a distance of CurveDistanceScaler ? 4.0f, the sound will be at one quarter volume or -12 dB, and so on.
pVolumeCurve and pLFECurve are independent of each other. pVolumeCurve does not affect LFE channel volume.
pVolumeCurve and pLFECurve are independent of each other. pLFECurve does not affect non LFE channel volume.
The parameter type
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.
-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
The created XAPO will have a reference count of 1. Client code should call IUnknown::Release after passing the XAPO to XAudio2 to allow XAudio2 to dispose of the XAPO when it is no longer needed. Use
Echo only supports FLOAT32 audio formats.
-Each band ranges from FrequencyCenterN - (BandwidthN / 2) to FrequencyCenterN + (BandwidthN / 2).
-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.
-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.
-Returns
Returns
The
Returns
The
Returns
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.
| Note |
|---|
| XAudio2 does not call this method, it should be called by the client before passing the XAPO to XAudio2. |
Constant and locked parameters such as the input and output formats remain unchanged. Variables set by
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.
-Returns
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. -
-| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
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
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
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.
-Returns the number of input frames required.
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.
-Returns the number of output frames that will be produced.
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.
- XAPO instances are passed to XAudio2 as
XAPO instances are passed to XAudio2 as
The data in pParameters is completely effect-specific and determined by the implementation of the
SetParameters can only be called on the real-time audio processing thread; no synchronization between SetParameters and the
The data in pParameters is completely effect-specific and determined by the implementation of the
Unlike SetParameters, XAudio2 does not call this method on the realtime audio processing thread. Thus, the XAPO must protect variables shared with
XAudio2 calls this method from the
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 XAPO_LOCKFORPROCESS_PARAMETERS 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 XAPO_LOCKFORPROCESS_PARAMETERS.MaxFrameCount for this buffer.
| Note |
|---|
| Only constant-bit-rate XAPOs are currently supported. |
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Targets features supported by Direct3D 11.1 including Direct3D device sharing. Device sharing enables Direct3D 10 and Direct3D 11 APIs to use one underlying rendering device. For more information about device sharing, see
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
The IAudioClient::Initialize and IAudioClient::IsFormatSupported methods use the constants defined in the
In shared mode, the client can share the audio endpoint device with clients that run in other user-mode processes. The audio engine always supports formats for client streams that match the engine's mix format. In addition, the audio engine might support another format if the Windows audio service can insert system effects into the client stream to convert the client format to the mix format.
In exclusive mode, the Windows audio service attempts to establish a connection in which the client has exclusive access to the audio endpoint device. In this mode, the audio engine inserts no system effects into the local stream to aid in the creation of the connection point. Either the audio device can handle the specified format directly or the method fails.
For more information about shared-mode and exclusive-mode streams, see User-Mode Audio Components.
-The audio stream will run in shared mode. For more information, see Remarks.
The audio stream will run in exclusive mode. For more information, see Remarks.
The AudioSessionState enumeration defines constants that indicate the current state of an audio session.
-When a client opens a session by assigning the first stream to the session (by calling the IAudioClient::Initialize method), the initial session state is inactive. The session state changes from inactive to active when a stream in the session begins running (because the client has called the IAudioClient::Start method). The session changes from active to inactive when the client stops the last running stream in the session (by calling the IAudioClient::Stop method). The session state changes to expired when the client destroys the last stream in the session by releasing all references to the stream object.
The system volume-control program, Sndvol, displays volume controls for both active and inactive sessions. Sndvol stops displaying the volume control for a session when the session state changes to expired. For more information about Sndvol, see Audio Sessions.
The IAudioSessionControl::GetState and IAudioSessionEvents::OnStateChanged methods use the constants defined in the AudioSessionState enumeration.
For more information about session states, see Audio Sessions.
-The audio session is inactive. (It contains at least one stream, but none of the streams in the session is currently running.)
The audio session is active. (At least one of the streams in the session is running.)
The audio session has expired. (It contains no streams.)
[This documentation is preliminary and is subject to change.]
Specifies the category of an audio stream.
-Media, such as music or streaming audio.
Real-time communications, such as VOIP or chat.
Voice narration, such as a screen reader or ebook reader.
Alert sounds.
Sound effects.
Game sound effects.
Background audio for games.
Other audio stream.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing XAPO instances are passed to XAudio2 as
For additional information on using XAPOs with XAudio2 see How to: Create an Effect Chain and How to: Use an XAPO in XAudio2.
-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
Memory allocated to hold a
See XAudio2 Callbacks for restrictions on callback implementation.
-There are many preset values defined for the
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.
-| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
| Note |
|---|
| PositionRight is ignored in mono-in/mono-out mode. |
| Note |
|---|
| PositionMatrixRight is ignored in mono-in/mono-out mode. |
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | +1 | +2 | +3 | +4 |
Note that a LowEQGain value of 8 results in the decay time of low frequencies being equal to the decay time at 1 kHz. Permitted range is from 0 to 12 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (Hz) | 50 | 100 | 150 | 200 | 250 | 300 | 350 | 400 | 450 | 500 |
Permitted range is from 0 to 9 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|---|---|---|---|---|---|---|---|---|---|
| Gain (dB) | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 |
Permitted range is from 0 to 8 (no units).
| Value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Frequency (kHz) | 1 | 1.5 | 2 | 2.5 | 3 | 3.5 | 4 | 4.5 | 5 | 5.5 | 6 | 6.5 | 7 | 7.5 | 8 |
Permitted range is from 0 to 14 (no units).
| Note |
|---|
| All parameters related to sampling rate or time are relative to a 48kHz sampling rate and must be scaled for use with other sampling rates. See remarks section below for additional information. |
This structure is used with the XAudio2
pPeakLevels and pRMSLevels are not returned by
ChannelCount must be set by the application to match the number of channels in the voice the effect is applied to.
-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 -
The X3DAudio function
| Note |
|---|
Returns
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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
| Note |
|---|
| If pEffectChain is non- |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call SetEffectChain from within a callback. If you call SetEffectChain within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Returns
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
EnableEffect takes effect immediately when you call it from an XAudio2 callback with an OperationSet of
Returns
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
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
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
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
SetEffectParameters takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Note |
|---|
Returns
Fails with E_NOTIMPL if the effect does not support a generic parameter control interface.
GetEffectParameters always returns the effect's actual current parameters. However, these may not match the parameters set by the most recent call to IXAudio2Voice::SetEffectParameters: the actual parameters are only changed the next time the audio engine runs after the
Returns
SetFilterParameters will fail if the voice was not created with the
This method is usable only on source and submix voices and has no effect on mastering voices.
| Note |
|---|
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Returns
SetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on a mastering voice's sends.
| Note |
|---|
GetOutputFilterParameters will fail if the send was not created with the XAUDIO2_SEND_USEFILTER flag. This method is usable only on sends belonging to source and submix voices and has no effect on mastering voices? sends.
| Note |
|---|
Returns
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 -
| Note |
|---|
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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 -
| Note |
|---|
| |
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 -224 to 224, 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.
| Note |
|---|
| GetChannelVolumes always returns the volume levels most recently set by |
| Note |
|---|
| If the voice sends to a single target voice then specifying |
For example, when rendering two-channel stereo input into 5.1 output that is weighted toward the front channels?but is absent from the center and low-frequency channels?the matrix might have the values shown in the following table.
| Output | Left Input [Array Index] | Right Input [Array Index] |
|---|---|---|
| Left | 1.0 [0] | 0.0 [1] |
| Right | 0.0 [2] | 1.0 [3] |
| Front Center | 0.0 [4] | 0.0 [5] |
| LFE | 0.0 [6] | 0.0 [7] |
| Rear Left | 0.8 [8] | 0.0 [9] |
| Rear Right | 0.0 [10] | 0.8 [11] |
Note that the left and right input are fully mapped to the output left and right channels; 80 percent of the left and right input is mapped to the rear left and right channels.
See Remarks for more information on volume levels.
Returns
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 -
The X3DAudio function
| Note |
|---|
| Note |
|---|
| If the voice sends to a single target voice then specifying |
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 -224 to 224, 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
| Note |
|---|
| GetOutputMatrix always returns the levels most recently set by |
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
It is illegal to call DestroyVoice from within a callback. If DestroyVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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
It is illegal to call SetOutputVoices from within a callback. If SetOutputVoices is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
| Note |
|---|
| Calling SetOutputVoices invalidates any send matrices previously set with |
GetFilterParameters will fail if the voice was not created with the
GetFilterParameters always returns this voice's actual current filter parameters. However, these may not match the parameters set by the most recent
| Note |
|---|
| GetFilterParameters is usable only on source and submix voices and has no effect on mastering voices. |
Volume levels are expressed as floating-point amplitude multipliers between -224 to 224, 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.
| Note |
|---|
| GetVolume always returns the volume most recently set by |
Returns
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
| Value | Description |
|---|---|
| Continue emitting effect output after the voice is stopped.? |
Returns
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
By default, any pending output from voice effects?for example, reverb tails?is not played. Instead, the voice is immediately rendered silent. The
A voice stopped with the
Stop is always asynchronous, even if called within a callback.
| Note |
|---|
| XAudio2 never calls any voice callbacks for a voice if the voice is stopped (even if it was stopped with |
Returns
The voice processes and plays back the buffers in its queue in the order that they were submitted.
The
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
If all or part of the buffer should be played in a continuous loop, the LoopBegin, LoopLength and LoopCount fields in
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.
| Xbox 360 |
|---|
For certain audio formats, there may be additional restrictions on the valid endpoints of any play or loop regions; e.g. for XMA buffers, the regions can only begin or end at 128-sample boundaries in the decoded audio. |
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
Up to
SubmitSourceBuffer takes effect immediately when called from an XAudio2 callback with an OperationSet of
| Xbox 360 |
|---|
This method can be called from an Xbox system thread (most other XAudio2 methods cannot). However, a maximum of two source buffers can be submitted from a system thread at a time. |
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
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
Because calling Discontinuity is equivalent to applying the
| Note |
|---|
| XAudio2 may consume its entire buffer queue and emit a warning before the Discontinuity call takes effect, so Discontinuity is not guaranteed to suppress the warnings. |
Returns
If the cursor for the voice is not in a loop region, ExitLoop does nothing.
-Returns the voice's current cursor position data.
-If a client needs to obtain the correlated positions of several voices (i.e. to know exactly which sample of a given voice is playing when a given sample of another voice is playing) it must make GetState calls in an XAudio2 engine callback, to ensure that none of the voices advance while the calls are being made. See the XAudio2 Callbacks overview for information about using XAudio2 callbacks.
-Returns
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.
| Note |
|---|
GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
For information on frequency ratios, see
Returns
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
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.
-GetFrequencyRatio always returns the voice's actual current frequency ratio. However, this may not match the ratio set by the most recent
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
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.
-See the XAudio2 Callbacks topic for restrictions on callback implementation.
-Returns
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 illegal to call RegisterForCallbacks from within a callback. If RegisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-It is illegal to call UnregisterForCallbacks from within a callback. If UnregisterForCallbacks is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-XAudio2 supports PCM and ADPCM voice types. XAudio2 supports the following PCM formats.
8-bit (unsigned) integer PCM
16-bit integer PCM (optimal format for XAudio2)
20-bit integer PCM (either in 24 or 32 bit containers)
24-bit integer PCM (either in 24 or 32 bit containers)
32-bit integer PCM
32-bit float PCM (preferred format after 16-bit integer)
The number of channels in a source voice must be less than or equal to
| Note |
|---|
| Data formats such as ADPCM that require more information than provided by |
| Value | Description |
|---|---|
| No pitch control is available on the voice.? | |
| No sample rate conversion is available on the voice. The voice's outputs must have the same sample rate. Note The | |
| The filter effect should be available on this voice.? |
The maximum value for this argument is defined as
If MaxFrequencyRatio is less than 1.0, the voice will use that ratio immediately after being created (rather than the default of 1.0).
| Xbox 360 |
|---|
| For XMA voices, there is one more restriction on the MaxFrequencyRatio argument and the voice's sample rate. The product of these two numbers cannot exceed XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO for one-channel voices or XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL for voices with any other number of channels. If the value specified for MaxFrequencyRatio is too high for the specified format, the call to CreateSourceVoice fails and produces a debug message. |
| Note |
|---|
| You can use the lowest possible MaxFrequencyRatio value to reduce XAudio2's memory usage. |
Returns
See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.
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
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 illegal to call CreateSourceVoice from within a callback. If you call CreateSourceVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
InputChannels must be less than or equal to
| Value | Description |
|---|---|
| The filter effect should be available on this voice.? |
Returns
See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.
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 illegal to call CreateSubmixVoice from within a callback. If you call CreateSubmixVoice within a callback, XAUDIO2_E_INVALID_CALL is returned.
The
Creates and configures a mastering voice.
-InputChannels must be less than or equal to
InputChannels can be set to
| Windows |
|---|
| Attempts to detect the system speaker configuration setup. |
| Xbox 360 |
|---|
| Defaults to 5.1 surround. |
InputSampleRate must be between
InputSampleRate can be set to
| Windows |
|---|
| Windows XP defaults to 44100. Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver). |
| Xbox 360 |
|---|
| Defaults to 48000. |
Returns
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, a mastering voice should be created 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. Alternatively, IXAudio2::GetDeviceDetails can be used to find the native audio rate, and that can be used throughout the majority of the title's audio graph.
No source or submix voices can be created until a mastering voice exists, and a mastering voice cannot be destroyed 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.
Several mastering voices can exist at once, but only one of them can be started. Only one device can be used by XAudio2 at a time.
When first created, mastering voices are in the started state.
It is illegal to call CreateMasteringVoice from within a callback. If CreateMasteringVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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 illegal to call StartEngine from within a callback. If StartEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-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 illegal to call StopEngine from within a callback. If StopEngine is called within a callback XAUDIO2_E_INVALID_CALL will be returned.
-Returns
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
| Note |
|---|
| This function has no effect in this version of XAudio2. |
This function only has an effect in debug versions of the XAudio2 library. SetDebugConfiguration sets the debug configuration for all instances of XAudio2 in the current process, not just the one interface on which the call was made.
The default debug level produces only ERROR and WARNING messages. See
For specific information on the statistics returned by GetPerformanceData, see the
When streaming an xWMA file a few packets at a time,
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
Memory allocated to hold a
Debugging messages can be completely turned off by initializing
Setting
FilterParams; FilterParams.Frequency = 1.0f; FilterParams.OneOverQ = 1.0f; FilterParams.Type = LowPassFilter;
The following formulas show the relationship between the members of
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 -
If XAUDIO2_HELPER_FUNCTIONS is defined, XAudio2.h will include the XAudio2RadiansToCutoffFrequency and XAudio2CutoffFrequencyToRadians helper functions for converting between hertz and radian frequencies.
CPU cycles are recorded using . Use to convert these values.
-| Note |
|---|
| This only counts cycles on the CPU on which XAudio2 is running. |
| Windows |
|---|
| The delay reported is a variable value equal to the rough distance between the last sample submitted to the driver by XAudio2 and the sample currently playing. The following factors can affect the delay: playing multichannel audio on a hardware-accelerated device; the type of audio device (WavePci, WaveCyclic, or WaveRT); and, to a lesser extent, audio hardware implementation. |
| Xbox 360 |
|---|
| The delay reported is a fixed value, which is normally 1,024 samples (21.333 ms at 48 kHz). If XOverrideSpeakerConfig has been called using the XAUDIOSPEAKERCONFIG_LOW_LATENCY flag, the delay reported is 512 samples (10.667 ms at 48 kHz). |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| Number of source voices decoding XMA data. |
| Windows |
|---|
| Unsupported. |
| Xbox 360 |
|---|
| A voice can use more than one XMA stream. |
If pSends is not
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
| Value | Description |
|---|---|
| Enables matrix coefficient table calculation.? | |
| Enables delay time array calculation (stereo only).? | |
| Enables low pass filter (LPF) direct-path coefficient calculation.? | |
| Enables LPF reverb-path coefficient calculation.? | |
| Enables reverb send level calculation.? | |
| Enables Doppler shift factor calculation.? | |
| Enables emitter-to-listener interior angle calculation.? | |
| Fills the center channel with silence. This flag allows you to keep a 6-channel matrix so you do not have to remap the channels, but the center channel will be silent. This flag is only valid if you also set | |
| Applies an equal mix of all source channels to a low frequency effect (LFE) destination channel. It only applies to matrix calculations with a source that does not have an LFE channel and a destination that does have an LFE channel. This flag is only valid if you also set |
For a detailed explanation of sound cones see Sound Cones.
-The following members must be initialized before passing this structure to the
pMatrixCoefficients
pDelayTimes
SrcChannelCount
DstChannelCount
The following members are returned by passing this structure to the
pMatrixCoefficients
pDelayTimes
LPFDirectCoefficient
LPFReverbCoefficient
ReverbLevel
DopplerFactor
EmitterToListenerAngle
EmitterToListenerDistance
EmitterVelocityComponent
ListenerVelocityComponent
| Note |
|---|
| For pMatrixCoefficients and pDelayTimes, |
The parameter type
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.
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:
Inner Radius and Inner Radius Angle.pPoints[PointCount-1].DSPSetting)
InnerRadius is used to specify an area of smooth transition around the origin point as a sound travels directly through, above or below the listener. Elevation is accounted for by specifying an InnerRadiusAngle, whereby a sound whose elevation increases or decreases, will eventually start to bleed the sound into more than just two speakers.
When Inner Radius and Inner Radius Angle are not used, emitters are audible in the two closest speakers to their current position/orientation (or, if directly on a line with one speaker's defined angle, solely from that one speaker).
Inner Radius and Inner Radius Angle have no effect on emitters positioned outside of the cones they describe. Inside of the cone, they will gradually cause the sound to bleed into the opposite speakers, until the sound will be equally heard in all speakers when the emitter is at the same position as (or directly above or below) the listener.
-When distance is greater than CurveDistanceScaler ? 1.0f, the amplification factor is (CurveDistanceScaler ? 1.0f)/distance. At a distance of CurveDistanceScaler ? 2.0f, the sound will be at half volume or -6 dB, at a distance of CurveDistanceScaler ? 4.0f, the sound will be at one quarter volume or -12 dB, and so on.
pVolumeCurve and pLFECurve are independent of each other. pVolumeCurve does not affect LFE channel volume.
pVolumeCurve and pLFECurve are independent of each other. pLFECurve does not affect non LFE channel volume.
The parameter type
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.
-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
The created XAPO will have a reference count of 1. Client code should call IUnknown::Release after passing the XAPO to XAudio2 to allow XAudio2 to dispose of the XAPO when it is no longer needed. Use
Echo only supports FLOAT32 audio formats.
-Each band ranges from FrequencyCenterN - (BandwidthN / 2) to FrequencyCenterN + (BandwidthN / 2).
-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.
-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.
-Returns
Returns
The
Returns
The
Returns
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.
| Note |
|---|
| XAudio2 does not call this method, it should be called by the client before passing the XAPO to XAudio2. |
Constant and locked parameters such as the input and output formats remain unchanged. Variables set by
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.
-Returns
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. -
-| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
| Note |
|---|
| XAudio2 currently supports only one input stream and one output stream. |
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
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
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.
-Returns the number of input frames required.
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.
-Returns the number of output frames that will be produced.
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.
- XAPO instances are passed to XAudio2 as
XAPO instances are passed to XAudio2 as
The data in pParameters is completely effect-specific and determined by the implementation of the
SetParameters can only be called on the real-time audio processing thread; no synchronization between SetParameters and the
The data in pParameters is completely effect-specific and determined by the implementation of the
Unlike SetParameters, XAudio2 does not call this method on the realtime audio processing thread. Thus, the XAPO must protect variables shared with
XAudio2 calls this method from the
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 XAPO_LOCKFORPROCESS_PARAMETERS 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 XAPO_LOCKFORPROCESS_PARAMETERS.MaxFrameCount for this buffer.
| Note |
|---|
| Only constant-bit-rate XAPOs are currently supported. |
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing s = det([o_2 - o_1, d_2, d_1 x d_2]) / ||d_1 x d_2||^2
- t = det([o_2 - o_1, d_1, d_1 x d_2]) / ||d_1 x d_2||^2
- Where o_1 is the position of the first ray, o_2 is the position of the second ray,
- d_1 is the normalized direction of the first ray, d_2 is the normalized direction
- of the second ray, det denotes the determinant of a matrix, x denotes the cross
- product, [ ] denotes a matrix, and || || denotes the length or magnitude of a vector.
- start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing Driver type options.
-The driver type is required when calling
The driver type is unknown.
A hardware driver, which implements Direct3D features in hardware. This is the primary driver that you should use in your Direct3D applications because it provides the best performance. A hardware driver uses hardware acceleration (on supported hardware) but can also use software for parts of the pipeline that are not supported in hardware. This driver type is often referred to as a hardware abstraction layer or HAL.
A reference driver, which is a software implementation that supports every Direct3D feature. A reference driver is designed for accuracy rather than speed and as a result is slow but accurate. The rasterizer portion of the driver does make use of special CPU instructions whenever it can, but it is not intended for retail applications; use it only for feature testing, demonstration of functionality, debugging, or verifying bugs in other drivers. This driver is installed by the DirectX SDK. This driver may be referred to as a REF driver, a reference driver or a reference rasterizer.
A
A software driver, which is a driver implemented completely in software. The software implementation is not intended for a high-performance application due to its very slow performance.
A WARP driver, which is a high-performance software rasterizer. The rasterizer supports feature levels 9_1 through level 10.1 with a high performance software implementation. For information about limitations creating a WARP device on certain feature levels, see Limitations Creating WARP and Reference Devices. For more information about using a WARP driver, see Windows Advanced Rasterization Platform (WARP) In-Depth Guide.
Describes the set of features targeted by a Direct3D device.
-For an overview of the capabilities of each feature level, see Overview For Each Feature Level.
For information about limitations creating nonhardware-type devices on certain feature levels, see Limitations Creating WARP and Reference Devices.
-Targets features supported by feature level 9.1 including shader model 2.
Targets features supported by feature level 9.2 including shader model 2.
Targets features supported by feature level 9.3 including shader model 2.0b.
Targets features supported by Direct3D 10.0 including shader model 4.
Targets features supported by Direct3D 10.1 including shader model 4.
Targets features supported by Direct3D 11.0 including shader model 5.
Targets features supported by Direct3D 11.1 including Direct3D device sharing. Device sharing enables Direct3D 10 and Direct3D 11 APIs to use one underlying rendering device. For more information about device sharing, see
Values that indicate how the pipeline interprets vertex data that is bound to the input-assembler stage. These primitive topology values determine how the vertex data is rendered on screen.
-Use the
The following diagram shows the various primitive types for a geometry shader object.
-Values that identify the type of resource to be viewed as a shader resource.
-A
The type is unknown.
The resource is a buffer.
The resource is a 1D texture.
The resource is an array of 1D textures.
The resource is a 2D texture.
The resource is an array of 2D textures.
The resource is a multisampling 2D texture.
The resource is an array of multisampling 2D textures.
The resource is a 3D texture.
The resource is a cube texture.
The resource is an array of cube textures.
The resource is an extended buffer.
This interface is used to return arbitrary length data.
-An
The ID3DBlob interface is type defined in the D3DCommon.h header file as a
Blobs can be used as a data buffer, storing vertex, adjacency, and material information during mesh optimization and loading operations. Also, these objects are used to return object code and error messages in APIs that compile vertex, geometry and pixel shaders.
-Get a reference to the data.
-Returns a reference.
Get the size.
-The size of the data, in bytes.
Get a reference to the data.
-Get the size.
-Defines a shader macro.
-You can use shader macros in your shaders. The
The following shader or effect creation functions take an array of shader macros as an input parameter:
The macro name.
The macro definition.
The
The IAudioClient::Initialize and IAudioClient::IsFormatSupported methods use the constants defined in the
In shared mode, the client can share the audio endpoint device with clients that run in other user-mode processes. The audio engine always supports formats for client streams that match the engine's mix format. In addition, the audio engine might support another format if the Windows audio service can insert system effects into the client stream to convert the client format to the mix format.
In exclusive mode, the Windows audio service attempts to establish a connection in which the client has exclusive access to the audio endpoint device. In this mode, the audio engine inserts no system effects into the local stream to aid in the creation of the connection point. Either the audio device can handle the specified format directly or the method fails.
For more information about shared-mode and exclusive-mode streams, see User-Mode Audio Components.
-The audio stream will run in shared mode. For more information, see Remarks.
The audio stream will run in exclusive mode. For more information, see Remarks.
The AudioSessionState enumeration defines constants that indicate the current state of an audio session.
-When a client opens a session by assigning the first stream to the session (by calling the IAudioClient::Initialize method), the initial session state is inactive. The session state changes from inactive to active when a stream in the session begins running (because the client has called the IAudioClient::Start method). The session changes from active to inactive when the client stops the last running stream in the session (by calling the IAudioClient::Stop method). The session state changes to expired when the client destroys the last stream in the session by releasing all references to the stream object.
The system volume-control program, Sndvol, displays volume controls for both active and inactive sessions. Sndvol stops displaying the volume control for a session when the session state changes to expired. For more information about Sndvol, see Audio Sessions.
The IAudioSessionControl::GetState and IAudioSessionEvents::OnStateChanged methods use the constants defined in the AudioSessionState enumeration.
For more information about session states, see Audio Sessions.
-The audio session is inactive. (It contains at least one stream, but none of the streams in the session is currently running.)
The audio session is active. (At least one of the streams in the session is running.)
The audio session has expired. (It contains no streams.)
[This documentation is preliminary and is subject to change.]
Specifies the category of an audio stream.
-Media, such as music or streaming audio.
Real-time communications, such as VOIP or chat.
Voice narration, such as a screen reader or ebook reader.
Alert sounds.
Sound effects.
Game sound effects.
Background audio for games.
Other audio stream.
The
-
The
-
The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The
-
The
-
The Read method reads a specified number of bytes from the stream object into memory, starting at the current seek reference.
-A reference to the buffer which the stream data is read into.
The number of bytes of data to read from the stream object.
A reference to a ULONG variable that receives the actual number of bytes read from the stream object.
Note??The number of bytes read may be zero.
This method reads bytes from this stream object into memory. The stream object must be opened in STGM_READ mode. This method adjusts the seek reference by the actual number of bytes read.
The number of bytes actually read is also returned in the pcbRead parameter.
Notes to CallersThe actual number of bytes read can be less than the number of bytes requested if an error occurs or if the end of the stream is reached during the read operation. The number of bytes returned should always be compared to the number of bytes requested. If the number of bytes returned is less than the number of bytes requested, it usually means the Read method attempted to read past the end of the stream.
The application should handle both a returned error and
The Write method writes a specified number of bytes into the stream object starting at the current seek reference.
-A reference to the buffer that contains the data that is to be written to the stream. A valid reference must be provided for this parameter even when cb is zero.
The number of bytes of data to attempt to write into the stream. This value can be zero.
A reference to a ULONG variable where this method writes the actual number of bytes written to the stream object. The caller can set this reference to
If the seek reference is currently past the end of the stream and the byte count is nonzero, this method increases the size of the stream to the seek reference and writes the specified bytes starting at the seek reference. The fill bytes written to the stream are not initialized to any particular value. This is the same as the end-of-file behavior in the MS-DOS FAT file system.
With a zero byte count and a seek reference past the end of the stream, this method does not create the fill bytes to increase the stream to the seek reference. In this case, you must call the
-
The pcbWritten parameter can have a value even if an error occurs.
In the COM-provided implementation, stream objects are not sparse. Any fill bytes are eventually allocated on the disk and assigned to the stream.
- The
-
The
-
The methods in this interface present your object's data as a contiguous sequence of bytes that you can read or write. There are also methods for committing and reverting changes on streams that are open in transacted mode and methods for restricting access to a range of bytes in the stream.
Streams can remain open for long periods of time without consuming file-system resources. The IUnknown::Release method is similar to a close function on a file. Once released, the stream object is no longer valid and cannot be used.
Clients of asynchronous monikers can choose between a data-pull or data-push model for driving an asynchronous
- IMoniker::BindToStorage operation and for receiving asynchronous notifications. See
- URL Monikers for more information. The following table compares the behavior of asynchronous
-
The Seek method changes the seek reference to a new location. The new location is relative to either the beginning of the stream, the end of the stream, or the current seek reference.
-The displacement to be added to the location indicated by the dwOrigin parameter. If dwOrigin is STREAM_SEEK_SET, this is interpreted as an unsigned value rather than a signed value.
The origin for the displacement specified in dlibMove. The origin can be the beginning of the file (STREAM_SEEK_SET), the current seek reference (STREAM_SEEK_CUR), or the end of the file (STREAM_SEEK_END). For more information about values, see the STREAM_SEEK enumeration.
A reference to the location where this method writes the value of the new seek reference from the beginning of the stream.
You can set this reference to
You can also use this method to obtain the current value of the seek reference by calling this method with the dwOrigin parameter set to STREAM_SEEK_CUR and the dlibMove parameter set to 0 so that the seek reference is not changed. The current seek reference is returned in the plibNewPosition parameter.
-The SetSize method changes the size of the stream object.
-Specifies the new size of the stream as a number of bytes.
This method can return one of the following values.
The size of the stream object was successfully changed.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The stream size is not changed because there is no space left on the storage device.
The value of the libNewSize parameter is not valid. Since streams cannot be greater than 232 bytes in the COM-provided implementation, the high DWORD data type of libNewSize must be 0. If it is nonzero, this parameter is not valid.
The object has been invalidated by a revert operation above it in the transaction tree.
If the libNewSize parameter is smaller than the current stream, the stream is truncated to the indicated size.
The seek reference is not affected by the change in stream size.
Calling
The CopyTo method copies a specified number of bytes from the current seek reference in the stream to the current seek reference in another stream.
-A reference to the destination stream. The stream pointed to by pstm can be a new stream or a clone of the source stream.
The number of bytes to copy from the source stream.
A reference to the location where this method writes the actual number of bytes written to the destination. You can set this reference to
A reference to the location where this method writes the actual number of bytes read from the source. You can set this reference to
The CopyTo method copies the specified bytes from one stream to another. It can also be used to copy a stream to itself. The seek reference in each stream instance is adjusted for the number of bytes read or written. This method is equivalent to reading cb bytes into memory using
-
The destination stream can be a clone of the source stream created by calling the
-
If
If
To copy the remainder of the source from the current seek reference, specify the maximum large integer value for the cb parameter. If the seek reference is the beginning of the stream, this operation copies the entire stream.
-The Commit method ensures that any changes made to a stream object open in transacted mode are reflected in the parent storage. If the stream object is open in direct mode,
Controls how the changes for the stream object are committed. See the
This method can return one of the following values.
Changes to the stream object were successfully committed to the parent level.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The commit operation failed due to lack of space on the storage device.
The object has been invalidated by a revert operation above it in the transaction tree.
The Commit method ensures that changes to a stream object opened in transacted mode are reflected in the parent storage. Changes that have been made to the stream since it was opened or last committed are reflected to the parent storage object. If the parent is opened in transacted mode, the parent may revert at a later time, rolling back the changes to this stream object. The compound file implementation does not support the opening of streams in transacted mode, so this method has very little effect other than to flush memory buffers. For more information, see
-
If the stream is open in direct mode, this method ensures that any memory buffers have been flushed out to the underlying storage object. This is much like a flush in traditional file systems.
The
The Revert method discards all changes that have been made to a transacted stream since the last
-
This method can return one of the following values.
The stream was successfully reverted to its previous version.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information see IFillLockBytes and Asynchronous Storage.
The Revert method discards changes made to a transacted stream since the last commit operation.
-The LockRegion method restricts access to a specified range of bytes in the stream. Supporting this functionality is optional since some file systems do not provide it.
-Integer that specifies the byte offset for the beginning of the range.
Integer that specifies the length of the range, in bytes, to be restricted.
Specifies the restrictions being requested on accessing the range.
This method can return one of the following values.
The specified range of bytes was locked.
Asynchronous Storage only: Part or all of the stream's data is currently unavailable. For more information, see IFillLockBytes and Asynchronous Storage.
Locking is not supported at all or the specific type of lock requested is not supported.
Requested lock is supported, but cannot be granted because of an existing lock.
The object has been invalidated by a revert operation above it in the transaction tree.
The byte range of the stream can be extended. Locking an extended range for the stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.
Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the
-
Any region locked with
Since the type of locking supported is optional and can vary in different implementations of
-
The LockRegion method has no effect in the compound file implementation, because the implementation does not support range locking.
Notes to ImplementersSupport for this method is optional for implementations of stream objects since it may not be supported by the underlying file system. The type of locking supported is also optional. The STG_E_INVALIDFUNCTION error is returned if the requested type of locking is not supported.
- The Stat method retrieves the
-
The Clone method creates a new stream object with its own seek reference that references the same bytes as the original stream.
-When successful, reference to the location of an
The Clone method creates a new stream object for accessing the same bytes but using a separate seek reference. The new stream object sees the same data as the source-stream object. Changes written to one object are immediately visible in the other. Range locking is shared between the stream objects.
The initial setting of the seek reference in the cloned stream instance is the same as the current setting of the seek reference in the original stream at the time of the clone operation.
- The
-
start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing start + (end - start) * amount
- Passing