The DirectXTex library includes a full-featured DDS reader and writer including legacy format conversions, a TGA reader and writer, a HDR reader and writer, a WIC-based bitmap reader and writer (BMP, JPEG, PNG, TIFF, and HD Photo), and various texture processing functions.

This library is intended primarily for tool usage. For a library that is more optimized for runtime use, see DirectX Tool Kit for DX11 / DX12.

Support for EXR requires the OpenEXR library and additional code. See Adding OpenEXR for more details.

The majority of the header files here are intended for internal implementation of the library only (BC.h, DDS.h, DirectXTexP.h, and scoped.h). Only DirectXTex.h (and DirectXTex.inl) is meant as a 'public' header for the library.

#include "DirectXTex.h"

By default, the library supports Direct3D 11. If you want to support Direct3D 12, then you need to #include <d3d12.h> before you do #include "DirectXTex.h".

All the functions in the library are in the DirectX C++ namespace.

The library assumes that the client code will have already called CoInitialize, CoInitializeEx, or Windows::Foundation::Initialize as needed by the application before calling any DirectXTex routines. Most DirectXTex functions use the Windows Imaging Component which requires COM.

For a Universal Windows Platform (UWP) app using /ZW, the Windows Runtime and COM is initialized by the C/C++ Run-Time. For C++/WinRT applications, this is done by calling winrt::init_apartment();.

For a classic Windows desktop application you have to do this explicitly:

HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
if (FAILED(hr))
    // error

If you need Windows Runtime functionality in your application on Windows 10 or Windows 11, use:

#if (_WIN32_WINNT >= 0x0A00 /*_WIN32_WINNT_WIN10*/)
    Microsoft::WRL::Wrappers::RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
        // error
#else
    HRESULT hr = CoInitializeEx(nullptr, COINITBASE_MULTITHREADED);
    if (FAILED(hr))
        // error
#endif

If you get an E_NOINTERFACE HRESULT back from a DirectXTex function, then you likely didn't initialize COM on the calling thread.

These functions perform file I/O for DirectDraw Surface (.DDS) files. These functions support many legacy Direct3D 9 .DDS files and all Direct3D 10.x/11.x era DX10 extension .DDS files.

• GetMetadataFromDDSMemory - Extracts the metadata from a DDS file in memory
• GetMetadataFromDDSFile - Extracts the metadata from a DDS file on disk
• LoadFromDDSMemory - Loads image data from a DDS file in memory
• LoadFromDDSFile - Loads image data from a DDS file on disk
• SaveToDDSMemory - Creates a DDS file in memory
• SaveToDDSFile - Creates a DDS file on disk
• EncodeDDSHeader - Helper for creating your own DDS files

The Radiance RGBE (.HDR) format is commonly used as a texture source file format in game development for high-dynamic range images, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

• GetMetadataFromHDRMemory - Extracts the metadata from a HDR file in memory
• GetMetadataFromHDRFile - Extracts the metadata from a HDR file on disk
• LoadFromHDRMemory - Loads image data from a HDR file in memory
• LoadFromHDRFile - Loads image data from a HDR file on disk
• SaveToHDRMemory - Creates a HDR file in memory
• SaveToHDRFile - Creates a HDR file on disk

The Targa Truevision (.TGA) format is commonly used as a texture source file format in game development, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.

• GetMetadataFromTGAMemory - Extracts the metadata from a TGA file in memory
• GetMetadataFromTGAFile - Extracts the metadata from a TGA file on disk
• LoadFromTGAMemory - Loads image data from a TGA file in memory
• LoadFromTGAFile - Loads image data from a TGA file on disk
• SaveToTGAMemory - Creates a TGA file in memory
• SaveToTGAFile - Creates a TGA file on disk

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 - Extracts the metadata from a WIC-supported file in memory
• GetMetadataFromWICFile - Extracts the metadata from a WIC-supported file on disk
• LoadFromWICMemory - Loads image data from a WIC-supported file in memory
• LoadFromWICFile - Loads image data from a WIC-supported file on disk
• SaveToWICMemory - Creates a WIC-supported file in memory
• SaveToWICFile - Creates a WIC-supported file on disk

