rakata_formats/dds/

mod.rs

//! DDS (DirectDraw Surface) reader and writer.
//!
//! This module provides container-level support for KotOR-era DDS files.
//! Parsing and serialization are backed by `ddsfile`, but the public API is kept
//! focused on D3D9-era headers and formats that KotOR actually uses.
//!
//! ## KotOR Notes
//! - Reader support includes:
//!   - standard `DDS ` containers (D3D9-era headers; canonical compressed formats are DXT1/DXT5).
//!   - a `CResDDS` prefix-header container variant used by vanilla resource paths.
//! - Canonical KotOR compressed paths currently target DXT1 and DXT5.
//! - Writer support currently emits standard `DDS ` containers only.
//!
//! ## Two variants, told apart by the first four bytes
//!
//! A standard DDS opens with the `DDS ` magic and a 124-byte D3D9-era header.
//! The `CResDDS` variant vanilla resource paths use has no magic at all: twenty
//! bytes of proprietary prefix metadata sit where the header would be, and the
//! surface payload follows directly. The prefix replaces the DDS header rather
//! than preceding it.
//!
//! Both are read and only the standard form is written. Emitting the prefixed
//! variant would reproduce a container the engine reads and nothing else does.
//! The prefix field map and the engine's own read are in
//! `docs/src/formats/textures/dds.md`.

mod reader;
mod writer;

pub use reader::{read_dds, read_dds_from_bytes};
pub use writer::{write_dds, write_dds_to_vec};

use thiserror::Error;

use ddsfile::{Caps2, D3DFormat, Dds as DdsFile, Error, Header, NewD3dParams};

use crate::binary::{DecodeBinary, EncodeBinary};

/// DDS D3D-format enum re-export.
pub type DdsD3dFormat = D3DFormat;
/// DDS caps2 bitflag re-export.
pub type DdsCaps2 = Caps2;
/// Constructor parameter set for D3D-style DDS creation.
pub type DdsNewD3dParams = NewD3dParams;

/// In-memory DDS container.
#[derive(Debug, Clone)]
pub struct Dds {
    /// Standard DDS header.
    pub header: Header,
    /// Raw surface payload bytes.
    pub data: Vec<u8>,
    /// Source container flavor used on decode.
    pub source_flavor: DdsSourceFlavor,
}

/// DDS source container flavor.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum DdsSourceFlavor {
    /// Standard `DDS ` container.
    Standard,
    /// CResDDS compressed-raster prefix container used by vanilla resource paths.
    ///
    /// Observed in `swkotor.exe` `CResDDS::OnResourceServiced` (`0x00710f30`) and
    /// `CResDDS::GetDDSAttrib` (`0x00710ee0`): a 20-byte metadata header precedes
    /// surface payload bytes.
    CResDds(CResDdsHeader),
}

/// Parsed `CResDDS` prefix metadata header.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CResDdsHeader {
    /// Base width in pixels.
    pub width: u32,
    /// Base height in pixels.
    pub height: u32,
    /// Prefix bytes-per-pixel code as stored on disk.
    ///
    /// Canonically observed values:
    /// - `3` => DXT1 payload sizing
    /// - `4` => 16-byte block-family payload sizing (modeled as DXT5 here)
    pub bytes_per_pixel_code: u8,
    /// Reserved bytes from offsets `+0x09..+0x0B`.
    ///
    /// Native K1 attribute-read paths do not consume these bytes, but they are
    /// retained for loss-aware inspection/debugging.
    pub reserved_gap_bytes: [u8; 3],
    /// Base-level payload size field from header.
    pub base_level_data_size: u32,
    /// Prefix alpha-mean metadata float (`+0x10`).
    ///
    /// Native K1 attribute-read paths surface this value directly as part of the
    /// compressed-texture attribute tuple and route it into texture alpha-mean
    /// handling.
    pub alpha_mean: f32,
}

