directxtex Wiki Rss Feed

Updated Wiki: Version History

walbourn — Wed, 17 Apr 2013 00:55:23 GMT

April 16, 2013

Updated alpha-mode metadata details in .DDS files
Added new control flags for Convert
Added new optional flags for ComputeMSE
Fixed conversion handling for sRGB formats
Fixed internal routines for handling R10G10B10_XR_BIAS_A2_UNORM, R9G9B9E5_SHAREDEXP, and FORMAT_R1_UNORM
Fixed WIC I/O for GUID_WICPixelFormat32bppRGBE pixel format files (HD Photo)
Fixed non-square image handling in GenerateMipMaps3D
Fixed some error handling in the DDS load code

March 22, 2013

Supports reading and writing alpha-mode (straight, premultiplied, etc.) metadata in .DDS files
Added build option to use WICCreateImagingFactory_Proxy instead of CoCreateInstance to obtain WIC factory

January 29, 2013

Added PremultiplyAlpha to DirectXTex; -pmalpha switch for texconv command-line tool
Fixed problem with forceSRGB implementation for Ex versions of CreateTexture, CreateShaderResourceView, DDSTextureLoader and WICTextureLoader

December 11, 2012

Ex versions of CreateTexture, CreateShaderResourceView, DDSTextureLoader and WICTextureLoader
Fixed BC2 and BC3 decompression issue for unusual color encoding case
Converted annotation to SAL2 for improved VS 2012 /analyze experience
Updated DirectXTex, DDSView, and Texconv with VS 2010 + Windows 8.0 SDK project using official 'property sheets'

November 15, 2012

Added support for WIC2 when available on Windows 8 and Windows 7 with KB 2670838
Added optional targetGUID parameter to SaveWIC* APIs to influence final container pixel format choice
Fixed bug in SaveDDS* which was generating invalid DDS files for 1D dimension textures
Improved robustness of CaptureTexture when resolving MSAA source textures
Sync'd DDSTextureLoader, ScreenGrab, and WICTextureLoader standalone versions with latest DirectXTK release

September 28, 2012

Added ScreenGrab module for creating runtime screenshots
Renamed project files for better naming consistency
New Typeless utilities for DirectXTex
Some minor code cleanup for DirectXTex's WIC writer function
Bug fixes and new -tu/-tf options for texconv

June 22, 2012

Moved to using XNA Math 2.05 instead of XNA Math 2.04 for USE_XNAMATH builds
Fixed BGR vs. RGB color channel swizzle problem with 24bpp legacy .DDS files in DirectXTex
Update to DirectXTex WIC and WICTextureLoader for additional 96bpp float format handling on Windows 8

May 31, 2012

Minor fix for DDSTextureLoader's retry fallback that can happen with 10level9 feature levels
Switched to use "_DEBUG" instead of "DEBUG" and cleaned up debug warnings
added Metro style application project files for DirectXTex

April 20, 2012

DirectTex's WIC-based writer opts-in for the Windows 8 BMP encoder option for writing 32 bpp RGBA files with the BITMAPV5HEADER

March 30, 2012

WICTextureLoader updated with Windows 8 WIC pixel formats DirectXTex updated with limited non-power-of-2 texture support and TEXFILTERSEPARATE_ALPHA option
Texconv updated with '-sepalpha' command-line option
Added USE_XNAMATH control define to build DirectXTex using either XNAMath or DirectXMath
Added VS 2012 project files (which use DirectXMath instead of XNAMath and define DXGI12_FORMATS)

March 15, 2012

Fix for resource leak in CreateShaderResourceView() Direct3D 11 helper function in DirectXTex

March 5, 2012

Fix for too much temp memory allocated by WICTextureLoader; cleaned up legacy 'min/max' macro usage in DirectXTex

February 21, 2012

WICTextureLoader updated to handle systems and device drivers without BGRA or 16bpp format support

February 20, 2012

Some code cleanup for DirectXTex and DDSTextureLoader
Fixed bug in 10:10:10:2 format fixup in the LoadDDSFromMemory function
Fixed bugs in "non-zero alpha" special-case handling in LoadTGAFromFile
Fixed bug in _SwizzleScanline when copying alpha channel for BGRA<->RGBA swizzling

February 11, 2012

Update of DDSTextureLoader to also build in Metro style apps; added WICTextureLoader
Added CMYK WIC pixel formats to the DirectXTex conversion table

January 30, 2012

Minor code-cleanup for DirectXTex to enable use of PCH through 'directxtexp.h' header

January 24, 2011

Some code-cleanup for DirectXTex
Added DXGI 1.2 implementation for DDSTextureLoader and DirectXTex guarded with DXGI12_FORMATS compiliation define

December 16, 2011

Fixed x64 compilation warnings in DDSTextureLoader

November 30, 2011

Fixed some of the constants used in IsSupportedTexture(),
added ability to strip off top levels of mips in DDSTextureLoader,
changed DirectXTex to use CoCreateInstance rather than LoadLibrary to obtain the WIC factory,
a few minor /analyze related annotations for DirectXTex

October 27, 2011

Original release

Updated Wiki: ComputeMSE

walbourn — Tue, 16 Apr 2013 23:27:06 GMT

Computes the mean-squared error for each component based on two input images.

HRESULT ComputeMSE( _In_ const Image& image1, _In_ const Image& image2,
    _Out_ float& mse, _Out_writes_opt_(4) float* mseV,
    _In_ DWORD flags = 0 );

Parameters

flags: a combination of the following flags

CMSE_DEFAULT Default flags

CMSE_IMAGE1_SRGB Indicates image1 should have sRGB -> scRGB conversion applied before comparison.
CMSE_IMAGE2_SRGB Indicates image2 should have sRGB -> scRGB conversion applied before comparison.

