ddsfile

ddsfile is a Rust crate for parsing and composing Microsoft DirectDraw Surface (.DDS) files, the container format widely used for texture data across DirectX, OpenGL, Vulkan, and Metal asset pipelines. It handles the container envelope end to end: parsing headers, computing layout metadata such as pitch, stride, and mipmap sizes, and providing structured access to the raw texture bytes.

The library supports both the legacy Direct3D 9 D3DFormat system and the modern DirectX 10+ DxgiFormat system, including the DX10 extension header. It understands mipmapped textures, volume textures, texture arrays, cubemaps, and block-compressed formats from DXT1 through BC7, while leaving the actual pixel encoding and decoding to your own code.

What You Get

• A pure-Rust reader and writer for .DDS texture container files
• Support for both legacy D3DFormat (Direct3D 9) and modern DxgiFormat (DirectX 10+) format systems
• Layout queries for pitch, stride, block size, bits per pixel, array layers, and mipmap levels
• Handling of mipmaps, volume textures, texture arrays, cubemaps, and DXT1-BC7 compressed data
• The DX10 extension header (Header10) and RGBA bitmask-identified formats

Common Use Cases

• Loading DDS textures into a game engine or renderer pipeline
• Converting or repackaging texture assets between format systems
• Inspecting DDS header and layout metadata in asset tooling

Under The Hood

Architecture - The crate is organized around a central Dds struct that owns a Header, an optional Header10 DX10 extension, and the raw texture byte buffer. Parsing and composition flow through src/header.rs and src/header10.rs, while the src/format module separates the two format eras into d3d.rs (Direct3D 9 FourCC and RGB bitmask formats), dxgi.rs (DirectX 10+ DXGI formats), and pixel_format.rs, with layout computation (pitch, stride, mipmap sizes) built on top in src/lib.rs.

Tech Stack - Written in Rust (edition 2021, MSRV 1.73) with a deliberately small dependency set: bitflags for header flag sets, byteorder for endian-correct binary reads and writes, and enum-primitive-derive plus num-traits for mapping numeric format codes to enums. Two small binary utilities (ddsinfo, retag) ship alongside the library.

Code Quality - The codebase is compact (~2,600 lines) and idiomatic, using typed enums and bitflags to model the format space and a dedicated error.rs for error types. Documentation-embedded examples are extensive, though the dedicated tests.rs file is minimal, so most correctness assurance comes from doc examples and the type system rather than a broad unit-test suite. Tooling includes deny.toml, renovate.json, and a pinned rust-toolchain.toml.

API Design - The public surface is ergonomic: descriptive getters like get_width, get_num_mipmap_levels, and get_dxgi_format read naturally, and construction uses a NewDxgiParams builder-style struct to make the many optional texture attributes explicit at call sites. A published MSRV policy and docs.rs documentation lower the barrier to adoption.