Microsoft DirectX 9.0

IDirect3DSurface9::LockRect Method

Locks a rectangle on a surface.


HRESULT LockRect(      

    D3DLOCKED_RECT *pLockedRect,     const RECT *pRect,     DWORD Flags );


[out] Pointer to a D3DLOCKED_RECT structure that describes the locked region.
[in] Pointer to a rectangle to lock. Specified by a pointer to a RECT structure. Specifying NULL for this parameter expands the dirty region to cover the entire surface.
[in] Combination of zero or more locking flags that describe the type of lock to perform. For this method, all of the flags in D3DLOCK are valid except D3DLOCK_NOOVERWRITE.

Return Value

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be D3DERR_INVALIDCALL or D3DERR_WASSTILLDRAWING.


If the D3DLOCK_DONOTWAIT flag is specified and the driver cannot lock the surface immediately, IDirect3DSurface9::LockRect will return D3DERR_WASSTILLDRAWING so that an application can use the CPU cycles while waiting for the driver to lock the surface.

The only lockable format for a depth-stencil surface is D3DFMT_D16_LOCKABLE. See D3DFORMAT.

For performance reasons, dirty regions are recorded only for level zero of a texture. Dirty regions are automatically recorded when IDirect3DSurface9::LockRect is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. See IDirect3DDevice9::UpdateTexture for more information.

A multisample back buffer cannot be locked.

See Also


© 2002 Microsoft Corporation. All rights reserved.