Directxtex Usage

microsoft/directxtex-usage

>- 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.

5k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

2136

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/microsoft/DirectXTex --skill directxtex-usage

What comes with it

11 545 bytes besides the instruction

reference/overview.md

The instruction itself

31 sections, as written by the author

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:

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

vcpkg (classic)

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:

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

#include <d3d12.h>        // or <d3d11_1.h> — include BEFORE DirectXTex.h
#include <DirectXTex.h>

using namespace DirectX;

For auxiliary features, include additional headers:

#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.

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

// 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

// 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

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

Resizing

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

Mipmap Generation

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

Block Compression

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

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

Normal Map Generation

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

Premultiplied Alpha

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

Creating Direct3D 11 Resources

#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

#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:

// 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:

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:

texconv -f BC7_UNORM -m 0 -y diffuse.png

How to use it

Copy the folder

Take microsoft/directxtex-usage from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.