Crate ddsfile 

A library for reading and writing Microsoft DirectDraw Surface (DDS) files.

DDS is a container format for storing texture data, originally designed for DirectX but widely used across graphics APIs (OpenGL, Vulkan, Metal) and asset pipelines. This library handles the container envelope — parsing headers, computing layout metadata, and providing access to the raw texture data. It does not decode or encode pixel data.

Examples

Reading a DDS file:

use ddsfile::Dds;

let file = std::fs::File::open("texture.dds").unwrap();
let dds = Dds::read(file).unwrap();

println!("{}x{}", dds.get_width(), dds.get_height());
println!("Mipmaps: {}", dds.get_num_mipmap_levels());
println!("Format: {:?}", dds.get_dxgi_format());

// Access the pixel data for the first (or only) layer
let data = dds.get_data(0).unwrap();

Creating and writing a DDS file:

use ddsfile::{Dds, DxgiFormat, NewDxgiParams, D3D10ResourceDimension, AlphaMode};

let dds = Dds::new_dxgi(NewDxgiParams {
    height: 256,
    width: 256,
    depth: None,
    format: DxgiFormat::BC7_UNorm_sRGB,
    mipmap_levels: Some(1),
    array_layers: None,
    caps2: None,
    is_cubemap: false,
    resource_dimension: D3D10ResourceDimension::Texture2D,
    alpha_mode: AlphaMode::Unknown,
}).unwrap();

// Fill dds.data with your texture data, then write:
let mut file = std::fs::File::create("output.dds").unwrap();
dds.write(&mut file).unwrap();

Format systems: D3D vs DXGI

DDS files exist in two eras, and this library supports both:

• D3DFormat — The original format system from Direct3D 9. Formats are identified by FourCC codes or RGB bitmasks stored in the PixelFormat struct within the Header. Supports ~44 formats including DXT1–DXT5 compression and common uncompressed layouts.

• DxgiFormat — The modern format system introduced with DirectX 10. Supports 80+ formats including sRGB variants, typeless formats, BC6H/BC7 compression, and video/planar formats. When a DDS file uses this system, the PixelFormat FourCC is set to "DX10" and an additional Header10 follows the main Header, carrying the DxgiFormat enum value directly.

If you’re creating new DDS files, prefer Dds::new_dxgi unless you specifically need compatibility with tools that only understand the legacy D3D format.

Headers: Header vs Header10

Every DDS file has a Header (124 bytes) containing dimensions, pitch/linear size, mipmap count, pixel format, and capability flags. Files using DxgiFormat also have a Header10 (20 bytes) immediately after, which stores the DXGI format enum, resource dimension, array size, and alpha mode. The presence of Header10 is signaled by FourCC = "DX10" in the header’s pixel format.

Most users should interact with the Dds struct directly rather than reading headers manually — the getters handle both paths transparently.

Structs

Caps

Surface complexity flags.

Caps2

Additional surface detail flags for cubemaps and volume textures.

Dds

A parsed DDS (DirectDraw Surface) file.

FourCC

A four-character code stored as a little-endian u32.

Header

The mandatory 124-byte DDS header present in every DDS file.

Header10

The DX10 extension header (20 bytes), present in DDS files that use DxgiFormat.

HeaderFlags

Flags indicating which header fields contain valid data.

MiscFlag

Miscellaneous resource flags for Header10.

NewD3dParams

Parameters for Dds::new_d3d.

NewDxgiParams

Parameters for Dds::new_dxgi.

PixelFormat

Describes the pixel layout within the legacy DDS header.

PixelFormatFlags

Flags indicating which fields in PixelFormat contain valid data.

Enums

AlphaMode

Describes how to interpret the alpha channel in a DDS texture.

D3D10ResourceDimension

The type of resource stored in the DDS file.

D3DFormat

Pixel formats from the legacy Direct3D 9 era.

DxgiFormat

Pixel formats from the DirectX Graphics Infrastructure (DXGI), introduced with DirectX 10.

Error

Errors that can occur when reading, writing, or querying a DDS file.

Traits

DataFormat

Common interface for querying format metadata from both D3DFormat and DxgiFormat.