IWICBitmapSourceTransform::CopyPixels method

Copies pixel data using the supplied input parameters.

Syntax


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

Parameters

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

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

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]

Header

Wincodec.h

IDL

Wincodec.idl

Library

Windowscodecs.lib

See also

IWICBitmapSourceTransform
Conceptual
Microsoft Windows Imaging Codec
Programming Guide
References
Samples and Code Examples

 

 

Community Additions

ADD
Show:
© 2014 Microsoft