DirectSound API Reference

Creates a DirectSound object. Entry point for all DirectSound use.

HRESULT DirectSoundCreate(
    LPGUID          lpGuid,
    LPDIRECTSOUND*  ppDS,
    IUnknown*       pUnkOuter
);

COM reference counting implemented with std::atomic<ULONG>. Release() deletes the object when the count reaches zero. Initial reference count after DirectSoundCreate is 1.

ULONG AddRef();
ULONG Release();

Both return the new reference count after the operation.

Sets the cooperative level for the DirectSound object. In free-direct this call is accepted for compatibility but does not change any SDL audio behavior. Audio is always operated at the equivalent of DSSCL_NORMAL.

HRESULT SetCooperativeLevel(
    HWND    hwnd,
    DWORD   dwLevel
);

Creates a sound buffer. free-direct creates a software PCM buffer backed by std::vector<uint8_t>. Hardware buffers are not supported — DSBCAPS_LOCHARDWARE is silently treated as software.

HRESULT CreateSoundBuffer(
    LPCDSBUFFERDESC      pcDSBufferDesc,
    LPDIRECTSOUNDBUFFER* ppDSBuffer,
    IUnknown*            pUnkOuter
);

Accepted DSBUFFERDESC.dwFlags combinations and their effect:

COM reference counting with std::atomic<ULONG>. Release() when count reaches zero: calls Stop(), destroys the SDL_AudioStream, frees the PCM vector. Initial reference count is 1.

ULONG AddRef();
ULONG Release();

Both return the new reference count.

Obtains write access to a region of the PCM buffer. Returns one or two pointers directly into the internal std::vector<uint8_t>. No mutex or synchronization is used — caller must not call Play() while locked.

HRESULT Lock(
    DWORD   dwWriteCursor,
    DWORD   dwWriteBytes,
    LPVOID* ppvAudioPtr1,
    LPDWORD pdwAudioBytes1,
    LPVOID* ppvAudioPtr2,
    LPDWORD pdwAudioBytes2,
    DWORD   dwFlags
);

Wrap-around behaviour: The buffer is treated as circular. If dwWriteCursor + dwWriteBytes > dwBufferBytes:

• Segment 1: from dwWriteCursor to end-of-buffer → size = dwBufferBytes − dwWriteCursor.
• Segment 2: from start of buffer → size = dwWriteBytes − size1.

If no wrap, segment 2 pointer is nullptr and size is 0.

Signals write completion. In free-direct this is a no-op — the vector is already in-place, no flush or copy is needed. Parameters are accepted for API compatibility and then ignored.

HRESULT Unlock(
    LPVOID  pvAudioPtr1,
    DWORD   dwAudioBytes1,
    LPVOID  pvAudioPtr2,
    DWORD   dwAudioBytes2
);

Starts playback. The entire PCM buffer is put into a new SDL_AudioStream and the stream is bound to the shared device. The buffer plays once; DSBPLAY_LOOPING is accepted but does not cause the buffer to repeat.

HRESULT Play(
    DWORD  dwReserved1,
    DWORD  dwPriority,
    DWORD  dwFlags
);

Internal steps on Play():

1. Open SharedAudioDevice singleton if not yet open (SDL_OpenAudioDevice).
2. Create a new SDL_AudioStream for the buffer's PCM format (sample rate, channels, bit depth).
3. Apply current volume: compute gain = 10^(volume_cb / 2000), call SDL_SetAudioStreamGain(stream, gain).
4. Put all PCM data into the stream: SDL_PutAudioStreamData(stream, data.data(), data.size()).
5. Bind the stream to the audio device: SDL_BindAudioStream(device, stream).
6. Set playing = true.

Stops playback. Unbinds the SDL_AudioStream from the device and destroys it. The PCM vector contents are preserved. The buffer can be played again with Play(). Calling Stop on an already-stopped buffer is harmless (idempotent).

HRESULT Stop();

Returns the current playback status. free-direct tracks a simple playing boolean. It does not detect when SDL finishes consuming the stream, so DSBSTATUS_PLAYING may remain set after audio has finished.

HRESULT GetStatus(
    LPDWORD pdwStatus
);

Sets the playback volume. Volume is specified in centibels (hundredths of a decibel). Converted to a linear gain and applied to the SDL_AudioStream immediately if one is open; stored for future Play() calls otherwise.

HRESULT SetVolume(
    LONG lVolume
);

Conversion formula: float gain = powf(10.0f, lVolume / 2000.0f);

Applied with SDL_SetAudioStreamGain(stream, gain) if a stream is open.

Sets the stereo pan position. The value and the computed left/right gains are stored but the result is (void)-discarded before it reaches SDL. Pan has no audible effect.

HRESULT SetPan(
    LONG lPan
);

Sets the playback start position. Stored in the buffer but not used to seek within an active SDL stream (SDL_AudioStream does not support seeking). Effective only before Play().

HRESULT SetCurrentPosition(
    DWORD dwNewPosition
);

Returns the current play and write cursor positions. free-direct always returns 0 for both — SDL_AudioStream does not expose a consumption position.

HRESULT GetCurrentPosition(
    LPDWORD pdwCurrentPlayCursor,
    LPDWORD pdwCurrentWriteCursor
);

Describes a sound buffer. Passed to IDirectSound::CreateSoundBuffer.

typedef struct {
    DWORD          dwSize;        // sizeof(DSBUFFERDESC)
    DWORD          dwFlags;       // DSBCAPS_* capability flags
    DWORD          dwBufferBytes; // PCM buffer size in bytes
    DWORD          dwReserved;    // must be 0
    LPWAVEFORMATEX lpwfxFormat;   // pointer to PCMWAVEFORMAT (see note)
} DSBUFFERDESC;

Base wave format structure. Embedded as the first member of PCMWAVEFORMAT.

typedef struct {
    WORD  wFormatTag;       // audio format type
    WORD  nChannels;        // number of channels
    DWORD nSamplesPerSec;   // sample rate in Hz
    DWORD nAvgBytesPerSec;  // nSamplesPerSec * nBlockAlign
    WORD  nBlockAlign;      // bytes per sample frame
} WAVEFORMAT;
// sizeof(WAVEFORMAT) = 14 bytes on LP64 (no internal padding)

PCM wave format descriptor. This is the correct struct to pass as lpwfxFormat in free-direct.

typedef struct {
    WAVEFORMAT wf;            // base format (14 bytes)
    WORD       wBitsPerSample; // bits per sample (at byte offset 14)
} PCMWAVEFORMAT;
// sizeof(PCMWAVEFORMAT) = 16 bytes

// CORRECT: use PCMWAVEFORMAT
PCMWAVEFORMAT pcm = {};
pcm.wf.wFormatTag      = 1;      // WAVE_FORMAT_PCM
pcm.wf.nChannels       = 1;      // mono
pcm.wf.nSamplesPerSec  = 22050;
pcm.wf.nBlockAlign     = 2;      // 1 ch * 2 bytes
pcm.wf.nAvgBytesPerSec = 44100;
pcm.wBitsPerSample     = 16;
bufDesc.lpwfxFormat = (LPWAVEFORMATEX)&pcm;

Extended wave format. Defined in dsound.h for compile compatibility. Do not use this struct directly as lpwfxFormat in free-direct — use PCMWAVEFORMAT instead.

typedef struct {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;  // at offset 16 on LP64 (NOT offset 14)
    WORD  cbSize;          // extra bytes beyond this struct
} WAVEFORMATEX;