Device.UpdateTexture(BaseTexture,BaseTexture) Method (Microsoft.DirectX.Direct3D)

  • Article

Updates the dirty portions of a texture.

Definition

Visual Basic Public Sub UpdateTexture( _
    ByVal sourceTexture As BaseTexture, _
    ByVal destinationTexture As BaseTexture _
)
C# public void UpdateTexture(
    BaseTexture sourceTexture,
    BaseTexture destinationTexture
);
C++ public:
void UpdateTexture(
    BaseTexture^ sourceTexture,
    BaseTexture^ destinationTexture
);
JScript public function UpdateTexture(
    sourceTexture : BaseTexture,
    destinationTexture : BaseTexture
);

Parameters

sourceTexture Microsoft.DirectX.Direct3D.BaseTexture
A BaseTexture object that represents the source texture, which must be in system memory (Pool.SystemMemory).
destinationTexture Microsoft.DirectX.Direct3D.BaseTexture
A BaseTexture object that represents the destination texture, which must be in the default memory pool (Pool.Default).

Remarks

To dirty a portion of a texture, either lock it or call one of the following methods.

Device.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 recorded only for level 0 of a texture. For sublevels, it is assumed that the corresponding (scaled) rectangle or box is also dirty. Dirty regions are automatically recorded when Texture.LockRectangle or VolumeTexture.LockBox is called without LockFlags.NoDirtyUpdate or LockFlags.ReadOnly. Also, the destination surface of Device.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 fails 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 fails.

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

The following scenarios are supported for source and destination surface combinations.

  • If sourceTexture is a non-autogenerated mipmap and destinationTexture 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 sourceTexture and destinationTexture are autogenerated mipmaps, only the topmost matching level is updated. The sublevels from the source are ignored and the destination sublevels are regenerated.
  • If sourceTexture is an autogenerated mipmap and destinationTexture a non-autogenerated mipmap, this method fails.

Exceptions

InvalidCallException

The method call is invalid. For example, a method's parameter might contain an invalid value.