WIC I O Functions

These functions use the Windows Imaging Component (WIC) to read or write an image file. There are built-in WIC codecs in Windows for .BMP, .PNG, .GIF, .TIFF, .JPEG, and JPEG-XR / HD Photo images. Some containers (.GIF and .TIFF) can contain multi-frame bitmaps files.

GetMetadataFromWICMemory, GetMetadataFromWICFile

Returns the TexMetadata from a WIC-supported bitmap file.

HRESULT GetMetadataFromWICMemory( const void* pSource, size_t size,
    DWORD flags, TexMetadata& metadata,
    std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );

HRESULT GetMetadataFromWICFile( const wchar_t* szFile,
    DWORD flags, TexMetadata& metadata,
    std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );

LoadFromWICMemory, LoadFromWICFile

Loads a WIC-supported bitmap file.

HRESULT LoadFromWICMemory( const void* pSource, size_t size,
    DWORD flags, TexMetadata* metadata, ScratchImage& image,
    std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );

HRESULT LoadFromWICFile( const wchar_t* szFile,
    DWORD flags, TexMetadata* metadata, ScratchImage& image,
    std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );

SaveToWICMemory, SaveToWICFile

Saves a single image or a set of images to a WIC-supported bitmap file. The caller provides the desired WIC container format to use via guidContainerFormat (see GetWICCodec for a helper). There is an optional targetFormat to specify a desired WIC pixel format (which will result in an E_FAIL if not supported by the WIC codec)

HRESULT SaveToWICMemory( const Image& image,
    DWORD flags, REFGUID guidContainerFormat,
    Blob& blob, const GUID* targetFormat = nullptr,
    std::function<void(IPropertyBag2*)> setCustomProps = nullptr );

HRESULT SaveToWICMemory( const Image* images, size_t nimages,
    DWORD flags, REFGUID guidContainerFormat,
    Blob& blob, const GUID* targetFormat = nullptr,
    std::function<void(IPropertyBag2*)> setCustomProps = nullptr );

HRESULT SaveToWICFile( const Image& image,
    DWORD flags, REFGUID guidContainerFormat,
    const wchar_t* szFile, const GUID* targetFormat = nullptr,
    std::function<void(IPropertyBag2*)> setCustomProps = nullptr );

HRESULT SaveToWICFile( const Image* images, size_t nimages,
    DWORD flags, REFGUID guidContainerFormat,
    const wchar_t* szFile, const GUID* targetFormat = nullptr,
    std::function<void(IPropertyBag2*)> setCustomProps = nullptr );

Parameters

For the load functions, the metadata parameter can be nullptr as this information is also available in the returned ScratchImage.

For the metadata and loading functions, getMQR is an optional callback. If it is non-null and the WIC container codec supports a metadata query reader, then the callback is triggered. This allows an application to extract additional metadata from the file that is otherwise unused by DirectXTex.

For the saving functions, setCustomProps is an optional callback. If it is non-null, then the callback is triggered so it can set additional WIC properties such as compression methods.

Examples

This is a simple loading example. Since it only returns a single 2D image, the TexMetadata info is redundant information.

auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromWICFile( L"WINLOGO.BMP", WIC_FLAGS_NONE, nullptr, *image );
if ( FAILED(hr) )
    // error

This is a multi-image loading example which can load an array of 2D images.

TexMetadata info;
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromDDSFile( L"MULTIFRAME.TIF",
                 WIC_FLAGS_ALL_FRAMES, &info, *image );
if ( FAILED(hr) )
    // error

Here we provide an optional callback to check for the System.Photo.Orientation metadata query property:

TexMetadata info;
auto image = std::make_unique<ScratchImage>();
uint16_t orientation = 1;
HRESULT hr = LoadFromWICFile( L"Image.JPG", WIC_FLAGS_NONE, &info, *image,
                          [&](IWICMetadataQueryReader* reader)
                          {
                              PROPVARIANT value;
                              PropVariantInit( &value );

                              if ( SUCCEEDED(reader->GetMetadataByName( L"System.Photo.Orientation", &value ) )
                                   && value.vt == VT_UI2 )
                              {
                                  orientation = value.uiVal;
                              }

                              PropVariantClear( &value );
                          } );
if ( FAILED(hr) )
    // error

This is saving a simple 2D image to a specific file container. You can either use the WIC GUID directly or make use of the GetWICCodec helper. Keep in mind that WIC may convert the pixel format in the final output image, so there is an optional additional parameter you can use to request a specific storage pixel format. In this case, we want the file's pixel format to be an 8-bit per channel RGB without an alpha channel.

const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
    GUID_ContainerFormatPng, L"NEW_IMAGE.PNG", &GUID_WICPixelFormat24bppBGR );
if ( FAILED(hr) )
    // error

You can also save data directly from memory without using the intermediate ScratchImage at all. This example assumes a single 2D image is being written out since a JPG file cannot contain an image array.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format that maps directly to a WIC supported format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToWICFile( img, WIC_FLAGS_NONE, GetWICCodec(WIC_CODEC_JPEG),
                            L"NEW_IMAGE.PNG" );
if ( FAILED(hr) )
    // error

When writing WIC files, you can also provide a callback for setting specific encoding options.

