IDirectSoundBuffer::SetFormat

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The IDirectSoundBuffer::SetFormatmethod 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 WAVEFORMATEXstructure 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_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::SetFormatis 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.

This method will succeed even if the hardware does not support the requested format. DirectSound will set the buffer to the closest supported format, then mix the sound in the requested format and convert it before sending it to the primary buffer. To determine whether this is happening, an application can call the IDirectSoundBuffer::GetFormatmethod for the primary buffer and compare the result with the format that was requested with the SetFormatmethod.

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.

Requirements

Runs On	Versions	Defined in	Include	Link to
Windows CE OS	2.12 or later. Version 2.12 requires DXPAK 1.0 or later.	dsound.h		dsound.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.