IDirectSoundBuffer8::SetFX

The SetFX method enables effects on a buffer.

For this method to succeed, CoInitialize must have been called. This is done automatically in applications that create DirectSound by using IDirectMusicPerformance8::InitAudio. However, applications that create DirectSound by using DirectSoundCreate8 must also call CoInitialize.

The buffer must not be playing or locked.

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 Values

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.

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.

If the buffer is part of a DirectMusic audiopath, the audiopath must be inactive.

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.

Import Library: Use Dsound3d.dll.

See Also

IDirectSoundBuffer8