IDirectSoundBuffer8
[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 IDirectSoundBuffer8 interface is used to manage sound buffers.
The IDirectSoundBuffer8 interface supersedes IDirectSoundBuffer and adds new methods.
To obtain the interface, use the CreateSoundBuffer method to retrieve IDirectSoundBuffer, and then pass IID_IDirectSoundBuffer8 to IDirectSoundBuffer::QueryInterface.
For the primary buffer, you must use the IDirectSoundBuffer interface; IDirectSoundBuffer8 is not available. IDirectSoundBuffer is not documented separately. For documentation, see the corresponding IDirectSoundBuffer8 methods.
Not all methods of IDirectSoundBuffer are valid for primary buffers. For example, SetCurrentPosition will fail. See the reference topics for individual methods.
In addition to the methods inherited from IUnknown, the IDirectSoundBuffer8 interface exposes the following methods, arranged by category.
Effects
| Method | Description |
|---|---|
| IDirectSoundBuffer8::GetObjectInPath | The GetObjectInPath method retrieves an interface for an effect object associated with the buffer. |
| IDirectSoundBuffer8::SetFX | Number of elements in the pDSFXDesc and pdwResultCodes arrays. If this value is 0, pDSFXDesc and pdwResultCodes must both be NULL. Set to 0 to remove all effects from the buffer. |
Resource Management
| Method | Description |
|---|---|
| IDirectSoundBuffer8::AcquireResources | The AcquireResources method allocates resources for a buffer that was created with the DSBCAPS_LOCDEFER flag in the DSBUFFERDESCDSBUFFERDESC |
| IDirectSoundBuffer8::Restore | The Restore method restores the memory allocation for a lost sound buffer. |
Play Management
| Method | Description |
|---|---|
| IDirectSoundBuffer8::GetCurrentPosition | The GetCurrentPosition method retrieves the position of the play and write cursors in the sound buffer. |
| IDirectSoundBuffer8::Lock | The Lock method readies all or part of the buffer for a data write and returns pointers to which data can be written. |
| IDirectSoundBuffer8::Play | The Play method causes the sound buffer to play, starting at the play cursor. |
| IDirectSoundBuffer8::SetCurrentPosition | The SetCurrentPosition method sets the position of the play cursor, which is the point at which the next byte of data is read from the buffer. |
| IDirectSoundBuffer8::Stop | The Stop method causes the sound buffer to stop playing. |
| IDirectSoundBuffer8::Unlock | The Unlock method releases a locked sound buffer. |
Sound Parameters
| Method | Description |
|---|---|
| IDirectSoundBuffer8::GetFrequency | The GetFrequency method retrieves the frequency, in samples per second, at which the buffer is playing. |
| IDirectSoundBuffer8::GetPan | The GetPan method retrieves the relative volume of the left and right audio channels. |
| IDirectSoundBuffer8::GetVolume | The GetVolume method retrieves the attenuation of the sound. |
| IDirectSoundBuffer8::SetFrequency | The SetFrequency method sets the frequency at which the audio samples are played. |
| IDirectSoundBuffer8::SetPan | The SetPan method sets the relative volume of the left and right channels. |
| IDirectSoundBuffer8::SetVolume | The SetVolume method sets the attenuation of the sound. |
Miscellaneous
| Method | Description |
|---|---|
| IDirectSoundBuffer8::GetCaps | The GetCaps method retrieves the capabilities of the buffer object. |
| IDirectSoundBuffer8::GetFormat | The GetFormat method retrieves a description of the format of the sound data in the buffer, or the buffer size needed to retrieve the format description. |
| IDirectSoundBuffer8::GetStatus | The GetStatus method retrieves the status of the sound buffer. |
| IDirectSoundBuffer8::Initialize | The Initialize method initializes a sound buffer object if it has not yet been initialized. |
| IDirectSoundBuffer8::SetFormat | 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. |
The LPDIRECTSOUNDBUFFER8 type is defined as a pointer to the IDirectSoundBuffer interface:
typedef struct IDirectSoundBuffer8 *LPDIRECTSOUNDBUFFER8;
Requirements
Header: Declared in DSound.h.
Library: Use Dsound3d.dll.