Making DirectSound Talk Back

You may be wondering if there is any way to query DirectSound for information about the sound system or a sound that is playing, like finding out whether the sound is done. Of course there is! DirectSound has a number of functions to do stuff like that. First, here's the general DirectSound capability function to determine the capabilities of your hardware:

HRESULT GetCaps(LPDSCAPS lpDSCaps); // ptr to DSCAPS structure

The function simply takes a pointer to a DSCAPS structure and fills it in. Here's the DSCAPS structure for your reference (you'll have to refer to the DirectX SDK for more complete descriptions of these fields, but most of them are decipherable by their names):

typedef {
    DWORD  dwSize;
    DWORD  dwFlags;
    DWORD  dwMinSecondarySampleRate;
    DWORD  dwMaxSecondarySampleRate;
    DWORD  dwPrimaryBuffers;
    DWORD  dwMaxHwMixingAllBuffers;
    DWORD  dwMaxHwMixingStaticBuffers;
    DWORD  dwMaxHwMixingStreamingBuffers;
    DWORD  dwFreeHwMixingAllBuffers;
    DWORD  dwFreeHwMixingStaticBuffers;
    DWORD  dwFreeHwMixingStreamingBuffers;
    DWORD  dwMaxHw3DAllBuffers;
    DWORD  dwMaxHw3DStaticBuffers;
    DWORD  dwMaxHw3DStreamingBuffers;
    DWORD  dwFreeHw3DAllBuffers;
    DWORD  dwFreeHw3DStaticBuffers;
    DWORD  dwFreeHw3DStreamingBuffers;
    DWORD  dwTotalHwMemBytes;
    DWORD  dwFreeHwMemBytes;
    DWORD  dwMaxContigFreeHwMemBytes;
    DWORD  dwUnlockTransferRateHwBuffers;
    DWORD  dwPlayCpuOverheadSwBuffers;
    DWORD  dwReserved1;
    DWORD  dwReserved2;
} DSCAPS, *LPDSCAPS;

You would call the function like this:

DSCAPS dscaps; // hold the caps

if (FAILED(lpds->GetCaps(&dscaps)))
    { /* error */ }

Then you can test any of the fields you want and determine what capabilities your sound hardware has. There's also a similar function for a DirectSound buffer that returns a DSBCAPS structure:

HRESULT GetCaps(LPDSBCAPS lpDSBCaps); // ptr to DSBCAPS struct

Here, a DSBCAPS structure looks like this:

typedef struct {
 DWORD dwSize;  // size of structure, you must set this
 DWORD dwFlags; // flags buffer has
 DWORD dwBufferBytes;        // size of buffer
 DWORD dwUnlockTransferRate; // sample rate
 DWORD dwPlayCpuOverhead;    // percentage of processor needed
                             // to mix this sound
} DSBCAPS, *LPDSBCAPS;

Here's how you would check out the sound buffer lpdsbuffer that you've been using in the examples:

DSBCAPS dsbcaps; // used to hold the results

// set up the struct
dsbcaps.dwSize = sizeof(DSBCAPS); // ultra important

// get the caps
if (FAILED(lpdsbuffer->GetCaps(&dsbcaps)))
   { /* error */ }

That's all there is to it. Of course, there are functions to retrieve the volume, pan setting, frequency, etc. of any sound buffer, but I'll let you look those up yourself.

The last get function I want to show you is used to determine the status of a playing sound buffer:

HRESULT GetStatus(LPDWORD lpdwStatus); // ptr to result

Just call the function from the interface pointer of the sound buffer you're interested in with a pointer to the DWORD where you want the status to be stored, like this:

DWORD status; // used to hold status

if (FAILED(lpdsbuffer->GetStatus(&status)))
  { / * error */ }

The data in the status will be one of the following:

• DSBSTATUS_BUFFERLOST— Something happened to the buffer. Very bad.

• DSBSTATUS_LOOPING— The sound is playing in looped mode.

• DSBSTATUS_PLAYING— The sound is currently playing. If this bit isn't set, the sound is not playing at all.