IDirect3DDevice9::UpdateTexture method (d3d9.h)

Updates the dirty portions of a texture.

Syntax

HRESULT UpdateTexture(
  [in] IDirect3DBaseTexture9 *pSourceTexture,
  [in] IDirect3DBaseTexture9 *pDestinationTexture
);

Parameters

[in] pSourceTexture

Type: IDirect3DBaseTexture9*

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

[in] pDestinationTexture

Type: IDirect3DBaseTexture9*

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

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.

Remarks

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

IDirect3DDevice9::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 IDirect3DVolumeTexture9::LockBox is called without D3DLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY. Also, the destination surface of IDirect3DDevice9::UpdateSurface is marked dirty.

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


32x16, 16x8, 8x4, 4x2, 2x1, 1x1

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


1x1

For the following two-level destination.


2x1, 1x1

Or, for the following three-level destination.


4x2, 2x1, 1x1

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 fewer levels than the destination, the method will fail.

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

Here are the possibilities for source and destination surface combinations:

  • If pSourceTexture is a non-autogenerated mipmap and pDestinationTexture is an autogenerated mipmap, only the topmost matching level is updated, and the destination sublevels are regenerated. All other source sublevels are ignored.
  • If both pSourceTexture and pDestinationTexture are autogenerated mipmaps, only the topmost matching level is updated. The sublevels from the source are ignored and the destination sublevels are regenerated.
  • If pSourceTexture is an autogenerated mipmap and pDestinationTexture a non-autogenerated mipmap, UpdateTexture will fail.

Requirements

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

See also

IDirect3D9::CreateDevice

IDirect3DDevice9