impl Dds {
    /// Creates a DDS container with a D3D format.
    ///
    /// # Errors
    ///
    /// [`DdsBinaryError::InvalidHeader`] when `params.format` is DXT3, which
    /// vanilla never writes and this crate refuses to produce, and
    /// [`DdsBinaryError::Ddsfile`] when the dimensions or mipmap count do not
    /// describe a buildable surface.
    pub fn new_d3d(params: DdsNewD3dParams) -> Result<Self, DdsBinaryError> {
        validate_canonical_standard_d3d_format(params.format)?;
        let dds = DdsFile::new_d3d(params).map_err(DdsBinaryError::from)?;
        Ok(Self::from_ddsfile(dds))
    }

    /// Returns the image width from the DDS header.
    pub fn width(&self) -> u32 {
        self.header.width
    }

    /// Returns the image height from the DDS header.
    pub fn height(&self) -> u32 {
        self.header.height
    }

    /// Returns depth for 3D textures; defaults to `1` for 2D textures.
    pub fn depth(&self) -> u32 {
        self.header.depth.unwrap_or(1)
    }

    /// Returns the mipmap level count (at least `1`).
    pub fn mipmap_levels(&self) -> u32 {
        self.header.mip_map_count.unwrap_or(1)
    }

    /// Returns the array-layer count derived from headers.
    pub fn array_layers(&self) -> u32 {
        if self.header.caps2.contains(Caps2::CUBEMAP) {
            6
        } else {
            1
        }
    }

    /// Returns whether the container is marked as a cubemap.
    pub fn is_cubemap(&self) -> bool {
        self.header.caps2.contains(Caps2::CUBEMAP)
    }

    /// Returns the parsed D3D format when representable from pixel format fields.
    pub fn d3d_format(&self) -> Option<DdsD3dFormat> {
        D3DFormat::try_from_pixel_format(&self.header.spf)
    }

    pub(super) fn from_ddsfile(dds: DdsFile) -> Self {
        Self {
            header: dds.header,
            data: dds.data,
            source_flavor: DdsSourceFlavor::Standard,
        }
    }

    pub(super) fn to_ddsfile(&self) -> DdsFile {
        DdsFile {
            header: self.header.clone(),
            header10: None,
            data: self.data.clone(),
        }
    }
}

impl DecodeBinary for Dds {
    type Error = DdsBinaryError;

    fn decode_binary(bytes: &[u8]) -> Result<Self, Self::Error> {
        read_dds_from_bytes(bytes)
    }
}

impl EncodeBinary for Dds {
    type Error = DdsBinaryError;

    fn encode_binary(&self) -> Result<Vec<u8>, Self::Error> {
        write_dds_to_vec(self)
    }
}

/// Errors produced while parsing or serializing DDS data.
#[derive(Debug, Error)]
pub enum DdsBinaryError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// DDS parser/writer error from `ddsfile`.
    #[error("DDS parse/write error: {0}")]
    Ddsfile(#[source] Error),
    /// Header/body layout is invalid.
    #[error("invalid DDS header: {0}")]
    InvalidHeader(String),
}

impl From<Error> for DdsBinaryError {
    fn from(value: Error) -> Self {
        match value {
            Error::Io(error) => Self::Io(error),
            other => Self::Ddsfile(other),
        }
    }
}

impl From<crate::binary::BinaryLayoutError> for DdsBinaryError {
    fn from(error: crate::binary::BinaryLayoutError) -> Self {
        Self::InvalidHeader(error.to_string())
    }
}

fn validate_canonical_standard_d3d_format(format: D3DFormat) -> Result<(), DdsBinaryError> {
    if format == D3DFormat::DXT3 {
        return Err(DdsBinaryError::InvalidHeader(
            "DXT3 is non-canonical for vanilla KotOR DDS handling; canonical support is DXT1/DXT5"
                .to_string(),
        ));
    }
    Ok(())
}