IDirect3DDevice8::CopyRects

Copies rectangular subsets of pixels from one surface to another.

HRESULT CopyRects(
  IDirect3DSurface8* pSourceSurface,
  CONST RECT* pSourceRectsArray,
  UINT cRects,
  IDirect3DSurface8* pDestinationSurface,
  CONST POINT* pDestPointsArray
);

Parameters

pSourceSurface

[in] Pointer to an IDirect3DSurface8 interface, representing the source surface. This parameter must point to a different surface than pDestinationSurface.

pSourceRectsArray

[in] Pointer to an array of RECT structures, representing the rectangles to be transferred. Each rectangle will be transferred to the destination surface, with its top-left pixel at the position identified by the corresponding element of pDestPointsArray. Specifying NULL for this parameter causes the entire surface to be copied.

cRects

[in] Number of RECT structures contained in pSourceRectsArray.

pDestinationSurface

[in] Pointer to an IDirect3DSurface8 interface, representing the destination surface. This parameter must point to a different surface than pSourceSurface.

pDestPointsArray

[in] Pointer to an array of POINT structures, identifying the top-left pixel position of each rectangle contained in pSourceRectsArray. If this parameter is NULL, the RECTs are copied to the same offset (same top/left location) as the source rectangle.

Return Values

If the method succeeds, the return value is D3D_OK.

If the method fails, the return value can be one of the following values.

Remarks

This method does not support stretch, color key, alpha blend, format conversion, or clipping of either source or destination rectangles. Note that this method will fail unless all the source rectangles and their corresponding destination rectangles are completely contained within the source and destination surfaces respectively. The format of the two surfaces must match, but they can have different dimensions.

If the destination surface is level zero of a texture, then it will be marked dirty. See IDirect3DDevice8::UpdateTexture and IDirect3DTexture8::AddDirtyRect for more details.

This method cannot be applied to surfaces whose formats are classified as depth stencil formats.

A POINT structure defines the x- and y- coordinates of a point. For more information on POINT, see the Microsoft® Platform Software Development Kit (SDK).

This method can return D3DERR_DEVICELOST when the source object is in volatile memory (D3DPOOL_DEFAULT) and the destination object is in nonvolatile memory (D3DPOOL_SYSTEMMEM or D3DPOOL_MANAGED). For more information, see Lost Devices.

Requirements

  Header: Declared in D3d8.h.
  Import Library: Use D3d8.lib.