IDirectSoundBuffer8::AcquireResources

The AcquireResources method allocates resources for a buffer that was created with the DSBCAPS_LOCDEFER flag in the DSBUFFERDESC structure.

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 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.

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.

Import Library: Use Dsound3d.dll.

See Also

IDirectSoundBuffer8