Crate dds

Crate dds 

Source
Expand description

§DDS

A Rust library for decoding and encoding DDS (DirectDraw Surface) files.

§The DDS format

DDS is a container format for storing compressed and uncompressed textures, cube maps, volumes, buffers, and arrays of the before. It is used by DirectX, OpenGL, Vulkan, and other graphics APIs.

A DDS files has 2 parts: a header and a data section. The header describes the type of data in the file (e.g. a BC1-compressed 100x200px texture) and determines the layout of the data section. The data section then contains the binary pixel data.

§Features

  • rayon (default): Parallel encoding using the rayon crate.

    This feature will enable parallel encoding of DDS files. Both the high-level Encoder and low-level encode() functions will take advantage of rayon for faster processing, but may use more memory.

All features marked with “(default)” are enabled by default.

§Usage

§Decoding

The Decoder type is the high-level interface for decoding DDS files.

The most common case, a single texture, can be decoded as follows:

use std::fs::File;
let file = File::open("path/to/file.dds").unwrap();
let mut decoder = dds::Decoder::new(file).unwrap();
// ensure the file contains a single texture
assert!(decoder.layout().is_texture());
// prepare a buffer to decode as 8-bit RGBA
let size = decoder.main_size();
let mut data = vec![0_u8; size.pixels() as usize * 4];
let view = dds::ImageViewMut::new(&mut data, size, dds::ColorFormat::RGBA_U8).unwrap();
// decode into the buffer
decoder.read_surface(view).unwrap();

Cube maps, volumes, and texture arrays can be detected using the DataLayout returned by Decoder::layout(). This contains all the necessary information to interpret the contents of the DDS file.

As for decoding those contents:

If you only need a portion of a surface, use Decoder::read_surface_rect.

§Encoding

Since the data of a DDS file is determined by the header, the first step to encoding a DDS file is to create a header. See the documentation of the dds::header module for more details.

use dds::{*, header::*};
use std::fs::File;

fn save_rgba_image(
    file: &mut File,
    image_data: &[u8],
    width: u32,
    height: u32,
) -> Result<(), EncodingError> {
    let format = Format::BC1_UNORM;
    let header = Header::new_image(width, height, format);

    let mut encoder = Encoder::new(file, format, &header)?;
    encoder.encoding.quality = CompressionQuality::Fast;

    let view = ImageView::new(image_data, Size::new(width, height), ColorFormat::RGBA_U8)
        .expect("invalid image data");
    encoder.write_surface(view)?;
    encoder.finish()?;
    Ok(())
}

Note the use of Encoder::finish(). This method will verify that the file has been created correctly and contains all necessary data. Always use Encoder::finish() instead of dropping the encoder.

To create DDS files with mipmaps, we simply create a header with mipmaps and enable automatic mipmap generation in the encoder:

use dds::{*, header::*};
use std::fs::File;

fn save_rgba_image_with_mipmaps(
    file: &mut File,
    image_data: &[u8],
    width: u32,
    height: u32,
) -> Result<(), EncodingError> {
    let format = Format::BC1_UNORM;
    // Create a header with mipmaps
    let header = Header::new_image(width, height, format).with_mipmaps();

    let mut encoder = Encoder::new(file, format, &header)?;
    encoder.encoding.quality = CompressionQuality::Fast;
    encoder.mipmaps.generate = true; // Enable automatic mipmap generation

    let view = ImageView::new(image_data, Size::new(width, height), ColorFormat::RGBA_U8)
        .expect("invalid image data");
    encoder.write_surface(view)?;
    encoder.finish()?;
    Ok(())
}

Note: If the header does not specify mipmaps, no mipmaps will be generated even if automatic mipmap generation is enabled.

For other types of data:

  • Texture arrays can be encoded using Encoder::write_surface for each texture in the array.

  • Cube maps, like texture arrays, can be encoded using Encoder::write_surface for each face. The order of the faces must be +X, -X, +Y, -Y, +Z, -Z. Writing whole cube maps at once is not supported.

  • Volumes can be encoded one depth slice at a time using Encoder::write_surface.

    Automatic mipmap generation is not supported for volumes. If enabled, the options will be silently ignored and no mipmaps will be generated.

§Progress reporting

The decoder is generally so fast that progress reporting is not needed for decoding a single surface.

The encoder, however, can take a long time to encode large images. Use the progress parameter of the Encoder::write_surface_with_progress method to get periodic updates on the encoding progress. See the Progress type for more details.

§Low-level API

Besides the Encoder and Decoder types, the library also exposes a low-level API for encoding and decoding DDS surfaces. It should generally not be necessary to use this API.

The encode() and decode() functions are used to encode and decode a single DDS surface. SplitView can be used to split a surface into multiple fragments for parallel encoding.

Modules§

header
Functionality for reading, parsing, and writing DDS headers.

Structs§

BiPlanarPixelInfo
See PixelInfo::BiPlanar.
BlockPixelInfo
See PixelInfo::Block.
CancellationToken
A token that can be used to cooperatively cancel an operation.
ColorFormat
A color format with a specific number of channels and precision.
CubeMapFaces
A bitset representing which faces of a cube map are present.
DecodeOptions
Decoder
A decoder for reading the pixel data of a DDS file.
EncodeOptions
Encoder
An encoder for DDS files.
EncodingSupport
Describes the extent of support for encoding a format.
ImageView
A borrowed slice of image data.
ImageViewMut
A borrowed mutable slice of image data.
MipmapOptions
Offset
Progress
A progress reporter used by Encoder and encode().
Size
SplitView
An ImageView that has been split into horizontal fragments.
SurfaceDescriptor
Texture
A 2D texture with mipmaps (if any).
TextureArray
An array of textures.
Volume
A 3D texture with mipmaps (if any).
VolumeDescriptor

Enums§

Channels
The number and semantics of the color channels in a surface.
CompressionQuality
The level of trade-off between compression quality and speed.
DataLayout
The type and layout of the surfaces/volumes in the data section of a DDS file.
DecodingError
Dithering
EncodingError
ErrorMetric
Format
The format of the pixel data of a surface.
FormatError
HeaderError
LayoutError
PixelInfo
This describes the number of bits per pixel and the layout of pixels within a surface.
Precision
The precision/bit depth of the values in a surface.
ResizeFilter
TextureArrayKind

Traits§

DataRegion

Functions§

decode
Decodes the image data of a surface from the given reader and writes it to the given output buffer.
decode_rect
Decodes a rectangle of the image data of a surface from the given reader and writes it to the given output buffer.
encode
Encodes a single surfaces in the given format and writes the encoded pixel data to the given writer.