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.
NOTE: WICTextureLoader is not supported on Windows Phone 8, because WIC is not available on that platform.
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 DirectXTex http://go.microsoft.com/fwlink/?LinkId=248926
The module assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling the WIC loader routines
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.
CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.
For both 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.
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.
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.
NOTE: WICTextureLoader is not supported on Windows Phone 8, because WIC is not available on that platform.
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 DirectXTex http://go.microsoft.com/fwlink/?LinkId=248926
The module assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling the WIC loader routines
Functions
CreateWICTextureFromMemoryLoads 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.
CreateWICTextureFromFile
Loads a WIC-supported bitmap file from disk, creates a Direct3D 11 resource from it, and optionally a Direct3D 11 shader resource view.
For both 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.
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.
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.usingnamespace DirectX; usingnamespace Microsoft::WRL; ComPtr<ID3D11ShaderResourceView> srv; HRESULT hr = CreateWICTextureFromFile( d3dDevice, immContext, L"LOGO.BMP", nullptr, &srv ) ThrowIfFailed(hr);
Release Notes
- On a system with the DirectX 11.0 Runtime, 16bpp pixel formats will be converted to a RGBA 32-bit format.
Implementation Details
- The conversion tables are designed so that they prefer to convert to RGB if a conversion is required as a general preferance for DXGI 1.0 supporting formats supported by WDDM 1.0 drivers. The majority of Direct3D 11 devices actually support BGR DXGI 1.1 formats so we use them when they are the best match. For example, GUID_WICPixelFormat32bppBGRA loads directly as DXGI_FORMAT_B8G8R8A8_UNORM, but GUID_WICPixelFormat32bppPBGRA converts to DXGI_FORMAT_R8G8B8A8_UNORM.
- GUID_WICPixelFormatBlackWhite is always converted to a greyscale DXGI_FORMAT_R8_UNORM since DXGI_FORMAT_R1_UNORM is not supported by Direct3D 10.x/11.x.
- If WIC2 is supported (Windows 8 or Windows 7 SP1 with KB 2670838 installed), then it will load the new WIC pixel format GUID_WICPixelFormat96bppRGBFloat directly as DXGI_FORMAT_R32G32B32_FLOAT. Otherwise the module converts this to DXGI_FORMAT_R32G32B32A32_FLOAT.
- If WIC2 is supported (Windows 8 or Windows 7 SP1 with KB 2670838 installed), then it will include conversions cases for the new WIC pixel formats GUID_WICPixelFormat32bppRGB, GUID_WICPixelFormat64bppRGB, and GUID_WICPixelFormat64bppPRGBAHalf.
- If WIC2 is supported (Windows 8 or Windows 7 SP1 with KB 2670838 installed), then it will convert the WIC pixel format GUID_WICPixelFormat96bppRGBFixedPoint to DXGI_FORMAT_R32G32B32_FLOAT. There is special-case handling so that if auto-gen mips fails for this format (this is optional support for Feature Level 10.0 or later devices), it will use DXGI_FORMAT_R32G32B32A32_FLOAT instead (which has required support for Feature Level 10.0 or later devices).