unityrs-texture 1.0.0

Texture2D decoders with UnityPy 1.25.2's output: the formats it decodes with Pillow's raw and bcn decoders, the ETC and EAC formats, and the ASTC LDR formats.
Documentation
// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/TextureSwizzler.py's is_switch_swizzled, and export/Texture2DConverter.py's XBOX_SWAP_FORMATS and the order parse_image_data reads a texture's fields in. See THIRD_PARTY_LICENSES.
//! Which textures are exported, and which are skipped with which reason
//! (`docs/plans/extract.md` E66, `docs/BATCH_SPEC.md` section 3): a pure
//! function of a `Texture2D`'s fields, [`select()`].
//!
//! It lives here, beside the decoders, because its rules are UnityPy's
//! texture rules (`TextureSwizzler.is_switch_swizzled`,
//! `Texture2DConverter.XBOX_SWAP_FORMATS`, the `TextureFormat` names) and
//! must agree with what the decoders accept: a texture [`select()`] exports is
//! one [`crate::decode()`] decodes as UnityPy does, and a skipped one is never
//! decoded as another format. It exports the five formats version 1 exports
//! ([`Format::EXPORTED`]): the other formats [`crate::decode()`] also
//! decodes, the rest of Pillow's raw and `bcn` formats, the ETC and EAC
//! formats and the ASTC LDR formats, are `unsupported_format` to it, as `docs/BATCH_SPEC.md` section
//! 3 says, until a spec version exports them. The engine reads the fields
//! (the object's `m_TextureFormat`, `m_Width`, `m_Height` and
//! `m_PlatformBlob`, and the platform of the SerializedFile that holds it,
//! as `get_image_from_texture2d` reads them,
//! `export/Texture2DConverter.py:237-251`) and records the skip.
//!
//! **Order.** Where more than one skip applies, the first of: a side of 0
//! (`empty_image`), because `parse_image_data` returns its empty image
//! before it looks at the format or the platform
//! (`export/Texture2DConverter.py:265-266`), so the oracle records
//! `empty_image` for such a texture in any format; then the format
//! (`unsupported_format`); then the platform (`unsupported_platform`).
//! Switch layouts without a referenced texel block retain a platform refusal.
//! A negative side is no skip: UnityPy raises for it while decoding
//! (Pillow's "Width and height must be >= 0", or a crop or tile error), and
//! [`crate::decode()`] returns [`crate::DecodeError::NegativeSize`].
//!
//! **What it does not read.** `Texture2D.image` fetches the data before
//! `parse_image_data` sees the size (`get_image_data`,
//! `classes/legacy_patch/Texture2D.py:63-75`: the object's `image_data`, else
//! what its `m_StreamData` names), and raises there for a texture with
//! neither, or whose resource file is not loaded. A side of 0 is
//! `empty_image` without any fetch (`docs/BATCH_SPEC.md` section 3): the
//! extractor skips a zero width before it reads the image, and the oracle
//! records a zero height's raise as `empty_image` (`docs/plans/extract.md`
//! section 5). [`select()`] reads no data, so for any other texture the
//! fetch, and its failure, are the engine's to record.

use std::fmt;

use crate::format::{Format, texture_format_name};
use crate::formats::Formats;

/// `BuildTarget.XBOX360` (`enums/BuildTarget.py:16`).
pub const XBOX360: i32 = 11;
/// `BuildTarget.Switch` (`enums/BuildTarget.py:39`).
pub const SWITCH: i32 = 38;

/// The formats UnityPy byte-swaps on Xbox 360: `RGB565`, `DXT1`,
/// `DXT1Crunched`, `DXT5`, `DXT5Crunched`
/// (`export/Texture2DConverter.py:569`). Of the five exported, DXT1 and
/// DXT5.
pub const XBOX_SWAP_FORMATS: [i32; 5] = [7, 10, 28, 12, 29];

/// What [`select()`] reads of a `Texture2D`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct TextureFields<'a> {
    /// `m_TextureFormat`.
    pub texture_format: i32,
    /// `m_Width`.
    pub width: i32,
    /// `m_Height`.
    pub height: i32,
    /// The target platform of the SerializedFile that holds the texture
    /// (`object_reader.platform`, a `BuildTarget` value).
    pub platform: i32,
    /// `m_PlatformBlob`'s bytes, or `None` where the texture has no such
    /// field (UnityPy's `getattr(..., None)`); an empty blob reads as `None`
    /// does.
    pub platform_blob: Option<&'a [u8]>,
}

const _: () = crate::send_sync::<TextureFields<'static>>();

impl TextureFields<'_> {
    /// The decoded mode, including empty images and Switch's RGB promotion,
    /// without validating sizes, reading data or allocating.
    #[must_use]
    pub fn image_mode(&self) -> Option<crate::Mode> {
        if self.width == 0 || self.height == 0 {
            return Some(crate::Mode::Rgba);
        }
        let format = if is_switch_swizzled(self.platform, self.platform_blob) {
            match self.texture_format {
                3 => 4,
                8 => 14,
                other => other,
            }
        } else {
            self.texture_format
        };
        Format::from_texture_format(format).map(Format::mode)
    }
}

/// What [`select()`] decides.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Selection {
    /// Decode it as this format.
    Export(Format),
    /// Skip it for this reason.
    Skip(Skip),
}

const _: () = crate::send_sync::<Selection>();

