Crate image_dds

image_dds

image_dds enables converting uncompressed image data to and from compressed formats.

Start converting image data by creating a Surface and using one of the provided methods.

Usage

The main conversion functions image_from_dds and dds_from_image convert between ddsfile and image. For working with floating point images like EXR files, use imagef32_from_dds and dds_from_imagef32.

These functions are wrappers over conversion methods for Surface, SurfaceRgba8, and SurfaceRgba32Float. These methods are ideal for internal conversions in libraries or applications that want to use Surface instead of DDS as an intermediate format.

Surfaces may use owned or borrowed data depending on whether the operation is lossless or not. A SurfaceRgba8 can represent a view over an image::RgbaImage without any copies, for example.

For working with custom texture file formats like in video games, consider defining conversion methods to and from Surface to enable chaining operations. These methods may need to return an error if not all texture formats are supported by ImageFormat.

let dds = custom_tex.to_surface()?.to_dds()?;

let image = image::open("cat.png").unwrap().to_rgba8();
let surface = image_dds::SurfaceRgba8::from_image(&image).encode(
    image_dds::ImageFormat::BC7RgbaUnorm,
    image_dds::Quality::Normal,
    image_dds::Mipmaps::GeneratedAutomatic,
)?;
let new_custom_tex = CustomTex::from_surface(surface)?;

Features

Despite the name, neither the ddsfile nor image crates are required and can be disabled in the Cargo.toml by setting default-features = false. The "ddsfile" and "image" features can then be enabled individually. The "encode" feature is enabled by default but can be disabled to resolve compilation errors on some targets if not needed.

Direct Draw Surface (DDS)

DDS can store GPU texture data in a variety of formats. This includes compressed formats like ImageFormat::BC7RgbaUnorm or uncompressed formats like ImageFormat::Rgba8Unorm. Libraries and applications for working with custom GPU texture file formats often support DDS. This makes DDS a good interchange format for texture conversion workflows.

DDS has more limited application support compared to standard formats like TIFF or PNG especially on Linux and MacOS. GPU compression formats tend to be lossy, which makes it a poor choice for archival purposes. For this reason, it’s often more convenient to work with texture data in an uncompressed format.

image_dds enables safe and efficient compressed GPU texture conversion across platforms. A conversion pipeline may look like GPU Texture <-> DDS <-> image with the conversions to and from image and DDS provided by image_dds.

Although widely supported by modern desktop and console hardware, not all contexts support compressed texture formats. DDS plugins for image editors may not support newer compression formats like BC7. Rendering APIs may not support some compressed formats or only make it available via an extension such as in the browser. image_dds supports decoding surfaces to RGBA u8 or f32 for better compatibility at the cost of increased memory usage.

Limitations

Not all targets will compile by default due to intel-tex-rs-2 using the Intel ISPC compiler and lacking precompiled kernels for all targets. Disable the "encode" feature if not needed.

Re-exports

pub use ddsfile;

pub use image;

Modules

error

Structs

DdsFormatInfo

Format information for all DDS variants.

ImageFormatIter

An iterator over the variants of ImageFormat

MipmapsIter

An iterator over the variants of Mipmaps

QualityIter

An iterator over the variants of Quality

Surface

A surface with an image format known at runtime.

SurfaceRgba8

An uncompressed ImageFormat::Rgba8Unorm surface with 4 bytes per pixel.

SurfaceRgba32Float

An uncompressed ImageFormat::Rgba32Float surface with 16 bytes per pixel.

Enums

CreateDdsError

Errors that can occur when converting to DDS.

ImageFormat

Supported image formats for encoding and decoding.

Mipmaps

Options for how many mipmaps to generate. Mipmaps are counted starting from the base level, so a surface with only the full resolution base level has 1 mipmap.

Quality

The conversion quality when encoding to compressed formats.

Functions

dds_from_image

Encode image to a 2D DDS file with the given format.

dds_from_imagef32

Encode image to a 2D DDS file with the given format.

dds_image_format

Returns the format of dds or None if the format is unrecognized.

image_from_dds

Decode the given mip level from dds to an RGBA8 image. Array layers are arranged vertically from top to bottom.

imagef32_from_dds

Decode the given mip level from dds to an RGBAF32 image. Array layers are arranged vertically from top to bottom.

mip_dimension

The reduced value for base_dimension at level mipmap.