Windows Imaging Component Codec Guidelines for Camera RAW Image Formats - 2

Windows Imaging Component Codec Guidelines for Camera RAW Image Formats - 2

Windows Imaging Component Codec Guidelines for Camera RAW Image Formats

October 19, 2012

Abstract

The Microsoft Windows Imaging Component (WIC) provides an extensible framework for working with images and image metadata. WIC makes it possible for software and hardware vendors to develop codecs so that their own image formats can obtain the same platform support as native image formats such as tagged image file format (TIFF), Joint Photographic Experts Group (JPEG), or Windows Media Photo.

This paper provides guidelines to help RAW format manufacturers in their development of WIC codecs.

This information applies to the following operating systems:

Windows Imaging Component (WIC)

Windows 7

Windows Vista

Microsoft Windows XP

References and resources discussed here are listed at the end of this paper.

The current version of this paper is maintained on the Web at:
Windows Imaging Component Codec Guidelines for Camera RAW Image Formats

Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious.No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2012 Microsoft. All rights reserved.

Document History

Date / Change /
October 19, 2012 / Updated to current template; fixed links in Resources section

Contents

Contents 2

Introduction 3

RAW Image Formats in Windows 3

General Guidelines for Implementing RAW Codecs 3

Feature Completeness: Required Interfaces 4

Required Methods on Each Interface 5

Metadata Support 7

Decoding 8

Encoding 9

Support for IWICDevelopRaw 9

Implementation Guidelines for Serializing IWICDevelopRAW Settings 10

Performance 12

High Dynamic Range Pixel Formats 12

Thumbnails and Previews 13

Reliability and Security 13

Codec Availability and Platform Support 15

Codec Discovery 15

Windows XP Platform Support 16

RAW Codec Requirements for Windows 7 16

For More Information 17

October 19, 2012
© 2012 Microsoft. All rights reserved.

Windows Imaging Component Codec Guidelines for Camera RAW Image Formats - 17

Introduction

The Microsoft® Windows® Imaging Component (WIC) provides an extensible framework for working with images and image metadata. WIC makes it possible for software and hardware vendors to develop codecs so that their own image formats can get the same platform support as native image formats such as tagged image file format (TIFF), Joint Photographic Experts Group (JPEG), or HD Photo.

WIC provides a single, consistent set of interfaces for all image processing, regardless of image format. Therefore, any application that uses WIC receives automatic support for new image formats as soon as the codec is installed. WIC also provides an extensible metadata framework that makes it possible for applications to read and write their own proprietary metadata directly to image files, so the metadata is never lost or separated from the image.

WIC is included with Windows Presentation Foundation (WPF) and is built into Windows Vista and additional Windows versions. It is also available as a stand-alone redistributable component for Microsoft WindowsXP.

These guidelines are designed to help RAW format manufacturers in their development of WIC codecs.

RAW Image Formats in Windows

Windows Vista Explorer, Windows Vista Photo Gallery, Window Live Photo Gallery, and the Windows 7 Photo Viewer all use WIC and therefore support RAW image formats when appropriate codecs are installed on the computer.

Because WIC is an extensible imaging architecture, any WIC application can consume new image formats as soon as new codecs are installed on the system. This makes WIC ideal as a Plug and Play solution for the RAW image formats that digital cameras produce. Through WIC, Windows applications can gain support for new camera models whenever updated codecs are made available (ideally in-box with new cameras). Codec authors can support these scenarios by implementing WIC interfaces that are common to all image types, as described in more detail in this document.

Today, most mainstream consumer applications have no special knowledge of RAW image formats and do not expose a user interface for adjusting RAW processing settings.

However, to support specialized imaging applications, RAW codec authors must also implement the IWICDevelopRAW interface. This interface exposes special features for RAW images, such as the ability to make common image adjustments and to process (develop) RAW images into specified red-green-blue (RGB) color spaces.

Several other WIC interfaces are important for RAW codec authors to implement. These are discussed in more detail in this document.

General Guidelines for Implementing RAW Codecs

Compared to non-RAW image types such as JPEG or TIFF, there are two notable differences in how RAW image formats are expected to behave in Windows:

·  Most RAW image formats are presumed to be “read only” and probably will not support pixel encoding to RAW format. However, because WIC requires an encoder to support metadata write-back, RAW codec authors should plan to implement at least a skeleton encoder class.

