IDirect3DVolume8::LockBox

Locks a box on a volume resource.

HRESULT LockBox(
  D3DLOCKED_BOX* pLockedVolume,
  CONST D3DBOX* pBox,
  DWORD Flags
);

Parameters

pLockedVolume

[out] Pointer to a D3DLOCKED_BOX structure, describing the locked region.

pBox

[in] Pointer to a box to lock. Specified by a pointer to a D3DBOX structure. Specifying NULL for this parameter locks the entire volume.

Flags

[in] A combination of zero or more locking flags, describing the type of lock to perform.

D3DLOCK_DISCARD

The application overwrites, with a write-only operation, every location within the region being locked. This is a valid flag only when using dynamic textures.

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 volumes changed during the lock operation.

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

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

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.

See Also

IDirect3DVolume8::UnlockBox