Edit

IDirect3DDevice9::UpdateSurface method (d3d9.h)

  • Article

Copies rectangular subsets of pixels from one surface to another.

Syntax

HRESULT UpdateSurface(
  [in] IDirect3DSurface9 *pSourceSurface,
  [in] const RECT        *pSourceRect,
  [in] IDirect3DSurface9 *pDestinationSurface,
  [in] const POINT       *pDestPoint
);

Parameters

[in] pSourceSurface

Type: IDirect3DSurface9*

Pointer to an IDirect3DSurface9 interface, representing the source surface. This parameter must point to a different surface than pDestinationSurface.

[in] pSourceRect

Type: const RECT*

Pointer to a rectangle on the source surface. Specifying NULL for this parameter causes the entire surface to be copied.

[in] pDestinationSurface

Type: IDirect3DSurface9*

Pointer to an IDirect3DSurface9 interface, representing the destination surface.

[in] pDestPoint

Type: const POINT*

Pointer to the upper left corner of the destination rectangle. Specifying NULL for this parameter causes the entire surface to be copied.

Return value

Type: HRESULT

If the method succeeds, the return value is D3D_OK. If the method fails, the return value can be one of the following: D3DERR_INVALIDCALL.

Remarks

This method is similar to CopyRects in DirectX 8.

This function has the following restrictions.

  • The source surface must have been created with D3DPOOL_SYSTEMMEM.
  • The destination surface must have been created with D3DPOOL_DEFAULT.
  • Neither surface can be locked or holding an outstanding device context.
  • Neither surface can be created with multisampling. The only valid flag for both surfaces is D3DMULTISAMPLE_NONE.
  • The surface format cannot be a depth stencil format.
  • The source and dest rects must fit within the surface.
  • No stretching or shrinking is allowed (the rects must be the same size).
  • The source format must match the dest format.
The following table shows the supported combinations.
Dest formats
Texture RT texture RT Off-screen plain
Src formats Texture Yes Yes Yes* Yes
RT texture No No No No
RT No No No No
Off-screen plain Yes Yes Yes Yes
 
  • If the driver does not support the requested copy, it will be emulated using lock and copy.

If the application needs to copy data from a D3DPOOL_DEFAULT render target to a D3DPOOL_SYSTEMMEM surface, it can use GetRenderTargetData.

Requirements

Requirement Value
Target Platform Windows
Header d3d9.h (include D3D9.h)
Library D3D9.lib

See also

IDirect3DDevice9