Edit

IWICDdsDecoder::GetFrame method (wincodec.h)

  • Article

Retrieves the specified frame of the DDS image.

Syntax

HRESULT GetFrame(
  [in]  UINT                  arrayIndex,
  [in]  UINT                  mipLevel,
  [in]  UINT                  sliceIndex,
  [out] IWICBitmapFrameDecode **ppIBitmapFrame
);

Parameters

[in] arrayIndex

Type: UINT

The requested index within the texture array.

[in] mipLevel

Type: UINT

The requested mip level.

[in] sliceIndex

Type: UINT

The requested slice within the 3D texture.

[out] ppIBitmapFrame

Type: IWICBitmapFrameDecode**

A pointer to a IWICBitmapFrameDecode object.

Return value

Type: HRESULT

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

Remarks

A DDS file can contain multiple images that are organized into a three level hierarchy. First, DDS file may contain multiple textures in a texture array. Second, each texture can have multiple mip levels. Finally, the texture may be a 3D (volume) texture and have multiple slices, each of which is a 2D texture. See the DDS documentation for more information.

WIC maps this three level hierarchy into a linear array of IWICBitmapFrameDecode, accessible via IWICBitmapDecoder::GetFrame. However, determining which frame corresponds to a triad of arrayIndex, mipLevel, and sliceIndex value is not trivial because each mip level of a 3D texture has a different depth (number of slices). This method provides additional convenience over IWICBitmapDecoder::GetFrame for DDS images by calculating the correct frame given the three indices.

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

CreateBitmap

ID3D11Device::CreateTexture2D

IWICDdsDecoder

WICDdsFormatInfo