| Microsoft DirectX 9.0 |
The SetFormat method sets the format of the
Because primary sound buffers do not support the IDirectSoundBuffer8 interface, this method must be called on IDirectSoundBuffer.
On WDM drivers, setting the primary buffer format has no effect. The output format is determined by the kernel mixer. For more information, see DirectSound Driver Models.
Syntax
HRESULT SetFormat(
LPCWAVEFORMATEX pcfxFormat
);
Parameters
pcfxFormat
Address of a WAVEFORMATEX structure that describes the new format for the primary sound buffer.
Return Values
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, the buffer must be stopped before SetFormat is called. If 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 IDirectSoundBuffer8::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.
See Also