IDirectSound::CreateSoundBuffer

This method creates a DirectSoundBuffer object to hold a sequence of audio samples.

Syntax

HRESULT CreateSoundBuffer( LPCDSBUFFERDESC lpcDSBufferDesc, LPLPDIRECTSOUNDBUFFER lplpDirectSoundBuffer, IUnknown FAR* pUnkOuter );

Parameters

  • lpcDSBufferDesc
    Address of a DSBUFFERDESC structure that contains the description of the sound buffer to be created.
  • lplpDirectSoundBuffer
    Address of a pointer to the new DirectSoundBuffer object, or NULL if the buffer cannot be created.
  • pUnkOuter
    Controlling unknown of the aggregate. Its value must be NULL.

Return Value

If the method succeeds, the return value is DS_OK.

If the method fails, the return value may be one of the following error values:

Return Code
DSERR_ALLOCATED
DSERR_CONTROLUNAVAIL
DSERR_BADFORMAT
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

Remarks

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the IDirectSound::SetCooperativeLevel method.

The lpDSBufferDesc parameter points to a structure that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to IDirectSoundBuffer::SetFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in on-board memory, if available, to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag.

To find out if the buffer was created in hardware or software, call the IDirectSoundBuffer::GetCaps method and check for the DBSCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag in the dwFlags member of the returned DSBCAPS structure.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound.lib.

See Also

IDirectSound::DuplicateSoundBuffer
IDirectSound::SetCooperativeLevel
IDirectSoundBuffer
IDirectSoundBuffer::GetFormat
IDirectSoundBuffer::GetVolume
IDirectSoundBuffer::Lock
IDirectSoundBuffer::Play
IDirectSoundBuffer::SetFormat
IDirectSoundBuffer::SetFrequency
DSBUFFERDESC