const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
    GUID_ContainerFormatTiff, L"NEW_IMAGE.TIF", nullptr, 
    [&](IPropertyBag2* props)
    {
        PROPBAG2 options[2] = { 0, 0 };
        options[0].pstrName = L"CompressionQuality";
        options[1].pstrName = L"TiffCompressionMethod";

        VARIANT varValues[2];
        varValues[0].vt = VT_R4;
        varValues[0].fltVal = 0.75f;

        varValues[1].vt = VT_UI1;
        varValues[1].bVal = WICTiffCompressionNone;

        (void)props->Write( 2, options, varValues ); 
    });
if ( FAILED(hr) )
    // error

Related Flags

• WIC_FLAGS_NONE Default flags.

• WIC_FLAGS_FORCE_RGB By default we map many BGR formats directly to DXGI 1.1 formats. Use of this flag forces the use of DXGI 1.0 RGB formats instead for improved Direct3D 10.0/Windows Vista RTM/WDDM 1.0 driver support.

• WIC_FLAGS_NO_X2_BIAS By default GUID_WICPixelFormat32bppRGBA1010102XR is loaded as R10G10B10_XR_BIAS_A2_UNORM. Use of this flag will force it to convert to R10G10B10A2_UNORM instead.

• WIC_FLAGS_NO_16BPP By default, 5:6:5 and 5:5:5:1 formats are returned as DXGI 1.2 formats. If this flag is used, the loader will expand these to R8G8B8A8 instead.

• WIC_FLAGS_ALLOW_MONO By default, monochrome data is converted to greyscale. By using this flag, this data is loaded as R1_UNORM which is not supported for rendering by Direct3D.

• WIC_FLAGS_ALL_FRAMES By default, only the first frame of a multi-frame file is loaded. If this flag is provided, all frames are loaded and resized to match the size of the first image to fit the DirectXTex requirements for a 2D array.

Color space

• WIC_FLAGS_IGNORE_SRGB While there is no explicit 'sRGB' pixel format defined for WIC, the load function will check for known metadata tags and may return DXGI_FORMAT_*_SRGB formats if there are equivalents of the same size and channel configuration available. If this flag is specified, any 'sRGB' metadata is ignored instead.

Dithering

These flags control the use of dithering for image conversions. It defaults to 'no' dithering.

• WIC_FLAGS_DITHER WIC will use 4x4 ordered dithering.
• WIC_FLAGS_DITHER_DIFFUSION WIC will use error-diffusion (Floyd-Steinberg dithering).

Algorithm

These flags control the use of interpolation modes for image conversions/resizing. It defaults to "Fant"

• WIC_FLAGS_FILTER_POINT Nearest-neighbor
• WIC_FLAGS_FILTER_LINEAR - Bilinear interpolation
• WIC_FLAGS_FILTER_CUBIC - Bicubic interpolation
• WIC_FLAGS_FILTER_FANT - Fant which is equivalent to 'box' filteirng for down-scaling.

Release Notes

• JPEG-XR / HD Photo supports nearly all WIC pixel formats including floating-point for both encoding and decoding.

• TIFF can contain floating-point data (128bpp or 96bpp), but the WIC built-in codec can only decode such images. It always converts floating-point data to unorm when encoding. Windows 7 incorrectly handles decoding 96bpp TIFF files, which is corrected with WIC2 by returning the new format GUID_WICPixelFormat96bppRGBFloat

• Windows WIC codec for .BMP files does not support alpha channels for 16-bit files. For 32-bit files, the alpha channel is ignored by Windows 7 or earlier. The WIC2 BMP codec can read 32-bit alpha channels if using the BITMAPV5HEADER header. DirectXTex opts into the WIC2 behavior for writing 32-bit alpha channels using the V5 header when available

• GUID_WICPixelFormat32bppRGBE is an 8:8:8:8 format, which does not match DXGI_FORMAT_R9G9B9E5_SHAREDEXP. This WIC pixel format is therefore converted to GUID_WICPixelFormat128bppRGBAFloat and returns as DXGI_FORMAT_R32G32B32A32_FLOAT.

• Paletted WIC formats are not supported for writing by the SaveToWIC functions.

• When writing PNG files, if the input image format is DXGI_FORMAT_*_SRGB, then the resulting file will have the sRGB rendering intent chunk. Otherwise, it will not have the sRGB chunk and instead will have an explicit gAMA chunk of 1.0.

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.

• The WIC2 pixel format GUID_WICPixelFormat96bppRGBFloat loads as DXGI_FORMAT_R32G32B32_FLOAT. Otherwise it converts this to DXGI_FORMAT_R32G32B32A32_FLOAT.

• Conversions cases for WIC2 pixel formats GUID_WICPixelFormat32bppRGB, GUID_WICPixelFormat64bppRGB, and GUID_WICPixelFormat64bppPRGBAHalf are included. The pixel format GUID_WICPixelFormat96bppRGBFixedPoint is converted to DXGI_FORMAT_R32G32B32_FLOAT rather than DXGI_FORMAT_R32G32B32A32_FLOAT

See Windows Imaging Component and Windows 8

Windows Store apps

Load

If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromWICFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).

create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
    if (file)
    {
        auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
        create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
        {
            if ( tempFile )
            {
                HRESULT hr = LoadFromWICFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

Save

For SaveToWICFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:

auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base

If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:

auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base