Creating Secondary Buffers

[C++]

To create a sound buffer, your application fills a DSBUFFERDESC structure and then passes its address to the IDirectSound::CreateSoundBuffer method. This method creates a DirectSoundBuffer object and returns a pointer to an IDirectSoundBuffer interface. Your application uses this interface to manipulate and play the buffer.

The following example illustrates how to create a basic secondary sound buffer:

BOOL AppCreateBasicBuffer( 
        LPDIRECTSOUND 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; 
 
    // 3-second buffer. 
    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec; 
    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX)&pcmwf; 
    // Create buffer. 
    hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound, 
        &dsbdesc, lplpDsb, NULL); 
    if SUCCEEDED(hr) 
    { 
        // Valid interface is in *lplpDsb. 
        return TRUE; 
    } 
    else 
    { 
        // Failed. 
        *lplpDsb = NULL; 
        return FALSE; 
    } 
}

An application should create buffers for the most important sounds first. 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.

If you want 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.

You can ascertain the location of an existing buffer by using the IDirectSoundBuffer::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.

DirectSoundBuffer 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.

[Visual Basic]

To create a sound buffer, call the DirectSound.CreateSoundBuffer, DirectSound.CreateSoundBufferFromFile, or DirectSound.CreateSoundBufferFromResource method. The method creates and returns a DirectSoundBuffer object which can then be used to manipulate and play the buffer.

DirectSound.CreateSoundBufferFromFile and DirectSound.CreateSoundBufferFromResource are good methods to use when the sound is not very long. DirectSound creates a buffer big enough to hold the entire sound and also fills it with the data from the file or resource. DirectSound.CreateSoundBuffer is suitable for streaming buffers; however, you have to do your own parsing of the wave file or resource as well as handling the streaming of data to the buffer.

CreateSoundBuffer is also used to create a primary buffer from which a DirectSound3DListener object can be obtained. For more information, see Obtaining the DirectSound3DListener Object.

The following example shows how to create a basic secondary sound buffer.

Dim m_dx As New DirectX7
Dim m_ds As DirectSound
 
Private Sub Form_Load()
  Set m_ds = m_dx.DirectSoundCreate("")
  CreateSoundBuffer
End Sub 
 
Public Sub CreateSoundBuffer()
  Dim m_dsb As DirectSoundBuffer
  Dim buffdesc As DSBUFFERDESC
  Dim format As WAVEFORMATEX
 
  ' Specify the wave format.
 
  format.nFormatTag = WAVE_FORMAT_PCM
  format.nChannels = 2
  format.lSamplesPerSec = 22050
  format.nBitsPerSample = 16
  format.nBlockAlign = (format.nChannels * format.nBitsPerSample) / 8
  format.lAvgBytesPerSec = format.lSamplesPerSec * format.nBlockAlign
  format.nSize = 0

  ' Describe the sound buffer to create.
 
  buffdesc.lBufferBytes = format.lAvgBytesPerSec
  buffdesc.lFlags = DSBCAPS_CTRLPAN Or DSBCAPS_CTRLVOLUME _
          Or DSBCAPS_CTRLFREQUENCY
 
  ' Create the buffer.
 
  Set m_dsb = m_ds.CreateSoundBuffer(buffdesc, format)
End Sub

The DSBUFFERDESC type describes the characteristics of the desired buffer, 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 buffer without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to DirectSoundBuffer.SetFrequency will fail.

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 type. If the DSBCAPS_LOCHARDWARE flag is set and there are insufficient hardware resources, the buffer creation request fails.

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