CMSE_IGNORE_RED Indicates comparison should ignore differences in the RED (X) channel.
CMSE_IGNORE_GREEN Indicates comparison should ignore differences in the GREEN (Y) channel.
CMSE_IGNORE_BLUE Indicates comparison should ignore differences in the BLUE (Z) channel.
CMSE_IGNORE_ALPHA Indicates comparison should ignore differences in the ALPHA (W) channel.

Remarks

Image data is converted to DXGI_FORMAT_R32G32B32A32_FLOAT for this operation. BC data is automatically decompressed.

Updated Wiki: ComputeMSE

walbourn — Tue, 16 Apr 2013 23:26:31 GMT

Computes the mean-squared error for each component based on two input images.

HRESULT ComputeMSE( _In_ const Image& image1, _In_ const Image& image2,
    _Out_ float& mse, _Out_writes_opt_(4) float* mseV,
    _In_ DWORD flags = 0 );

Parameters

flags: a combination of the following flags

CMSE_DEFAULT Default flags

CMSE_IMAGE1_SRGB Indicates image1 should have SRGB -> scRGB conversion applied before comparison.
CMSE_IMAGE2_SRGB Indicates image2 should have SRGB -> scRGB conversion applied before comparison.

CMSE_IGNORE_RED Indicates comparison should ignore differences in the RED (X) channel.
CMSE_IGNORE_GREEN Indicates comparison should ignore differences in the GREEN (Y) channel.
CMSE_IGNORE_BLUE Indicates comparison should ignore differences in the BLUE (Z) channel.
CMSE_IGNORE_ALPHA Indicates comparison should ignore differences in the ALPHA (W) channel.

Remarks

Image data is converted to DXGI_FORMAT_R32G32B32A32_FLOAT for this operation. BC data is automatically decompressed.

Updated Wiki: Texture Functions

walbourn — Tue, 16 Apr 2013 23:21:03 GMT

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.

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.

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.

PremultiplyAlpha
This converts an image assuming the original is not using premultiplied alpha into a premultiplied alpha version of the same image.

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.

Examples

These are flexible functions for doing texture processing that can be used in many different ways. See the Texconv command-line utility for some extensive examples of using them.

Related Flags

See Filter Flags

Updated Wiki: Filter Flags

walbourn — Tue, 16 Apr 2013 23:19:45 GMT

enum TEX_FILTER_FLAGS

TEX_FILTER_DEFAULT Default flags
TEX_FILTER_SEPARATE_ALPHA WIC makes use of pre-multiplied alpha when resizing images, which works fine for standard transparency data. If the alpha channel, however, contains some other kind of value then the resulting image can have 'holes' in it. Use of this flag uses an alternative algorithm which resizes the RGB and alpha channels independantly and then recombines the result.

This selects the use of dithering for resizing and format conversions. By default it uses no dithering.

TEX_FILTER_DITHER 4x4 dithering
TEX_FILTER_DITHER_DIFFUSION Error-diffusion dithering

This selects the filtering mode used for resizing. By default it uses "Fant".

TEX_FILTER_POINT Nearest neighbhor
TEX_FILTER_LINEAR Linear
TEX_FILTER_CUBIC Cubic
TEX_FILTER_FANT Fant which is euivalent to a box filter for down-scaling.

This controls color space transformation for conversions.

TEX_FILTER_SRGB_IN Indicates the input format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB_OUT Indicates the output format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB This is the same as setting both TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT

When both WIC-based and non-WIC based codepaths are in place, these flags can influence the standard logic choice:

TEX_FILTER_FORCE_NON_WIC
TEX_FILTER_FORCE_WIC

For Convert operations, these flags control special-case logic in the non-WIC paths. Without these flags, RGB to R conversions default to converting to a luminance value and RGB to RG conversion defaults to coping the RED and GREEN channels.

TEX_FILTER_RGB_COPY_RED When converting from RGB to R formats, this indicates that the RED channel could be copied. For RGB to RG conversions, it can be combined with GREEN or BLUE to control which channels end up in the output.
TEX_FILTER_RGB_COPY_GREEN When converting from RGB to R formats, this indicates that the GREEN channel could be copied. For RGB to RG conversions, it can be combined with RED or BLUE to control which channels end up in the output.
TEX_FILTER_RGB_COPY_BLUE When converting from RGB to R formats, this indicates that the BLUE channel could be copied. For RGB to RG conversions, it can be combined with RED or GREEN to control which channels end up in the output.

Updated Wiki: Filter Flags

walbourn — Tue, 16 Apr 2013 23:17:06 GMT

enum TEX_FILTER_FLAGS

TEX_FILTER_DEFAULT Default flags
TEX_FILTER_SEPARATE_ALPHA WIC makes use of pre-multiplied alpha when resizing images, which works fine for standard transparency data. If the alpha channel, however, contains some other kind of value then the resulting image can have 'holes' in it. Use of this flag uses an alternative algorithm which resizes the RGB and alpha channels independantly and then recombines the result.

This selects the use of dithering for resizing and format conversions. By default it uses no dithering.

TEX_FILTER_DITHER 4x4 dithering
TEX_FILTER_DITHER_DIFFUSION Error-diffusion dithering

This selects the filtering mode used for resizing. By default it uses "Fant".

TEX_FILTER_POINT Nearest neighbhor
TEX_FILTER_LINEAR Linear
TEX_FILTER_CUBIC Cubic
TEX_FILTER_FANT Fant which is euivalent to a box filter for down-scaling.

This controls color space transformation for conversions.

TEX_FILTER_SRGB_IN Indicates the input format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB_OUT Indicates the output format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB This is the same as setting both TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT

When both WIC-based and non-WIC based codepaths are in place, these flags can influence the standard logic choice:

TEX_FILTER_FORCE_NON_WIC
TEX_FILTER_FORCE_WIC

For Convert operations, these flags control special-case logic in the non-WIC paths:

TEX_FILTER_RGB_COPY_RED
TEX_FILTER_RGB_COPY_GREEN
TEX_FILTER_RGB_COPY_BLUE

Updated Wiki: Filter Flags

walbourn — Tue, 16 Apr 2013 23:16:46 GMT

enum TEX_FILTER_FLAGS

TEX_FILTER_DEFAULT Default flags
TEX_FILTER_SEPARATE_ALPHA WIC makes use of pre-multiplied alpha when resizing images, which works fine for standard transparency data. If the alpha channel, however, contains some other kind of value then the resulting image can have 'holes' in it. Use of this flag uses an alternative algorithm which resizes the RGB and alpha channels independantly and then recombines the result.

This selects the use of dithering for resizing and format conversions. By default it uses no dithering.

TEX_FILTER_DITHER 4x4 dithering
TEX_FILTER_DITHER_DIFFUSION Error-diffusion dithering

This selects the filtering mode used for resizing. By default it uses "Fant".

TEX_FILTER_POINT Nearest neighbhor
TEX_FILTER_LINEAR Linear
TEX_FILTER_CUBIC Cubic
TEX_FILTER_FANT Fant which is euivalent to a box filter for down-scaling.

This controls color space transformation for conversions.

TEX_FILTER_SRGB_IN Indicates the input format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB_OUT Indicates the output format is the sRGB (gamma 2.2) format. This is implied if using a DXGI_FORMAT_*_SRGB format
TEX_FILTER_SRGB This is the same as setting both TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT

When both WIC-based and non-WIC based codepaths are in place, these flags can influence the standard logic choice:

TEX_FILTER_FORCE_NON_WIC
TEX_FILTER_FORCE_WIC

For Convert operations, these flags control special-case logic in the non-WIC paths:

TEX_FILTER_RGB_COPY_RED
TEX_FILTER_RGB_COPY_GREEN
TEX_FILTER_RGB_COPY_BLUE

Updated Wiki: DirectXTex

walbourn — Tue, 16 Apr 2013 18:47:44 GMT

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

The library assumes that the client code will have already called CoInitialize or CoInitializeEx as needed by the application before calling any DirectXTex routines

NOTE: DirectXTex is not supported on Windows Phone 8, because WIC is not available on that platform. The .DDS files it generates are suitable for use on Windows Phone 8 assuming the pixel format is supported by the device (currently Feature Level 9.3).

Headers

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 is meant as a 'public' header for the library.

Namespace

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

Functions

DDS I/O Functions

TGA I/O Functions

WIC I/O Functions

Texture Functions

Direct3D 11 Helper Functions

Utility Functions

Structures

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

TEX_DIMENSION_TEXTURE1D, TEX_DIMENSION_TEXTURE2D, and TEX_DIMENSION_TEXTURE3D are alises for D3D10_RESOURCE_DIMEMSION and D3D11_RESOURCE_DIMENSION.
TEX_MISC_TEXTURECUBE is an alias for the same D3D10_RESOURCE_MISC_FLAG and D3D11_RESOURCE_MISC_FLAG.
TEX_MISC2_ALPHA_MODE_MASK is a mask for miscFlags2 to obtain the TEX_ALPHA_MODE.

Image contains information about the surface including width, height, format, pitch, and a pointer to pixel data.

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.

Adding to a VS Project

In your application's solution, right-click on the Solution and use "Add \ Existing Project..." to add the appropriate .vcxproj file to your solution.

DirectXTex_Desktop_2012 is for Win32 desktop applications building with VS 2012 Express for Desktop, VS 2012 Professional or higher
DirectXTex_Desktop_2010_SDK80 is for Win32 desktop applications building with VS 2010 using the Windows 8.0 SDK
DirectXTex_Desktop_2010 is for Win32 desktop applications building with VS 2010 using an older Windows SDK using XNAMath 2.05 rather than DirectXMath http://blogs.msdn.com/b/chuckw/archive/2012/06/22/xna-math-version-2-05-smoothing-the-transition-to-directxmath.aspx
DirectXTex_Windows8 is for Windows Store apps building with VS 2012

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTex project name and click OK. For a Windows Store app, you need to set Reference Assembly Output to false since DirectXTex is a static C++ library and not a WinRT component.

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Platforms", and then add the relative path to DirectXTex; to the Additional Include Directories properties. Click Apply.

Release Notes

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.

The DirectXTex library does not support block compression or decompression of mipmapped non-power-of-2 textures, although DDSTextureLoader will load these files correctly if the underlying device supports it. CodePlex issue 640

The DirectXTex library only supports CLAMP filtering, and does not yet support MIRROR or WRAP filtering (WIC operations only support CLAMP filtering). CodePlex issue 641

The DirectXTex library only supports box and POINT filtering, and does not support LINEAR or CUBIC filtering, for 3D volume mipmap-generation. CodePlex issue 642

The WIC conversion cases currently ignore TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT out, which results in incorrect sRGB handling in a number of cases. CodePlex issue 643

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

For the DXGI 1.1 version of DirectXTex, 4:4:4:4 pixel format DDS files are always expanded to 8:8:8:8 upon load since DXGI 1.0 and DXGI 1.1 versions of Direct3D do not support these resource formats. The DXGI 1.2 version (indicated by #define DXGI_1_2_FORMATS) of DirectXTex make use of the DXGI_FORMAT_B4G4R4A4_UNORM format instead.

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 fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).

Loading of 96bpp floating-point TIFF files results in a corrupted image prior to Windows 8. This fix is available on Windows 7 SP1 with KB 2670838 installed.

Updated Wiki: DDSTextureLoader

walbourn — Thu, 11 Apr 2013 22:43:50 GMT

A streamlined version of the DirectX SDK sample DDSWithoutD3DX11 texture loading code for a simple light-weight runtime .DDS file loader. This version only supports Direct3D 11 and performs no runtime pixel data conversions (see Release Notes for more details). This is ideal for runtime usage, and supports the full complement of Direct3D 11 texture resources (1D, 2D, volume maps, cubemaps, mipmap levels, texture arrays, BC formats, etc.). It supports both legacy and 'DX10' extension header format .dds files.

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

