IDirect3DCubeTexture9::LockRect method (d3d9helper.h)

Article
02/22/2024

Locks a rectangle on a cube texture resource.

Syntax

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

Parameters

[in] FaceType

Type: D3DCUBEMAP_FACES

Member of the D3DCUBEMAP_FACES enumerated type, identifying a cube map face.

[in] Level

Type: UINT

Specifies a level of a mipmapped cube texture.

[out] pLockedRect

Type: D3DLOCKED_RECT*

Pointer to a D3DLOCKED_RECT structure, describing the region to lock.

[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 cube 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

You may not specify a subrect when using D3DLOCK_DISCARD. For a description of the flags, see D3DLOCK.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. D3DERR_INVALIDCALL is returned if one or more of the arguments is invalid.

Remarks

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

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

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

Requirements

Requirement	Value
Target Platform	Windows
Header	d3d9helper.h (include D3D9.h)
Library	D3D9.lib