rakata_formats/tga/

reader.rs

//! TGA (Targa) reader.

use std::io::Read;

use tinytga::{Bpp, Compression, DataType, ImageOrigin, RawTga};

use super::{
    checked_pixel_count, Tga, TgaBinaryError, TgaBitsPerPixel, TgaCompression, TgaDataType,
    TgaHeader, TgaOrigin, TgaReadMode, TgaReadOptions,
};

/// Reads TGA data from a reader.
///
/// # Errors
///
/// The same as [`read_tga_with_options`] under the default options.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_tga<R: Read>(reader: &mut R) -> Result<Tga, TgaBinaryError> {
    read_tga_with_options(reader, TgaReadOptions::default())
}

/// Reads TGA data from a reader with explicit options.
///
/// # Errors
///
/// [`TgaBinaryError::Io`] when the stream will not read to end, and whatever
/// [`read_tga_from_bytes_with_options`] reports for the bytes it collected.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader, options))
)]
pub fn read_tga_with_options<R: Read>(
    reader: &mut R,
    options: TgaReadOptions,
) -> Result<Tga, TgaBinaryError> {
    let mut bytes = Vec::new();
    reader.read_to_end(&mut bytes)?;
    read_tga_from_bytes_with_options(&bytes, options)
}

/// Reads TGA data from bytes.
///
/// # Errors
///
/// The same as [`read_tga_from_bytes_with_options`] under the default options.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_tga_from_bytes(bytes: &[u8]) -> Result<Tga, TgaBinaryError> {
    read_tga_from_bytes_with_options(bytes, TgaReadOptions::default())
}

/// Reads TGA data from bytes with explicit options.
///
/// # Errors
///
/// [`TgaBinaryError::InvalidHeader`] when `bytes` are shorter than the header
/// or its dimensions run past the end, [`TgaBinaryError::Parse`] for an image
/// or colour-map type this reader has no decoder for, and
/// [`TgaBinaryError::InvalidData`] when the pixel data is short for the
/// dimensions declared. [`TgaBinaryError::ValueOverflow`] when those
/// dimensions multiply past `usize`. TGA carries no magic, so a file that is
/// not one fails on its declared layout rather than on a signature.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes, options), fields(bytes_len = bytes.len()))
)]
pub fn read_tga_from_bytes_with_options(
    bytes: &[u8],
    options: TgaReadOptions,
) -> Result<Tga, TgaBinaryError> {
    let raw = RawTga::from_slice(bytes)?;
    let source_header = raw.header();

    if source_header.width == 0 || source_header.height == 0 {
        return Err(TgaBinaryError::InvalidHeader(
            "width/height must be non-zero".into(),
        ));
    }

    if matches!(source_header.data_type, DataType::NoData) {
        return Err(TgaBinaryError::InvalidHeader(
            "image declares no pixel data".into(),
        ));
    }

    validate_read_header_mode(&source_header, options.input)?;
    validate_uncompressed_source_size(&raw)?;

    let width = usize::from(source_header.width);
    let height = usize::from(source_header.height);
    let pixel_count = checked_pixel_count(width, height)?;
    let mut rgba = vec![0_u8; pixel_count * 4];

    for raw_pixel in raw.pixels() {
        let mut x = usize::try_from(raw_pixel.position.x)
            .map_err(|_| TgaBinaryError::InvalidData("pixel x position out of range".into()))?;
        let y = usize::try_from(raw_pixel.position.y)
            .map_err(|_| TgaBinaryError::InvalidData("pixel y position out of range".into()))?;

        if x >= width || y >= height {
            return Err(TgaBinaryError::InvalidData(
                "pixel position outside declared bounds".into(),
            ));
        }

        if matches!(
            source_header.image_origin,
            ImageOrigin::TopRight | ImageOrigin::BottomRight
        ) {
            x = width - 1 - x;
        }

        let source_color = resolve_raw_pixel_color(&raw, &source_header, raw_pixel.color)?;
        let rgba_pixel = decode_raw_color(
            source_color,
            raw.color_bpp(),
            source_header.alpha_channel_depth,
        )?;

        let offset = (y * width + x)
            .checked_mul(4)
            .ok_or(TgaBinaryError::ValueOverflow("rgba offset"))?;
        rgba[offset..offset + 4].copy_from_slice(&rgba_pixel);
    }

    let header = map_header(source_header)?;
    let image_id = raw.image_id().unwrap_or(&[]).to_vec();

    Ok(Tga {
        header,
        image_id,
        rgba_pixels: rgba,
    })
}

