IDirectSound::CreateSoundBuffer

  • Article

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

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 Values

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:

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.

On Windows CE, no call to SetCooperativeLevel is necessary – see CE specific remarks for SetCooperativeLevel. Calls to CreateSoundBuffer with DSBCAPS_PRIMARYBUFFER specified will fail.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Dsound.h.
Link Library: Dsound.lib.

See Also

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

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.