GitCorner

Code

ossartcrafttexturecraft๐ŸŒ
d84914ef1e5a
//! Conversion of composited tiles to the texture formats the viewport samples.
//!
//! GPU packing (one texture per [`DisplayKind`], all `TILE`-aligned, same resolution):
//!
//! | texture   | format   | r                 | g              | b                 | a                 |
//! |-----------|----------|-------------------|----------------|-------------------|-------------------|
//! | BaseColor | sRGB8    | base color        |                |                   | opacity           |
//! | Orm       | RGBA8    | AO (ร— baked)      | roughness      | metallic          | specular level    |
//! | Normal    | RGBA16F  | normal x          | normal y       | normal z          | sheen roughness   |
//! | Height    | RGBA16F  | height            | Specular (F0) r| g                 | b                 |
//! | Emissive  | sRGB8    | emissive          |                |                   | scattering weight |
//! | Lobes     | RGBA8    | coat weight       | coat roughness | anisotropy level  | anisotropy angle  |
//! | Sheen     | sRGB8    | sheen color       |                |                   | sheen weight      |
//! | Extra     | RGBA8    | coat normal x     | coat normal y  | transmission      | tile scale        |
//!
//! Normal holds the tangent-space normal signed (flat is `(0, 0, 1)`) in half floats: baked
//! normals are high-precision data, and 8 bits per axis bands smooth surfaces in the shading.
//!
//! Extra packs the coat normal's x and y as `128 + 127 ร— n` (the default normal is exactly 0;
//! z is rebuilt in the shader). Its alpha is the [`Composite::block_scales`] of the texel's UV
//! tile as `32 ร— log2(1 / scale)` (0 for a tile filling its block): the shader turns height
//! slopes down by it.
//!
//! Alpha of sRGB formats is linear. Channels a set lacks pack their default values, which switch
//! the extra lobes off, so the renderer can keep Lobes and Sheen as 1ร—1 placeholders until a
//! tile with a non-default value arrives.

use texturecraft_core::{BakedMap, Channel};
use texturecraft_texel::{TILE, TILE_AREA, srgb_lut};

use crate::eval::Composite;
use crate::store::BakedMaps;

/// One of the textures the viewport shader samples.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum DisplayKind {
    /// sRGB8: base color, alpha = opacity.
    BaseColor,
    /// RGBA8 linear: ambient occlusion (channel ร— baked), roughness (1 โˆ’ glossiness when the set
    /// has a Glossiness channel), metallic, specular level.
    Orm,
    /// RGBA16F: the shown tangent-space normal, signed (flat is `(0, 0, 1)`), alpha = sheen roughness.
    Normal,
    /// RGBA16F: height in r, the linear Specular (F0) color in gba.
    Height,
    /// sRGB8: emissive color, alpha = scattering weight.
    Emissive,
    /// RGBA8 linear: coat weight, coat roughness, anisotropy level, anisotropy angle.
    Lobes,
    /// sRGB8: sheen color, alpha = sheen weight.
    Sheen,
    /// RGBA8 linear: coat normal x and y, transmission, tile scale.
    Extra,
}

impl DisplayKind {
    pub const ALL: [DisplayKind; 8] = [
        DisplayKind::BaseColor,
        DisplayKind::Orm,
        DisplayKind::Normal,
        DisplayKind::Height,
        DisplayKind::Emissive,
        DisplayKind::Lobes,
        DisplayKind::Sheen,
        DisplayKind::Extra,
    ];

    /// Bytes per texel of the upload format.
    pub fn bytes_per_texel(self) -> usize {
        if matches!(self, DisplayKind::Height | DisplayKind::Normal) { 8 } else { 4 }
    }

    /// Display textures affected by a channel.
    pub fn of_channel(c: Channel) -> DisplayKind {
        match c {
            Channel::BaseColor | Channel::Opacity => DisplayKind::BaseColor,
            Channel::Normal | Channel::SheenRoughness => DisplayKind::Normal,
            Channel::Height | Channel::Specular => DisplayKind::Height,
            Channel::Emissive | Channel::ScatterWeight => DisplayKind::Emissive,
            Channel::CoatWeight | Channel::CoatRoughness | Channel::AnisotropyLevel | Channel::AnisotropyAngle => DisplayKind::Lobes,
            Channel::SheenColor | Channel::SheenWeight => DisplayKind::Sheen,
            Channel::CoatNormal | Channel::Transmission => DisplayKind::Extra,
            _ => DisplayKind::Orm,
        }
    }

