IDirect3DVertexBuffer7::Lock

The IDirect3DVertexBuffer::Lock methods locks a vertex buffer and obtains a pointer to the vertex buffer memory.

HRESULT Lock(
  DWORD   dwFlags,  
  LPVOID* lplpData, 
  LPDWORD lpdwSize  
); 

Parameters

dwFlags

Flags indicating how the vertex buffer memory should be locked.

DDLOCK_EVENT

Not currently implemented.

DDLOCK_NOSYSLOCK

If possible, do not take the Win16Mutex (also known as Win16Lock).

DDLOCK_READONLY

Indicates that the memory being locked is only to be read from.

DDLOCK_SURFACEMEMORYPTR

Indicates that a valid memory pointer to the vertex buffer is returned; this is the default.

DDLOCK_WAIT

If a lock cannot be obtained immediately, the method retries until a lock is obtained or another error occurs.

DDLOCK_WRITEONLY

Indicates that the memory being locked is only to be written to.

DDLOCK_DISCARDCONTENTS

New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no assumptions are made about the contents of the vertex buffer during this lock. This enables Direct3D or the driver to provide an alternative memory area as the vertex buffer. This is useful when you plan to clear the contents of the vertex buffer and fill in new data.

DDLOCK_NOOVERWRITE

New for DirectX 7.0. Used only with Direct3D vertex-buffer locks. Indicates that no vertices that were referred to in vertex-buffer DrawPrimitive calls since the start of the frame (or the last lock without this flag) are modified during the lock. This can be useful when you want only to append data to the vertex buffer.

lplpData

Address of a variable that receives the address of the vertex buffer memory if the call succeeds.

lpdwSize

Address of a variable that receives the size of the vertex buffer memory at lplpData. Set to NULL if the buffer size is not needed.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values:

Remarks

After locking the vertex buffer, you can access the memory until a corresponding call to IDirect3DVertexBuffer7::Unlock.

You cannot render from a locked vertex buffer; calls to the IDirect3DDevice7::DrawIndexedPrimitiveVB or IDirect3DDevice7::DrawPrimitiveVB method using a locked buffer fail, returning D3DERR_VERTEXBUFFERLOCKED.

This method often causes the system to hold the Win16Mutex until you call the IDirect3DVertexBuffer7::Unlock method. GUI debuggers cannot operate while the Win16Mutex is held.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Version: Requires DirectX 7.0.
  Header: Declared in d3d.h.

See Also

IDirect3DVertexBuffer7::Unlock, Accessing the Contents of a Vertex Buffer