DirectSound API Reference

Introduction to DirectSound

DirectSound is a component of Microsoft's DirectX API that provides low-level access to sound hardware. It enables developers to create and manage sound buffers, mix audio streams, and implement advanced audio features such as 3D sound positioning and environmental effects.

DirectSound simplifies audio programming by abstracting the complexities of various sound card drivers and hardware capabilities. It offers a unified interface for playing back and capturing digital audio data.

Key Concepts

  • Sound Buffer: A DirectSound object that holds audio data to be played. Buffers can be created for primary sound (direct output) or secondary sounds (mixable streams).
  • Primary Buffer: The buffer that is directly rendered to the sound device. It represents the main audio output.
  • Secondary Buffer: A buffer that can be mixed with other secondary buffers and the primary buffer. It's used for sound effects, music, and other independent audio streams.
  • DirectSound Object: The main interface (IDirectSound or IDirectSound8) that represents the sound device and provides methods for creating buffers and managing the audio environment.
  • DirectSound Capture Object: The interface (IDirectSoundCapture or IDirectSoundCapture8) used for recording audio from input devices.
  • 3D Sound: DirectSound supports spatializing sounds in a 3D environment, allowing for realistic audio positioning relative to a listener.

Core Objects

IDirectSound

The primary interface for interacting with the sound output device. It is used to create sound buffers, set cooperative levels, and manage the overall DirectSound environment.

IDirectSoundBuffer

Represents a buffer containing audio data. This interface provides methods for loading audio data, playing, stopping, looping, and managing buffer properties like volume, frequency, and position.

IDirectSound3DListener

An interface associated with the primary buffer, representing the listener in a 3D sound environment. It defines the listener's position, orientation, and velocity.

IDirectSound3DBuffer

An interface associated with a secondary buffer, representing a sound source in a 3D sound environment. It defines the sound's position, velocity, and 3D properties like cone angles and rolloff factors.

IDirectSoundCapture

The primary interface for interacting with sound input devices (microphones). It is used to create capture buffers.

IDirectSoundCaptureBuffer

Represents a buffer for capturing audio data from an input device. It allows for managing the capture process, locking/unlocking buffer sections, and retrieving captured data.

Functions

DirectSoundCreate

Creates an instance of the DirectSound object.

HRESULT DirectSoundCreate(
  LPGUID lpGuid,
  LPDIRECTSOUND *lplpDS,
  LPUNKNOWN pUnkOuter
);

Parameters

Name Description
lpGuid Pointer to the GUID of the sound device to use. If NULL, the default sound device is used.
lplpDS Address of a pointer to receive the IDirectSound interface.
pUnkOuter Pointer to the controlling unknown for COM aggregation. Must be NULL for non-aggregated objects.

Return Value

Value Description
S_OK The method succeeded.
DSERR_ALLOCATED The existing sound device is already in use.
DSERR_NODRIVER No sound driver is available for use.
E_POINTER Invalid pointer specified.

Remarks

This function initializes DirectSound and obtains an IDirectSound interface to the specified sound device. Use Release() to decrement the reference count when done.

DirectSoundCaptureCreate

Creates an instance of the DirectSoundCapture object.

HRESULT DirectSoundCaptureCreate(
  LPGUID lpGuid,
  LPDIRECTSOUNDCAPTURE *lplpDSC,
  LPUNKNOWN pUnkOuter
);

Parameters

Name Description
lpGuid Pointer to the GUID of the sound input device to use. If NULL, the default input device is used.
lplpDSC Address of a pointer to receive the IDirectSoundCapture interface.
pUnkOuter Pointer to the controlling unknown for COM aggregation. Must be NULL for non-aggregated objects.

Return Value

Value Description
S_OK The method succeeded.
DSERR_ALLOCATED The existing sound device is already in use.
DSERR_NODRIVER No sound input driver is available for use.
E_POINTER Invalid pointer specified.

Remarks

This function initializes DirectSound capture and obtains an IDirectSoundCapture interface to the specified input device. Use Release() to decrement the reference count when done.

Interfaces (DirectSound 8 and Later)

DirectSound 8 introduced several updated interfaces (ending with version 8) that offer enhanced capabilities and improved performance.

IDirectSound8

The enhanced primary interface for DirectSound, offering advanced features over IDirectSound.

IDirectSoundBuffer8

The enhanced buffer interface, providing additional control and functionality.

IDirectSound3DListener8

The enhanced listener interface for 3D audio.

IDirectSound3DBuffer8

The enhanced sound source interface for 3D audio.

IDirectSoundCapture8

The enhanced interface for sound capture.

IDirectSoundCaptureBuffer8

The enhanced buffer interface for capture.

Structures

DirectSound utilizes various structures to define audio formats, listener properties, and buffer descriptions.

  • DSBUFFERDESC: Describes a sound buffer to be created.
  • DSCBUFFERDESC: Describes a capture buffer.
  • DSFREQUENCY: Specifies a frequency value.
  • DSVOLUME: Specifies a volume value.
  • DS3DLISTENER: Defines the properties of a 3D listener.
  • DS3DBUFFER: Defines the properties of a 3D sound buffer.
  • WAVEFORMATEX / WAVEFORMATEXTENSIBLE: Structures defining audio data format (sample rate, channels, bits per sample, etc.).

Enumerations

Enumerations are used to specify various states, flags, and options within DirectSound.

  • DSCAPS flags: Capabilities of a DirectSound capture device.
  • DSSPECIALEFFECT: Defines special audio effects like chorus, flanger, etc.
  • DSFXFLAGS: Flags for applying special effects.
  • DSBLOCKSIZE: Options for buffer block sizes.

Error Codes

DirectSound functions return HRESULT values. Common DirectSound specific error codes include:

  • DSERR_ALLOCATED: The requested resource (e.g., device) is already in use.
  • DSERR_BADFORMAT: The specified sound format is not supported.
  • DSERR_BADPARTITION: The specified buffer partition is invalid.
  • DSERR_BUFFERLOST: The buffer has been lost and must be reloaded.
  • DSERR_DRIVERFAILURE: A failure occurred in the sound driver.
  • DSERR_HANDLEINVALID: The provided handle is invalid.
  • DSERR_INVALIDCALL: The method is not valid in the current state.
  • DSERR_NODRIVER: No sound driver is available.
  • DSERR_OUTOFMEMORY: Not enough memory is available.
  • DSERR_SOUNDPLANEBUSY: The sound plane is currently busy.
  • DSERR_UNINITIALIZED: DirectSound has not been initialized.