fn validate_read_header_mode(
    header: &tinytga::TgaHeader,
    mode: TgaReadMode,
) -> Result<(), TgaBinaryError> {
    if matches!(mode, TgaReadMode::Compatibility) {
        return Ok(());
    }

    let supported_type = matches!(
        (header.data_type, header.compression),
        (DataType::ColorMapped, Compression::Uncompressed)
            | (DataType::ColorMapped, Compression::Rle)
            | (DataType::TrueColor, Compression::Uncompressed)
            | (DataType::TrueColor, Compression::Rle)
            | (DataType::BlackAndWhite, Compression::Uncompressed)
    );
    if !supported_type {
        return Err(TgaBinaryError::InvalidHeader(
            "canonical K1 reader rejects unsupported TGA image type".into(),
        ));
    }

    if !matches!(header.pixel_depth, Bpp::Bits8 | Bpp::Bits24 | Bpp::Bits32) {
        return Err(TgaBinaryError::InvalidHeader(
            "canonical K1 reader only supports 8/24/32-bit source pixel depth".into(),
        ));
    }

    if matches!(
        (header.data_type, header.compression),
        (DataType::TrueColor, Compression::Rle)
    ) && !matches!(header.pixel_depth, Bpp::Bits24 | Bpp::Bits32)
    {
        return Err(TgaBinaryError::InvalidHeader(
            "canonical K1 reader requires true-color RLE payloads to be 24 or 32-bit".into(),
        ));
    }

    Ok(())
}

fn map_header(source: tinytga::TgaHeader) -> Result<TgaHeader, TgaBinaryError> {
    Ok(TgaHeader {
        id_len: source.id_len,
        has_color_map: source.has_color_map,
        data_type: map_data_type(source.data_type),
        compression: map_compression(source.compression),
        color_map_start: source.color_map_start,
        color_map_len: source.color_map_len,
        color_map_depth: source
            .color_map_depth
            .map(TgaBitsPerPixel::try_from_tinytga)
            .transpose()?,
        x_origin: source.x_origin,
        y_origin: source.y_origin,
        width: source.width,
        height: source.height,
        pixel_depth: TgaBitsPerPixel::try_from_tinytga(source.pixel_depth)?,
        image_origin: map_origin(source.image_origin),
        alpha_channel_depth: source.alpha_channel_depth,
    })
}

fn map_data_type(data_type: DataType) -> TgaDataType {
    match data_type {
        DataType::NoData => TgaDataType::NoData,
        DataType::ColorMapped => TgaDataType::ColorMapped,
        DataType::TrueColor => TgaDataType::TrueColor,
        DataType::BlackAndWhite => TgaDataType::BlackAndWhite,
    }
}

fn map_compression(compression: Compression) -> TgaCompression {
    match compression {
        Compression::Uncompressed => TgaCompression::Uncompressed,
        Compression::Rle => TgaCompression::Rle,
    }
}

fn map_origin(origin: ImageOrigin) -> TgaOrigin {
    match origin {
        ImageOrigin::BottomLeft => TgaOrigin::BottomLeft,
        ImageOrigin::BottomRight => TgaOrigin::BottomRight,
        ImageOrigin::TopLeft => TgaOrigin::TopLeft,
        ImageOrigin::TopRight => TgaOrigin::TopRight,
    }
}

fn resolve_raw_pixel_color(
    raw: &RawTga<'_>,
    source_header: &tinytga::TgaHeader,
    raw_color: u32,
) -> Result<u32, TgaBinaryError> {
    let Some(color_map) = raw.color_map() else {
        return Ok(raw_color);
    };

    let raw_index = usize::try_from(raw_color)
        .map_err(|_| TgaBinaryError::InvalidData("color-map index overflow".into()))?;
    let start = usize::from(source_header.color_map_start);
    let length = usize::from(source_header.color_map_len);

    let palette_index = raw_index.checked_sub(start).ok_or_else(|| {
        TgaBinaryError::InvalidData(format!(
            "color-map index {raw_index} below color_map_start {start}"
        ))
    })?;

    if palette_index >= length {
        return Err(TgaBinaryError::InvalidData(format!(
            "color-map index {raw_index} out of range for length {length}"
        )));
    }

    color_map.get_raw(palette_index).ok_or_else(|| {
        TgaBinaryError::InvalidData(format!(
            "missing color-map entry at palette index {palette_index}"
        ))
    })
}

