The IDirectSoundBuffer::SetFormat method sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.
HRESULT SetFormat(
LPCWAVEFORMATEX lpcfxFormat
);
Parameters
lpcfxFormat
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:
DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED
Remarks
If this method is called on a primary buffer that is being accessed in write-primary cooperative level, the buffer must be stopped before IDirectSoundBuffer::SetFormat is called. If this method is being called on a primary buffer for a non-write-primary level, DirectSound will implicitly stop the primary buffer, change the format, and restart the primary; the application need not do this explicitly.
If the hardware does not support the requested format, DirectSound may be able to mix the sound in the requested format and then convert it before sending it to the primary buffer. To determine whether this is happening, an application can call the IDirectSoundBuffer::GetFormat method for the primary buffer and compare the result with the format that was requested with the SetFormat method.
If the hardware does not support the requested format and DirectSound is unable to emulate it, the call to SetFormat fails.
A call to this method also fails if the calling application has the DSSCL_NORMAL cooperative level.
This method is not valid for secondary sound buffers. If a secondary sound buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.
DirectSound supports PCM formats; it does not currently support compressed formats.
QuickInfo
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 OSR2 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in dsound.h.
Import Library: Use dsound.lib.
See Also