IDirect3DMobileDevice::UpdateTexture

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method updates the dirty portions of a texture.

Syntax

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

Parameters

• pSourceTexture
  [in] Pointer to an IDirect3DMobileBaseTexture interface that represents the source texture. The source texture must be in system memory (D3DMPOOL_SYSTEMMEM).

• pDestinationTexture
  [in] Pointer to an IDirect3DMobileBaseTexture interface that represents the destination texture.

Return Value

If the method succeeds, the return value is D3DM_OK (see D3DM Values).

If the method fails, the return value can be D3DMERR_INVALIDCALL (see D3DMERR Values).

Remarks

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

• IDirect3DMobileTexture::AddDirtyRect
• IDirect3DMobileDevice::CopyRects

IDirect3DMobileDevice::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 IDirect3DMobileTexture::LockRect is called without D3DMLOCK_NO_DIRTY_UPDATE or D3DLOCK_READONLY (see D3DMLOCK Values). Also, the destination surface of a IDirect3DMobileDevice::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 possible that bytes not marked dirty will be copied.

Requirements

See Also

Reference

IDirect3DMobileDevice
IDirect3DMobileBaseTexture
IDirect3DMobileTexture::AddDirtyRect
IDirect3DMobileDevice::CopyRects
IDirect3DMobileTexture::LockRect
D3DMLOCK Values