Copies a rectangle of pixels from one image to another.

HRESULT CopyRectangle( _In_ const Image& srcImage, _In_ const Rect& srcRect,
   _In_ const Image& dstImage,
   _In_ DWORD filter, _In_ size_t xOffset, _In_ size_t yOffset );


srcRect: A rectangle described with x, y of the upper right corner, and w and h with the width and height, which indicates pixel location from srcImage to copy. The w and h also define the size of the destination rectangle in dstImage. Both rectangles must be valid for the size of the images (i.e. the API does not support clipping).

filter: See Filter Flags. Source and destination images do not need to be the same format, in which case conversions will use these flags.

xOffset, yOffset: Pixel location of destination rectangle in dstImage. The width and height of the destination rectangle is the same as srcRect.w and srcRect.h.


Here's an example that copies a source image to the location (100,50) location in a new, larger image.

ScratchImage srcImage;


ScratchImage destImage;
destImage.Iniitalize2D( ... );

auto mdata = srcImage.GetMetadata();
Rect r( 0, 0, mdata.width, mdata.height );
hr = CopyRectangle( *srcImage.GetImage(0,0,0), r, *dstImage.GetImage(0,0,0), 
   TEX_FILTER_DEFAULT, 100, 50 );
if ( FAILED(hr) )


Behavior of this function is not defined if the source and destination image are the same and the source and destination rectangles overlap.

Block compressed images are not supported as either the source or destination. Use Decompress to uncompress BC images before using this function.

This function cannot operate directly on a planar format image. See ConvertToSinglePlane for a method for converting planar data to a format that is supported by this routine.

Last edited Jun 22, 2015 at 7:01 AM by walbourn, version 6