Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IWICBitmapSourceTransform::CopyPixels method

Copies pixel data using the supplied input parameters.


HRESULT CopyPixels(
  [in, unique] const WICRect                   *prc,
  [in]               UINT                      uiWidth,
  [in]               UINT                      uiHeight,
  [in, unique]       WICPixelFormatGUID        *pguidDstFormat,
  [in]               WICBitmapTransformOptions dstTransform,
  [in]               UINT                      nStride,
  [in]               UINT                      cbBufferSize,
  [out]              BYTE                      *pbBuffer


prc [in]

Type: const WICRect*

The rectangle of pixels to copy.

uiWidth [in]

Type: UINT

The width to scale the source bitmap. This parameter must equal the value obtainable through IWICBitmapSourceTransform::GetClosestSize.

uiHeight [in]

Type: UINT

The height to scale the source bitmap. This parameter must equal the value obtainable through IWICBitmapSourceTransform::GetClosestSize.

pguidDstFormat [in]

Type: WICPixelFormatGUID*

The GUID of desired pixel format in which the pixels should be returned.

This GUID must be a format obtained through an GetClosestPixelFormat call.

dstTransform [in]

Type: WICBitmapTransformOptions

The desired rotation or flip to perform prior to the pixel copy.

The transform must be an operation supported by an DoesSupportTransform call.

If a dstTransform is specified, nStride is the transformed stride and is based on the pguidDstFormat pixel format, not the original source's pixel format.

nStride [in]

Type: UINT

The stride of the destination buffer.

cbBufferSize [in]

Type: UINT

The size of the destination buffer.

pbBuffer [out]

Type: BYTE*

The output buffer.

Return value


If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.


Codec Developer Remarks

If NULL is passed in for prc, the entire image is copied.

For codec developer implementation details for this method, see Implementing IWICBitmapSourceTransform.

When multiple transform operations are requested, the result is dependent on the order in which the operations are performed. To ensure predictability and consistency across CODECs, it's important that all CODECs perform these operations in the same order. The recommended order of these operations is:

  1. Scale
  2. Crop
  3. Flip/Rotate

Pixel format conversion can be performed at any time, since it has no effect on the other transforms.

The first parameter, prc is used to specify the region of interest for clipping the image. By convention, scaling is performed before clipping so, if the image is to be scaled as well as clipped, the region of interest should be determined after the image has been scaled.

If a dstTransform is specified, the stride is the transformed stride, and is based on the pixelFormat specified in the CopyPixels call, not the original frame's pixel format.


Minimum supported client

Windows XP with SP2, Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]







See also

Microsoft Windows Imaging Codec
Programming Guide
Samples and Code Examples



© 2016 Microsoft