IDirectSound::CreateSoundBuffer

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectSound::CreateSoundBuffermethod 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 DSBUFFERDESCstructure 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:

Remarks

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

The lpDSBufferDescparameter 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::SetFrequencywill 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::GetCapsmethod and check for the DBSCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag in the dwFlagsmember of the returned DSBCAPSstructure.

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

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	dsound.h		dsound.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.