NEWS: This project is now hosted on GitHub https://github.com/Microsoft/DirectXTex. This site is being maintained for now, but please move to using GitHub. https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader

A Direct3D 11 2D texture loader that uses WIC to load a bitmap (BMP, JPEG, PNG, TIFF, GIF, HD Photo, or other WIC supported file container), resize if needed based on the current feature level (or by explicit parameter), format convert to a standard DXGI format if required, and then create a 2D texture. Furthermore, if a Direct3D 11 device context is provided and the current device supports it for the given pixel format, it will auto-generate mipmaps.

This loader does not support array textures, 1D textures, 3D volume textures, or cubemaps. For these scenarios, use the .DDS file format and DDSTextureLoader instead.

DDSTextureLoader is recommended for fully "precooked" textures for maximum performance and image quality, but this loader can be useful for creating simple 2D texture from standard image files at runtime.

Also part of DirectXTK http://go.microsoft.com/fwlink/?LinkId=248929

NOTE: WICTextureLoader is not supported on Windows Phone 8.0 because WIC is not available on that platform.

The module assumes that the client code will have already called CoInitialize, CoInitializeEx, or Windows::Foundation::Initialize as needed by the application before calling the WIC loader routines

Functions

CreateWICTextureFromMemory
Loads a WIC-supported bitmap file from a memory buffer. It creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
   _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView,
   _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromMemory( _In_ ID3D11Device* d3dDevice,
   _In_opt_ ID3D11DeviceContext* d3dContext,
   _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView,
   _In_ size_t maxsize = 0 );

CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
   _In_z_ const wchar_t* szFileName,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView,
   _In_ size_t maxsize = 0 );

HRESULT CreateWICTextureFromFile( _In_ ID3D11Device* d3dDevice,
   _In_opt_ ID3D11DeviceContext* d3dContext,
   _In_z_ const wchar_t* szFileName,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView,
   _In_ size_t maxsize = 0 );

CreateWICTextureFromMemoryEx
CreateWICTextureFromFileEx
These versions provide explicit control over the created resource's usage, binding flags, CPU access flags, and miscellaneous flags for advanced / expert scenarios. The standard routines default to D3D11_USAGE_DEFAULT, D3D11_BIND_SHADER_RESOURCE, 0, and 0 respectively. For auto-gen mipmaps, the default binding flags are D3D11_BIND_SHADER_RESOURCE | D3D11_BIND_RENDER_TARGET and miscellaneous flags is set to D3D11_RESOURCE_MISC_GENERATE_MIPS. There is also a 'forceSRGB' option for working around gamma issues with content that is in the sRGB or similar color space but is not encoded explicitly as an SRGB format.

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
   _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
   _In_ size_t maxsize,
   _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags,
   _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags,
   _In_ bool forceSRGB,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromMemoryEx( _In_ ID3D11Device* d3dDevice,
   _In_opt_ ID3D11DeviceContext* d3dContext,
   _In_reads_bytes_(wicDataSize) const uint8_t* wicData, _In_ size_t wicDataSize,
   _In_ size_t maxsize,
   _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags,
   _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags,
   _In_ bool forceSRGB,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _In_ ID3D11Device* d3dDevice,
   _In_z_ const wchar_t* szFileName,
   _In_ size_t maxsize,
   _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags,
   _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags,
   _In_ bool forceSRGB,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView );

HRESULT CreateWICTextureFromFileEx( _In_ ID3D11Device* d3dDevice,
   _In_opt_ ID3D11DeviceContext* d3dContext,
   _In_z_ const wchar_t* szFileName,
   _In_ size_t maxsize,
   _In_ D3D11_USAGE usage, _In_ unsigned int bindFlags,
   _In_ unsigned int cpuAccessFlags, _In_ unsigned int miscFlags,
   _In_ bool forceSRGB,
   _Out_opt_ ID3D11Resource** texture,
   _Out_opt_ ID3D11ShaderResourceView** textureView );

Parameters

For all these functions above, the maxsize parameter provides an upper limit on the size of the resulting texture. If given a 0, the functions assume a maximum size determined from the device's current feature level. If the bitmap file contains a larger image, it will be resized using WIC at load-time to provide scaling.

If a d3dContext is given to these functions, they will attempt to use the auto-generation of mipmaps features in the Direct3D 11 API if supported for the pixel format. Note the quality of auto-gen mipmaps is up to the driver, so can vary widely. Also if a context is passed, the function is not thread safe.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering. It also makes use of the immediate ID3D11DeviceContext immContext to auto-gen mipmaps if supported.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateWICTextureFromFile( d3dDevice, immContext, L"LOGO.BMP",
    nullptr, &pSRV );
if (FAILED(hr))
   // error

Release Notes

Implementation Details

WIC2

WIC2 is available on Windows 8 and on Windows 7 Service Pack 1 with KB 2670838 installed.
http://support.microsoft.com/kb/2670838

Windows Store apps

The texture loader function is typically used to load texture files from the application's install folder as they were included with the AppX package. If you wish to create a texture 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 WICTextureLoader 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).

#include <ppltasks.h>
using namespace concurrency;

using Windows::Storage;
using Windows::Storage::Pickers;

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 = CreateWICTextureFromFile( ..., tempFile->Path->Data(), ... );
                DX::ThrowIfFailed(hr);
            }
        });
    });

http://msdn.microsoft.com/en-us/library/windows/apps/hh758319.aspx