Creating Secondary Buffers

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)); // Zero it out. 
    dsbdesc.dwSize = sizeof(DSBUFFERDESC); 
    // Need default controls (pan, volume, frequency). 
    dsbdesc.dwFlags = DSBCAPS_CTRLDEFAULT; 
    // 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; 
    } 
} 
 

Your application should create buffers for the most important sounds first, and then create buffers for other sounds in descending order of importance. DirectSound allocates hardware resources to the first buffer that can take advantage of them.

If your application must explicitly locate buffers in hardware or software, you can specify either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag in the DSBUFFERDESC structure. If the DSBCAPS_LOCHARDWARE flag is specified and there is insufficient hardware memory or mixing capacity, the buffer creation request fails.

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.

When you create a sound buffer, you can indicate that a buffer is static by specifying the DSBCAPS_STATIC flag. If you do not specify this flag, the buffer is a streaming buffer. For more information, see Static and Streaming Sound Buffers.

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.