Microsoft DirectX 8.0 (C++)

IDirectSoundBuffer8::SetFX

Enables effects on a buffer. The buffer must not be playing or locked.

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.

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

Parameters

dwEffectsCount
Value that specifies the 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 following values indicating the result of the attempt to create the corresponding effect in the pDSFXDesc array.
DSFXR_LOCHARDWARE
Effect is instantiated in hardware.
DSFXR_LOCSOFTWARE
Effect is instantiated in software.
DSFXR_UNALLOCATED
Effect has not yet been assigned to hardware nor 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
The 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
The effect is not registered on the system, and the method failed as a result.

This parameter can be NULL is no result values are wanted, and must be NULL if dwEffectsCount is 0

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 following error values:

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.

If the buffer is part of an audiopath, the audiopath must be inactive. See IDirectMusicAudioPath8::Activate.

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

Requirements

  Header: Declared in dsound.h.

See Also

DSBCAPS, IDirectSoundBuffer8::AcquireResources