IDirect3DTexture9::LockRect method (d3d9helper.h)

Locks a rectangle on a texture resource.

Syntax

HRESULT LockRect(
  [in]  UINT           Level,
  [out] D3DLOCKED_RECT *pLockedRect,
  [in]  const RECT     *pRect,
  [in]  DWORD          Flags
);

Parameters

[in] Level

Type: UINT

Specifies the level of the texture resource to lock.

[out] pLockedRect

Type: D3DLOCKED_RECT*

Pointer to a D3DLOCKED_RECT structure, describing the locked region.

[in] pRect

Type: const RECT*

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] Flags

Type: DWORD

Combination of zero or more locking flags that describe the type of lock to perform. For this method, the valid flags are:

• D3DLOCK_DISCARD
• D3DLOCK_NO_DIRTY_UPDATE
• D3DLOCK_NOSYSLOCK
• D3DLOCK_READONLY

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be D3DERR_INVALIDCALL.

Remarks

Textures created with D3DPOOL_DEFAULT are not lockable. Textures created in video memory are lockable when created with USAGE_DYNAMIC.

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 D3DLOCK_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 Direct3D 9 does not recognize. These can be locked.

This method cannot retrieve data from a texture resource created with D3DUSAGE_RENDERTARGET because such a texture must be assigned to D3DPOOL_DEFAULT memory and is therefore not lockable. In this case, use instead IDirect3DDevice9::GetRenderTargetData to copy texture data from device memory to system memory.

Requirements

See also

IDirect3DDevice9::GetRenderTargetData

IDirect3DDevice9::UpdateTexture

IDirect3DTexture9

IDirect3DTexture9::UnlockRect