These functions also work with additional installed codecs. For example, you can read HEIF files if you install the HEIF WIC Codec, but this only supports reading so the save functions can't write these files.

Functions for doing texture processing based on DirectXTex data typically loaded from a WIC or TGA image file and then written to a .DDS file.

The majority of these functions cannot operate on planar or palettized formats. For video formats, AYUV, Y410, Y416, YUY2, Y216, and Y416 are supported and all operations are performed in RGB colorspace.

• FlipRotate - Flip and/or rotate image or set of images
• Resize - Resize an image or set of images
• Convert - Convert an image or set of images from one pixel format to another
• ConvertToSinglePlane - Converts a planar image or set of images to a single-plane pixel format
• GenerateMipMaps - Generates mipmaps for an image or a set of images
• GenerateMipMaps3D - Generates mipmaps for a 3D volume texture from a set of images representing the slices
• ScaleMipMapsAlphaForCoverage - Scales mipmaps to preserve alpha coverage
• PremultiplyAlpha - This converts to/from premultiplied alpha
• Compress - Compresses an image or set of images to a BC format
• Decompress - Decompresses a BC format to a non-BC format image
• ComputeNormalMap - Converts a height-map to a normal-map
• CopyRectangle - Copies a rectangle from a soure image to a destination image. Does not support block compressed formats
• ComputeMSE - Computes the mean-squared error for each component based on two input images
• EvaluateImage - Evaluates a user-defined function for an input image
• TransformImage - Create a new image from an existing image with a user-defined function

See Filter Flags, Texconv, Texassemble

Functions for working with the Direct3D 11 / DirectX 12 API using DirectXTex image data.

• IsSupportedTexture - Returns true if the given texture metadata is supported by the device
• CreateTexture - Creates a Direct3D resource from a set of images
• CreateShaderResourceView - Creates a Direct3D 11 resource and shader resource view from a set of images
• CaptureTexture - Captures a Direct3D render target and returns an image.

These functions provide utility functionality when working with DXGI_FORMAT throughout the library.

• GetWICCodec - Returns a WIC GUID for a given file container given a simple enumeration value. This function is optional and you can instead use the WIC container GUID directly instead.

This function exists to make it easier to use the WIC I/O DirectXTex functions without having to include the wincodec.h header globally.

• GetWICFactory - Helper to obtain a WIC factory. If not already initialized, a new one is created.
• SetWICFactory - Helper to set the WIC factory to use in DirectXTex.

• IsValid - Returns false if the DXGI format is unknown.
• IsCompressed - Returns true if the DXGI format is a block compressed format.
• IsPacked - Returns true if the DXGI format is a 'packed' format (such as 4:2:2 video formats)
• IsVideo - Returns true if the DXGI format is a DXGI 1.2 'video' format defined for Direct3D 11.1 video.
• IsPlanar - Returns true if the DXGI format is a 'planar' format (such as 4:2:0 or 4:1:1 video formats).
• IsPalettized - Returns true if the DXGI format is a paletted format (only legacy Direct3D 11.1 video formats are paletted).
• IsDepthStencil - Returns true if the DXGI format is for use with depth/stencil resources.
• IsSRGB - Returns true if the DXGI format is an sRGB format.
• IsBGR - Returns true if the DXGI format is a BGR (as opposed to RGB) format.
• IsTypeless - Returns true if the DXGI format is a 'typeless' format. If partialTypeless is 'true' (the default) then formats with both typeless and typed content return true. If partialTypeless is 'false', then the mixed DXGI types (such as DXGI_FORMAT_R32_FLOAT_X8X24_TYPELESS) will return false instead.

• HasAlpha - Returns true of the DXGI format includes an alpha channel. Note that BC1 formats return true because they have a 'transparency bit' trick in the encoding to handle 1-bit alpha.
• BitsPerPixel - Returns the bits-per-pixel for a given DXGI format. For example, it returns 32 for DXGI_FORMAT_R10G10B10A2_UNORM.
• BitsPerColor - Returns the color-depth (aka bit-depth) for a given DXGI format. For formats with a mix of different channel sizes, it returns the color-depth of the largest channel. For example, it returns 10 for DXGI_FORMAT_R10G10B10A2_UNORM.
• BytesPerBlock - Returns the number of bytes in a compressed block given a DXGI block-compression format.
• FormatDataType - Returns the primary data-type for the given DXGI format. The result is FORMAT_TYPE_FLOAT, FORMAT_TYPE_UNORM, FORMAT_TYPE_SNORM, FORMAT_TYPE_UINT, FORMAT_TYPE_SINT, or FORMAT_TYPE_TYPELESS.

