Export (0) Print
Expand All

IDirect3DSurface9::LockRect method

Locks a rectangle on a surface.

Syntax


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

Parameters

pLockedRect [out]

Type: D3DLOCKED_RECT*

Pointer to a D3DLOCKED_RECT structure that describes the locked region.

pRect [in]

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 surface.

Flags [in]

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_DONOTWAIT
  • 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.

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

Remarks

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.

This method cannot retrieve data from a surface that is is contained by 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

Header

D3D9.h

Library

D3D9.lib

See also

IDirect3DSurface9
IDirect3DSurface9::UnlockRect

 

 

Community Additions

ADD
Show:
© 2015 Microsoft