Edit

Implementing IWICBitmapFrameDecode

  • Article

IWICBitmapFrameDecode

IWICBitmapFrameDecode is the frame-level interface that provides access to the actual image bits. You implement this interface on your frame-level decoding class. Because it’s derived from IWICBitmapSource, your implementation of IWICBitmapFrameDecode will include an implementation of the IWICBitmapSource methods. The additional methods on IWICBitmapFrameDecode provide access to the frame-level thumbnail, any color contexts for the image, and the metadata query reader for the frame.

interface IWICBitmapFrameDecode : IWICBitmapSource
{
// Required methods
HRESULT GetThumbnail ( IWICBitmapSource **ppIThumbnail );
HRESULT GetColorContexts ( UINT cCount, 
IWICColorContext **ppIColorContexts, UINT *pcActualCount );
HRESULT GetMetadataQueryReader ( IWICMetadataQueryReader **ppIMetadataQueryReader );

// Methods inherited from IWICBitmapSource
HRESULT GetSize ( UINT *puiWidth, UINT *puiHeight );
HRESULT GetPixelFormat ( WICPixelFormatGUID *pPixelFormat );
HRESULT GetResolution ( double *pDpiX, double *pDpiY );
HRESULT CopyPixels ( const WICRect *prc, 
   UINT cbStride,
   UINT cbBufferSize, 
   BYTE *pbBuffer );
// Optional method
HRESULT CopyPalette ( IWICPalette *pIPalette );
}

GetThumbnail

GetThumbnail returns the thumbnail for the current frame. For performance reasons, thumbnails are most commonly encoded in a JPEG format. Just as with the Preview on the decoder, it is not necessary or recommended to provide your own JPEG decoder for thumbnails. Instead, you should delegate to the JPEG decoder provided by Windows Imaging Component (WIC).

For more information on thumbnails, see the SetThumbnail method on Implementing IWICBitmapFrameEncode.

GetColorContexts

GetColorContexts returns the valid color contexts (also known as color profiles) associated with the image in this frame. In most cases, this will only be one, but there could be cases where there are two or, rarely, more. The caller will pass in one or more IWICColorContext objects, setting the cCount parameter to indicate how many they are passing in. This method populates the IWICColorContext objects with the actual color context data for the color profiles associated with the image. Set the pcActualCount parameter to the actual number of color contexts associated with the image, even if this is greater than the number you can return. (In the case where more color contexts are available than the number of IWICColorContext objects passed in by the caller, this tells the caller there are one or more others available.)

GetMetadataQueryReader

GetMetadataQueryReader returns an IWICMetadataQueryReader that an application can use to retrieve metadata from the image frame. This interface is implemented by a metadata handler, and allows an application to query for specific metadata properties belonging to a particular metadata format. For more information, see Implementing IWICMetadataBlockReader.

To instantiate an IWICMetadataQueryReader, call CreateQueryReaderFromBlockReader on the IWICComponentFactory.

IWICMetadataQueryReader* pQueryReader = NULL;
HRESULT hr;

hr = m_pComponentFactory->CreateQueryReaderFromBlockReader( 
  static_cast<IWICMetadataBlockWriter*>(this),
  &pQueryReader);

GetSize, GetPixelFormat, and GetResolution

GetSize, GetPixelFormat, and GetResolution are self-explanatory, and return the requested properties of the image.

CopyPixels

CopyPixels is the method an application calls when it wants to create a bitmap in memory that can be rendered to the display or printer. This is the method that does the actual decoding of the image bits. The parameters are a rectangle, which represents the region of interest in the source image to copy into memory; the stride, which specifies the number of bytes in one scan line; the size of the buffer in memory that has been allocated by the application; and a pointer to the buffer into which the requested image bits should be copied. (To prevent potential buffer overruns from introducing security vulnerabilities, be sure to copy only as much image data into the buffer as the cbBufferSize parameter specifies.)

CopyPalette

Only codecs that have indexed pixel formats must implement the CopyPalette method. If an image uses an indexed format, use this method to return the palette of colors used in the image. If your codec doesn’t have an indexed format, return WINCODEC_ERR_PALETTEUNAVAILABLE.

Reference

IWICBitmapSource

IWICBitmapDecoder

IWICBitmapFrameDecode

Conceptual

Implementing IWICBitmapSource

Implementing IWICMetadataBlockReader

How to Write a WIC-Enabled CODEC

Windows Imaging Component Overview