Getting Started

The DirectXTex library is designed to operate on textures to prepare them for use by Direct3D. The project includes a C++ library and a number of programs built using the library.

flowchart TD
    A(DirectXTex C++ Library)
    A-->B
    A-->C
    A-->D
    A--sample-->E
    B[texconv]
    C[texdiag]
    D[texdiag]
    E[DDSView]

Loading

The DirectXTex library itself consists of a few functional areas:

graph LR

subgraph Direct3D interop functions
    1[D3D11]
    2[D3D12]
end

subgraph Image operations
    C[Pixel format conversion]
    F[Resizing and mipmaps]
    B[Block compression<br />BC1-BC7]
    E[Helper functions]
    N[Normal maps]
    P[Precomputed alpha]
end

subgraph Image I/O
    W[WIC]
    D[DDS]
    T[TGA]
    H[HDR]
end

Loading

WIC is the Windows Image Component which is a built-in library for reading and writing image files like BMP, PNG, JPEG, etc. The DirectXTex library makes extensive use of WIC where applicable, but also includes custom code focused on the needs of texture processing. On non-Windows platforms, WIC is not available so only a subset of functionality is implemented.  

Command-line tools

The texassemble, texconv, and texdiag programs are command-line tools for doing various operations related to Direct3D texture files. For example, the following will convert an image to a DDS file using BC3 format compression:

texconv -ft DDS -f BC3_UNORM texture.png

The output will be texture.dds in the current working directory which will includes a mipmap chain generated from the image by resizing.

"Hello, World"

The following is a simple program which does the same thing as the texconv option above:

#include <Windows.h>

#include "DirectXTex.h"

#include <cstdio>

using namespace DirectX;

int main()
{
    HRESULT hr = CoInitializeEx(nullptr, COINIT_MULTITHREADED);
    if (FAILED(hr))
    {
        wprintf(L"Failed to initialize COM (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    ScratchImage image;
    hr = LoadFromWICFile(L"texture.png", WIC_FLAGS_NONE, nullptr, image);
    if (FAILED(hr))
    {
        wprintf(L"Failed to load texture.png (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    ScratchImage timage;
    hr = GenerateMipMaps(image, TEX_FILTER_DEFAULT, 0, timage);
    if (FAILED(hr))
    {
        wprintf(L"Failed to generate mipmaps (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    image.Release();

    hr = Compress(timage.GetImages(), timage.GetImageCount(), timage.GetMetadata(),
        DXGI_FORMAT_BC3_UNORM, TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT,
        image);
    if (FAILED(hr))
    {
        wprintf(L"Failed to compress texture (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    hr = SaveToDDSFile(image.GetImages(), image.GetImageCount(), image.GetMetadata(),
        DDS_FLAGS_NONE, L"texture.dds");
    if (FAILED(hr))
    {
        wprintf(L"Failed to write texture to DDS (%08X)\n", static_cast<unsigned int>(hr));
        return 1;
    }

    return 0;
}

Further reading

DirectXTex provides details on how to build and link the library

See texassemble, texconv, and texdiag for more details on the command-line tools.