Direct3DDevice8.UpdateTexture

Updates the dirty portions of a texture.

object.UpdateTexture( _ 
    SourceTexture As Direct3DBaseTexture8, _ 
    DestinationTexture As Direct3DBaseTexture8)

Parts

object

Object expression that resolves to a Direct3DDevice8 object.

SourceTexture

A Direct3DBaseTexture8 object, representing the source texture. The source texture must be in system memory (D3DPOOL_SYSTEMMEM).

DestinationTexture

A Direct3DBaseTexture8 object, representing the destination texture. The destination texture must be in the D3DPOOL_DEFAULT memory pool.

Error Codes

If the method fails, an error is raised and Err.Number can be set to D3DERR_INVALIDCALL.

For information on trapping errors, see the Microsoft® Visual Basic® Error Handling topic.

Remarks

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

• Direct3DCubeTexture8.AddDirtyRect
• Direct3DTexture8.AddDirtyRect
• Direct3DVolumeTexture8.AddDirtyBox
• Direct3DDevice8.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.