Microsoft DirectX 9.0

IDirect3DTexture9::LockRect Method

Locks a rectangle on a texture resource.


HRESULT LockRect(      

    UINT Level,     D3DLOCKED_RECT *pLockedRect,     CONST RECT *pRect,     DWORD Flags );


[in] Specifies the level of the texture resource to lock.
[out] Pointer to a D3DLOCKED_RECT structure, describing 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 texture.
[in] Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:

For a description of the flags, see D3DLOCK.

Return Value

If the method succeeds, the return value is D3D_OK.

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


Textures created with D3DPOOL_DEFAULT are not lockable. Textures created in video memory are lockable when created with USAGE_DYNAMIC. For more information about usages, see D3DUSAGE.

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

The only lockable format for a depth-stencil texture is D3DFMT_D16_LOCKABLE.

Video memory textures cannot be locked, but must be modified by calling IDirect3DDevice9::UpdateSurface or IDirect3DDevice9::UpdateTexture. There are exceptions for some proprietary driver pixel formats that Microsoft?DirectX?9.0 does not recognize. These can be locked.

See Also

IDirect3DTexture9::UnlockRect, IDirect3DDevice9::UpdateTexture

© 2002 Microsoft Corporation. All rights reserved.