·  Decoding a full-size RAW image can take a long time compared to other formats. For this reason, Microsoft recommends that certain approaches be taken to minimize decoding latency and to ensure support for scenarios such as rapid rendering of thumbnails and previews.

For example, all RAW codec authors must implement the IWICBitmapSourceTransform interface, which provides a mechanism to notify the decoder in advance of the target bitmap size, thus enabling optimized decoding to a smaller output image size.

The following sections describe the specific WIC interfaces that must be implemented, along with Microsoft’s recommendations for ensuring the code quality, security, and performance that is required to support professional-level applications on Windows.

Feature Completeness: Required Interfaces

All RAW codecs should implement at least the following WIC interfaces.

Interface / Required for / Description /
IWICBitmapDecoder / Decoders / Required. Represents the starting point for decoding an image file. Provides access to container-level properties like thumbnails, frames, and palette.
IWICBitmapFrameDecode / Decoders / Required. Represents a specific image frame within the container that provides access to frame-level properties. This is the interface that decodes the actual image bits.
IWICMetadataBlockReader / Decoders / Used for or enumerating and iterating through metadata blocks and invoking the appropriate metadata readers when reading from an image file.
Note: If the RAW container format is TIFF compatible or uses standard IFDs or IRBs to store EXIF or XMP metadata, codec authors can choose to invoke the built-in metadata readers rather than writing their own.
IWICBitmapSourceTransform / Decoders / Required. Allows the caller to specify desired scaling, cropping, rotation, or pixel format for the decoded image, which can significantly improve decoder performance. For example, Microsoft’s JPEG and Wireless Datagram Protocol (WDP) decoders use a pyramid optimization scheme to achieve faster decoding when the target bitmap is smaller than the source bitmap. Windows Vista (and later) will attempt to use this interface to extract a “fast” preview from a RAW image whenever the embedded preview is missing or less than 1,024 pixels in its largest dimension.
IWICDevelopRaw / Decoders / Required for RAW formats. Exposes parameters that are specific to RAW image processing. RAW codecs should support as many of these parameters as apply to the codec.
IWICBitmapEncoder / Encoders / Required. Represents the starting point for encoding an image file. This interface is used for setting container-level properties, such as thumbnails, frames, and palette. It is also required to invoke a metadata writer to enable metadata persistence to the image file. For these reasons, this interface is necessary even if encoding the primary bitmap to the RAW format is not supported.
IWICBitmapFrameEncode / Encoders / Required. Represents a specific image frame within the container. This interface is used to encode the actual image bits and to set per-frame metadata and properties.
IWICMetadataBlockWriter / Encoders / Required for iterating through metadata blocks and invoking the appropriate metadata writers when serializing an image file.
Note: If the RAW container format is TIFF-compatible, codec authors can choose to invoke the built-in metadata writers rather than writing their own.

Required Methods on Each Interface

Not every method on every interface must have an implementation. For example, some codecs have global metadata, thumbnails, or color contexts, whereas other codecs provide these only on a per-frame basis. If codec authors provide these only on a per-frame basis, they need only implement the Get or Set methods for thumbnails or ColorContexts, or implement the GetMetadataQueryReader or GetMetadataQueryWriter methods on the IWICBitmapFrameDecode and IWICBitmapFrameEncode rather than on the IWICBitmapDecoder and IWICBitmapEncoder.Likewise, some codecs do not use indexed formats and so are not required to implement the Copy and SetPalette methods. These methods are therefore optional and are left to the discretion of the codec creator. Most other methods are required.

For Windows 7 Get/SetPreview and Set/SetThumbnail are required and must be implemented on either the contain-level classes or on the frame-level classes. If your image file format doesn’t support previews or thumbnails in either of these locations, then you should revise your image file format to provide such support.

When a method is not implemented, it is important to return an appropriate error so the caller can determine that the requested feature is not supported. For example, if codec authors do not support container-level thumbnails, they should return WINCODEC_ERR_CODECNOTHUMBNAIL when an application calls IWICDecoder::GetThumbnail, and if they don't have a palette, they should return WINCODEC_ERR_PALETTEUNAVAILABLE. If no suitable WINCODEC_ERR code exists, then the codec should just return E_NOTIMPL for unimplemented methods.

IWICBitmapDecoder

Required / Optional /
QueryCapability / GetPreview1
Initialize / GetThumbnail2
GetContainerFormat / GetColorContexts
GetDecoderInfo / GetMetadataQueryReader
GetFrameCount / CopyPalette
GetFrame

