Edit

IWICBitmapSourceTransform::CopyPixels method (wincodec.h)

  • Article

Copies pixel data using the supplied input parameters.

Syntax

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

Parameters

[in] prc

Type: const WICRect*

The rectangle of pixels to copy.

[in] uiWidth

Type: UINT

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

[in] uiHeight

Type: UINT

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

[in] pguidDstFormat

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.

[in] dstTransform

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.

[in] nStride

Type: UINT

The stride of the destination buffer.

[in] cbBufferSize

Type: UINT

The size of the destination buffer.

[out] pbBuffer

Type: BYTE*

The output buffer.

Return value

Type: HRESULT

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

Remarks

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.

Requirements

Requirement Value
Minimum supported client Windows XP with SP2, Windows Vista [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 [desktop apps | UWP apps]
Target Platform Windows
Header wincodec.h
Library Windowscodecs.lib

See also

Conceptual

IWICBitmapSourceTransform

Microsoft Windows Imaging Codec

Programming Guide

References

Samples and Code Examples