Skill v1.0.0

currentTrusted Publisher100/100

microsoft/directxtex/directxtex-usage

──Details

PublishedJuly 9, 2026 at 06:44 AM

Content Hashsha256:9b8c8b5c28a4b149...

Git SHA

──Files

Files (1 file, 9.9 KB)

SKILL.md9.9 KBactive

SKILL.md · 345 lines · 9.9 KB

version: "1.0.0" name: directxtex-usage description: >- Guide for integrating and using the DirectXTex texture processing library in new projects. Use this skill when asked about adding DirectXTex to a project, loading/saving textures, format conversion, mipmap generation, block compression, or Direct3D resource creation. license: MIT metadata: author: chuckw version: "1.0"

DirectXTex Usage Guide

This skill provides guidance for integrating the DirectXTex texture processing library into a C++ project.

When to Use

Invoke this skill when:

Adding DirectXTex as a dependency to a new or existing project.
Writing code that processes texture data (resizing, format conversion, mipmap generation, DirectX Block Compression, etc.).
Needing to understand the typical DirectXTex processing pipeline.

Overview

DirectXTex is a texture processing library for Direct3D 11 and Direct3D 12 applications. It provides support for reading and writing DDS files, and performing various texture content processing operations including resizing, format conversion, mipmap generation, block compression, and normal map creation.

Repository: <https://github.com/microsoft/DirectXTex>
Documentation: <https://github.com/microsoft/DirectXTex/wiki>
NuGet Packages: directxtex_desktop_win10, directxtex_uwp
vcpkg Port: directxtex

Integration Methods

vcpkg manifest-mode (Recommended)

In your vcpkg.json file, add the following:

json

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "directxtex"
  ]
}

vcpkg (classic)

bash

vcpkg install directxtex

Features: dx12 (DirectX 12 API support), openexr (OpenEXR support), tools (command-line tools). Triplets: x64-windows, x64-linux, arm64-windows, etc.

For DLL usage (x64-windows default triplet), define DIRECTX_TEX_IMPORT in your consuming project. For static library usage, use -static-md triplet variants.

CMakeLists.txt:

cmake

find_package(directxtex CONFIG REQUIRED)
target_link_libraries(${PROJECT_NAME} PRIVATE Microsoft::DirectXTex)

NuGet

Use directxtex_desktop_win10 for Win32 desktop applications or directxtex_uwp for UWP apps.

Project Reference

Add the appropriate .vcxproj from the DirectXTex/ folder to your solution and add a project reference. Add the DirectXTex directory to your Additional Include Directories.

Header Include

cpp

#include <d3d12.h>        // or <d3d11_1.h> — include BEFORE DirectXTex.h
#include <DirectXTex.h>
 
using namespace DirectX;

For auxiliary features, include additional headers:

cpp

#include <DirectXTexEXR.h>   // OpenEXR support
#include <DirectXTexJPEG.h>  // libjpeg support (non-WIC)
#include <DirectXTexPNG.h>   // libpng support (non-WIC)
#include <DirectXTexXbox.h>  // Xbox tiling extensions

DirectXTexJPEG, DirectXTexPNG are typically only used on Linux.

Key Concepts

ScratchImage

ScratchImage is the primary image container. It owns pixel memory and provides access to individual mip levels, array slices, and volume depth slices.

cpp

ScratchImage image;
HRESULT hr = LoadFromDDSFile(L"texture.dds", DDS_FLAGS_NONE, nullptr, image);
if (FAILED(hr))
    // handle error
 
const TexMetadata& metadata = image.GetMetadata();
const Image* img = image.GetImage(0, 0, 0); // mip 0, item 0, slice 0

TexMetadata

Describes the texture dimensions, format, mip levels, array size, and type (1D, 2D, 3D, cubemap).

Blob

A memory buffer used for serialized output (e.g., saving to memory rather than files).

Error Handling

All processing functions return HRESULT. Check with FAILED() / SUCCEEDED() macros.

Common Workflows

Loading Textures

cpp

// From DDS file
ScratchImage image;
HRESULT hr = LoadFromDDSFile(L"texture.dds", DDS_FLAGS_NONE, nullptr, image);
 
// From WIC file (PNG, BMP, JPEG, TIFF, etc.) — Windows only
ScratchImage image;
HRESULT hr = LoadFromWICFile(L"texture.png", WIC_FLAGS_NONE, nullptr, image);
 
// From TGA file
ScratchImage image;
HRESULT hr = LoadFromTGAFile(L"texture.tga", TGA_FLAGS_NONE, nullptr, image);
 
// From HDR file
ScratchImage image;
HRESULT hr = LoadFromHDRFile(L"texture.hdr", nullptr, image);
 
// From memory
ScratchImage image;
HRESULT hr = LoadFromDDSMemory(pData, dataSize, DDS_FLAGS_NONE, nullptr, image);

Saving Textures

cpp

// Save to DDS file
const Image* img = image.GetImages();
size_t nimages = image.GetImageCount();
const TexMetadata& metadata = image.GetMetadata();
HRESULT hr = SaveToDDSFile(img, nimages, metadata, DDS_FLAGS_NONE, L"output.dds");
 
// Save single image to WIC file (PNG) — Windows only
hr = SaveToWICFile(*image.GetImage(0, 0, 0), WIC_FLAGS_NONE,
    GetWICCodec(WIC_CODEC_PNG), L"output.png");
 
// Save to memory blob
Blob blob;
hr = SaveToDDSMemory(img, nimages, metadata, DDS_FLAGS_NONE, blob);

Format Conversion

cpp