Functions

CreateDDSTextureFromMemory
Loads a .DDS file assuming the image of the file is located in a memory buffer. Creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

CreateDDSTextureFromFile
Loads a .DDS file from disk and creates a Direct3D 11 resource and optionally a Direct3D 11 shader resource view.

For both these functions if 'maxsize' parameter non-zero, then all mipmap levels larger than the maxsize are ignored before creating the Direct3D 11 resource. This allows for load-time scaling. If '0', then if the attempt to create the Direct3D 11 resource fails and there are mipmaps present, it will retry assuming a maxsize based on the device's current feature level.

For both these functions if 'maxsize' parameter non-zero, then all mipmap levels larger than the maxsize are ignored before creating the Direct3D 11 resource. This allows for load-time scaling. If '0', then if the attempt to create the Direct3D 11 resource fails and there are mipmaps present, it will retry assuming a maxsize based on the device's current feature level.

The last optional parameter for both functions is a pointer to return the alpha mode of the DDS file. This can be one of the following values to return information about the alpha channel if present in the file:

DDS_ALPHA_MODE_UNKNOWN (0) - This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_STRAIGHT (1) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. Viewers should use the alpha channel with 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (2) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.
DDS_ALPHA_MODE_CUSTOM (4) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.

CreateDDSTextureFromMemoryEx
CreateDDSTextureFromFileEx
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 cubemaps, the miscellaneous flags default to D3D11_RESOURCE_MISC_TEXTURECUBE. 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. Note that the 'maxsize' parameter is not at the end of the parameter list like it is in the non-Ex version.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &pSRV );
if (FAILED(hr))
   // error

Feature Level Notes

In order to support all feature levels, you should make sure your DDS textures are mip-mapped so that they contain a suitably sized image. Non-mipmapped textures will either need explicit feature level association, or be sized less than or equal to 2048 for 1D, 2048 x 2048 for 2D, 512 x 512 for cubemaps, and 256 x 256 x 256 for volume maps.

Texture arrays require Feature Level 10.0 or later. Cubemap arrays requires Feature Level 10.1 or later.

Be sure to review the various format limitations for the different feature levels. To support all feature levels, stick with textures in the following formats:

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

If built with #define DXGI_1_2_FORMATS the code supports loading BGRA 4:4:4:4 files. Otherwise, it fails.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: DirectXTex

walbourn — Thu, 11 Apr 2013 22:40:55 GMT

Headers

Namespace

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

Functions

DDS I/O Functions

TGA I/O Functions

WIC I/O Functions

Texture Functions

Direct3D 11 Helper Functions

Utility Functions

Structures

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

TEX_DIMENSION_TEXTURE1D, TEX_DIMENSION_TEXTURE2D, and TEX_DIMENSION_TEXTURE3D are alises for D3D10_RESOURCE_DIMEMSION and D3D11_RESOURCE_DIMENSION.
TEX_MISC_TEXTURECUBE is an alias for the same D3D10_RESOURCE_MISC_FLAG and D3D11_RESOURCE_MISC_FLAG.
TEX_MISC2_ALPHA_MODE_MASK is a mask for miscFlags2 to obtain the TEX_ALPHA_MODE.

Adding to a VS Project

In your application's solution, right-click on the Solution and use "Add \ Existing Project..." to add the appropriate .vcxproj file to your solution.

DirectXTex_Desktop_2012 is for Win32 desktop applications building with VS 2012 Express for Desktop, VS 2012 Professional or higher
DirectXTex_Desktop_2010_SDK80 is for Win32 desktop applications building with VS 2010 using the Windows 8.0 SDK
DirectXTex_Desktop_2010 is for Win32 desktop applications building with VS 2010 using an older Windows SDK using XNAMath 2.05 rather than DirectXMath http://blogs.msdn.com/b/chuckw/archive/2012/06/22/xna-math-version-2-05-smoothing-the-transition-to-directxmath.aspx
DirectXTex_Windows8 is for Windows Store apps building with VS 2012

Release Notes

The DirectXTex library does not support block compression or decompression of mipmapped non-power-of-2 textures, although DDSTextureLoader will load these files correctly if the underlying device supports it. CodePlex issue 640

The DirectXTex library only supports CLAMP filtering, and does not yet support MIRROR or WRAP filtering (WIC operations only support CLAMP filtering). CodePlex issue 641

The DirectXTex library only supports box and POINT filtering, and does not support LINEAR or CUBIC filtering, for 3D volume mipmap-generation. CodePlex issue 642

The WIC conversion cases currently ignore TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT out, which results in incorrect sRGB handling in a number of cases. CodePlex issue 643

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

For the DXGI 1.1 version of DirectXTex, 4:4:4:4 pixel format DDS files are always expanded to 8:8:8:8 upon load since DXGI 1.0 and DXGI 1.1 versions of Direct3D do not support these resource formats. The DXGI 1.2 version (indicated by #define DXGI_1_2_FORMATS) of DirectXTex make use of the DXGI_FORMAT_B4G4R4A4_UNORM format instead.

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 fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).

Loading of 96bpp floating-point TIFF files results in a corrupted image prior to Windows 8. This fix is available on Windows 7 SP1 with KB 2670838 installed.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:31:32 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_4TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &pSRV );
if (FAILED(hr))
   // error

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

If built with #define DXGI_1_2_FORMATS the code supports loading BGRA 4:4:4:4 files. Otherwise, it fails.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: Texconv

walbourn — Sat, 23 Mar 2013 06:31:18 GMT

This DirectXTex sample is an implementation of the "texconv" command-line texture utility from the DirectX SDK utilizing DirectXTex rather than D3DX.

Syntax

Texconv.exe uses the following command syntax:

