Microsoft DirectX 8.0 (C++) |
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.
Since primary sound buffers do not support the IDirectSoundBuffer8 interface, this method must be called on IDirectSoundBuffer.
HRESULT SetFormat( LPCWAVEFORMATEX pcfxFormat );
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 |
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 IDirectSoundBuffer8::SetFormat is called. If the format is not supported, the method fails.
If the cooperative level is DSSCL_PRIORITY or DSSCL_EXCLUSIVE, 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.
Header: Declared in dsound.h.