IDirectSoundBuffer8::SetFormat 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 SetFormat method sets the format of the primary buffer. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.
Syntax
HRESULT SetFormat(
LPCWAVEFORMATEX pcfxFormat
)
Parameters
- pcfxFormat
Address of a WAVEFORMATEX structure that describes the new format for the primary sound buffer.
Return Value
If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:
| Return code |
| DSERR_BADFORMAT |
| DSERR_INVALIDCALL |
| DSERR_INVALIDPARAM |
| DSERR_OUTOFMEMORY |
| DSERR_PRIOLEVELNEEDED |
| DSERR_UNSUPPORTED |
Remarks
The format of the primary buffer should be set before secondary buffers are created.
The method fails if the application has the DSSCL_NORMAL cooperative level.
If the application is using DirectSound at the DSSCL_WRITEPRIMARY cooperative level, and the format is not supported, the method fails.
If the cooperative level is DSSCL_PRIORITY, DirectSound stops the primary buffer, changes the format, and restarts the buffer. The method succeeds even if the hardware does not support the requested format; DirectSound sets the buffer to the closest supported format. To determine whether this has happened, an application can call the GetFormat method for the primary buffer and compare the result with the format that was requested with the SetFormat method.
This method is not available for secondary sound buffers. If a new format is required, the application must create a new DirectSoundBuffer object.
Requirements
Header: Declared in DSound.h.
Library: Use Dsound3d.dll.