1Required if your image file format supports container-level previews. If this is not the case you are strongly encouraged to revise your image file format to support this. If implemented here, then a corresponding SetPreview is required on the container-level encode class.

2Required either here, and/or on the frame-level decode class, depending on where your image file format stores thumbnails. If implemented here, then a corresponding SetThumbnail is required on the container-level encode class.

IWICBitmapFrameDecode

Required / Optional /
GetColorContexts / GetThumbnail1
GetMetadataQueryReader / CopyPalette
GetSize
GetPixelFormat
GetResolution
CopyPixels

1Required either here, and/or on the container-level decode class, depending on where you image file format stores thumbnails. If implemented here, then a corresponding SetThumbnail is required on the frame-level encoder class

IWICMetadataBlockReader

Required /
GetContainerFormat
GetCount
GetReaderByIndex
GetEnumerator

IWICBitmapSourceTransform

Required / Optional /
DoesSupportTransform / GetClosestSize
CopyPixels / GetClosestPixelFormat

IWICDevelopRaw

See Support for IWICDevelopRaw, later in this document.

IWICBitmapEncoder

Required / Optional /
Initialize / SetPreview1
GetContainerFormat / SetThumbnail2
GetEncoderInfo / SetColorContexts
CreateNewFrame / GetMetadataQueryWriter
Commit / SetPalette

1Required if your image file format supports frame-level previews.

2Required either here, and/or on the frame-level encode class, depending on where your image file format stores thumbnails. If implemented here, then a corresponding GetThumbnail is required on the container-level decode class.

IWICBitmapFrameEncode

Required / Optional /
Initialize / SetThumbnail1
SetColorContexts / CopyPalette
GetMetadataQueryWriter
SetSize
SetPixelFormat
SetResolution
WritePixels
WriteSource
Commit

1Required either here, and/or on the container-level encode class, depending on where your image file format stores thumbnails. If implemented here, then a corresponding GetThumbnail is required on the frame-level decode class.

IWICMetadataBlockWriter

Required /
InitializeFromBlockReader
AddWriter
GetWriterByIndex
SetWriterByIndex
RemoveWriterByIndex

Metadata Support

RAW formats should also support the common metadata read and write scenarios for images in Windows. Microsoft has developed a set of native metadata providers for exchangeable image file (EXIF), International Press Telecommunications Council (IPTC), and Extensible Metadata Platform (XMP) metadata that are currently invoked only for TIFF and JPEG containers. If the RAW image is stored in one of these container formats, it is recommended to use the Microsoft built-in metadata providers. However, the codec author is responsible for configuring this properly. For RAW files that are not based on a TIFF container, it might be necessary to implement EXIF, IPTC, or XMP writers because the built-in readers and writers expect the data to conform to EXIF, IPTC, and XMP on-disk layout specifications. Codec authors can also implement their own providers for any custom metadata.

Because of the architecture of WIC, metadata writers can be invoked only through an instance of an image encoder. Therefore, RAW format owners should create at least a “stub” WIC encoder, even if the actual encoding of pixels into a RAW format is not implemented. The codec author must invoke the proper metadata handlers:

·  IWICMetadataBlockReader on both the decoder and frame decoder as appropriate.

·  IWICMetadataBlockWriter on both the encoder and frame encoder as appropriate.

To support all of the anticipated scenarios in imaging applications in Windows Vista, Microsoft recommends that codec vendors support the following at a minimum:

·  EXIF read

·  Partial EXIF write (to permit updates to capture date and time)

·  XMP read and write (including optionally IPTC Core for XMP)

·  IPTC IIMv4 read and write

Most of the metadata access (both read and write) in Windows Vista occurs through the IWICMetadataQueryReader or IWICMetadataQueryWriter interface. Therefore, to participate in the Windows Vista metadata experiences, RAW codec authors must implement the IWICBitmapFrameDecode::GetMetadataQueryReader and IWICBitmapFrameEncode::GetMetadataQueryWriter methods.

Decoding

To properly support metadata, decoder authors must do the following:

·  Implement IWICBitmapDecoder and IWICBitmapFrameDecode interfaces.

·  Implement IWICMetadataBlockReader on the frame decoder. If the codec supports container-level metadata, this interface must be implemented on the container-level decoder as well as on the frame decoder.