rakata_formats/txi/

mod.rs

//! TXI ASCII reader and writer.
//!
//! TXI (texture info) resources are line-based text sidecars for texture
//! resources. Each directive is a command followed by optional arguments.
//!
//! ## Shape of the file
//!
//! One directive per line, a command token followed by its arguments. No
//! header, no terminator, no required order. The only structure beyond a flat
//! list is `upperleftcoords` and `lowerrightcoords`, which declare a count and
//! are followed by that many coordinate triples.
//!
//! Empty lines are ignored and command matching is case-insensitive. Two write
//! modes exist because both are legitimate: policy-normalised regularises
//! command spelling, source-preserving keeps whatever the input used so someone
//! else's file round-trips without being editorialised.
//!
//! Text is decoded and encoded as Windows-1252. The grammar and the engine's
//! parse behaviour, including how unrecognised directives and malformed boolean
//! arguments fail silently, are in `docs/src/formats/textures/txi.md`.

mod reader;
mod writer;

pub use reader::{
    read_txi, read_txi_from_bytes, read_txi_from_bytes_with_options, read_txi_with_options,
};
pub use writer::{
    write_txi, write_txi_to_vec, write_txi_to_vec_with_options, write_txi_with_options,
};

use thiserror::Error;

use rakata_core::{DecodeTextError, EncodeTextError};

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

const UPPER_LEFT_COORDS_COMMAND: &str = "upperleftcoords";
const LOWER_RIGHT_COORDS_COMMAND: &str = "lowerrightcoords";
const DECAL1_ALIAS: &str = "decal1";
const DECAL_COMMAND: &str = "decal";

/// Reader options for TXI parsing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct TxiReadOptions {
    /// Enables compatibility aliasing of `decal1` to `decal 1`.
    ///
    /// Native K1 TXI parse paths match `decal` but do not expose a `decal1`
    /// token in the observed string table. Keep this disabled by default.
    pub compatibility_decal1_alias: bool,
}

/// Writer options for TXI serialization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub struct TxiWriteOptions {}

/// One TXI UV coordinate entry.
#[derive(Debug, Clone, PartialEq)]
pub struct TxiCoordinate {
    /// First coordinate component.
    pub u: f32,
    /// Second coordinate component.
    pub v: f32,
    /// Third coordinate component (often 0).
    pub w: i32,
}

/// One TXI command with optional argument payload.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TxiDirective {
    /// Command token.
    ///
    /// In policy-normalized mode this is lowercase-normalized.
    pub command: String,
    /// Raw argument text after the first whitespace separator.
    pub arguments: String,
}

/// One TXI coordinate block command.
#[derive(Debug, Clone, PartialEq)]
pub struct TxiCoordinateBlock {
    /// Command token (`upperleftcoords` or `lowerrightcoords` in
    /// policy-normalized mode).
    pub command: String,
    /// Count declared on the command line.
    pub declared_count: usize,
    /// Parsed coordinate rows.
    pub coordinates: Vec<TxiCoordinate>,
}

/// One ordered TXI entry.
#[derive(Debug, Clone, PartialEq)]
pub enum TxiEntry {
    /// A plain command line.
    Directive(TxiDirective),
    /// A coordinate block command plus zero or more parsed rows.
    CoordinateBlock(TxiCoordinateBlock),
}

/// In-memory TXI container.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct Txi {
    /// Ordered entries as parsed or appended.
    pub entries: Vec<TxiEntry>,
}

impl Txi {
    /// Creates an empty TXI container.
    pub fn new() -> Self {
        Self::default()
    }

    /// Appends a plain command entry.
    pub fn push_directive(
        &mut self,
        command: impl Into<String>,
        arguments: impl Into<String>,
    ) -> &mut Self {
        self.entries.push(TxiEntry::Directive(TxiDirective {
            command: command.into().to_ascii_lowercase(),
            arguments: arguments.into(),
        }));
        self
    }

    /// Appends a coordinate block entry.
    pub fn push_coordinate_block(
        &mut self,
        command: impl Into<String>,
        declared_count: usize,
        coordinates: Vec<TxiCoordinate>,
    ) -> &mut Self {
        self.entries
            .push(TxiEntry::CoordinateBlock(TxiCoordinateBlock {
                command: command.into().to_ascii_lowercase(),
                declared_count,
                coordinates,
            }));
        self
    }
}

impl DecodeBinary for Txi {
    type Error = TxiError;

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

impl EncodeBinary for Txi {
    type Error = TxiError;

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

/// Errors produced while parsing or serializing TXI text data.
#[derive(Debug, Error)]
pub enum TxiError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// TXI text is structurally invalid.
    #[error("invalid TXI data: {0}")]
    InvalidData(String),
    /// Text cannot be represented in Windows-1252 output.
    #[error("TXI text encoding failed for {context}: {source}")]
    TextEncoding {
        /// Value context.
        context: String,
        /// Encoding error details.
        #[source]
        source: EncodeTextError,
    },
    /// Input bytes could not be decoded losslessly as Windows-1252.
    #[error("TXI text decoding failed for {context}: {source}")]
    TextDecoding {
        /// Value context.
        context: String,
        /// Decoding error details.
        #[source]
        source: DecodeTextError,
    },
}