ScratchImage converted;
HRESULT hr = Convert(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    DXGI_FORMAT_R8G8B8A8_UNORM, TEX_FILTER_DEFAULT, TEX_THRESHOLD_DEFAULT, converted);

Resizing

cpp

ScratchImage resized;
HRESULT hr = Resize(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    1024, 1024, TEX_FILTER_DEFAULT, resized);

Mipmap Generation

cpp

ScratchImage mipChain;
HRESULT hr = GenerateMipMaps(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    TEX_FILTER_DEFAULT, 0, mipChain);
// 0 levels = generate full mip chain

Block Compression

cpp

ScratchImage compressed;
HRESULT hr = Compress(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT, compressed);
 
// GPU-accelerated BC6H/BC7 compression (Direct3D 11)
ScratchImage compressed;
HRESULT hr = Compress(pDevice, image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_ALPHA_WEIGHT_DEFAULT, compressed);

Decompression

cpp

ScratchImage decompressed;
HRESULT hr = Decompress(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    DXGI_FORMAT_R8G8B8A8_UNORM, decompressed);

Normal Map Generation

cpp

ScratchImage normalMap;
HRESULT hr = ComputeNormalMap(*image.GetImage(0, 0, 0),
    CNMAP_CHANNEL_LUMINANCE, 2.0f,
    DXGI_FORMAT_R8G8B8A8_UNORM, normalMap);

Premultiplied Alpha

cpp

ScratchImage pmAlpha;
HRESULT hr = PremultiplyAlpha(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
    TEX_PMALPHA_DEFAULT, pmAlpha);

Creating Direct3D 11 Resources

cpp

#include <d3d11.h>
#include <DirectXTex.h>
 
// Create texture resource
ID3D11Resource* pTexture = nullptr;
HRESULT hr = CreateTexture(pDevice, image.GetImages(), image.GetImageCount(),
    image.GetMetadata(), &pTexture);
 
// Create shader resource view directly
ID3D11ShaderResourceView* pSRV = nullptr;
hr = CreateShaderResourceView(pDevice, image.GetImages(), image.GetImageCount(),
    image.GetMetadata(), &pSRV);

Creating Direct3D 12 Resources

cpp

#include <d3d12.h>
#include <DirectXTex.h>
 
// Create committed resource
ID3D12Resource* pTexture = nullptr;
HRESULT hr = CreateTexture(pDevice, image.GetMetadata(), &pTexture);
 
// Prepare upload data for CopyTextureRegion
std::vector<D3D12_SUBRESOURCE_DATA> subresources;
hr = PrepareUpload(pDevice, image.GetImages(), image.GetImageCount(),
    image.GetMetadata(), subresources);

Typical Texture Pipeline

A common offline texture processing pipeline:

cpp

// 1. Load source image
ScratchImage source;
HRESULT hr = LoadFromWICFile(L"diffuse.png", WIC_FLAGS_NONE, nullptr, source);
if (FAILED(hr)) return hr;
 
// 2. Resize if needed
ScratchImage resized;
if (source.GetMetadata().width != 1024 || source.GetMetadata().height != 1024)
{
    hr = Resize(*source.GetImage(0, 0, 0), 1024, 1024, TEX_FILTER_DEFAULT, resized);
    if (FAILED(hr)) return hr;
}
else
{
    resized = std::move(source);
}
 
// 3. Generate mipmaps
ScratchImage mipChain;
hr = GenerateMipMaps(*resized.GetImage(0, 0, 0), TEX_FILTER_DEFAULT, 0, mipChain);
if (FAILED(hr)) return hr;
 
// 4. Compress to BC7
ScratchImage compressed;
hr = Compress(mipChain.GetImages(), mipChain.GetImageCount(), mipChain.GetMetadata(),
    DXGI_FORMAT_BC7_UNORM, TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT, compressed);
if (FAILED(hr)) return hr;
 
// 5. Save as DDS
hr = SaveToDDSFile(compressed.GetImages(), compressed.GetImageCount(),
    compressed.GetMetadata(), DDS_FLAGS_NONE, L"diffuse.dds");

Format Utilities

DirectXTex provides utility functions for querying DXGI format properties:

cpp

bool compressed = IsCompressed(DXGI_FORMAT_BC7_UNORM);     // true
size_t bpp = BitsPerPixel(DXGI_FORMAT_R8G8B8A8_UNORM);    // 32
bool srgb = IsSRGB(DXGI_FORMAT_R8G8B8A8_UNORM_SRGB);     // true
 
DXGI_FORMAT srgbFmt = MakeSRGB(DXGI_FORMAT_R8G8B8A8_UNORM);   // _SRGB variant
DXGI_FORMAT linearFmt = MakeLinear(DXGI_FORMAT_R8G8B8A8_UNORM_SRGB); // non-SRGB
 
size_t rowPitch, slicePitch;
ComputePitch(DXGI_FORMAT_R8G8B8A8_UNORM, 256, 256, rowPitch, slicePitch);

Platform Support

Platform	DDS	HDR	TGA	WIC	Direct3D 11	Direct3D 12
Windows desktop	✓	✓	✓	✓	✓	✓
UWP	✓	✓	✓	✓	✓	✓
Xbox (GDK)	✓	✓	✓	—	✓	✓
Linux	✓	✓	✓	—	—	—

Command-Line Tools

DirectXTex includes three CLI tools for texture processing:

texconv — Convert images to DDS with compression, mipmaps, and resizing
texassemble — Create cubemaps, texture arrays, and volume maps from individual images
texdiag — Inspect and validate DDS files

Example texconv usage: