Crate image_dds

source ·
Expand description

§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 compiliation 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§

Modules§

Structs§

Enums§

  • Errors that can occur when converting to DDS.
  • Supported image formats for encoding and decoding.
  • 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.
  • The conversion quality when encoding to compressed formats.

Functions§

  • Encode image to a 2D DDS file with the given format.
  • Encode image to a 2D DDS file with the given format.
  • Returns the format of dds or None if the format is unrecognized.
  • Decode the given mip level from dds to an RGBA8 image. Array layers are arranged vertically from top to bottom.
  • Decode the given mip level from dds to an RGBAF32 image. Array layers are arranged vertically from top to bottom.
  • The reduced value for base_dimension at level mipmap.