Crate image_dds

Introduction

DDS can store the vast majority of both compressed and uncompressed GPU texture data. This includes 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 often don’t support newer compression formats like BC7. Rendering APIs may not support compressed formats or only make it available via an extension such as in the browser. image_dds supports decoding surfaces to RGBA8 for better compatibility at the cost of increased memory usage.

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.

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.

Limitations

BC2 data can be decoded but not encoded due to limitations in intel-tex-rs-2. This format is very rarely used in practice. 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.

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.