Edit

Share via

IWICPlanarBitmapSourceTransform::CopyPixels method (wincodec.h)

  • Article

Copies pixels into the destination planes. Configured by the supplied input parameters.

If a dstTransform, scale, or format conversion is specified, cbStride is the transformed stride and is based on the destination pixel format of the pDstPlanes parameter, not the original source's pixel format.

Syntax

HRESULT CopyPixels(
  [in] const WICRect             *prcSource,
       UINT                      uiWidth,
       UINT                      uiHeight,
       WICBitmapTransformOptions dstTransform,
  [in] WICPlanarOptions          dstPlanarOptions,
       const WICBitmapPlane      *pDstPlanes,
       UINT                      cPlanes
);

Parameters

[in] prcSource

Type: const WICRect*

The source rectangle of pixels to copy.

uiWidth

Type: UINT

The width to scale the source bitmap. This parameter must be equal to a value obtainable through IWICPlanarBitmapSourceTransform:: DoesSupportTransform.

uiHeight

Type: UINT

The height to scale the source bitmap. This parameter must be equal to a value obtainable through IWICPlanarBitmapSourceTransform:: DoesSupportTransform.

dstTransform

Type: WICBitmapTransformOptions

The desired rotation or flip to perform prior to the pixel copy. A rotate can be combined with a flip horizontal or a flip vertical, see WICBitmapTransformOptions.

[in] dstPlanarOptions

Type: const WICPlanarOptions

Used to specify additional configuration options for the transform. See WICPlanarOptions for more detail.

WIC JPEG Decoder: WICPlanarOptionsPreserveSubsampling can be specified to retain the subsampling ratios when downscaling. By default, the JPEG decoder attempts to preserve quality by downscaling only the Y plane in some cases, changing the image to 4:4:4 chroma subsampling.

pDstPlanes

Type: WICBitmapPlane

Specifies the pixel format and output buffer for each component plane. The number of planes and pixel format of each plane must match values obtainable through IWICPlanarBitmapSourceTransform::DoesSupportTransform.

cPlanes

Type: UINT

The number of component planes specified by the pDstPlanes parameter.

Return value

Type: HRESULT

If the specified scale, flip/rotate, and planar format configuration is not supported this method fails with WINCODEC_ERR_INVALIDPARAMETER. You can check if a transform is supported by calling IWICPlanarBitmapSourceTransform::DoesSupportTransform.

Remarks

WIC JPEG Decoder: Depending on the configured chroma subsampling of the image, the source rectangle has the following restrictions:

Chroma Subsampling X Coordinate Y Coordinate Chroma Width Chroma Height
4:2:0 Multiple of 2 Multiple of 2 lumaWidth / 2 Rounded up to the nearest integer. lumaHeight / 2 Rounded up to the nearest integer.
4:2:2 Multiple of 2 Any lumaWidth / 2 Rounded up to the nearest integer. lumaHeight
4:4:4 Any Any llumaWidth llumaHeight
4:4:0 Any Multiple of 2 lumaWidth llumaHeight / 2 Rounded up to the nearest integer.
 

The pDstPlanes parameter supports the following pixel formats.

Plane Count Plane 1 Plane 2 Plane 3
3 GUID_WICPixelFormat8bppY GUID_WICPixelFormat8bppCb GUID_WICPixelFormat8bppCr
2 GUID_WICPixelFormat8bppY GUID_WICPixelFormat16bppCbCr N/A

Requirements

Requirement Value
Minimum supported client Windows 8.1 [desktop apps | UWP apps]
Minimum supported server Windows Server 2012 R2 [desktop apps | UWP apps]
Target Platform Windows
Header wincodec.h
Library Windowscodecs.lib
DLL Windowscodecs.dll

See also

IWICPlanarBitmapSourceTransform