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 Dsound.lib.