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.
- IDirect3DCubeTexture9::AddDirtyRect
- IDirect3DTexture9::AddDirtyRect
- IDirect3DVolumeTexture9::AddDirtyBox
- IDirect3DDevice9::UpdateSurface
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 |