/// Extracts bits `[shift .. shift+8)` from a `u32` as a `u8`.
fn byte_at(value: u32, shift: u32) -> u8 {
    u8::try_from((value >> shift) & 0xFF).expect("masked to 8 bits")
}

/// Extracts bits `[shift .. shift+5)` from a `u16` as a `u8`.
fn bits5_at(value: u16, shift: u16) -> u8 {
    u8::try_from((value >> shift) & 0x1F).expect("masked to 5 bits")
}

fn decode_raw_color(
    raw_color: u32,
    bpp: Bpp,
    alpha_channel_depth: u8,
) -> Result<[u8; 4], TgaBinaryError> {
    match bpp {
        Bpp::Bits8 => {
            let v = byte_at(raw_color, 0);
            Ok([v, v, v, 255])
        }
        Bpp::Bits16 => {
            let value = u16::try_from(raw_color & 0xFFFF).expect("masked to 16 bits");
            let blue = expand_5bit(bits5_at(value, 0));
            let green = expand_5bit(bits5_at(value, 5));
            let red = expand_5bit(bits5_at(value, 10));
            let alpha = if alpha_channel_depth > 0 && (value & 0x8000) == 0 {
                0
            } else {
                255
            };
            Ok([red, green, blue, alpha])
        }
        Bpp::Bits24 => Ok([
            byte_at(raw_color, 16),
            byte_at(raw_color, 8),
            byte_at(raw_color, 0),
            255,
        ]),
        Bpp::Bits32 => Ok([
            byte_at(raw_color, 16),
            byte_at(raw_color, 8),
            byte_at(raw_color, 0),
            byte_at(raw_color, 24),
        ]),
        _ => Err(TgaBinaryError::InvalidData(
            "unsupported bits-per-pixel value in decoded source data".into(),
        )),
    }
}

fn expand_5bit(value: u8) -> u8 {
    (value << 3) | (value >> 2)
}

