| Microsoft DirectX 8.1 (C++) |
The Lock method locks a portion of the buffer. Locking the buffer returns pointers into the buffer, allowing the application to read or write audio data into memory.
Syntax
HRESULT Lock(
DWORD dwOffset,
DWORD dwBytes,
LPVOID *ppvAudioPtr1,
LPDWORD pdwAudioBytes1,
LPVOID *ppvAudioPtr2,
LPDWORD pdwAudioBytes2,
DWORD dwFlags
);
Parameters
dwOffset
Value that specifies the offset, in bytes, from the start of the buffer to the point where the lock begins.
dwBytes
Value that specifies the size, in bytes, of the portion of the buffer to lock. Because the buffer is conceptually circular, 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. This value can be zero or the following flag:
| Value | Description |
| DSCBLOCK_ENTIREBUFFER | Ignore dwReadBytes and lock the entire capture 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 values:
| Return code |
| DSERR_INVALIDPARAM |
| DSERR_INVALIDCALL |
Remarks
This method accepts an offset and a byte count, and returns two read 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.
The application should read data from the pointers returned by this method and then immediately call IDirectSoundCaptureBuffer8::Unlock. The sound buffer should not remain locked while it is running; if it does, the capture cursor will reach the locked bytes and audio problems may result.
Requirements
Header: Declared in dsound.h.
See Also