| Microsoft DirectX 8.1 (C++) |
The AcquireResources method allocates resources for a buffer that was created with the DSBCAPS_LOCDEFER flag in the DSBUFFERDESC structure.
Syntax
HRESULT AcquireResources(
DWORD dwFlags,
DWORD dwEffectsCount,
LPDWORD pdwResultCodes
);
Parameters
dwFlags
Flags specifying how resources are to be allocated for a buffer created with the DSBCAPS_LOCDEFER flag. For a list of values, see the voice management and voice allocation flags for IDirectSoundBuffer8::Play.
dwEffectsCount
Value that specifies the number of elements in the pdwResultFlags array, or 0 if pdwResultCodes is NULL.
pdwResultCodes
Address of an array of DWORD variables that receives information about the effects associated with the buffer. This array must contain one element for each effect that was assigned to the buffer by IDirectSoundBuffer8::SetFX. For each effect, one of the following values is returned.
| Value | Description |
| DSFXR_LOCHARDWARE | Effect is instantiated in hardware. |
| DSFXR_LOCSOFTWARE | Effect is instantiated in software. |
| DSFXR_FAILED | No effect was created because resources weren't available. |
| DSFXR_PRESENT | The effect is available but was not created because the method failed for some other reason. |
| DSFXR_UNKNOWN | No effect was created because the effect isn't registered on the system. |
This parameter can be NULL if result codes are not wanted.
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 |
| DSERR_CONTROLUNAVAIL |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
Remarks
Normally, buffers created with DSBCAPS_LOCDEFER are not allocated resources until IDirectSoundBuffer8::Play is called. IDirectSoundBuffer8::AcquireResources can be used to allocate resources for deferred buffers. By doing so, the application can retrieve information about effects processing and set effect parameters before the buffer is played.
If the method fails, check the values in pdwResultCodes to determine which effects caused the failure.
A buffer with acquired resources that is not yet playing is not a candidate for premature termination by the voice management flags passed to the Play method.
Resources that have been acquired by AcquireResources are released when playback is stopped.
If the method is called on a buffer on which it has already been called, the status of the effects is returned but no additional resources are allocated.
The dwEffectsCount parameter to this function must be the same as the one passed in the call to IDirectSoundBuffer8::SetFX.
If an attempt is made to acquire resources for a buffer with the DSBCAPS_LOCHARDWARE flag on a system where hardware acceleration is not available, the method fails with either DSERR_CONTROLUNAVAIL or DSERR_INVALIDCALL, depending on the operating system.
Requirements
Header: Declared in dsound.h.
See Also