texconv [-w number] [-h number] [-d number] [-m number] [-f format] [-if filter] [-mf filter] [-c color] [-hflip] [-vflip] [-sepalpha] [-pmalpha] [-tu | -tf] [-dword] [-dx10] [-srgbi] [-srgbo] [-px string] [-sx string] [-o directory] [-ft file-type] [-nologo] file-name

The file-name parameter indicates the file to convert.

The optional command-line switches are described in the following table.

Optional Switches Description

-d number Depth of the output texture. This setting applies only to volume textures.
-f format Output format. Can use most of the formats in D3DFORMAT without the DXGIFORMAT prefix (except: D3DFMTMULTI2ARGB8).
-ft file-type A file type for the output texture. Use one of the following: bmp, dds, jpg, png, or tiff. The default value is dds.
-h number Height of the output texture in pixels.
-w number Width of the output texture in pixels.
-if filter Image filter. Use one of the following: NONE, POINT, LINEAR, CUBIC, FANT, POINT_DITHER, LINEAR_DITHER, CUBIC_DITHER, or FANT_DITHER. Filters with DITHER in their name indicate that a 4x4 ordered dither algorithm is also applied. See D3DX_FILTER for descriptions of the filters.
-m number Number of mipmap levels to generate in the output texture. This setting only applies to DDS output.
-mf filter Mipmap filter (see -if for filter options).
-nologo Suppress copyright message.
-o directory Output directory.
-px string Text string to attach to the front of the resulting texture's name.
-srgb, -srgbi, or -srgbo Use sRGB if both the input and output data are in the sRGB color format (ie. gamma = 2.2). Use sRGBi if only the input is in sRGB; use sRGBo if only the output is in sRGB.
-sx string Text string to attach to the end of the resulting texture's name.
-hflip Perform horizonal flip of image
-vflip Perform horizonal flip of image
-sepalpha Separates alpha channel for resize/mipmap generation. This implies an alpha mode setting of DDS_ALPHA_MODE_4TH_CHANNEL as this is typically only used if the alpha channel doesn't contain transparency information.
-pmalpha Converts the final texture data to use premultiplied alpha. This sets an alpha mode of DDS_ALPHA_MODE_PREMULTIPLIED unless the entire alpha channel is fully opaque.
-tu DDS files with TYPELESS formats are treated as UNORM
-tf DDS files with TYPELESS formats are treated as FLOAT
-dword For DDS files use a DWORD alignment instead of BYTE alignment (used for some legacy files)
-dx10 Forces DDS file output to always use the "DX10" header extension, and allows the writing of alpha mode metadata information. The resulting file may not be compatible with the legacy D3DX10 or D3DX11 libraries.

Updated Wiki: DDS I/O Functions

walbourn — Sat, 23 Mar 2013 06:27:22 GMT

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

GetMetadataFromDDSMemory
GetMetadataFromDDSFile
Returns the TexMetadata from a .DDS file.

LoadFromDDSMemory
LoadFromDDSFile
Loads a .DDS file.

SaveToDDSMemory
SaveToDDSFile
Saves a single image or a set of images to a .DDS file.

Examples

This is a simple loading example. A DDS file can potentially include any kind of Direct3D resource in any DXGI format, so the TexMetadata info is needed to understand the full content of the file.

TexMetadata info;
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS", DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
    // error

When saving a DDS file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.). Therefore, the writer needs the TexMetadata info to know how to interpret the image set.

const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
     DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
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.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI 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 = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
    // error

Related Flags

DDS_FLAGS_NONE is the default
DDS_FLAGS_LEGACY_DWORD is used for loading some legacy Direct3D 8 era 24bpp .DDS files that use the non-standard DWORD alignment instead of BYTE. There's no realiable way to determine this from the file, so this requires trial-and-error.
DDS_FLAGS_NO_LEGACY_EXPANSION - By default the loader will expand many legacy Direct3D 9 .DDS files to supported formats. The use of this flag prevents expansions that increase the size of the pixels, and will return a failure instead.
DDS_FLAGS_NO_R10B10G10A2_FIXUP - By default, the loader uses a work-around for a long-standing issue with the D3DX DDS file format which reverses the RGB bit-masks for 10:10:10:2 formats. If this flag is used, then the loader instead assumes such data was written 'correctly'.
DDS_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.
DDS_FLAGS_NO_16BPP - By default, 5:6:5, 5:5:5:1, and 4:4:4:4 formats are returned as DXGI 1.2 formats. If this flag is used, the loader will expand these to R8G8B8A8 instead.
DDS_FLAGS_FORCE_DX10_EXT - When saving DDS files, the writer tries to use legacy Direct3D 9 .DDS file formats if possible rather than the 'DX10' header extension for better compatiblity with older tools. Using this flag, the writer will always generate 'DX10' extension header files which are much faster to parse at load-time. These files are compatible with the legacy D3DX10 or D3DX11 library.
DDS_FLAGS_FORCE_DX10_EXT_MISC2 - When saving DDS files, always use the 'DX10' header extension and write miscFlags2 data as needed, if even if the resulting file is not compatible with the legacy D3DX10 or D3DX11 libraries.

Updated Wiki: DDS I/O Functions

walbourn — Sat, 23 Mar 2013 06:26:53 GMT

Examples

This is a simple loading example. A DDS file can potentially include any kind of Direct3D resource in any DXGI format, so the TexMetadata info is needed to understand the full content of the file.

TexMetadata info;
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS", DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
    // error

When saving a DDS file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.). Therefore, the writer needs the TexMetadata info to know how to interpret the image set.

const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
     DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
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.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI 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 = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
    // error

Related Flags

