IDirect3DDevice8::UpdateTexture

Updates the dirty portions of a texture.

HRESULT UpdateTexture(
  IDirect3DBaseTexture8* pSourceTexture,
  IDirect3DBaseTexture8* pDestinationTexture
);

Parameters

pSourceTexture

[in] Pointer to an IDirect3DBaseTexture8 interface, representing the source texture. The source texture must be in system memory (D3DPOOL_SYSTEMMEM).

pDestinationTexture

[in] Pointer to an IDirect3DBaseTexture8 interface, representing the destination texture. The destination texture must be in the D3DPOOL_DEFAULT memory pool.

Return Values

If the method succeeds, the return value is D3D_OK.

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

Remarks

You can dirty a portion of a texture by locking it, or by calling one of the following methods.

• IDirect3DCubeTexture8::AddDirtyRect
• IDirect3DTexture8::AddDirtyRect
• IDirect3DVolumeTexture8::AddDirtyBox
• IDirect3DDevice8::CopyRects

UpdateTexture retrieves the dirty portions of the texture by calculating what has been accumulated since the last update operation.

For performance reasons, dirty regions are only recorded for level zero of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when LockRect or LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the destination surface of a CopyRects call is marked dirty.

This method fails if the textures are of different types, if their bottom-level buffers are of different sizes, and also if their matching levels do not match. For example, consider a six level source texture with the following dimensions.

32×16, 16×8, 8×4, 4×2, 2×1, 1×1

This six level source texture could be the source for the following one level destination.

1×1

For the following two level destination.

2×1, 1×1

Or, for the following three level destination.

4×2, 2×1, 1×1

In addition, this method will fail if the textures are of different formats. If the destination texture has fewer levels than the source, only the matching levels are copied.

If the source texture has dirty regions, the copy may be optimized by restricting the copy to only those regions. It is not guaranteed that only those bytes marked dirty will be copied.

Requirements

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

See Also

IDirect3D8::CreateDevice