/// Why a texture is skipped (`docs/BATCH_SPEC.md` section 3). Its
/// [`Display`](fmt::Display) form is the manifest's reason
/// (`docs/BATCH_SPEC.md` 9.3).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Skip {
    /// A side of 0: `empty_image`.
    EmptyImage,
    /// A format outside the set exported (version 1's five,
    /// [`Format::EXPORTED`]), by its `TextureFormat` value:
    /// `unsupported_format(<name>)`, UnityPy's member name, or the decimal
    /// value where its enum has none.
    UnsupportedFormat(i32),
    /// A Switch texture without a referenced texel block:
    /// `unsupported_platform(switch | xbox360)`.
    UnsupportedPlatform(SkippedPlatform),
}

const _: () = crate::send_sync::<Skip>();

/// The platform an [`Skip::UnsupportedPlatform`] names.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SkippedPlatform {
    /// A Switch texture `is_switch_swizzled` holds for.
    Switch,
    /// Retained reason vocabulary for callers; Xbox byte swapping is implemented.
    Xbox360,
}

const _: () = crate::send_sync::<SkippedPlatform>();

impl fmt::Display for Skip {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmptyImage => f.write_str("empty_image"),
            Self::UnsupportedFormat(value) => match texture_format_name(*value) {
                Some(name) => write!(f, "unsupported_format({name})"),
                None => write!(f, "unsupported_format({value})"),
            },
            Self::UnsupportedPlatform(SkippedPlatform::Switch) => {
                f.write_str("unsupported_platform(switch)")
            }
            Self::UnsupportedPlatform(SkippedPlatform::Xbox360) => {
                f.write_str("unsupported_platform(xbox360)")
            }
        }
    }
}

/// Whether UnityPy deswizzles a texture as a Switch texture
/// (`TextureSwizzler.is_switch_swizzled`,
/// `helpers/TextureSwizzler.py:121-127`): the platform is Switch, the
/// platform blob holds at least 12 bytes, and `1 << n` is more than one GOB
/// per block, `n` being the little-endian `u32` at bytes 8 to 12 of the blob
/// (`get_switch_gobs_per_block`, `helpers/TextureSwizzler.py:117-118`), so
/// whenever `n` is not 0.
#[must_use]
pub fn is_switch_swizzled(platform: i32, platform_blob: Option<&[u8]>) -> bool {
    if platform != SWITCH {
        return false;
    }
    match platform_blob.and_then(|blob| blob.get(8..12)) {
        Some(gobs) => gobs.iter().any(|&b| b != 0),
        None => false,
    }
}

/// Whether a texture is exported, and as what, or skipped, and why
/// (module docs), under version 1's five formats ([`Formats::V1`]).
#[must_use]
pub fn select(texture: &TextureFields<'_>) -> Selection {
    select_in(texture, Formats::V1, (0, 0))
}

/// [`select()`] under the formats a spec names (`docs/BATCH_SPEC.md` 1.5):
/// a format outside `formats` is `unsupported_format`, as one this crate
/// does not decode is. Unity's names in `formats` allow both DXT crunch
/// variants: before Unity 2017.3 the decoder is legacy, from 2017.3 it is
/// Unity's fork. An unknown version `(u16::MAX, u16::MAX)` uses the fork.
/// Crunched ETC always uses the fork (`export/Texture2DConverter.py:297-306`).
#[must_use]
pub fn select_in(
    texture: &TextureFields<'_>,
    formats: Formats,
    unity_version: (u16, u16),
) -> Selection {
    if texture.width == 0 || texture.height == 0 {
        return Selection::Skip(Skip::EmptyImage);
    }
    if texture.texture_format == 6 || (texture.texture_format == 21 && texture.width % 2 != 0) {
        return Selection::Skip(Skip::UnsupportedFormat(texture.texture_format));
    }
    // Version 1 exports the five of E15, version 2 the formats its spec
    // names; the other formats this crate also decodes are
    // `unsupported_format` to it (`docs/BATCH_SPEC.md` section 3).
    let Some(format) = Format::from_texture_format(texture.texture_format)
        .filter(|f| formats.contains(*f))
        .map(|f| match f {
            Format::Dxt1Crunched if unity_version >= (2017, 3) => Format::UnityDxt1Crunched,
            Format::Dxt5Crunched if unity_version >= (2017, 3) => Format::UnityDxt5Crunched,
            other => other,
        })
    else {
        return Selection::Skip(Skip::UnsupportedFormat(texture.texture_format));
    };
    let switch_format = match texture.texture_format {
        3 => 4,
        8 => 14,
        other => other,
    };
    if is_switch_swizzled(texture.platform, texture.platform_blob)
        && crate::platform::switch_block(switch_format).is_none()
    {
        return Selection::Skip(Skip::UnsupportedPlatform(SkippedPlatform::Switch));
    }
    Selection::Export(format)
}

/// Select crunched DXT/ETC with an explicit Unity `(major, minor)`.
/// The version split and ETC exception are UnityPy's
/// `export/Texture2DConverter.py:297-306`. Empty images precede it, and
/// the existing Switch/Xbox gates still apply. Other formats use
/// version 1's five formats, as [`select()`] does.
#[must_use]
pub fn select_crunch(texture: &TextureFields<'_>, unity_version: (u16, u16)) -> Selection {
    select_in(
        texture,
        Formats::V1
            .with(Format::Dxt1Crunched)
            .with(Format::Dxt5Crunched)
            .with(Format::EtcRgb4Crunched)
            .with(Format::Etc2Rgba8Crunched),
        unity_version,
    )
}