IXAudio2Voice::SetEffectParameters method

Sets parameters for a given effect in the voice's effect chain.


HRESULT SetEffectParameters(
  [in]       UINT32 EffectIndex,
  [inconst void   *pParameters,
  [in]       UINT32 ParametersByteSize,
  [in]       UINT32 OperationSet = XAUDIO2_COMMIT_NOW


EffectIndex [in]

Zero-based index of an effect within the voice's effect chain.

pParameters [in]

Returns the current values of the effect-specific parameters.

ParametersByteSize [in]

Size of the pParameters array in bytes.

OperationSet [in]

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.

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 XAUDIO2_COMMIT_NOW. Otherwise, the parameters are applied to the effect later, during the first processing pass after the IXAudio2::CommitChanges function is called with the same OperationSet argument.

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

Note  IXAudio2Voice::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 IXAudio2Voice::SetEffectParameters call (or after the corresponding IXAudio2::CommitChanges call, if IXAudio2Voice::SetEffectParameters was called with a deferred operation ID).

Platform Requirements

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




See also

How to: Create an Effect Chain
XAPO Overview