DDS

edit

DDS files (.dds) store the textures of Direct3D and of most game engines: block-compressed (BC1 to BC7, the DXT formats) or uncompressed pixels, with their mipmaps, the faces of a cube map, the elements of a texture array or the depth slices of a volume texture. The library reads them, and writes them with DdsEncoder: its own block compressors encode BC1 to BC7.

Image.Load gives the full-size level of the first face or element (the first depth slice of a volume texture). ImageCollection.Load reaches every surface.

What is read

Reading
Block-compressedBC1 (DXT1, with 1-bit alpha), BC2 (DXT3), BC3 (DXT5), BC4 and BC5 unsigned and signed (ATI1, ATI2, BC4U, BC4S, BC5U, BC5S), BC6H unsigned and signed, BC7 (the eight modes); their _SRGB and _TYPELESS forms
UncompressedR8G8B8A8 and B8G8R8A8 (UNORM and SRGB), B8G8R8X8, B5G6R5, B5G5R5A1, B4G4R4A4, R10G10B10A2, R16G16B16A16 (UNORM and FLOAT), R32G32B32A32_FLOAT and the formats of fewer channels, R8, R8G8, R16, R16G16, A8, R11G11B10_FLOAT, R9G9B9E5_SHAREDEXP
Legacy headersEvery bit-mask layout of 8 to 32 bits (RGB, luminance, alpha), the DXT FourCCs and the numeric codes of the Direct3D 9 floating-point formats
StructureMipmaps, cube maps (and the partial cube maps of Direct3D 9), texture arrays, arrays of cube maps, volume textures, 1D textures

The image of a format is the lossless form of what it stores:

  • 8-bit formats and BC1, BC2, BC3 and BC7 decode to 8-bit pixels; formats with a channel of more than 8 bits (R16, R10G10B10A2, R16G16B16A16_UNORM) to 16-bit pixels. Channels of 4, 5 or 6 bits are expanded to the nearest 8-bit value.
  • One channel (R8, R16, BC4, a luminance layout) is gray; two channels (R8G8, BC5) are red and green with a blue of 0; A8 is an alpha mask. A format without alpha is opaque.
  • Floating-point formats, BC6H, R11G11B10_FLOAT and R9G9B9E5_SHAREDEXP decode to RgbaHalf or RgbaFloat in linear light, values outside [0, 1] included; the formats of one channel (R16_FLOAT, R32_FLOAT) decode to GrayHalf or GrayFloat. The signed BC4 and BC5 formats decode to GrayFloat and RgbaFloat values in [-1, 1] (normal maps).
  • The _SRGB formats are labeled with the CICP description of sRGB; the other integer formats are untagged. The colors are never converted.

BC7 and BC6H decode to the exact values of their specification; BC1 to BC5 are rounded once from the real numbers the specification gives to the precision of the format.

Read every surface of a texture

public static IReadOnlyList<string> ExportCubeFaces(string ddsPath, string outputDirectory)
{
    // Image.Load gives the top level of the first face; a collection reaches every surface, decoded on demand
    using var texture = ImageCollection.Load(ddsPath);
    var written = new List<string>();
    foreach (var entry in texture.Entries)
    {
        // Each entry says where it is in the texture: keep the full-size level of every face
        if (entry.TextureSurface is not { MipLevel: 0, Face: { } face } surface)
            continue;

        var path = Path.Combine(outputDirectory, $"{surface.ArrayIndex}-{face}.png");
        using var image = entry.Decode();
        image.Save(path);
        written.Add(path);
    }

    return written;
}

A DDS collection has the kind ImageCollectionKind.TextureSurfaces. Its entries are in file order: for each element of the array, for each face of a cube map (+X, −X, +Y, −Y, +Z, −Z: the faces a partial cube map stores), for each mipmap level from the largest, the surface of the level, and for a volume texture each depth slice of the level. TextureSurface tells where an entry is:

PropertyMeaning
ArrayIndexThe element of the array (of the cube map in an array of cube maps), 0 otherwise
FaceThe CubeMapFace of a cube map, null otherwise
MipLevelThe mipmap level: 0 is the full size, each level halves the dimensions (at least 1)
DepthSliceThe depth slice of a level of a volume texture, 0 otherwise

The collection reads the headers only; an entry decodes its surface when you call Decode. The number of surfaces counts against MaxFrames, and ImageInfo.CollectionEntryCount gives it without loading the collection. A texture collection can be saved again with DdsEncoder or Ktx2Encoder (see below), or its entries decoded and saved in another format.

Write a texture

