| Microsoft DirectX 8.1 (C++) |
The SetFX method 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.
Syntax
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.
| 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 neither the hardware or the 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:
| 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
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