IXAudio2Voice::EnableEffect method (xaudio2.h)

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

Syntax

\\HRESULT EnableEffect(
  [in] UINT32 EffectIndex,
  [in] UINT32 OperationSet
);

Parameters

[in] EffectIndex

Zero-based index of an effect in the effect chain of the voice.

[in] OperationSet

Identifies this call as part of a deferred batch. See the XAudio2 Operation Sets overview for more information.

Return value

Returns S_OK if successful; otherwise, an error code. See XAudio2 Error Codes for descriptions of error codes.

Remarks

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 XAUDIO2_EFFECT_DESCRIPTOR structure's OutputChannels field to specify the number of channels it wants each effect to produce. Each effect in an effect chain must produce a number of channels that the next effect can consume. Any calls to IXAudio2Voice::EnableEffect or IXAudio2Voice::DisableEffect that would make the effect chain stop fulfilling these requirements will fail.

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

Platform Requirements

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)

Requirements

Requirement Value
Target Platform Windows
Header xaudio2.h

See also

IXAudio2Voice

XAPO Overview