public static void SaveDdsTextures(string albedoPath, IReadOnlyList<string> skyFacePaths, string outputDirectory)
{
    // A color texture: BC7 with sRGB colors, and the full chain of mipmaps averaged in linear light
    using (var albedo = Image.Load(albedoPath))
    {
        albedo.Save(Path.Combine(outputDirectory, "albedo.dds"), new DdsEncoder
        {
            TextureFormat = DdsTextureFormat.Bc7UnormSrgb,
            GenerateMipmaps = true,
        });
    }

    // A cube map: the six faces (+X, -X, +Y, -Y, +Z, -Z) are the entries of a collection of texture surfaces
    using var sky = ImageCollection.Create(ImageCollectionKind.TextureSurfaces);
    for (var i = 0; i < 6; i++)
    {
        using var face = Image.Load(skyFacePaths[i]);
        sky.Add(face, new TextureSurface(face: (CubeMapFace)i));
    }

    sky.Save(Path.Combine(outputDirectory, "sky.dds"), new DdsEncoder { TextureFormat = DdsTextureFormat.Bc1UnormSrgb, GenerateMipmaps = true });
}

Save with a .dds path, or ImageEncoder.Create, gives a DdsEncoder with its default settings: the uncompressed format that keeps the pixels exactly (R8G8B8A8_UNORM for 8-bit pixels, R8 or R16 for gray, R16G16B16A16 for 16-bit pixels, the floating-point formats for floating-point pixels). The settings:

SettingMeaning
TextureFormatThe DdsTextureFormat: R8G8B8A8 and B8G8R8A8 (UNORM and SRGB), R8, R8G8, R16, R16G16B16A16 (UNORM and FLOAT), R32G32B32A32_FLOAT, BC1, BC2, BC3 and BC7 (UNORM and SRGB), BC4 and BC5 (UNORM and SNORM), BC6H (UF16 and SF16)
QualityThorough (the default) searches more modes and partitions per block; Fast is several times faster
GenerateMipmapsWrites the full chain of mipmaps, down to 1×1
HeaderVersionThe legacy header when it can describe the texture (the default), or always the DX10 header
AllowBitDepthReductionAccepts 16-bit pixels in an 8-bit format (BC1 to BC5 and BC7 are 8-bit formats)
AllowChannelReductionAccepts pixels whose channels the format lacks: alpha in a format without alpha, colors in a one-channel format (red is kept), blue in a two-channel one

ImageCollection.Save writes cube maps, texture arrays and arrays of cube maps: a collection of the kind ImageCollectionKind.TextureSurfaces, loaded from a DDS or KTX 2.0 file, or created with ImageCollection.Create and filled with Add(image, surface), where a TextureSurface says where each image goes. Every face and every array element must be there, with the same mipmap levels at the sizes of the chain; a collection of base levels gets its mipmaps from GenerateMipmaps. Volume textures are not written.

Mipmaps average the texels each level covers (a box filter, exact for odd sizes), weighted by their alpha, in linear light for sRGB-encoded colors.

Choose a block format

The block compressors are deterministic: the same pixels and settings give the same bytes on every platform.

FormatUse it forSolid colors
BC1Opaque colors, or a 1-bit cutout, at the smallest sizeWithin 1 of the color (the best 5:6:5 endpoints)
BC2Colors with sharp, banded alphaColors as BC1; alpha within 8 (4-bit alpha)
BC3Colors with smooth alphaColors as BC1; alpha exact
BC4, BC5One or two channels: masks, height maps, normal mapsExact
BC7Colors, with or without alpha, when quality matters more than sizeExact
BC6HHigh dynamic range colors (halves), such as environment mapsExact for every finite half

Use Thorough for assets built once and shipped, and Fast for previews and textures generated at run time.

BC1 to BC3 and BC4 and BC5 store each block as points on one line of colors: busy textures lose detail there first, BC7 keeps it. BC1 transparency is exact: an alpha below 128 is transparent, the other texels opaque. The Thorough level of BC7 and BC6H uses every mode and the partitions of two and three subsets; Fast uses the one-subset modes, and for BC7 the two-subset ones on blocks they fit much better.

Pitfalls

  • Premultiplied alpha (DXT2, DXT4, the alpha mode DDS_ALPHA_MODE_PREMULTIPLIED) is rejected with an UnsupportedImageFeatureException: the library never divides the colors by their alpha. The alpha modes straight, opaque and custom keep the stored alpha.
  • Video formats (YUY2, NV12...), depth and stencil formats, integer (_UINT, _SINT) and most signed formats, and typeless formats that have no single reading (BC6H_TYPELESS, R32G32B32A32_TYPELESS) are rejected.
  • The masks of a legacy header are read as they are written. DirectXTex reads the 10:10:10:2 masks with red and blue swapped, because D3DX wrote them backwards: such files decode with these two channels exchanged, as their header says.
  • Writers fill the dwPitchOrLinearSize field unreliably. A value that contradicts the size of the surface is rejected by default; lenient decoding ignores it, as DirectXTex does.
  • Image.Load reads the first surface only: a file whose later surfaces are cut loads, and its collection is rejected.
  • Floating-point textures cannot be loaded as integer pixels without a conversion policy: see Pixel formats.
  • The _SRGB formats declare sRGB-encoded colors; the UNORM formats are read back untagged. An image labeled linear can only be written with a MetadataHandling that discards the label. The floating-point and signed formats store linear light: an image labeled sRGB is rejected there unless the label is discarded.
  • BC6H stores finite halves (at most 65,504, not negative for UF16) and the signed BC4 and BC5 values in [-1, 1]; other samples are rejected, never clamped.