Creating Secondary Buffers

To create a sound buffer, call the IDirectSound8::CreateSoundBuffer method. This method returns a pointer to an IDirectSoundBuffer interface, from which the application can obtain an IDirectSoundBuffer8 interface.

The following example shows how to create a secondary sound buffer:

BOOL AppCreateBasicBuffer( 
    LPDIRECTSOUND8 lpDirectSound, 
    LPDIRECTSOUNDBUFFER *lplpDsb) 
{ 
  PCMWAVEFORMAT pcmwf; 
  DSBUFFERDESC dsbdesc; 
  HRESULT hr; 
 
  // Set up wave format structure. 
  memset(&pcmwf, 0, sizeof(PCMWAVEFORMAT)); 
  pcmwf.wf.wFormatTag = WAVE_FORMAT_PCM; 
  pcmwf.wf.nChannels = 2; 
  pcmwf.wf.nSamplesPerSec = 22050; 
  pcmwf.wf.nBlockAlign = 4; 
  pcmwf.wf.nAvgBytesPerSec = 
    pcmwf.wf.nSamplesPerSec * pcmwf.wf.nBlockAlign; 
  pcmwf.wBitsPerSample = 16; 
 
  // Set up DSBUFFERDESC structure. 
 
  memset(&dsbdesc, 0, sizeof(DSBUFFERDESC)); 
  dsbdesc.dwSize = sizeof(DSBUFFERDESC); 
  dsbdesc.dwFlags = 
    DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY; 
 
  dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec; 
  dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf; 
 
  // Create buffer. 
 
  hr = lpDirectSound->CreateSoundBuffer(&dsbdesc, lplpDsb, NULL); 
  if SUCCEEDED(hr) 
  { 
    // IDirectSoundBuffer interface is in *lplpDsb. 
    // Use QueryInterface to obtain IDirectSoundBuffer8.
    return TRUE; 
  } 
  else 
  { 
    // Failed. 
    *lplpDsb = NULL; 
    return FALSE; 
  } 
} 
 

The example creates a streaming buffer large enough to hold 3 seconds of streaming data. Nonstreaming buffers should be made just large enough to accommodate the entire sound.

DirectSound allocates hardware resources to the first buffer that can take advantage of them. Because hardware buffers are mixed by the sound card processor, they have much less impact on application performance.

If you wish to specify the location of a buffer rather than letting DirectSound decide where it belongs, set either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag in the DSBUFFERDESC structure. If the DSBCAPS_LOCHARDWARE flag is set and there are insufficient hardware resources, the buffer creation request fails.

To take advantage of the voice management features of DirectSound, specify the DSBCAPS_LOCDEFER flag when creating the buffer. This flag defers the allocation of resources for the buffer until it is played. For more information, see Dynamic Voice Management.

You can ascertain the location of an existing buffer by using the IDirectSoundBuffer8::GetCaps method and checking the dwFlags member of the DSBCAPS structure for either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags. One or the other is always specified.

Setting the DSBCAPS_STATIC flag lets DirectSound know that the buffer should be created in on-board hardware memory if possible. The IDirectSound::CreateSoundBuffer method does not fail if a hardware buffer is not available. This flag has no effect on most modern sound cards, which use system memory for their buffers. Hardware static buffers should be used only for short sounds that are to be played repeatedly. For more information, see Voice Management on ISA and PCI Cards.

Buffer objects are owned by the DirectSound object that created them. When the DirectSound object is released, all buffers created by that object also will be released and should not be referenced.