Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

IDirect3DDevice9::UpdateTexture method

Updates the dirty portions of a texture.

Syntax


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

Parameters

pSourceTexture [in]

Type: IDirect3DBaseTexture9*

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

pDestinationTexture [in]

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

Header

D3D9.h

Library

D3D9.lib

See also

IDirect3DDevice9
IDirect3D9::CreateDevice

 

 

Community Additions

ADD
Show:
© 2015 Microsoft