DDS_FLAGS_NONE is the default
DDS_FLAGS_LEGACY_DWORD is used for loading some legacy Direct3D 8 era 24bpp .DDS files that use the non-standard DWORD alignment instead of BYTE. There's no realiable way to determine this from the file, so this requires trial-and-error.
DDS_FLAGS_NO_LEGACY_EXPANSION By default the loader will expand many legacy Direct3D 9 .DDS files to supported formats. The use of this flag prevents expansions that increase the size of the pixels, and will return a failure instead.
DDS_FLAGS_NO_R10B10G10A2_FIXUP By default, the loader uses a work-around for a long-standing issue with the D3DX DDS file format which reverses the RGB bit-masks for 10:10:10:2 formats. If this flag is used, then the loader instead assumes such data was written 'correctly'.
DDS_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.
DDS_FLAGS_NO_16BPP By default, 5:6:5, 5:5:5:1, and 4:4:4:4 formats are returned as DXGI 1.2 formats. If this flag is used, the loader will expand these to R8G8B8A8 instead.
DDS_FLAGS_FORCE_DX10_EXT When saving DDS files, the writer tries to use legacy Direct3D 9 .DDS file formats if possible rather than the 'DX10' header extension for better compatiblity with older tools. Using this flag, the writer will always generate 'DX10' extension header files which are much faster to parse at load-time. These files are compatible with the legacy D3DX10 or D3DX11 library.
DDS_FLAGS_FORCE_DX10_EXT_MISC2 When saving DDS files, always use the 'DX10' header extension and write miscFlags2 data as needed, if even if the resulting file is not compatible with the legacy D3DX10 or D3DX11 libraries.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:26:10 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewers should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &pSRV );
if (FAILED(hr))
   // error

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

If built with #define DXGI_1_2_FORMATS the code supports loading BGRA 4:4:4:4 files. Otherwise, it fails.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: DDSTextureLoader

walbourn — Sat, 23 Mar 2013 06:25:46 GMT

Functions

DDS_ALPHA_MODE_STRAIGHT (0) - This indicates that the alpha channel if present is assumed to be using 'straight' alpha. This is the default for most .DDS files if the specific metadata isn't present, and it's up to the application to know if it's really something else. Viewers should assume the alpha channel is intended for 'normal' alpha blending.
DDS_ALPHA_MODE_PREMULTIPLIED (1) - This indicates the alpha channel if present is premultiplied alpha. This information is only present if the file is written using the latest version of the "DX10" extended header, or if the file is BC2/BC3 with the "DXT2"/"DXT4" FourCC which are explicitly stored as premultiplied alpha. Viewers should use the alpha channel with premultiplied alpha blending.
DDS_ALPHA_MODE_TH_CHANNEL (2) - This indicates the alpha channel if present does not contain transparency (neither straight or premultiplied alpha) and instead is encoding some other channel of information. Viewer should not use the alpha channel for blending, and should instead view it as a distinct image channel.
DDS_ALPHA_MODE_OPAQUE (3) - This indicates that the alpha channel if present is fully opaque for all pixels. Viewers can assume there is no alpha blending.

Example

This example creates a shader resource view on the ID3D11Device d3dDevice which can be used for rendering.

ID3D11ShaderResourceView* pSRV = nullptr;
HRESULT hr = CreateDDSTextureFromFile( d3dDevice, L"SEAFLOOR.DDS", nullptr, &pSRV );
if (FAILED(hr))
   // error

Feature Level Notes

DXGI_FORMAT_R8G8B8A8_UNORM, DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
DXGI_FORMAT_R8G8B8A8_SNORM
DXGI_FORMAT_B8G8R8A8_UNORM
DXGI_FORMAT_R16G16_SNORM
DXGI_FORMAT_R8G8_SNORM
DXGI_FORMAT_R8_UNORM
DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB
DXGI_FORMAT_BC2_UNORM, DXGI_FORMAT_BC2_UNORM_SRGB
DXGI_FORMAT_BC3_UNORM, DXGI_FORMAT_BC3_UNORM_SRGB

On Windows 8 with WDDM 1.2 drivers, all feature levels support 16bpp formats as well DXGI_FORMAT_B5G6R5_UNORM, DXGI_FORMAT_B5G5R5A1_UNORM, and DXGI_FORMAT_B4G4R4A4_UNORM.

Release Notes

DDSTextureLoader performs no run-time conversions. If there is not a direct mapping to a DXGI supported format, the function fails. You can make use of the DirectXTex library or texconv tool to convert legacy Direct3D9 DDS files to a supported format. Legacy formats which require conversion include:
- D3DFMT_R8G8B8 (24bpp RGB) - Use a 32bpp format
- D3DFMT_X8B8G8R8 (32bpp RGBX) - Use BGRX, BGRA, or RGBA
- D3DFMT_A2R10G10B10 (BGRA 10:10:10:2) - Use RGBA 10:10:10:2
- D3DFMT_X1R5G5B5 (BGR 5:5:5) - Use BGRA 5:5:5:1 or BGR 5:6:5
- D3DFMT_A8R3G3B2, D3DFMT_R3G3B2 (BGR 3:3:2) - Expand to a supported format
- D3DFMT_P8, D3DFMT_A8P8 (8-bit palette) - Expand to a supported format
- D3DFMT_A4L4 (Luminance 4:4) - Expand to a supported format

http://go.microsoft.com/fwlink/?LinkId=248926.

If built with #define DXGI_1_2_FORMATS the code supports loading BGRA 4:4:4:4 files. Otherwise, it fails.

On a system with the DirectX 11.0 Runtime or lacking WDDM 1.2 drivers, attempts to load 16bpp format files (BGR 5:6:5, BGRA 5:5:5:1, and BGRA 4:4:4:4) will fail.

Partial cubemaps (i.e. DDS files without all six faces defined) are not supported by Direct3D 11.

Updated Wiki: Utility Functions

walbourn — Sat, 23 Mar 2013 01:10:44 GMT

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

GetWICCodec
Returns a WIC GUID for a given file container given a simple enumeration value.

