IDirectSoundBuffer8::Lock Method

  • Article

[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 Lock method readies all or part of the buffer for a data write and returns pointers to which data can be written.

Syntax

HRESULT Lock(
         DWORD dwOffset,
         DWORD dwBytes,
         LPVOID * ppvAudioPtr1,
         LPDWORD  pdwAudioBytes1,
         LPVOID * ppvAudioPtr2,
         LPDWORD pdwAudioBytes2,
         DWORD dwFlags
)

Parameters

  • dwOffset
    Offset, in bytes, from the start of the buffer to the point where the lock begins. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the dwFlags parameter.
  • dwBytes
    Size, in bytes, of the portion of the buffer to lock. The buffer is conceptually circular, so this number can exceed the number of bytes between dwOffset and the end of the buffer.
  • ppvAudioPtr1
    Address of a variable that receives a pointer to the first locked part of the buffer.
  • pdwAudioBytes1
    Address of a variable that receives the number of bytes in the block at ppvAudioPtr1. If this value is less than dwBytes, the lock has wrapped and ppvAudioPtr2 points to a second block of data at the beginning of the buffer.
  • ppvAudioPtr2
    Address of a variable that receives a pointer to the second locked part of the capture buffer. If NULL is returned, the ppvAudioPtr1 parameter points to the entire locked portion of the capture buffer.
  • pdwAudioBytes2
    Address of a variable that receives the number of bytes in the block at ppvAudioPtr2. If ppvAudioPtr2 is NULL, this value is zero.
  • dwFlags
    Flags modifying the lock event. The following flags are defined:
    Value Description
    DSBLOCK_FROMWRITECURSOR Start the lock at the write cursor. The dwOffset parameter is ignored.
    DSBLOCK_ENTIREBUFFER Lock the entire buffer. The dwBytes parameter is ignored.

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_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

Remarks

This method accepts an offset and a byte count, and returns two write pointers and their associated sizes. If the locked portion does not extend to the end of the buffer and wrap to the beginning, the second pointer, ppvAudioBytes2, receives NULL. If the lock does wrap, ppvAudioBytes2 points to the beginning of the buffer.

If the application passes NULL for the ppvAudioPtr2 and pdwAudioBytes2 parameters, the lock extends no further than the end of the buffer and does not wrap.

After writing data to the pointers returned by this method, the application must immediately call Unlock to notify DirectSound that the data is ready for playback. Failure to do so can cause audio breakup or silence on some sound device configurations.

This method returns write pointers only. The application should not try to read sound data from this pointer, because the data might not be valid. For example, if the buffer is located in on-card memory, the pointer might be an address to a temporary buffer in system memory. When IDirectSoundBuffer8::Unlock is called, the contents of this temporary buffer are transferred to the on-card memory.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound3d.dll.

See Also

IDirectSoundBuffer8