DirectSound

• Overview
• Concepts
• Interfaces
• Structures
• Functions
• Enumerations
• Constants
• DXERR Functions

DirectSound API Reference

The DirectSound API provides a low-level interface for managing sound hardware and playing back audio on Windows. It offers fine-grained control over audio mixing, effects, and spatialization, making it a powerful tool for game development and audio-intensive applications.

Key Features and Concepts

• Sound Buffers: The core of DirectSound. You create sound buffers to hold audio data. These can be static for short sound effects or streaming for longer audio content.
• Primary Buffer: A special buffer that represents the output device itself. All other buffers are mixed into the primary buffer before being sent to the sound card.
• Secondary Buffers: Buffers created for specific sound effects or music. They can have various properties like volume, panning, and effects.
• 3D Sound: DirectSound supports positional audio, allowing you to simulate sounds originating from different points in a 3D space. This involves setting listener and sound object positions, velocities, and other acoustic properties.
• Effects: A range of audio effects can be applied to sound buffers, including reverb, chorus, distortion, and equalization.
• Hardware Acceleration: DirectSound attempts to utilize hardware acceleration for mixing and effects, reducing CPU load.

Core Interfaces

The DirectSound API is largely object-oriented, relying on COM interfaces. The most fundamental interface is:

IDirectSound8

This is the primary interface for interacting with DirectSound. You obtain it by calling DirectSoundCreate8.

Other important interfaces include:

• IDirectSoundBuffer8: Represents a sound buffer.
• IDirectSound3DListener8: Manages the listener's position and orientation in 3D space.
• IDirectSound3DBuffer8: Manages the 3D properties of a sound buffer.
• IDirectSoundFXChorus8, IDirectSoundFXFlanger8, IDirectSoundFXGargle8, IDirectSoundFXWavesReverb8, etc.: Interfaces for applying specific audio effects.

Common Functions

Some frequently used functions include:

• DirectSoundCreate8: Creates an instance of the DirectSound object.
• IDirectSoundBuffer8::Play: Starts playback of a sound buffer.
• IDirectSoundBuffer8::Stop: Stops playback of a sound buffer.
• IDirectSoundBuffer8::SetVolume: Sets the volume of a sound buffer.
• IDirectSoundBuffer8::SetPan: Sets the stereo panning of a sound buffer.
• IDirectSoundListener::SetOrientation: Sets the listener's orientation.
• IDirectSound3DBuffer8::SetPosition: Sets the 3D position of a sound source.

Example Snippet (Creating a Secondary Buffer)

    IDirectSound8* pDS = NULL;
    IDirectSoundBuffer8* pDsbPrimary = NULL;
    IDirectSoundBuffer8* pDsbSecondary = NULL;
    DSBUFFERDESC dsbd;
    WAVEFORMATEX wfx;

    // Initialize DirectSound
    DirectSoundCreate8(NULL, &pDS, NULL);
    pDS->SetCooperativeLevel(GetForegroundWindow(), DSSCL_PRIORITY);

    // Set up the primary buffer description
    ZeroMemory(&dsbd, sizeof(dsbd));
    dsbd.dwSize = sizeof(dsbd);
    dsbd.dwFlags = DSBCAPS_PRIMARYBUFFER;
    dsbd.dwBufferBytes = 0;
    dsbd.lpwfxFormat = NULL;

    // Create the primary buffer
    pDS->CreateSoundBuffer(&dsbd, &pDsbPrimary, NULL);

    // Set up the secondary buffer description
    ZeroMemory(&dsbd, sizeof(dsbd));
    dsbd.dwSize = sizeof(dsbd);
    dsbd.dwFlags = 0; // No special flags for now
    dsbd.dwBufferBytes = /* size of your audio data */;
    dsbd.lpwfxFormat = &wfx; // Your WAVEFORMATEX

    // Create the secondary buffer
    pDS->CreateSoundBuffer(&dsbd, &pDsbSecondary, NULL);

    // ... Load audio data into pDsbSecondary ...
    // ... Then call pDsbSecondary->Play() ...

    // Clean up
    if (pDsbSecondary) pDsbSecondary->Release();
    if (pDsbPrimary) pDsbPrimary->Release();
    if (pDS) pDS->Release();