WIC_CODEC_BMP Windows Bitmap (.bmp)
WIC_CODEC_JPEG Joint Photographic Experts Group (.jpg, .jpeg)
WIC_CODEC_PNG Portable Network Graphics (.png)
WIC_CODEC_TIFF Tagged Image File Format (.tif, .tiff)
WIC_CODEC_GIF Graphics Interchange Format (.gif)
WIC_CODEC_WMP Windows Media Photo / HD Photo / JPEG XR (.hdp, .jxr, .wdp)
WIC_CODEC_ICO Windows Icon (.ico)

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.

IsVideo
Returns true if the DXGI format is a DXGI 1.2 'video' format that is not supported for general use with Direct3D 11.

IsSRGB
Returns true if the DXGI format is an sRGB format.

IsTypeless
Returns true if the DXGI format is a 'typeless' format

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.

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.

CP_FLAGS_NONE is the default
CP_FLAGS_LEGACY_DWORD is used for some legacy Direct3D 8 era DDS files, particularly 24bpp files, that used a DWORD alignment instead of BYTE
CP_FLAGS_24BPP used for computing pitch of Direct3D 9 era 24bpp DDS files (which cannot be indicated by a DXGI_FORMAT)
CP_FLAGS_16BPP used for computing pitch of 16bpp DDS files (which requires DXGI 1.2 headers to define all possible combinations, so we use the flag here instead)
CP_FLAGS_8BPP used for computing pitch of 8bpp DDS files

ComputeScanlines
Returns the number of horizontal scanlines in an image given the DXGI format and pixel height.

MakeSRGB
Converts a DXGI format to the sRGB equivalent if any.

MakeTypeless
Converts a DXGI format to a TYPELESS equiavlent 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.

Updated Wiki: DDS I/O Functions

walbourn — Sat, 23 Mar 2013 01:09:43 GMT

Examples

This is a simple loading example. A DDS file can potentially include any kind of Direct3D resource in any DXGI format, so the TexMetadata info is needed to understand the full content of the file.

TexMetadata info;
unique_ptr<ScratchImage> image ( new ScratchImage );
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS", DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
    // error

When saving a DDS file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.). Therefore, the writer needs the TexMetadata info to know how to interpret the image set.

const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
     DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
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.

Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI 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 = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
    // error

Related Flags

