DirectXTex

DirectXTex is a shared source library for texture processing. It provides capabilities for reading and writing .DDS files and performing various operations such as:

• Resizing and format conversion.
• Mip-map generation.
• Block compression for Direct3D runtime texture resources.
• Height-map to normal-map conversion.

The library utilizes Windows Image Component (WIC) APIs for bitmap processing (BMP, JPEG, PNG, TIFF, and HD Photo). It also includes built-in readers and writers for .TGA and .HDR formats, which are not natively supported by standard WIC codecs.

The WICTextureLoader is a Direct3D 9, 11, and 12 2D texture loader that uses WIC to load standard bitmap files (BMP, JPEG, PNG, HD Photo, etc.).

Capabilities:

• Loads and creates 2D textures.
• Can resize textures based on current feature level or explicit parameters.
• Can perform format conversion to a DXGI_FORMAT if required.

Limitations:

• Does not support 1D textures, volume textures, cubemaps, or texture arrays.
• For fully "precooked" textures, DDSTextureLoader is recommended for better performance and quality.

The DDSTextureLoader component provides a streamlined, lightweight version of DDS loading code for Direct3D runtimes. It is ideal for high-performance runtime usage as it performs no runtime pixel data conversions.

Available versions:

• Direct3D 9
• Direct3D 11
• Direct3D 12

It supports the full complement of Direct3D texture resources, including 1D, 2D, volume maps, cubemaps, mipmap levels, texture arrays, and BC formats.

When using the DirectXTex library in your own code, you should only include the public headers. Most headers in the DirectXTex/ directory are intended for internal implementation only.

Public Headers:

• DirectXTex.h
• DirectXTex.inl

Since the June 2020 release, DirectXTex uses typed enum bitmask flags. This affects how you pass flags to functions:

1. Do not use 0 literals: You must use the appropriate default enum value (e.g., CP_FLAGS_NONE, DDS_FLAGS_NONE, WIC_FLAGS_NONE, TEX_FILTER_DEFAULT, etc.).
2. Use the enum type: Instead of DWORD, use the specific enum type when building flag values locally.

Example of correct bitmask usage:

DDS_FLAGS flags = DDS_FLAGS_NONE;
if (...) flags |= DDS_FLAGS_EXPAND_LUMINANCE;

Combining flags: You can combine different flag types using the bitwise OR (|) operator if they overlap (e.g., combining TEX_FILTER_FLAGS with WIC_FLAGS).

WIC_FLAGS wicFlags = WIC_FLAGS_NONE | TEX_FILTER_CUBIC;

The texconv tool supports multiple command-line prefix styles:

• Windows-style: Uses - or / (e.g., -o <dir> or /o <dir>).
• GNU long-form: Uses -- and accepts space, =, or : as value separators (e.g., --width 100, --width=100, or --width:100).

Use texconv to convert between common image formats like PNG, DDS, JPEG, and BMP.

• PNG to DDS (Default): Converts a PNG to DDS with mipmaps and no compression.
• BC7 Compression: High-quality compression using the BC7 format.
• sRGB-aware BC7: Uses BC7 compression with sRGB awareness.
• DDS to PNG: Converts a DDS file back to PNG.
• JPEG with Quality: Converts a BMP to JPEG with a specific quality setting.

NuGet

• Use directxtex_desktop_win10 for Win32 desktop applications.
• Use directxtex_uwp for UWP applications.

Project Reference

1. Add the appropriate .vcxproj from the DirectXTex/ folder to your Visual Studio solution.
2. Add a project reference to the DirectXTex project.
3. Add the DirectXTex directory to your project's Additional Include Directories.

You can extract cubemap faces from a .dds file into various 2D layouts. The output defaults to cubemap.bmp unless specified with -o.

Available extraction commands:

• h-cross: Horizontal cross.
• v-cross: Vertical cross.
• v-cross-fnz: Vertical cross with flipped -Z face.
• h-strip: Horizontal strip.
• v-strip: Vertical strip.
• h-tee: Horizontal tee.

# Extract to horizontal cross
texassemble h-cross -o cubemap_cross.png cubemap.dds

# Extract to vertical strip
texassemble v-strip -o cubemap_vstrip.png cubemap.dds