The IDsDriver::CreateSoundBuffermethod is called only when the device has been opened by DirectSound through a call to IDsDriver::Open. DirectSound calls this method to request the driver to create a hardware sound buffer with specific attributes. If the driver is able to create the sound buffer and allocate the required resources, it returns a pointer to an IDsDriverBufferinterface that DirectSound uses to control the sound buffer. Otherwise the driver fails the request by returning an error code.

HRESULT CreateSoundBuffer(
LPWAVEFORMATEX
pwfx
,
DWORD
dwFlags
,
DWORD
dwCardAddress
,
LPDWORD
pdwcbBufferSize
,
LPBYTE *
ppbBuffer
,
LPVOID *
ppvObj
);

Parameters

pwfx

Pointer to a WAVEFORMATEXstructure that contains a description of the desired wave format for the sound buffer. If the device cannot create a sound buffer with that format, it should fail the call by returning DSERR_BADFORMAT.

dwFlags

The creation flags for this sound buffer. Note that these flags are a subset of those used by the IDirectSound::CreateSoundBuffermethod; DirectSound intercepts and uses some of the flags so the driver does not have to worry about them.

Value	Description
DSBCAPS_PRIMARYBUFFER	Primary buffer requested. If this flag is not specified, the application should attempt to create a secondary buffer. DirectSound only attempts to create secondary buffers if the driver has indicated (through the DSDRIVERCAPSstructure returned by IDsDriver::GetCaps) that it supports secondary hardware buffers.
DSBCAPS_CTRLFREQUENCY
DSBCAPS_CTRLPAN
DSBCAPS_CTRLVOLUME	These flags specify the controls required for the buffer. If these controls are not available, the driver should fail by returning DSERR_CONTROLUNAVAIL. Note that drivers should fail to create primary buffers if volume or pan control is requested; in the current release this doesn't work because of conflicts with the Windows 95 mixer controls.
DSBCAPS_CTRL3D	Specified only for secondary buffers. Specifies that the secondary buffer requires 3-D audio acceleration.

dwCardAddress

If the device has onboard sound memory and the driver requests that DirectSound or DirectDraw manage the heap (that is, the driver specifies DSDHEAP_CREATEHEAPor DSDHEAP_USEDIRECTDRAWHEAP), this method points to the card address of the sound memory to be used by this buffer. DirectSound guarantees that this memory is free and is large enough to contain the buffer.

pdwcbBufferSize

Pointer to a doubleword containing the requested size of the sound buffer. As an input parameter, it contains the buffer size requested by the calling application. For primary buffers, it may also be an output parameter if the hardware imposes restrictions on the size of the buffer. For example, for DMA-based cards, the driver should fill in this value with the size of the DMA buffer allocated on startup.

ppbBuffer

Pointer to a value containing the start address (that is, a pointer to a pointer) of the buffer memory. If this is a secondary buffer and the driver specified the DSDDESC_USESYSTEMMEMORY flag in the DSDRIVERDESCstructure returned by the IDsDriver::GetDriverDesccall, *ppbBufferis initialized with a pointer to the system memory allocated by DirectSound.

ppvObj

Pointer to an interface pointer that receives the IDsDriverBufferinterface to the buffer object created by the driver. If no buffer object and interface are created (that is, if the creation request fails), the driver should set the interface pointer to NULL.

Return Values

Returns DS_OK if successful, otherwise one of the following error values.

• DSERR_ALLOCATED
• DSERR_INVALIDPARAM
• DSERR_OUTOFMEMORY
• DSERR_BADFORMAT

  Remarks

  The requested size of the buffer is passed in a doubleword pointed to by the lpdwRequestedSizeparameter. When creating a primary buffer (that is, the DSBCAPS_PRIMARYBUFFER flag is specified), the driver may change this value to conform to hardware limitations (such as DMA buffer size). For secondary buffers, this value must not be changed.

  If a secondary buffer is requested and the driver specifies the DSDDESC_USESYSTEMMEMORY flag in the DSDRIVERDESCstructure returned by the IDsDriver::GetDriverDescmethod, DirectSound allocates system memory for the buffer and passes a pointer to this memory in the location pointed to by ppbBuffer. The buffer will be large enough to contain the number of bytes specified in *pdwcbBufferSize. The driver must use this memory or fail the call. If the driver needs to allocate its own memory, it should do so for all buffers and not use the DSDDESC_USESYSTEMMEMORY flag.

  If a primary buffer is requested or the driver does not specify the DSDDESC_USESYSTEMMEMORY flag, no memory is allocated and the ppbBufferparameter points to a NULL pointer. The driver should allocate the required buffer memory and return a pointer to this memory in the value pointed to by ppbBuffer.

  The driver should always check the DSBCAPS_CTRLxxx flags passed in the dwFlagsparameter. If the driver cannot create a buffer with the requested control attributes, it should fail the creation request. If the driver succeeds the creation request, it is required to succeed the control requests ( IDsDriverBuffer::SetVolumePan, and so on) when called on this buffer.

  If the device has onboard sound memory and the driver requests that DirectSound or DirectDraw manage the heap (that is, the driver fills in the dwMemStartAddressand dwMemEndAddressmembers and specifies the DSDHEAP_CREATEHEAP or DSDHEAP_USEDIRECTDRAWHEAP flags in the DSDRIVERDESCstructure), this method points to the card address of the sound memory to be used by this buffer. DirectSound guarantees that this memory is free and is large enough to contain the buffer. Otherwise this parameter is set to zero.

  Due to internal contention-management code in DirectSound, drivers should always make sure that the buffer memory for primary buffers is page-locked.

  
  

  ---

   Last updated on Tuesday, July 13, 2004

  © 2004 Microsoft Corporation. All rights reserved.