IXAudio2Voice::SetEffectChain method (xaudio2.h)

Replaces the effect chain of the voice.

Syntax

\\HRESULT SetEffectChain(
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

Parameters

[in, optional] pEffectChain

Pointer to an XAUDIO2_EFFECT_CHAIN structure that describes the new effect chain to use. If NULL is passed, the current effect chain is removed.

Return value

Returns S_OK if successful; otherwise, an error code.

See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.

Remarks

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 pointers to the effect.

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

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

Platform Requirements

Requirements

See also

How to: Create an Effect Chain

IXAudio2Voice

XAPO Overview