fn validate_uncompressed_source_size(raw: &RawTga<'_>) -> Result<(), TgaBinaryError> {
    if !matches!(raw.compression(), Compression::Uncompressed) {
        return Ok(());
    }

    let width =
        usize::try_from(raw.size().width).map_err(|_| TgaBinaryError::ValueOverflow("width"))?;
    let height =
        usize::try_from(raw.size().height).map_err(|_| TgaBinaryError::ValueOverflow("height"))?;
    let pixel_count = checked_pixel_count(width, height)?;
    let expected_bytes = pixel_count
        .checked_mul(usize::from(raw.image_data_bpp().bytes()))
        .ok_or(TgaBinaryError::ValueOverflow(
            "uncompressed image data bytes",
        ))?;

    if raw.image_data().len() < expected_bytes {
        return Err(TgaBinaryError::InvalidData(format!(
            "truncated uncompressed image data: expected at least {expected_bytes} bytes, got {}",
            raw.image_data().len()
        )));
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::tga::write_tga_to_vec;

    const CUBE_TGA: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/textures/cube/cm_506ond.tga"
    ));

    struct TestHeaderSpec {
        color_map_type: u8,
        image_type: u8,
        color_map_start: u16,
        color_map_len: u16,
        color_map_depth: u8,
        width: u16,
        height: u16,
        pixel_depth: u8,
        descriptor: u8,
    }

    fn make_tga_header(spec: TestHeaderSpec) -> Vec<u8> {
        let mut bytes = Vec::new();
        bytes.extend_from_slice(&[0]); // id length
        bytes.extend_from_slice(&[spec.color_map_type]);
        bytes.extend_from_slice(&[spec.image_type]);
        bytes.extend_from_slice(&spec.color_map_start.to_le_bytes());
        bytes.extend_from_slice(&spec.color_map_len.to_le_bytes());
        bytes.extend_from_slice(&[spec.color_map_depth]);
        bytes.extend_from_slice(&0_u16.to_le_bytes()); // x origin
        bytes.extend_from_slice(&0_u16.to_le_bytes()); // y origin
        bytes.extend_from_slice(&spec.width.to_le_bytes());
        bytes.extend_from_slice(&spec.height.to_le_bytes());
        bytes.extend_from_slice(&[spec.pixel_depth]);
        bytes.extend_from_slice(&[spec.descriptor]);
        bytes
    }

    #[test]
    fn parses_tga_fixture() {
        let tga = read_tga_from_bytes(CUBE_TGA).expect("fixture should parse");

        assert_eq!(tga.header.width, 4);
        assert_eq!(tga.header.height, 4);
        assert_eq!(tga.rgba_pixels.len(), 4 * 4 * 4);
    }

    #[test]
    fn roundtrip_canonical_rgba_tga() {
        let mut tga = Tga::new_rgba(
            2,
            2,
            vec![
                255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 0, 128,
            ],
        )
        .expect("create tga");
        tga.image_id = b"rakata-rs".to_vec();

        let bytes = write_tga_to_vec(&tga).expect("write should succeed");
        let parsed = read_tga_from_bytes(&bytes).expect("read should succeed");

        assert_eq!(parsed.header.width, 2);
        assert_eq!(parsed.header.height, 2);
        assert_eq!(parsed.image_id, b"rakata-rs");
        assert_eq!(parsed.rgba_pixels, tga.rgba_pixels);

        // Canonical writer emits uncompressed true-color 32bpp top-left.
        assert_eq!(bytes[2], 2);
        assert_eq!(bytes[16], 32);
        assert_eq!(bytes[17], 0x28);
    }

    #[test]
    fn writer_is_deterministic_for_canonical_tga() {
        let mut tga = Tga::new_rgba(
            2,
            2,
            vec![
                255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 0, 128,
            ],
        )
        .expect("create tga");
        tga.image_id = b"rakata-rs".to_vec();

        let first = write_tga_to_vec(&tga).expect("first write should succeed");
        let second = write_tga_to_vec(&tga).expect("second write should succeed");
        assert_eq!(first, second, "canonical TGA writer output drifted");
    }

    #[test]
    fn rejects_truncated_header() {
        let bytes = vec![0_u8; 17];
        let err = read_tga_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(
            err,
            TgaBinaryError::Parse(_) | TgaBinaryError::InvalidHeader(_)
        ));
    }

    #[test]
    fn normalizes_bottom_left_origin_to_top_left() {
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 2,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 1,
            height: 2,
            pixel_depth: 24,
            descriptor: 0x00,
        });

        // Stored as bottom row then top row for bottom-left origin.
        bytes.extend_from_slice(&[255, 0, 0]); // blue (BGR)
        bytes.extend_from_slice(&[0, 255, 255]); // yellow (BGR)

        let tga = read_tga_from_bytes(&bytes).expect("parse should succeed");
        assert_eq!(tga.rgba_pixels, vec![255, 255, 0, 255, 0, 0, 255, 255]);
    }

    #[test]
    fn normalizes_top_right_origin_to_top_left() {
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 2,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 2,
            height: 1,
            pixel_depth: 24,
            descriptor: 0x30,
        });

        // Top-right origin: first pixel belongs to the right-most column.
        bytes.extend_from_slice(&[0, 0, 255]); // red (BGR)
        bytes.extend_from_slice(&[0, 255, 0]); // green (BGR)

        let tga = read_tga_from_bytes(&bytes).expect("parse should succeed");
        assert_eq!(
            tga.rgba_pixels,
            vec![0, 255, 0, 255, 255, 0, 0, 255],
            "x-axis should be normalized to top-left row-major ordering"
        );
    }

    #[test]
    fn honors_color_map_start_index() {
        // Type 1: uncompressed color-mapped image.
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 1,
            image_type: 1,
            color_map_start: 1,
            color_map_len: 1,
            color_map_depth: 24,
            width: 1,
            height: 1,
            pixel_depth: 8,
            descriptor: 0x20,
        });

        // One palette entry at logical index 1: red in BGR form.
        bytes.extend_from_slice(&[0, 0, 255]);

        // Pixel references logical palette index 1.
        bytes.push(1);

        let tga = read_tga_from_bytes(&bytes).expect("parse should succeed");
        assert_eq!(tga.rgba_pixels, vec![255, 0, 0, 255]);
    }

    #[test]
    fn rejects_truncated_uncompressed_pixel_data() {
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 2,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 2,
            height: 2,
            pixel_depth: 24,
            descriptor: 0x20,
        });
        bytes.extend_from_slice(&[0, 0, 0]); // too short; expected at least 12

        let err = read_tga_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, TgaBinaryError::InvalidData(_)));
    }

    #[test]
    fn writer_rejects_mismatched_rgba_length() {
        let tga = Tga {
            header: TgaHeader {
                id_len: 0,
                has_color_map: false,
                data_type: TgaDataType::TrueColor,
                compression: TgaCompression::Uncompressed,
                color_map_start: 0,
                color_map_len: 0,
                color_map_depth: None,
                x_origin: 0,
                y_origin: 0,
                width: 2,
                height: 2,
                pixel_depth: TgaBitsPerPixel::Bits32,
                image_origin: TgaOrigin::TopLeft,
                alpha_channel_depth: 8,
            },
            image_id: Vec::new(),
            rgba_pixels: vec![0_u8; 3],
        };

        let err = write_tga_to_vec(&tga).expect_err("must fail");
        assert!(matches!(err, TgaBinaryError::InvalidData(_)));
    }

    #[test]
    fn bits_enum_reports_depth_values() {
        assert_eq!(TgaBitsPerPixel::Bits8.bits(), 8);
        assert_eq!(TgaBitsPerPixel::Bits16.bits(), 16);
        assert_eq!(TgaBitsPerPixel::Bits24.bits(), 24);
        assert_eq!(TgaBitsPerPixel::Bits32.bits(), 32);
    }

    #[test]
    fn canonical_output_when_pixels_edited() {
        // Parse a non-canonical bottom-left 24bpp TGA, then edit a pixel.
        let mut src_bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 2,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 1,
            height: 1,
            pixel_depth: 24,
            descriptor: 0x00, // non-canonical bottom-left
        });
        src_bytes.extend_from_slice(&[0, 0, 255]);

        let mut tga = read_tga_from_bytes(&src_bytes).expect("parse should succeed");
        tga.rgba_pixels[0] = 0; // edit pixel -- triggers canonical output

        let written = write_tga_to_vec(&tga).expect("write should succeed");
        // Canonical: image_type=2, pixel_depth=32, descriptor=0x28 (top-left, 8-bit alpha).
        assert_eq!(written[2], 2, "canonical output must use image_type 2");
        assert_eq!(written[16], 32, "canonical output must use 32bpp");
        assert_eq!(
            written[17], 0x28,
            "canonical output must be top-left with 8-bit alpha"
        );
        assert_ne!(
            written, src_bytes,
            "edited output must not equal source bytes"
        );
    }

    #[test]
    fn compat_tga_uses_canonical_output() {
        // When pixels ARE edited after a compat-mode parse, writer falls back to canonical.
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 11,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 1,
            height: 1,
            pixel_depth: 8,
            descriptor: 0x20,
        });
        bytes.extend_from_slice(&[0x80, 0x40]); // one-pixel grayscale RLE packet

        let mut tga = read_tga_from_bytes_with_options(
            &bytes,
            TgaReadOptions {
                input: TgaReadMode::Compatibility,
            },
        )
        .expect("compat parse should succeed");
        tga.rgba_pixels[0] ^= 1; // edit a pixel -- triggers canonical output

        let written = write_tga_to_vec(&tga).expect("write should succeed");
        assert_eq!(written[2], 2, "canonical output must use true-color type 2");
        assert_eq!(written[16], 32, "canonical output must use 32bpp");
        assert_eq!(
            written[17], 0x28,
            "canonical output must be top-left with 8-bit alpha"
        );

        let parsed = read_tga_from_bytes(&written).expect("canonical output should parse");
        assert_eq!(parsed.rgba_pixels.len(), tga.rgba_pixels.len());
    }

    #[test]
    fn canonical_reader_rejects_grayscale_rle_type11() {
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 11,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 1,
            height: 1,
            pixel_depth: 8,
            descriptor: 0x20,
        });
        bytes.extend_from_slice(&[0x80, 0x40]);

        let err = read_tga_from_bytes(&bytes).expect_err("canonical parse must fail");
        assert!(matches!(err, TgaBinaryError::InvalidHeader(_)));
    }

    #[test]
    fn compatibility_reader_allows_grayscale_rle_type11() {
        let mut bytes = make_tga_header(TestHeaderSpec {
            color_map_type: 0,
            image_type: 11,
            color_map_start: 0,
            color_map_len: 0,
            color_map_depth: 0,
            width: 1,
            height: 1,
            pixel_depth: 8,
            descriptor: 0x20,
        });
        bytes.extend_from_slice(&[0x80, 0x40]);

        let parsed = read_tga_from_bytes_with_options(
            &bytes,
            TgaReadOptions {
                input: TgaReadMode::Compatibility,
            },
        )
        .expect("compat parse must succeed");
        assert_eq!(parsed.rgba_pixels.len(), 4);
    }
}