The IDsCaptureDriver::CreateCaptureBuffermethod is called only when the device has been opened by DirectSound through a call to IDsCaptureDriver::Open. DirectSound calls this method to request the driver to create a hardware sound capture 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 IDsCaptureDriverBufferinterface that DirectSound uses to control the sound capture buffer. Otherwise the driver fails the request by returning an error code.

HRESULT CreateCaptureBuffer(
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 IDirectSoundCapture::CreateCaptureBuffermethod; DirectSound intercepts and uses some of the flags so the driver does not have to worry about them.

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_CREATEHEAP or 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 IDsCaptureDriver::GetDriverDesccall, *ppbBufferis initialized with a pointer to the system memory allocated by DirectSound.

ppvObj

Pointer to an interface pointer that receives the IDsCaptureDriverBufferinterface 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, or one of the following error values otherwise:

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

  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.