    /// Whether a texture reads anything but its own channels: Orm and Normal fold in the baked
    /// maps, Extra's alpha holds the tile scale, so they differ from the default even for a set
    /// without any of their channels.
    fn reads_more_than_channels(self) -> bool {
        matches!(self, DisplayKind::Orm | DisplayKind::Normal | DisplayKind::Extra)
    }

    /// The texel of a set that has none of this texture's channels (the GPU clear value).
    pub fn default_texel(self) -> Vec<u8> {
        let mut px = tile_bytes(&Composite::new(&[], TILE), &BakedMaps::default(), self, 0, 0);
        px.truncate(self.bytes_per_texel());
        px
    }
}

/// Display kinds to convert for a set with `channels`: always Orm, Normal and Extra (they read
/// baked maps or tile scales too); the others only when the set has one of their channels
/// (otherwise every tile is the placeholder default).
pub fn kinds_for(channels: &[Channel]) -> impl Iterator<Item = DisplayKind> + '_ {
    DisplayKind::ALL.into_iter().filter(|k| k.reads_more_than_channels() || channels.iter().any(|c| DisplayKind::of_channel(*c) == *k))
}

fn u8_of(v: u16) -> u8 {
    (v >> 8) as u8
}

/// Tile bytes (`TILE ร— TILE`, row-major) for `kind`, using channel defaults for absent source tiles.
pub fn tile_bytes(composite: &Composite, baked: &BakedMaps, kind: DisplayKind, tx: u32, ty: u32) -> Vec<u8> {
    let bytes_per_texel = kind.bytes_per_texel();
    let mut out = vec![0u8; TILE_AREA * bytes_per_texel];
    let srgb = srgb_lut();
    let get = |c: Channel| composite.channels.get(&c).and_then(|img| img.tile(tx, ty));
    let resolution = composite.resolution;
    let default16 = |c: Channel| texturecraft_texel::to_u16(c.default_value()[0]);

    // A scalar channel's texel `i` as 8 bits (its default where the set lacks it)
    let scalar8 = |c: Channel| {
        let (t, d) = (get(c), default16(c));
        move |i: usize| u8_of(t.and_then(|t| t.get(i).copied()).unwrap_or(d))
    };

    match kind {
        DisplayKind::BaseColor | DisplayKind::Emissive | DisplayKind::Sheen => {
            let (c, alpha) = match kind {
                DisplayKind::BaseColor => (Channel::BaseColor, Channel::Opacity),
                DisplayKind::Emissive => (Channel::Emissive, Channel::ScatterWeight),
                _ => (Channel::SheenColor, Channel::SheenWeight),
            };
            let (src, alpha) = (get(c), scalar8(alpha));
            let d = c.default_value().map(|v| (texturecraft_texel::linear_to_srgb(v) * 255.0 + 0.5) as u8);

            for i in 0..TILE_AREA {
                let pixel = &mut out[i * 4..i * 4 + 4];
                match src {
                    Some(s) => {
                        for k in 0..3 {
                            pixel[k] = srgb[(s.get(i * 3 + k).copied().unwrap_or(0) >> 4) as usize];
                        }
                    }
                    None => pixel[..3].copy_from_slice(&d),
                }
                pixel[3] = alpha(i);
            }
        }
        DisplayKind::Lobes => {
            let lanes = [Channel::CoatWeight, Channel::CoatRoughness, Channel::AnisotropyLevel, Channel::AnisotropyAngle].map(scalar8);

            for (i, pixel) in out.as_chunks_mut::<4>().0.iter_mut().enumerate() {
                for (d, lane) in pixel.iter_mut().zip(&lanes) {
                    *d = lane(i);
                }
            }
        }
        DisplayKind::Extra => {
            let (n, transmission) = (get(Channel::CoatNormal), scalar8(Channel::Transmission));

            // Signed 8-bit around 128 so the flat normal packs exactly
            let pack_signed_normal = |v: u16| (128.0 + 127.0 * (v as f32 / 65535.0 * 2.0 - 1.0)).round().clamp(0.0, 255.0) as u8;

            // A TILE never straddles two atlas blocks
            let scale = (-32.0 * composite.block_scales.at(tx * TILE, ty * TILE).log2()).round().clamp(0.0, 255.0) as u8;
            for (i, pixel) in out.as_chunks_mut::<4>().0.iter_mut().enumerate() {
                for (k, d) in pixel.iter_mut().take(2).enumerate() {
                    *d = n.and_then(|t| t.get(i * 3 + k)).map_or(128, |v| pack_signed_normal(*v));
                }
                pixel[2] = transmission(i);
                pixel[3] = scale;
            }
        }
        DisplayKind::Orm => {
            let (ao, m, s) = (get(Channel::AmbientOcclusion), get(Channel::Metallic), get(Channel::SpecularLevel));

            // Specular/glossiness sets: the viewport shades roughness = 1 โˆ’ glossiness
            let gloss = composite.channels.contains_key(&Channel::Glossiness);
            let (r, r_default) =
                if gloss { (get(Channel::Glossiness), default16(Channel::Glossiness)) } else { (get(Channel::Roughness), default16(Channel::Roughness)) };

            for i in 0..TILE_AREA {
                let (x, y) = (tx * TILE + (i as u32 % TILE), ty * TILE + (i as u32 / TILE));
                let baked_ao = baked
                    .sample_working(BakedMap::AmbientOcclusion, x, y, (resolution, composite.height), &composite.block_scales)
                    .map_or(1.0, |value| value[0]);
                let ch_ao = ao.and_then(|a| a.get(i)).map(|v| *v as f32 / 65535.0).unwrap_or(1.0);

                let pixel = &mut out[i * 4..i * 4 + 4];
                pixel[0] = ((baked_ao * ch_ao).clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
                let v = r.and_then(|t| t.get(i).copied()).unwrap_or(r_default);
                pixel[1] = u8_of(if gloss { 65535 - v } else { v });
                pixel[2] = u8_of(m.and_then(|t| t.get(i).copied()).unwrap_or(0));
                pixel[3] = u8_of(s.and_then(|t| t.get(i).copied()).unwrap_or(default16(Channel::SpecularLevel)));
            }
        }
        DisplayKind::Normal => {
            let (normal_tile, sheen_roughness_tile) = (get(Channel::Normal), get(Channel::SheenRoughness));
            let sheen_default = Channel::SheenRoughness.default_value()[0];
            let has_baked_normal = baked.maps.contains_key(&BakedMap::Normal);

            for (i, pixel) in out.as_chunks_mut::<8>().0.iter_mut().enumerate() {
                // Baked normals form the base for painted detail, matching export
                let (x, y) = (tx * TILE + (i as u32 % TILE), ty * TILE + (i as u32 / TILE));
                let baked_sample =
                    if has_baked_normal { baked.sample_working(BakedMap::Normal, x, y, (resolution, composite.height), &composite.block_scales) } else { None };

                // Invalid baked samples must not enter half-float shading
                let base = baked_sample.filter(|normal| normal.iter().all(|component| (0.0..=1.0).contains(component)));
                let painted = normal_tile.map(|tile| [0, 1, 2].map(|k| tile.get(i * 3 + k).map_or(0.0, |v| *v as f32 / 65535.0)));
                let packed = match (painted, base) {
                    (Some(painted), None) => painted,
                    (painted, Some(base)) => texturecraft_core::blend::rnm(base, painted.unwrap_or([0.5, 0.5, 1.0])),
                    (None, None) => [0.5, 0.5, 1.0],
                };

                let sheen = sheen_roughness_tile.and_then(|tile| tile.get(i)).map_or(sheen_default, |v| *v as f32 / 65535.0);
                let [x, y, z] = packed.map(|v| (v * 2.0 - 1.0).clamp(-1.0, 1.0));
                for (k, c) in [x, y, z, sheen].into_iter().enumerate() {
                    pixel[k * 2..k * 2 + 2].copy_from_slice(&half::f16::from_f32(c).to_le_bytes());
                }
            }
        }
        DisplayKind::Height => {
            let (h, spec) = (get(Channel::Height), get(Channel::Specular));
            let spec_default = Channel::Specular.default_value();

            for i in 0..TILE_AREA {
                let v = h.and_then(|t| t.get(i)).map(|v| texturecraft_texel::from_u16_signed(*v)).unwrap_or(0.0);
                let f0 = |k: usize| spec.and_then(|t| t.get(i * 3 + k)).map(|v| *v as f32 / 65535.0).unwrap_or(spec_default[k]);
                for (k, c) in [v, f0(0), f0(1), f0(2)].into_iter().enumerate() {
                    out[i * 8 + k * 2..i * 8 + k * 2 + 2].copy_from_slice(&half::f16::from_f32(c).to_le_bytes());
                }
            }
        }
    }

    out
}

#[cfg(test)]
mod tests {
    use super::*;
    use texturecraft_texel::to_u16;

    #[test]
    fn kinds_for_skips_kinds_without_channels() {
        assert_eq!(kinds_for(&[]).collect::<Vec<_>>(), [DisplayKind::Orm, DisplayKind::Normal, DisplayKind::Extra]);
        let with_base: Vec<_> = kinds_for(&[Channel::BaseColor, Channel::Roughness]).collect();
        assert_eq!(with_base, [DisplayKind::BaseColor, DisplayKind::Orm, DisplayKind::Normal, DisplayKind::Extra]);
        let with_sheen: Vec<_> = kinds_for(&[Channel::SheenColor]).collect();
        assert_eq!(with_sheen, [DisplayKind::Orm, DisplayKind::Normal, DisplayKind::Sheen, DisplayKind::Extra]);
    }

    #[test]
    fn kinds_skipped_for_a_set_are_its_default_texel() {
        for channels in [&[][..], &[Channel::Roughness, Channel::Metallic], &[Channel::SheenColor, Channel::Transmission]] {
            let mut comp = Composite::new(channels, 64);
            for img in comp.channels.values_mut() {
                img.set(0, 0, &[to_u16(0.3); 3]);
            }
            for kind in DisplayKind::ALL.into_iter().filter(|k| !kinds_for(channels).any(|n| n == *k)) {
                let want = kind.default_texel().repeat(TILE_AREA);
                assert!(tile_bytes(&comp, &BakedMaps::default(), kind, 0, 0) == want, "{kind:?} for {channels:?}");
            }
        }
    }

    #[test]
    fn base_color_uses_srgb_and_opacity() {
        let mut comp = Composite::new(&[Channel::BaseColor, Channel::Opacity], 64);
        comp.channels.get_mut(&Channel::BaseColor).unwrap().set(0, 0, &[to_u16(1.0), to_u16(0.5), 0]);
        comp.channels.get_mut(&Channel::Opacity).unwrap().set(0, 0, &[to_u16(0.5)]);

        let b = tile_bytes(&comp, &BakedMaps::default(), DisplayKind::BaseColor, 0, 0);

        assert_eq!(b[0], 255);
        assert!((b[1] as i32 - 188).abs() <= 1, "{}", b[1]);
        assert_eq!(b[2], 0);
        assert!((b[3] as i32 - 127).abs() <= 1);
    }

    #[test]
    fn extra_alpha_holds_the_tile_scale() {
        let mut set = texturecraft_core::TextureSet::new("s", 0, 256);
        set.uv_tiles = vec![1001, 1002];
        set.tile_resolutions.insert(1002, 64);
        let comp = Composite { block_scales: set.block_scales(), ..Composite::new(&[], 512) };
        let alpha = |tx: u32| tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Extra, tx, 0)[3];

        // Tile 1001 fills its block; 1002 fills a quarter, encoded as 32 ร— log2(4)
        assert_eq!((alpha(0), alpha(3), alpha(4), alpha(7)), (0, 0, 64, 64));
    }

    #[test]
    fn missing_channels_fall_back_to_defaults() {
        let comp = Composite::new(&[], 64);
        let orm = tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Orm, 0, 0);

        assert_eq!(&orm[..4], &[255, 128, 0, 128]);
        assert_eq!(normal_texel(&comp, &BakedMaps::default(), 0), [0.0, 0.0, 1.0, 0.5], "flat, sheen roughness 0.5 rides in alpha");
        assert_eq!(&tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Emissive, 0, 0)[..4], &[0, 0, 0, 0]);
        assert_eq!(&tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Lobes, 0, 0)[..4], &[0, 25, 0, 0], "lobes off, coat roughness 0.1");
        assert_eq!(&tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Sheen, 0, 0)[..4], &[255, 255, 255, 0]);
        assert_eq!(&tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Extra, 0, 0)[..4], &[128, 128, 0, 0], "flat coat normal, no transmission");

        for k in DisplayKind::ALL {
            assert_eq!(k.default_texel(), tile_bytes(&comp, &BakedMaps::default(), k, 3, 5)[..k.bytes_per_texel()]);
        }

        let h = tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Height, 0, 0);
        assert_eq!(h.len(), TILE_AREA * 8);
        assert_eq!(half::f16::from_le_bytes([h[2], h[3]]).to_f32(), half::f16::from_f32(0.04).to_f32(), "default F0");
    }

    #[test]
    fn the_baked_normal_is_the_base_of_the_shown_normal() {
        // A baked normal tilted to +X at the set resolution
        let tilted = [0.8f32, 0.5, 0.9];
        let baked = BakedMaps { resolution: 64, maps: [(BakedMap::Normal, std::sync::Arc::new(tilted.repeat(64 * 64)))].into_iter().collect() };
        let shown = |comp: &Composite| normal_texel(comp, &baked, 0)[..3].to_vec();
        let pack = |v: [f32; 3]| v.map(|x| half::f16::from_f32(x * 2.0 - 1.0).to_f32()).to_vec();

        // Without a painted normal, show the bake directly
        assert_eq!(shown(&Composite::new(&[], 64)), pack(tilted));

        // Flat paint preserves the bake; tilted paint reorients onto it
        let mut comp = Composite::new(&[Channel::Normal], 64);
        comp.channels.get_mut(&Channel::Normal).unwrap().set(0, 0, &[to_u16(0.5), to_u16(0.5), to_u16(1.0)]);

        assert!(shown(&comp).iter().zip(pack(tilted)).all(|(a, b)| (a - b).abs() < 1e-3), "{:?}", shown(&comp));

        comp.channels.get_mut(&Channel::Normal).unwrap().set(0, 0, &[to_u16(0.5), to_u16(0.8), to_u16(0.9)]);

        assert_eq!(shown(&comp), pack(texturecraft_core::blend::rnm(tilted, [0.5, 0.8, 0.9])));
    }

    /// Decode texel `i` of the Normal display tile (0, 0).
    fn normal_texel(comp: &Composite, baked: &BakedMaps, i: usize) -> [f32; 4] {
        let bytes = tile_bytes(comp, baked, DisplayKind::Normal, 0, 0);
        [0, 1, 2, 3].map(|k| half::f16::from_le_bytes([bytes[i * 8 + k * 2], bytes[i * 8 + k * 2 + 1]]).to_f32())
    }

    #[test]
    fn baked_normals_keep_more_than_8_bits_in_the_viewport() {
        // Steps of 1/1024 distinguish texels that an 8-bit texture merges
        let ramp: Vec<f32> = (0..64 * 64).flat_map(|i| [0.5 + (i % 64) as f32 / 1024.0, 0.5, 0.9]).collect();
        let baked = BakedMaps { resolution: 64, maps: [(BakedMap::Normal, std::sync::Arc::new(ramp))].into_iter().collect() };
        let comp = Composite::new(&[], 64);

        let xs: Vec<f32> = (0..8).map(|i| normal_texel(&comp, &baked, i)[0]).collect();

        assert!(xs.windows(2).all(|w| w[1] > w[0]), "every texel of the gradient is distinct: {xs:?}");
        assert!(xs.windows(2).all(|w| w[1] - w[0] < 1.0 / 255.0), "steps finer than one 8-bit level: {xs:?}");
    }

    #[test]
    fn nonfinite_baked_normal_does_not_reach_the_display_texture() {
        let mut pixels = vec![0.5; 64 * 64 * 3];
        pixels[..3].copy_from_slice(&[f32::NAN, 0.5, 1.0]);
        pixels[3..6].copy_from_slice(&[0.5, f32::INFINITY, 1.0]);
        let baked = BakedMaps { resolution: 64, maps: [(BakedMap::Normal, std::sync::Arc::new(pixels))].into_iter().collect() };
        let composite = Composite::new(&[], 64);

        assert_eq!(normal_texel(&composite, &baked, 0), [0.0, 0.0, 1.0, 0.5]);
        assert_eq!(normal_texel(&composite, &baked, 1), [0.0, 0.0, 1.0, 0.5]);
    }

    #[test]
    fn glossiness_shows_as_roughness_and_specular_rides_in_height() {
        let mut comp = Composite::new(&[Channel::Glossiness, Channel::Specular], 64);
        comp.channels.get_mut(&Channel::Glossiness).unwrap().set(0, 0, &[to_u16(0.8)]);
        comp.channels.get_mut(&Channel::Specular).unwrap().set(0, 0, &[to_u16(1.0), to_u16(0.5), 0]);

        let orm = tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Orm, 0, 0);

        assert!((orm[1] as i32 - 51).abs() <= 1, "roughness = 1 - 0.8, got {}", orm[1]);

        let h = tile_bytes(&comp, &BakedMaps::default(), DisplayKind::Height, 0, 0);
        let at = |k: usize| half::f16::from_le_bytes([h[k * 2], h[k * 2 + 1]]).to_f32();

        assert_eq!(at(0), 0.0);
        assert!((at(1) - 1.0).abs() < 1e-3 && (at(2) - 0.5).abs() < 1e-3 && at(3) == 0.0);
        assert_eq!(DisplayKind::of_channel(Channel::Specular), DisplayKind::Height);
        assert_eq!(DisplayKind::of_channel(Channel::Glossiness), DisplayKind::Orm);
    }

    #[test]
    fn lobe_channels_pack_into_lobes_sheen_and_spare_alphas() {
        let mut comp = Composite::new(&Channel::LOBES, 64);
        let mut set = |c: Channel, v: &[u16]| comp.channels.get_mut(&c).unwrap().set(1, 0, v);
        set(Channel::CoatWeight, &[to_u16(1.0)]);
        set(Channel::CoatRoughness, &[to_u16(0.2)]);
        set(Channel::AnisotropyLevel, &[to_u16(0.6)]);
        set(Channel::AnisotropyAngle, &[to_u16(0.25)]);
        set(Channel::SheenColor, &[to_u16(1.0), 0, to_u16(0.5)]);
        set(Channel::SheenWeight, &[to_u16(0.8)]);
        set(Channel::SheenRoughness, &[to_u16(0.3)]);
        set(Channel::ScatterWeight, &[to_u16(0.4)]);
        set(Channel::Transmission, &[to_u16(0.6)]);
        set(Channel::CoatNormal, &[to_u16(1.0), to_u16(0.5), to_u16(1.0)]);

        let px = |k: DisplayKind| tile_bytes(&comp, &BakedMaps::default(), k, 0, 0)[4..8].to_vec();
        let near = |a: &[u8], b: &[u8]| a.iter().zip(b).all(|(x, y)| x.abs_diff(*y) <= 1);

        assert!(near(&px(DisplayKind::Lobes), &[255, 51, 153, 64]), "{:?}", px(DisplayKind::Lobes));
        assert!(near(&px(DisplayKind::Sheen), &[255, 0, 188, 204]), "{:?}", px(DisplayKind::Sheen));
        assert!((normal_texel(&comp, &BakedMaps::default(), 1)[3] - 0.3).abs() < 1e-3 && near(&px(DisplayKind::Emissive)[3..], &[102]));
        assert!(near(&px(DisplayKind::Extra), &[255, 128, 153, 0]), "{:?}", px(DisplayKind::Extra));
        for c in Channel::LOBES {
            assert_ne!(DisplayKind::of_channel(c), DisplayKind::Orm, "{c:?}");
        }
    }
}