Enum DataLayout

pub enum DataLayout {
    Texture(Texture),
    Volume(Volume),
    TextureArray(TextureArray),
}

The type and layout of the surfaces/volumes in the data section of a DDS file.

DDS is a container format and supports a few different data types (e.g. images, volumes, cube maps). While varied, the data section of a DDS file is always a contiguous block of data and its layout is 100% determined by the header. There are no gaps, padding, or markers in the data section, just the raw data of the surfaces/volumes. This makes it necessary for readers to know the layout of the data in order to read it correctly.

DataLayout contains all of this information while providing a simple interface to iterate over the surfaces/volumes.

Note: DataLayout provides no methods to read the data itself. Use crate::Decoder or crate::Encoder to read/write the data section.

Variants

Texture(Texture)

A single texture with mipmaps (if any).

Example:

let header = Header::new_image(123, 345, Format::BC1_UNORM).with_mipmaps();
let layout = DataLayout::from_header(&header).unwrap();
let texture = layout.texture().unwrap();
assert_eq!(texture.main().size(), Size::new(123, 345));

// iterate over all mipmaps
for (level, mipmap) in texture.iter_mips().enumerate() {
    println!("Mipmap {}: {}x{}", level, mipmap.width(), mipmap.height());
}

Volume(Volume)

A 3D texture with mipmaps (if any).

DDS uses depth slices to represent 3D textures.

Example:

let header = Header::new_volume(123, 345, 678, Format::BC1_UNORM).with_mipmaps();
let layout = DataLayout::from_header(&header).unwrap();
let volume = layout.volume().unwrap();
assert_eq!(volume.main().size(), Size::new(123, 345));
assert_eq!(volume.main().depth(), 678);

// iterate over all mipmaps
for (level, mipmap) in volume.iter_mips().enumerate() {
    println!("Mipmap {}: {}x{}x{}", level, mipmap.width(), mipmap.height(), mipmap.depth());
}

TextureArray(TextureArray)

A simply array of 2D textures.

All textures within the array have the same size, mipmap count, and pixel format.

Example:

let mut header = Dx10Header::new_image(123, 345, DxgiFormat::BC1_UNORM);
header.array_size = 10;
let layout = DataLayout::from_header(&header.into()).unwrap();
let array = layout.texture_array().unwrap();
assert_eq!(array.len(), 10);
assert_eq!(array.size(), Size::new(123, 345));

// iterate over all textures in the array
for texture in array.iter() {
    for (level, mipmap) in texture.iter_mips().enumerate() {
        println!("Mipmap {}: {}x{}", level, mipmap.width(), mipmap.height());
    }
}

Cube maps

Cube maps are a special case of texture arrays. You can differentiate between normal texture arrays and cube maps using TextureArray::kind().

The faces of a cube map are always stored in the order:

1. Positive X
2. Negative X
3. Positive Y
4. Negative Y
5. Positive Z
6. Negative Z

Note that cube maps come in 2 flavors: full cube maps and partial cube maps. Partial cube maps are cube maps with fewer than 6 faces (see TextureArrayKind::PartialCubeMap) and are not supported by DX10+. In practice, partial cube maps are rarely used. This library only supports them for completeness.

Example:

let mut header = Header::new_cube_map(256, 256, Format::BC1_UNORM).with_mipmaps();
let layout = DataLayout::from_header(&header).unwrap();
let array = layout.texture_array().unwrap();
assert_eq!(array.kind(), TextureArrayKind::CubeMaps);
assert_eq!(array.len(), 6); // 6 faces
assert_eq!(array.size(), Size::new(256, 256));

let positive_x = array.get(0).unwrap();
let negative_x = array.get(1).unwrap();
let positive_y = array.get(2).unwrap();
let negative_y = array.get(3).unwrap();
let positive_z = array.get(4).unwrap();
let negative_z = array.get(5).unwrap();

DX10 also supports arrays of cube maps. Example:

let mut header = Dx10Header::new_cube_map(256, 256, DxgiFormat::BC1_UNORM);
header.array_size = 3;
let layout = DataLayout::from_header(&header.into()).unwrap();
let array = layout.texture_array().unwrap();
assert_eq!(array.kind(), TextureArrayKind::CubeMaps);
assert_eq!(array.len(), 18); // 6 faces * 3 cube maps

Implementations

impl DataLayout

pub fn from_header(header: &Header) -> Result<Self, DecodingError>

pub fn from_header_with( header: &Header, pixel_info: PixelInfo, ) -> Result<Self, LayoutError>

pub fn main_size(&self) -> Size

The size of the level 0 object.

For single textures and texture arrays, this will return the size of the texture (mipmap level 0). For cube maps, this will return the size of the individual faces (mipmap level 0). For volume textures, this will return the size of the first depth slice (mipmap level 0).

pub fn texture(&self) -> Option<Texture>

If this layout is a DataLayout::Texture, returns the texture.

pub fn volume(&self) -> Option<Volume>

If this layout is a DataLayout::Volume, returns the volume.

pub fn texture_array(&self) -> Option<TextureArray>

If this layout is a DataLayout::TextureArray, returns the texture array.

pub fn is_cube_map(&self) -> bool

Whether this layout is a cube map or partial cube map.

If true is returned, this layout is guaranteed to be a DataLayout::TextureArray. The TextureArray::kind() will be either TextureArrayKind::CubeMaps or TextureArrayKind::PartialCubeMap.

The texture array is not guaranteed to be contain exactly one (partial) cube map.

pub fn pixel_info(&self) -> PixelInfo

Trait Implementations

impl Clone for DataLayout

fn clone(&self) -> DataLayout

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DataRegion for DataLayout

fn data_len(&self) -> u64

The number of bytes this object occupies in the data section of a DDS file.

fn data_offset(&self) -> u64

The byte offset of this object in the data section of a DDS file.

fn data_end(&self) -> u64

The byte offset of the byte after this object in the data section of a DDS file.

impl Debug for DataLayout

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for DataLayout

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for DataLayout

fn eq(&self, other: &DataLayout) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for DataLayout

impl Eq for DataLayout

impl StructuralPartialEq for DataLayout