These functions use the Windows Imaging Componet (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.
GetMetadataFromWICMemoryGetMetadataFromWICFileReturns the
TexMetadata from a WIC-supported bitmap file.
LoadFromWICMemoryLoadFromWICFileLoads a WIC-supported bitmap file.
SaveToWICMemorySaveToWICFileSaves 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
Utility functions 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)
Examples
This is a simple loading example. Since it only returns a single 2D image, the TexMetadata info is redundant information.
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromWICFile( L"WINLOGO.BMP", WIC_FLAGS_NONE, nullptr, *image );
if ( FAILED(hr) )
// errorThis is a multi-image loading example which can load an array of 2D images.
TexMetadata info;
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromDDSFile( L"MULTIFRAME.TIF", WIC_FLAGS_ALL_FRAMES, &info, *image );
if ( FAILED(hr) )
// errorThis 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) )
// errorYou 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) )
// errorWhen 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) )
// errorRelated 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.
- 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 ignored instead.
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).
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.
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
http://support.microsoft.com/kb/2670838Windows 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