IWICDdsFrameDecode::CopyBlocks method (wincodec.h)

Article
10/13/2021

Requests pixel data as it is natively stored within the DDS file.

Syntax

HRESULT CopyBlocks(
  [in]  const WICRect *prcBoundsInBlocks,
  [in]  UINT          cbStride,
  [in]  UINT          cbBufferSize,
  [out] BYTE          *pbBuffer
);

Parameters

[in] prcBoundsInBlocks

Type: const WICRect*

The rectangle to copy from the source. A NULL value specifies the entire texture.

If the texture uses a block-compressed DXGI_FORMAT, all values of the rectangle are expressed in number of blocks, not pixels.

[in] cbStride

Type: UINT

The stride, in bytes, of the destination buffer. This represents the number of bytes from the buffer pointer to the next row of data. If the texture uses a block-compressed DXGI_FORMAT, a "row of data" is defined as a row of blocks which contains multiple pixel scanlines.

[in] cbBufferSize

Type: UINT

The size, in bytes, of the destination buffer.

[out] pbBuffer

Type: BYTE*

A pointer to the destination buffer.

Return value

Type: HRESULT

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

Remarks

If the texture does not use a block-compressed DXGI_FORMAT, this method behaves similarly to IWICBitmapSource::CopyPixels. However, it does not perform any pixel format conversion, and instead produces the raw data from the DDS file.

If the texture uses a block-compressed DXGI_FORMAT, this method copies the block data directly into the provided buffer. In this case, the prcBoundsInBlocks parameter is defined in blocks, not pixels. To determine if this is the case, call GetFormatInfo and read the DxgiFormat member of the returned WICDdsFormatInfo structure.

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