1 unstable release

0.5.1 Jun 14, 2024

#977 in Parser implementations


Used in 3 crates (via ira_drum)

MIT license

185KB
4K SLoC

image_dds

Latest Version docs.rs

A library for converting uncompressed image data to and from compressed formats.

Examples

The provided example projects demonstrate basic usage of the conversion functions. The library also provides functions for working directly with the raw bytes of a surface instead of a dds or image file. Floating point data like EXR files or BC6 DDS files is also supported.

cargo run --release --example img2dds image.png out.dds BC3RgbaUnorm
cargo run --release --example dds2img out.dds out.tiff

cargo run --release --example img2ddsf32 image.exr out.dds
cargo run --release --example dds2imgf32 out.dds out.exr

Array layers and depth slices in images should be stacked vertically. This enables surface creation to avoid making additional copies since the RGBA data is already in the desired layout.

cargo run --release --example img2dds 3d.dds 3d.png
cargo run --release --example img2dds 3d.png out.dds Rgba8Unorm depth

cargo run --release --example dds2imgf32 cube.dds cube.exr
cargo run --release --example img2ddsf32 cube.exr out.dds BC6hRgbUfloat layers

Supported Formats

The only compressed formats supported at this time are BCN formats since these are the formats commonly used by DDS files and compressed GPU textures. This library does not support other compressed formats used for GPU textures like ETC1. Compression is handled using intel-tex-rs-2 for bindings to Intel's ISPC texture compressor in C++. Decompression is handled using a safe Rust port of the bcdec library in C.

Format Encode Decode
BC1 ✔️ ✔️
BC2 ✔️
BC3 ✔️ ✔️
BC4 ✔️ ✔️
BC5 ✔️ ✔️
BC6 ✔️ ✔️
BC7 ✔️ ✔️

Some uncompressed formats are also supported. These formats are supported by DDS but are rarely used with DDS files in practice. Uncompressed formats are often used for small textures or textures used for window surfaces and UI elements.

Format Encode Decode
R8 ✔️ ✔️
R8G8B8A8 ✔️ ✔️
B8G8R8A8 ✔️ ✔️
R16G16B16A16Float ✔️ ✔️
R32G32B32A32Float ✔️ ✔️

Features

Helper functions for working with the files from the image and ddsfile crates are supported under feature flags and enabled by default. The encoding feature is enabled by default but can be disabled to resolve compilation issues on certain targets if not needed. The default features of the image crate are disabled by default. Features are additive, so simply add a reference to the appropriate version of image in the Cargo.toml to enable all the default features.

Building

Build the projects using cargo build --release with a newer version of the Rust toolchain installed. Builds support Windows, Linux, and MacOS. Some targets may not build properly due to a lack of precompiled ISP kernels in intel-tex-rs-2.

Dependencies

~3–11MB
~77K SLoC