Direct3DDevice8.CopyRects

Copies rectangular subsets of pixels from one surface to another.

object.CopyRects( _ 
    SourceSurface As Direct3DSurface8, _ 
    FirstElementOfSourceRectsArray As Any, _ 
    NumberOfRects As Long, _ 
    DestinationSurface As Direct3DSurface8, _ 
    FirstElementofDestPointArray As Any)

Parts

object

Object expression that resolves to a Direct3DDevice8 object.

SourceSurface

A Direct3DSurface8 object, representing the source surface. This parameter must be a different surface object than DestinationSurface.

FirstElementOfSourceRectsArray

First element of an array representing the rectangles to be transferred, or ByVal 0 to specify that the entire surface is copied. Each rectangle is transferred to the destination surface, with its top-left pixel at the position identified by the corresponding element of FirstElementofDestPointArray.

NumberOfRects

Number of rectangles contained in FirstElementOfSourceRectsArray.

DestinationSurface

A Direct3DSurface8 object, representing the destination surface. This parameter must be a different surface object than SourceSurface.

FirstElementofDestPointArray

First element of an array that defines a series of points, identifying the top-left pixel position of each rectangle contained in FirstElementOfSourceRectsArray. If this parameter is ByVal 0, the rectangles are copied to the same offset (same top/left location) as the source rectangle.

Error Codes

If the method fails, an error is raised and Err.Number can be set to one of the following values.

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

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 a level-zero of a texture, then it will be marked dirty. See Direct3DDevice8.UpdateTexture and Direct3DTexture8.AddDirtyRect for more details.

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

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.