IDirectSoundBuffer8::AcquireResources Method
[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 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 Play.dwEffectsCount
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 SetFX. For each effect, one of the values shown in the following table is returned.Note
This parameter can be NULL if result codes are not wanted.
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.
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 |
|---|
| DSERR_CONTROLUNAVAIL |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
Remarks
Normally, buffers created with DSBCAPS_LOCDEFER are not allocated resources until Play is called. IDirectSoundBuffer8::AcquireResources can be used to allocate resources for a deferred buffer before it is played. By doing so, the application can retrieve information about effects processing and set effect parameters. 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 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.
Library: Use Dsound3d.dll.