Partager via

IDirect3DTexture8::LockRect

  • Article

This method locks a rectangle on a texture resource.

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

Parameters

  • Level
    [in] Specifies the level of the texture resource to lock.
  • pLockedRect
    [out] Pointer to a D3DLOCKED_RECT structure, describing the locked region.
  • pRect
    [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.
  • Flags
    [in] Combination of zero or more locking flags, describing the type of lock to perform. The following table shows the available flags.
    Flag Description
    D3DLOCK_NO_DIRTY_UPDATE By default, a lock on a resource adds a dirty region to that resource. This flag prevents any changes to the dirty state of the resource. Applications should use this flag when they have additional information about the actual set of regions changed during the lock operation and can then pass this information to IDirect3DTexture8::AddDirtyRect.
    D3DLOCK_NOSYSLOCK The default behavior of a video memory lock is to reserve a system-wide critical section, guaranteeing that no display mode changes will occur for the duration of the lock. This flag causes the system-wide critical section not to be held for the duration of the lock.

    The lock operation is slightly more expensive, but can enable the system to perform other duties, such as moving the mouse cursor. This flag is useful for long-duration locks, such as the lock of the back buffer for software rendering that would otherwise adversely affect system responsiveness.
    D3DLOCK_READONLY The application will not write to the buffer. This enables resources stored in non-native formats to save the recompression step when unlocking.

Return Values

If the method succeeds, the return value is D3D_OK.

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

Remarks

Textures created in D3DPOOL_DEFAULT are not-lockable.

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

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

A multisample backbuffer cannot be locked. Video memory textures cannot be locked, but must be modified by calling IDirect3DDevice8::CopyRects or IDirect3DDevice8::UpdateTexture. There are exceptions for some proprietary driver pixel formats that Microsoft® DirectX® 8.0 does not recognize. These can be locked.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: D3d8.h.
Link Library: D3d8.lib.

See Also

IDirect3DDevice8::CopyRects | IDirect3DDevice8::UpdateTexture | IDirect3DTexture8::AddDirtyRect | IDirect3DTexture8::UnlockRect | D3DLOCKED_RECT | RECT | IDirect3DTexture8

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.