Share via

IDirectSoundBuffer8::SetFX Method

  • Article

[The feature associated with this page, DirectSound, is a legacy feature. It has been superseded by WASAPI and Audio Graphs. Media Casting have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Media Casting instead of DirectSound, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The SetFX method enables effects on a buffer.

For this method to succeed, CoInitialize must have been called. Additionally, the buffer must not be playing or locked.

Syntax

HRESULT SetFX(
         DWORD dwEffectsCount,
         LPDSEFFECTDESC pDSFXDesc,
         LPDWORD pdwResultCodes 
)

Parameters

  • dwEffectsCount
    Number of elements in the pDSFXDesc and pdwResultCodes arrays. If this value is 0, pDSFXDesc and pdwResultCodes must both be NULL. Set to 0 to remove all effects from the buffer.

  • pDSFXDesc
    Address of an array of DSEFFECTDESC structures, of size dwEffectsCount, that specifies the effects wanted on the buffer. Must be NULL if dwEffectsCount is 0.

  • pdwResultCodes
    Address of an array of DWORD elements, of size dwEffectsCount. Each element receives one of the values shown in the following table, indicating the result of the attempt to create the corresponding effect in the pDSFXDesc array.

    Note

    This parameter must be NULL if dwEffectsCount is 0, or can be NULL if results are not wanted.

    Value Description
    DSFXR_LOCHARDWARE Effect is instantiated in hardware.
    DSFXR_LOCSOFTWARE Effect is instantiated in software.
    DSFXR_UNALLOCATED Effect has not yet been assigned to hardware or software. This value is returned if the buffer was created with the DSBCAPS_LOCDEFER flag in DSBUFFERDESC.
    DSFXR_FAILED No effect was created because resources weren't available.
    DSFXR_PRESENT Effect is available but was not created because one of the other effects requested could not be created. If any of the effects requested cannot be created, none of them are, and the call fails.
    DSFXR_UNKNOWN Effect is not registered on the system, and the method failed as a result.

Return Value

If the method succeeds, the return value is DS_OK or DS_INCOMPLETE. If the method fails, the return value may be one of the error values shown in the following table.

Return code
CO_E_NOTINITIALIZED
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

In addition, the method can return an error value from DMO methods, including IMediaObject::SetInputType and IMediaObject::SetOutputType. See the DirectShow documentation for possible error values.

Remarks

If the method fails, the value for each effect in pdwResultCodes is either DSFXF_PRESENT or DSFXR_UNKNOWN. Check these values to determine which effects caused the failure.

For the method to succeed, the buffer must have been created with the DSBCAPS_CTRLFX flag and must not be playing or locked.

If the method returns DSERR_NOINTERFACE or another COM error, check the result code array for DSFXR_PRESENT or DSFXR_UNKNOWN to ascertain which effect caused the error. If the method returns DSERR_INVALIDPARAM, check the result codes for DSFXR_FAILED to see which effects failed to acquire resources.

An effect must be set on a buffer before the effect interface can be obtained. To obtain the effect interface, use GetObjectInPath.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound3d.dll.

See Also

IDirectSoundBuffer8