Share via


IDirectSound8::SetSpeakerConfig Method

[The feature associated with this page, DirectSound, is a legacy feature. It has been superseded by WASAPI and Audio Graphs. Media Casting have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Media Casting instead of DirectSound, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The SetSpeakerConfig method specifies the speaker configuration of the device.

Syntax

HRESULT SetSpeakerConfig(
         DWORD dwSpeakerConfig
)

Parameters

  • dwSpeakerConfig
    The speaker configuration. See the following remarks.

Return Value

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the error values shown in the following table.

Return code
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

Remarks

In Windows Vista and later versions of Windows, SetSpeakerConfig is a NOP. For Windows Vista and later versions, the speaker configuration is a system setting that should not be modified by an application. End users can set the speaker configuration through control panels.

Speaker Configurations

These tables contain the possible speaker configurations.

Value Description
DSSPEAKER_5POINT1_BACK The audio is played through a speaker arrangement of five surround speakers with a subwoofer. (DSSPEAKER_5POINT1 is still defined, but is obsolete as of Windows Vista. Use DSSPEAKER_5POINT1_BACK instead.)
DSSPEAKER_5POINT1_SURROUND The audio is played through a home theater speaker arrangement of five surround speakers with a subwoofer. This value applies to Windows Vista or later.
DSSPEAKER_DIRECTOUT The audio is passed through directly, without being configured for speakers.
DSSPEAKER_HEADPHONE The audio is played through headphones.
DSSPEAKER_MONO The audio is played through a single speaker.
DSSPEAKER_QUAD The audio is played through quadraphonic speakers.
DSSPEAKER_STEREO The audio is played through stereo speakers (default value).
DSSPEAKER_SURROUND The audio is played through surround speakers.
DSSPEAKER_7POINT1_WIDE The audio is played through a wide speaker arrangement of seven surround speakers with a subwoofer. (DSSPEAKER_7POINT1 is still defined, but is obsolete as of Windows XP SP 2. Use DSSPEAKER_7POINT1_WIDE instead.)
DSSPEAKER_7POINT1_SURROUND The audio is played through a home theater speaker arrangement of seven surround speakers with a subwoofer. This value applies to Windows XP SP2 or later.

DSSPEAKER_STEREO can be combined with one of the values shown in the following table.

Value Description
DSSPEAKER_GEOMETRY_WIDE The speakers are directed over an arc of 20 degrees.
DSSPEAKER_GEOMETRY_NARROW The speakers are directed over an arc of 10 degrees.
DSSPEAKER_GEOMETRY_MIN The speakers are directed over an arc of 5 degrees.
DSSPEAKER_GEOMETRY_MAX The speakers are directed over an arc of 180 degrees.

If a geometry value is to be used, it must be packed in a DWORD along with the DSSPEAKER_STEREO flag. This can be done by using the DSSPEAKER_COMBINED macro, as in the following C++ example:

    lpds->SetSpeakerConfig(DSSPEAKER_COMBINED(
        DSSPEAKER_STEREO, DSSPEAKER_GEOMETRY_WIDE));
	

To use #defines implemented in Windows Vista, set the DIRECTSOUND_VERSION to 0x1000 before including dsound.h.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound3d.dll.

See Also

IDirectSound8