• CalculateMipLevels - Validates and calculates the appropriate number of mipmap levels for 1D and 2D textures.
• CalculateMipLevels3D - Validates and calculates the appropriate number of mipmap levels for volume maps.
• ComputePitch - Returns both the row and slice pitch for a given width, height, and DXGI format. It supports a number of flags for overriding the default byte-alignment usually used by DDS files and Direct3D 11 resources.
• ComputeScanlines - Returns the number of horizontal scanlines in an image given the DXGI format and pixel height.
• ComputeTileShape - Computes Direct3D tile resource standard dimensions.

• MakeSRGB - Converts a DXGI format to the sRGB equivalent if any.
• MakeLinear - Converts a DXGI format to the non-sRGB equivalent.
• MakeTypeless - Converts a DXGI format to a TYPELESS equivalent if any. This does not modify depth/stencil formats which have multiple 'typeless' mappings.
• MakeTypelessUNORM - Converts a TYPELESS DXGI format to a UNORM equivalent if any.
• MakeTypelessFLOAT - Converts a TYPELESS DXGI format to a FLOAT equivalent if any.

Note if there is no format that matches the desired property for the input format, the original format is returned.

TexMetadata contains metadata information about the texture resource and organization such as width, height, depth, format, dimension, etc.

DDSMetadata is used to return extended metadata from DDS files.

Image contains information about the surface including width, height, format, rowPitch, slicePitch, and a pointer to pixel data. Note that for 1D and 2D images, slicePitch should be set to the full size of the image.

ScratchImage is a helper class that manages memory for functions that return a Image or set of Images.

Blob is a helper class that manages for functions that return a binary blob of data.

Rect contains a simple pixel-based rectangle used by the CopyRectangle function.

• To support offline texture operations for Xbox, there are DirectXTexXbox extension functions available as well. This also supports the XboxDDSTextureLoader module for DirectX Tool Kit DX11 / DX12.

The DirectXTex library assumes your binary is linking with the following system libraries:

• dxguid.lib: Provides COM GUID values for IID_ID3D11Device, IID_ID3D12Device, IID_ID3D12Resource, WKPDID_D3DDebugObjectName, etc.
• windowscodecs.lib or uuid.lib: Provides COM GUID values for WIC usage such as CLSID_WICImagingFactory, CLSID_WICImagingFactory1, CLSID_WICImagingFactory2, etc.
• For Win32 desktop applications, ole32.lib: Provides CoCreateInstance. For other platforms, this export is in the umbrella library (WindowsApps.lib, onecore.lib, etc.).

On Windows Subsystem for Linux, Windows Imaging Component (WIC) is not available so functionality that requires WIC is not present for that platform. Only DDS, HDR, and TGA file support is included. To support PNG and/or JPEG on this platform, see Using-JPEG-PNG-OSS.

• The alpha mode specification for DDS files was updated between the March 2013 and April 2013 releases. Any DDS files created using the DDS_FLAGS_FORCE_DX10_EXT_MISC2 flag or the texconv -dx10 switch using the March 2013 release should be refreshed.

• Due to the underlying Windows BMP WIC codec, alpha channels are not supported for 16bpp or 32bpp BMP pixel format files. In Windows 8.x and later, the Windows BMP WIC codec does support 32bpp pixel formats with alpha when using the BITMAPV5HEADER file header.

• While DXGI 1.0 and DXGI 1.1 include 5:6:5 (DXGI_FORMAT_B5G6R5_UNORM) and 5:5:5:1 (DXGI_FORMAT_B5G5R5A1_UNORM) pixel format enumerations, the DirectX 10.x and 11.0 Runtimes do not support these formats for use with Direct3D. The DirectX 11.1 runtime, DXGI 1.2, and the WDDM 1.2 driver model or later fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).

Integration

Implementation