mirror of https://github.com/microsoft/DirectXTex synced 2024-11-21 12:00:06 +00:00

Table of Contents

Parameters
Example
Remarks

DirectXTex

Copies a rectangle of pixels from one image to another.

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

Parameters

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).

struct Rect
{
    size_t x;
    size_t y;
    size_t w;
    size_t h;
}

filter: One or more Filter Flags. The default value is TEX_FILTER_DEFAULT. 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.

Example

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.Initialize2D( ... );

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) )
    ...

Remarks

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.