Share via


IDirectSound8::DuplicateSoundBuffer Method

[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 DuplicateSoundBuffer method creates a new secondary buffer that shares the original buffer's memory.

Syntax

HRESULT DuplicateSoundBuffer(
         LPDIRECTSOUNDBUFFER pDSBufferOriginal,
         LPDIRECTSOUNDBUFFER * ppDSBufferDuplicate
)

Parameters

  • pDSBufferOriginal
    Address of the IDirectSoundBuffer or IDirectSoundBuffer8 interface of the buffer to duplicate.
  • ppDSBufferDuplicate
    Address of a variable that receives the IDirectSoundBuffer interface pointer for the new buffer.

Return Value

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_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

Remarks

This method is not valid for buffers created with the DSBCAPS_CTRLFX flag.

Initially, the duplicate buffer will have the same parameters as the original buffer. However, the application can change the parameters of each buffer independently, and each can be played or stopped without affecting the other.

The buffer memory is released when the last object referencing it is released.

There is a known issue with volume levels of duplicated buffers. The duplicated buffer will play at full volume unless you change the volume to a different value than the original buffer's volume setting. If the volume stays the same (even if you explicitly set the same volume in the duplicated buffer with a IDirectSoundBuffer8::SetVolume call), the buffer will play at full volume regardless. To work around this problem, immediately set the volume of the duplicated buffer to something slightly different than what it was, even if you change it one millibel. The volume may then be immediately set back again to the original desired value.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound3d.dll.

See Also

IDirectSound8