DDS_FLAGS_NONE is the default
DDS_FLAGS_LEGACY_DWORD is used for loading some legacy Direct3D 8 era 24bpp .DDS files that use the non-standard DWORD alignment instead of BYTE. There's no realiable way to determine this from the file, so this requires trial-and-error.
DDS_FLAGS_NO_LEGACY_EXPANSION By default the loader will expand many legacy Direct3D 9 .DDS files to supported formats. The use of this flag prevents expansions that increase the size of the pixels, and will return a failure instead.
DDS_FLAGS_NO_R10B10G10A2_FIXUP By default, the loader uses a work-around for a long-standing issue with the D3DX DDS file format which reverses the RGB bit-masks for 10:10:10:2 formats. If this flag is used, then the loader instead assumes such data was written 'correctly'.
DDS_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.
DDS_FLAGS_NO_16BPP By default, 5:6:5, 5:5:5:1, and 4:4:4:4 formats are returned as DXGI 1.2 formats. If this flag is used, the loader will expand these to R8G8B8A8 instead.
DDS_FLAGS_FORCE_DX10_EXT When saving DDS files, the writer tries to use legacy Direct3D 9 .DDS file formats if possible rather than the 'DX10' header extension for better compatiblity with older tools. Using this flag, the writer will always generate 'DX10' extension header files which are much faster to parse at load-time. These files are compatible with the legacy D3DX10 or D3DX11 library.
{"DDSFLAGSFORCEDX10EXTMISC2}" When saving DDS files, always use the 'DX10' header extension and write miscFlags2_ data as needed, if even if the resulting file is not compatible with the legacy D3DX10 or D3DX11 libraries.

Updated Wiki: Version History

walbourn — Sat, 23 Mar 2013 00:58:47 GMT

March 22, 2013

Supports reading and writing alpha-mode (straight, premultiplied, etc.) metadata in .DDS files
Added build option to use WICCreateImagingFactory_Proxy instead of CoCreateInstance to obtain WIC factory

January 29, 2013

Added PremultiplyAlpha to DirectXTex; -pmalpha switch for texconv command-line tool
Fixed problem with forceSRGB implementation for Ex versions of CreateTexture, CreateShaderResourceView, DDSTextureLoader and WICTextureLoader

December 11, 2012

Ex versions of CreateTexture, CreateShaderResourceView, DDSTextureLoader and WICTextureLoader
Fixed BC2 and BC3 decompression issue for unusual color encoding case
Converted annotation to SAL2 for improved VS 2012 /analyze experience
Updated DirectXTex, DDSView, and Texconv with VS 2010 + Windows 8.0 SDK project using official 'property sheets'

November 15, 2012

Added support for WIC2 when available on Windows 8 and Windows 7 with KB 2670838
Added optional targetGUID parameter to SaveWIC* APIs to influence final container pixel format choice
Fixed bug in SaveDDS* which was generating invalid DDS files for 1D dimension textures
Improved robustness of CaptureTexture when resolving MSAA source textures
Sync'd DDSTextureLoader, ScreenGrab, and WICTextureLoader standalone versions with latest DirectXTK release

September 28, 2012

Added ScreenGrab module for creating runtime screenshots
Renamed project files for better naming consistency
New Typeless utilities for DirectXTex
Some minor code cleanup for DirectXTex's WIC writer function
Bug fixes and new -tu/-tf options for texconv

June 22, 2012

Moved to using XNA Math 2.05 instead of XNA Math 2.04 for USE_XNAMATH builds
Fixed BGR vs. RGB color channel swizzle problem with 24bpp legacy .DDS files in DirectXTex
Update to DirectXTex WIC and WICTextureLoader for additional 96bpp float format handling on Windows 8

May 31, 2012

Minor fix for DDSTextureLoader's retry fallback that can happen with 10level9 feature levels
Switched to use "_DEBUG" instead of "DEBUG" and cleaned up debug warnings
added Metro style application project files for DirectXTex

April 20, 2012

DirectTex's WIC-based writer opts-in for the Windows 8 BMP encoder option for writing 32 bpp RGBA files with the BITMAPV5HEADER

March 30, 2012

WICTextureLoader updated with Windows 8 WIC pixel formats DirectXTex updated with limited non-power-of-2 texture support and TEXFILTERSEPARATE_ALPHA option
Texconv updated with '-sepalpha' command-line option
Added USE_XNAMATH control define to build DirectXTex using either XNAMath or DirectXMath
Added VS 2012 project files (which use DirectXMath instead of XNAMath and define DXGI12_FORMATS)

March 15, 2012

Fix for resource leak in CreateShaderResourceView() Direct3D 11 helper function in DirectXTex

March 5, 2012

Fix for too much temp memory allocated by WICTextureLoader; cleaned up legacy 'min/max' macro usage in DirectXTex

February 21, 2012

WICTextureLoader updated to handle systems and device drivers without BGRA or 16bpp format support

February 20, 2012

Some code cleanup for DirectXTex and DDSTextureLoader
Fixed bug in 10:10:10:2 format fixup in the LoadDDSFromMemory function
Fixed bugs in "non-zero alpha" special-case handling in LoadTGAFromFile
Fixed bug in _SwizzleScanline when copying alpha channel for BGRA<->RGBA swizzling

February 11, 2012

Update of DDSTextureLoader to also build in Metro style apps; added WICTextureLoader
Added CMYK WIC pixel formats to the DirectXTex conversion table

January 30, 2012

Minor code-cleanup for DirectXTex to enable use of PCH through 'directxtexp.h' header

January 24, 2011

Some code-cleanup for DirectXTex
Added DXGI 1.2 implementation for DDSTextureLoader and DirectXTex guarded with DXGI12_FORMATS compiliation define

December 16, 2011

Fixed x64 compilation warnings in DDSTextureLoader

November 30, 2011

Fixed some of the constants used in IsSupportedTexture(),
added ability to strip off top levels of mips in DDSTextureLoader,
changed DirectXTex to use CoCreateInstance rather than LoadLibrary to obtain the WIC factory,
a few minor /analyze related annotations for DirectXTex

October 27, 2011

Original release

Updated Wiki: Compress

walbourn — Mon, 04 Mar 2013 20:02:45 GMT

Compresses an image or set of images to a block-compressed (BC) format.

HRESULT Compress( _In_ const Image& srcImage, _In_ DXGI_FORMAT format,
    _In_ DWORD compress, _In_ float alphaRef,
    _Out_ ScratchImage& cImage );

HRESULT Compress( _In_reads_(nimages) const Image* srcImages, _In_ size_t nimages,
    _In_ const TexMetadata& metadata,
    _In_ DXGI_FORMAT format, _In_ DWORD compress, _In_ float alphaRef,
    _Out_ ScratchImage& cImages );

Parameters

format: Format to compress to. Must be a BC compressed format (i.e. DXGI_FORMAT_BC1_UNORM, DXGI_FORMAT_BC1_UNORM_SRGB - DXGI_FORMAT_BC7_UNORM, DXGI_FORMAT_BC7_UNORM_SRGB)

compress: Compress control flags

TEX_COMPRESS_DEFAULT Default flags.
TEX_COMPRESS_RGB_DITHER Enables dithering RGB colors for BC1-3 compression
TEX_COMPRESS_A_DITHER Enables dithering alpha channel for BC1-3 compression
TEX_COMPRESS_DITHER Same as TEX_COMPRESS_RGB_DITHER and TEX_COMPRESS_A_DITHER
TEX_COMPRESS_UNIFORM By default, BC1-3 uses a perceptual weighting. By using this flag, the perceptual weighting is disabled which can be useful when using the RGB channels for other data.
TEX_COMPRESS_PARALLEL This opts-in to multi-threaded compression if enabled.

alphaRef: Threshold reference value when compressing an alpha channel for BC1 formats which support 1-bit transparency.

Example

ScratchImage srcImage;

...

ScratchImage bcImage;
hr = Compress( srcImage.GetImages(), srcImage.GetImageCount(), srcImage.GetMetadata(), DXGI_FORMAT_BC3_UNORM, TEX_COMPRESS_DEFAULT, 0.5f, bcImage );
if ( FAILED(hr) )
    ...

Remarks

By default, the BC1 - BC3 color encoding algorithms will use a perceptual weighting of the Red and Blue channels which usually gives better visual results for standard color textures. For textures that do not contain color data, you will likely want to use TEX_COMPRESS_UNIFORM to disable the perceptual weighting.

directxtex Wiki Rss Feed

Updated Wiki: Version History

Updated Wiki: ComputeMSE

Parameters

Remarks

Updated Wiki: ComputeMSE

Parameters

Remarks

Updated Wiki: Texture Functions

Examples

Related Flags

Updated Wiki: Filter Flags

Updated Wiki: Filter Flags

Updated Wiki: Filter Flags

Updated Wiki: DirectXTex

Headers

Namespace

Functions

Structures

Adding to a VS Project

Release Notes

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading

Updated Wiki: DirectXTex

Headers

Namespace

Functions

Structures

Adding to a VS Project

Release Notes

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading

Updated Wiki: Texconv

Syntax

Optional Switches Description

Updated Wiki: DDS I/O Functions

Examples

Related Flags

Updated Wiki: DDS I/O Functions

Examples

Related Flags

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading

Updated Wiki: DDSTextureLoader

Functions

Example

Feature Level Notes

Release Notes

Further Reading

Updated Wiki: Utility Functions

Updated Wiki: DDS I/O Functions

Examples

Related Flags

Updated Wiki: Version History

Updated Wiki: Compress

Parameters

Example

Remarks

Related Links