From e36f7973dac62d637c62c4b4b0c77779de2e5066 Mon Sep 17 00:00:00 2001 From: ".CooCoo" Date: Mon, 16 Nov 2026 18:32:18 -0800 Subject: [PATCH] craft-texture: add height to normal and ORM packing over row-read sources (#1403) --- Cargo.lock | 1 + crates/texture/Cargo.toml | 1 + crates/texture/README.md | 33 ++- crates/texture/src/lib.rs | 12 + crates/texture/src/normal.rs | 432 ++++++++++++++++++++++++++++++ crates/texture/src/packing.rs | 230 ++++++++++++++++ crates/texture/src/source.rs | 143 ++++++++++ crates/texture/src/tiled_tests.rs | 231 ++++++++++++++++ 8 files changed, 1079 insertions(+), 4 deletions(-) create mode 100644 crates/texture/src/normal.rs create mode 100644 crates/texture/src/packing.rs create mode 100644 crates/texture/src/source.rs create mode 100644 crates/texture/src/tiled_tests.rs diff --git a/Cargo.lock b/Cargo.lock index ef82f1afa..69fea687d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2989,6 +2989,7 @@ version = "0.1.0" dependencies = [ "bytemuck", "dds", + "half", "rayon", "thiserror 2.0.21", ] diff --git a/crates/texture/Cargo.toml b/crates/texture/Cargo.toml index 173abb0b0..964fafa41 100644 --- a/crates/texture/Cargo.toml +++ b/crates/texture/Cargo.toml @@ -24,5 +24,6 @@ dds = { version = "0.2.0", default-features = false, optional = true } bytemuck = { workspace = true, optional = true } [dev-dependencies] +half = "2" dds = { version = "0.2.0", default-features = false } bytemuck = { workspace = true } diff --git a/crates/texture/README.md b/crates/texture/README.md index 8c82e5d0b..c5b10eac1 100644 --- a/crates/texture/README.md +++ b/crates/texture/README.md @@ -40,9 +40,31 @@ network I/O and has no `unsafe` code. `to_rgba8_display` encodes 8-bit sRGB RGBA. `linear_to_srgb`, `srgb_to_linear` and `luminance` (Rec. 709) are scalar helpers. `resource_key` and `split_resource_key` tag a bitmap name with its color space. +- **Height to normal and ORM packing.** Both read a `ScalarSource`: a plane of linear scalar + samples that gives its size and one row at a time, so an adapter can decode a tiled or encoded + surface in place. Besides the output, each worker keeps at most three rows for the normal map + and one row for each given plane for ORM packing, never a full `f32` copy of the input. Both + check the output size against `Limits` before reading. An `Image` is a + `ScalarSource` of its gray value, or its Rec. 709 luminance for a color image. + - `normal::try_height_to_normal` returns an RGBA tangent-space normal map. It takes the 3×3 + Sobel gradient of the height, scales it by `strength` and normalizes `(-gx × s, gy × s, 1)`, + then stores `0.5 × n + 0.5` with alpha 1, as glTF 2.0 encodes normal textures. OpenGL + normals have green up the image; `NormalConvention::DirectX` negates green. Neighbors clamp + to the image, or with `BoundaryMode::ClampToBlock` to the `block × block` UV tile of the + center sample. A neighbor that `ScalarSource::covered` reports as not covered takes the + center height. `HeightNormalOptions::uv_tiles(height_strength, tile_res, block_scale)` gives + the strength `height_strength × tile_res × block_scale / 16` and clamps to UV tiles of + `tile_res`. A strength of 0 gives flat normals `[0.5, 0.5, 1]`. + - `packing::try_pack_orm` returns RGBA `[occlusion, roughness, metallic, 1]`, the channels + glTF 2.0 reads occlusion from (red) and metallic-roughness from (green and blue). A plane + that is not given takes 1, 0.5 or 0. `occlusion_multiplier` multiplies a second occlusion + plane, such as baked occlusion, into red. Every plane must have the same size, and `size` + gives it when no plane is given. + - Values are linear data with no transfer curve. A NaN or infinite strength, sample or block + scale, a block of 0, an occlusion product that overflows `f32`, mismatched sizes and a + failed row read return a `TextureOpError`. -Mirrored repeat, mip chains, height to normal, channel packing, decoding and texture-set -recognition are not in the crate yet. +Mirrored repeat, mip chains, decoding and texture-set recognition are not in the crate yet. ## Cargo features @@ -50,7 +72,7 @@ No default features. | Feature | Provides | Pulls in | |---|---|---| -| `parallel` | generated images and display conversion fill rows on several threads; the results are the same | `rayon` | +| `parallel` | generated images, display conversion, height to normal and ORM packing fill rows on several threads; the results are the same | `rayon` | Without `parallel` the crate builds for `wasm32-unknown-unknown`. @@ -58,7 +80,7 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. | Field | Default | Checked by | |---|---|---| -| `max_side` | 8192 | every `try_` constructor and `from_data` | +| `max_side` | 8192 | every `try_` constructor, `from_data`, `try_height_to_normal` and `try_pack_orm` | | `max_pixels` | 2^26 (8192 × 8192) | the same | | `max_bytes` | 1 GiB (an 8192 × 8192 RGBA plane) | the same | @@ -69,6 +91,8 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. | `Image`, `Kind`, sampling, resizing, conversions, sRGB helpers, resource keys and the six tests `sample_survives_huge_coordinates`, `resource_keys_round_trip`, `sample_wraps_and_clamps`, `resize_box_and_bilinear`, `hostile_sizes_are_clamped`, `conversions` | MaterialCraft `crates/image/src/lib.rs` at [3133062](https://github.com/storytold/materialcraft/commit/3133062968b8a1566eda12a357cb06062db16687) | | `get_axes`, `sample_axes`, `sample_nearest_axes`, `sample_stored` and the integer-sampling flag | MaterialCraft `crates/image/src/lib.rs` at [6c3b35c](https://github.com/storytold/materialcraft/commit/6c3b35c39632feafcda3d7a90ff18242f3ad910f), on this crate's coordinate reduction and `f64` bilinear sum | | `Limits`, the `try_` constructors, `from_data`, private fields with getters, the `parallel` feature, `with_integer_sampling` and `integer_sampling` | written here | +| The Sobel normal, its strength scale, UV-tile clamp and uncovered-neighbor rule, the ORM channels and defaults, and the tests `gltf_png_matches_the_composite`, `directx_flips_green`, `height_becomes_normal_detail`, `ao_mixes_baked_and_channel`, `converted_maps_invert_and_derive_normals` and `uv_tiles_export_one_file_per_tile_without_padding_across`, with assertions on the new functions | TextureCraft `crates/formats/src/export/mod.rs`, `presets.rs` and `tests.rs` and `crates/core/src/channel.rs` at [b89badc](https://github.com/storytold/texturecraft/commit/b89badcd6f883751f79960f93c554fb77f063885) | +| `ScalarSource`, row-at-a-time reading, the limit and non-finite checks, and the tiled-input tests | written here | ## Migration @@ -76,6 +100,7 @@ Without `parallel` the crate builds for `wasm32-unknown-unknown`. |---|---| | MaterialCraft | `materialcraft-image` is the source. The app switches to this crate in its own pull request. | | EffectCraft | Its texture sampling moves into this crate later, with mirrored repeat. | +| TextureCraft | Its export's height normal and ORM packing are the source of `normal` and `packing`. The app switches to them in its own pull request. | For MaterialCraft: diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs index baaabee66..54dffcb17 100644 --- a/crates/texture/src/lib.rs +++ b/crates/texture/src/lib.rs @@ -30,6 +30,10 @@ //! resampler of [`Image::try_resize`]. The forms without `try_` allocate like `Vec`. A failed //! infallible allocation ends the process. Rows are generated on several threads only with the //! `parallel` feature. +//! +//! [`normal`] makes tangent-space normal maps from a height plane, and [`packing`] packs +//! occlusion, roughness and metallic into one RGBA image. Both read a [`ScalarSource`] one row at +//! a time, so a tiled surface is read in place instead of copied into a float plane. #![forbid(unsafe_code)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] @@ -41,6 +45,14 @@ use std::sync::Arc; #[cfg(feature = "parallel")] use rayon::prelude::*; +pub mod normal; +pub mod packing; +mod source; +#[cfg(test)] +mod tiled_tests; + +pub use source::{ScalarSource, SourceError, TextureOpError}; + /// Largest side the clamping constructors make, and the default [`Limits::max_side`]. pub const MAX_SIDE: u32 = 8192; diff --git a/crates/texture/src/normal.rs b/crates/texture/src/normal.rs new file mode 100644 index 000000000..070740fd7 --- /dev/null +++ b/crates/texture/src/normal.rs @@ -0,0 +1,432 @@ +//! Tangent-space normal maps from a height plane. +//! +//! [`try_height_to_normal`] takes the 3×3 Sobel gradient of the height around each sample, scales +//! it by [`HeightNormalOptions::strength`] and normalizes `(-gx × s, gy × s, 1)`. Image `y` grows +//! downward, so height that rises toward the bottom of the image gives a positive OpenGL `y`. +//! Each unit normal is stored as `0.5 × n + 0.5` in red, green and blue, the encoding glTF 2.0 +//! section 3.9.3 gives for normal textures +//! (), with alpha 1. The output is +//! linear data. [`NormalConvention::DirectX`] negates `y` before the encoding. + +use crate::source::{ScalarSource, TextureOpError, read_checked, try_buffer, try_color_image}; +use crate::{Image, Limits}; + +/// Divisor of the slope scale in [`HeightNormalOptions::uv_tiles`]: the strength is +/// `height_strength × tile_res × block_scale / HEIGHT_SPAN`. +pub const HEIGHT_SPAN: f32 = 16.0; + +/// The direction of the green channel of a normal map. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum NormalConvention { + /// Green points up the image (X+, Y+, Z+), as glTF 2.0 normal textures do. + #[default] + OpenGl, + /// Green points down the image (X+, Y-, Z+). + DirectX, +} + +/// Which samples a neighbor of a sample may be read from. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)] +pub enum BoundaryMode { + /// A neighbor outside the image takes the nearest edge sample. + #[default] + ClampToImage, + /// The plane is a grid of `block × block` material blocks, the top-left block at `(0, 0)`. A + /// neighbor outside the block of the center sample, or outside the image, takes the nearest + /// sample inside both. `block` is at least 1. + ClampToBlock { block: u32 }, +} + +/// How [`try_height_to_normal`] turns heights into normals. +/// `#[non_exhaustive]`: start from [`HeightNormalOptions::default`] or +/// [`HeightNormalOptions::uv_tiles`] and set the fields you change. +#[derive(Clone, Copy, Debug, PartialEq)] +#[non_exhaustive] +pub struct HeightNormalOptions { + /// Multiplier of the Sobel gradient. 0 gives flat normals; a negative value inverts the + /// relief. Default 1. + pub strength: f32, + /// Default [`NormalConvention::OpenGl`]. + pub convention: NormalConvention, + /// Default [`BoundaryMode::ClampToImage`]. + pub boundary: BoundaryMode, +} + +impl Default for HeightNormalOptions { + fn default() -> Self { + Self { strength: 1.0, convention: NormalConvention::OpenGl, boundary: BoundaryMode::ClampToImage } + } +} + +impl HeightNormalOptions { + /// Options for a plane of `tile_res × tile_res` UV tiles: strength + /// `height_strength × tile_res × block_scale / HEIGHT_SPAN`, neighbors clamped to the UV tile + /// of the center sample, and OpenGL normals. `height_strength` must be finite, `tile_res` at + /// least 1 and `block_scale` finite and above 0. + pub fn uv_tiles(height_strength: f32, tile_res: u32, block_scale: f32) -> Result { + if !height_strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "height_strength", value: f64::from(height_strength) }); + } + if tile_res == 0 { + return Err(TextureOpError::BadParameter { name: "tile_res", value: 0.0 }); + } + if !(block_scale.is_finite() && block_scale > 0.0) { + return Err(TextureOpError::BadParameter { name: "block_scale", value: f64::from(block_scale) }); + } + let strength = height_strength * tile_res as f32 * block_scale / HEIGHT_SPAN; + if !strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "strength", value: f64::from(strength) }); + } + Ok(Self { strength, convention: NormalConvention::OpenGl, boundary: BoundaryMode::ClampToBlock { block: tile_res } }) + } +} + +/// The unit OpenGL normal of the height neighborhood `h`, rows top to bottom and columns left to +/// right with the center at `h[1][1]`. The Sobel gradients are +/// `gx = (h[0][2] + 2 h[1][2] + h[2][2] - h[0][0] - 2 h[1][0] - h[2][0]) / 8` and +/// `gy = (h[2][0] + 2 h[2][1] + h[2][2] - h[0][0] - 2 h[0][1] - h[0][2]) / 8`, and the result is +/// `(-gx × strength, gy × strength, 1)` normalized, computed in `f64`. NaN or infinite input +/// gives `[0, 0, 1]`. +pub fn normal_from_neighborhood(h: [[f32; 3]; 3], strength: f32) -> [f32; 3] { + let h = h.map(|row| row.map(f64::from)); + let gx = (h[0][2] + 2.0 * h[1][2] + h[2][2] - h[0][0] - 2.0 * h[1][0] - h[2][0]) / 8.0; + let gy = (h[2][0] + 2.0 * h[2][1] + h[2][2] - h[0][0] - 2.0 * h[0][1] - h[0][2]) / 8.0; + let s = f64::from(strength); + let (x, y) = (-gx * s, gy * s); + let len = (x * x + y * y + 1.0).sqrt(); + if !len.is_finite() { + return [0.0, 0.0, 1.0]; + } + [(x / len) as f32, (y / len) as f32, (1.0 / len) as f32] +} + +/// A unit OpenGL normal stored as `0.5 × n + 0.5` per component, with `y` negated first for +/// [`NormalConvention::DirectX`]. +pub fn encode_normal(n: [f32; 3], convention: NormalConvention) -> [f32; 3] { + let y = match convention { + NormalConvention::OpenGl => n[1], + NormalConvention::DirectX => -n[1], + }; + [n[0] * 0.5 + 0.5, y * 0.5 + 0.5, n[2] * 0.5 + 0.5] +} + +/// The RGBA normal map of the height plane `source`, the same size. +/// +/// Each sample's neighbors are clamped as [`HeightNormalOptions::boundary`] says, and a neighbor +/// that [`ScalarSource::covered`] reports as not covered takes the center height. Rows are read +/// from `source` one at a time, and at most three rows are kept per worker besides the output. +/// +/// Returns [`TextureOpError::BadParameter`] for a non-finite strength or a block of 0, an +/// [`crate::ImageError`] when the size is outside `limits` or memory runs out, both before any +/// row is read, [`TextureOpError::NonFiniteSample`] for a NaN or infinite height, and +/// [`TextureOpError::Source`] when a row cannot be read. +pub fn try_height_to_normal(source: &S, options: &HeightNormalOptions, limits: &Limits) -> Result { + if !options.strength.is_finite() { + return Err(TextureOpError::BadParameter { name: "strength", value: f64::from(options.strength) }); + } + let block = match options.boundary { + BoundaryMode::ClampToImage => None, + BoundaryMode::ClampToBlock { block: 0 } => return Err(TextureOpError::BadParameter { name: "block", value: 0.0 }), + BoundaryMode::ClampToBlock { block } => Some(block), + }; + let (w, h) = source.dimensions(); + let pass = Pass { source, strength: options.strength, convention: options.convention, block, w, h }; + try_color_image(w, h, limits, |y0, rows| pass.fill(y0, rows)) +} + +/// The first and last index on an axis of `n` samples that a neighbor of index `i` may take. +fn span(i: u32, n: u32, block: Option) -> (u32, u32) { + let last = n.saturating_sub(1); + match block { + None => (0, last), + Some(b) => { + let first = i / b * b; + (first, first.saturating_add(b - 1).min(last)) + } + } +} + +/// The indices of the previous sample, `i` and the next sample, clamped to `span`. +fn neighbors(i: u32, (first, last): (u32, u32)) -> [u32; 3] { + [i.saturating_sub(1).max(first), i, i.saturating_add(1).min(last)] +} + +struct Pass<'a, S: ?Sized> { + source: &'a S, + strength: f32, + convention: NormalConvention, + block: Option, + w: u32, + h: u32, +} + +impl Pass<'_, S> { + /// Fill the RGBA rows starting at row `y0`. + fn fill(&self, y0: u32, rows: &mut [f32]) -> Result<(), TextureOpError> { + let mut cache = RowCache::new(self.w, self.h)?; + for (y, out) in (y0..).zip(rows.chunks_exact_mut(self.w as usize * 4)) { + let ys = neighbors(y, span(y, self.h, self.block)); + cache.load(self.source, ys)?; + let input = ys.map(|y| cache.row(y)); + for (x, px) in (0u32..).zip(out.as_chunks_mut::<4>().0) { + let n = normal_from_neighborhood(self.neighborhood(x, y, ys, input), self.strength); + let [r, g, b] = encode_normal(n, self.convention); + *px = [r, g, b, 1.0]; + } + } + Ok(()) + } + + /// The 3×3 heights around `(x, y)`, read from the rows `ys`, whose samples are `rows`. + fn neighborhood(&self, x: u32, y: u32, ys: [u32; 3], rows: [&[f32]; 3]) -> [[f32; 3]; 3] { + let xs = neighbors(x, span(x, self.w, self.block)); + let center = rows[1].get(x as usize).copied().unwrap_or(0.0); + let mut h = [[center; 3]; 3]; + for ((hr, row), sy) in h.iter_mut().zip(rows).zip(ys) { + for (hv, sx) in hr.iter_mut().zip(xs) { + if (sx, sy) != (x, y) && self.source.covered(sx, sy) { + *hv = row.get(sx as usize).copied().unwrap_or(center); + } + } + } + h + } +} + +/// Up to three decoded rows, each tagged with its row index. +struct RowCache { + slots: [(Option, Vec); 3], +} + +impl RowCache { + fn new(w: u32, h: u32) -> Result { + let row = || try_buffer(w as usize, w, h); + Ok(RowCache { slots: [(None, row()?), (None, row()?), (None, row()?)] }) + } + + /// Read each row of `ys` that is not held yet into a slot that holds none of `ys`. + fn load(&mut self, source: &S, ys: [u32; 3]) -> Result<(), TextureOpError> { + for y in ys { + if self.slots.iter().any(|(k, _)| *k == Some(y)) { + continue; + } + if let Some((k, row)) = self.slots.iter_mut().find(|(k, _)| !k.is_some_and(|k| ys.contains(&k))) { + *k = None; + read_checked(source, y, row)?; + *k = Some(y); + } + } + Ok(()) + } + + /// The samples of row `y`, empty when it is not held. + fn row(&self, y: u32) -> &[f32] { + self.slots.iter().find(|(k, _)| *k == Some(y)).map_or(&[], |(_, row)| row.as_slice()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::{ImageError, Kind, SourceError}; + use std::sync::atomic::{AtomicUsize, Ordering}; + + /// An 8-bit channel value, as an 8-bit PNG stores it. + fn byte(v: f32) -> i32 { + (v.clamp(0.0, 1.0) * 255.0).round() as i32 + } + + fn normals(src: &Image, options: &HeightNormalOptions) -> Image { + match try_height_to_normal(src, options, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("normal map failed: {e}"), + } + } + + fn close(a: [f32; 3], b: [f32; 3], tol: f32) -> bool { + a.iter().zip(b).all(|(a, b)| (a - b).abs() <= tol) + } + + fn rgb(img: &Image, x: i64, y: i64) -> [f32; 3] { + let p = img.get(x, y, false); + [p[0], p[1], p[2]] + } + + #[test] + fn height_becomes_normal_detail() { + // Height rises to the right and down the image. + let height = Image::gray(64, 64, |x, y| (x as f32 + y as f32) / 160.0); + let Ok(options) = HeightNormalOptions::uv_tiles(8.0, 64, 1.0) else { panic!("valid options") }; + let n = normals(&height, &options); + let p = n.get(30, 30, false).map(byte); + assert!(p[0] < 120, "slope up to the right tilts the normal left: {p:?}"); + assert!(p[1] > 136, "slope up toward the image bottom tilts an OpenGL normal up: {p:?}"); + assert_eq!(n.get(30, 30, false)[3], 1.0); + let Ok(flat) = HeightNormalOptions::uv_tiles(0.0, 64, 1.0) else { panic!("valid options") }; + assert_eq!(normals(&height, &flat).get(30, 30, false).map(byte), [128, 128, 255, 255]); + } + + #[test] + fn directx_flips_green() { + let (x, y) = (0.3f32, 0.4f32); + let n = [x, y, (1.0 - x * x - y * y).sqrt()]; + let (a, b) = (encode_normal(n, NormalConvention::OpenGl).map(byte), encode_normal(n, NormalConvention::DirectX).map(byte)); + assert_eq!(a[0], byte(x * 0.5 + 0.5)); + assert_eq!(a[1], byte(y * 0.5 + 0.5), "{a:?}"); + assert_eq!(a[0], b[0]); + assert!((a[1] + b[1] - 255).abs() <= 1, "{a:?} vs {b:?}"); + assert_eq!(a[2], b[2]); + } + + #[test] + fn converted_maps_invert_and_derive_normals() { + let height = Image::gray(64, 64, |x, y| (x as f32 + y as f32) / 160.0); + let Ok(gl) = HeightNormalOptions::uv_tiles(8.0, 64, 1.0) else { panic!("valid options") }; + let dx = HeightNormalOptions { convention: NormalConvention::DirectX, ..gl }; + let (a, b) = (normals(&height, &gl).get(30, 30, false), normals(&height, &dx).get(30, 30, false)); + assert_eq!(a[0], b[0]); + assert_eq!(a[2], b[2]); + assert!(byte(a[1]) > 136 && (byte(a[1]) + byte(b[1]) - 255).abs() <= 1, "DirectX flips green: {a:?} vs {b:?}"); + assert!((a[1] + b[1] - 1.0).abs() < 1e-6); + } + + #[test] + fn uv_tiles_export_one_file_per_tile_without_padding_across() { + // Two 16-sample UV tiles side by side: a slope in the left one, a cliff of 100 in the right. + let atlas = Image::gray(32, 16, |x, y| if x < 16 { 0.05 * x as f32 + 0.02 * y as f32 } else { 100.0 }); + let left = Image::gray(16, 16, |x, y| 0.05 * x as f32 + 0.02 * y as f32); + let Ok(options) = HeightNormalOptions::uv_tiles(1.0, 16, 1.0) else { panic!("valid options") }; + let (a, l) = (normals(&atlas, &options), normals(&left, &HeightNormalOptions { boundary: BoundaryMode::ClampToImage, ..options })); + for y in 0..16 { + for x in 0..16 { + assert_eq!(rgb(&a, x, y), rgb(&l, x, y), "({x}, {y}) reads only its own tile"); + } + // The right tile is flat at its own left edge although the left tile is lower. + assert_eq!(rgb(&a, 16, y), [0.5, 0.5, 1.0]); + } + // Without the tile clamp the cliff tilts the last column of the left tile. + let open = normals(&atlas, &HeightNormalOptions { boundary: BoundaryMode::ClampToImage, ..options }); + assert!(open.get(15, 5, false)[0] < 0.1); + } + + #[test] + fn a_plane_gives_the_sobel_normal() { + let (a, b, s) = (0.03f32, -0.07f32, 5.0f32); + let plane = Image::gray(9, 7, |x, y| a * x as f32 + b * y as f32); + let len = ((a * s).powi(2) + (b * s).powi(2) + 1.0).sqrt(); + let want = [-a * s / len, b * s / len, 1.0 / len]; + let h = |x: i64, y: i64| plane.get(x, y, false)[0]; + let hood = [[h(3, 2), h(4, 2), h(5, 2)], [h(3, 3), h(4, 3), h(5, 3)], [h(3, 4), h(4, 4), h(5, 4)]]; + assert!(close(normal_from_neighborhood(hood, s), want, 1e-6)); + let n = normals(&plane, &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let enc = want.map(|c| 0.5 * c + 0.5); + for (x, y) in [(1, 1), (4, 3), (7, 5)] { + assert!(close(rgb(&n, x, y), enc, 1e-6), "({x}, {y}): {:?} vs {enc:?}", rgb(&n, x, y)); + } + // At the image edge the outside neighbors repeat the edge, halving that axis's slope. + let edge = normal_from_neighborhood([[h(0, 2), h(0, 2), h(1, 2)], [h(0, 3), h(0, 3), h(1, 3)], [h(0, 4), h(0, 4), h(1, 4)]], s); + assert!(close(rgb(&n, 0, 3), encode_normal(edge, NormalConvention::OpenGl), 1e-6)); + } + + /// A height plane whose samples in columns `x >= 2` are not covered. + struct Island(Image); + + impl ScalarSource for Island { + fn dimensions(&self) -> (u32, u32) { + self.0.dimensions() + } + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + self.0.read_row(y, x0, out) + } + fn covered(&self, x: u32, _y: u32) -> bool { + x < 2 + } + } + + #[test] + fn uncovered_neighbors_take_the_center_height() { + let island = Island(Image::gray(4, 3, |x, _| [0.0, 1.0, 50.0, 50.0][x as usize])); + let Ok(n) = try_height_to_normal(&island, &HeightNormalOptions::default(), &Limits::default()) else { panic!("normal map") }; + // At x = 1 the right neighbors are not covered and read as 1, so gx = (1 - 0) / 2. + let want = normal_from_neighborhood([[0.0, 1.0, 1.0]; 3], 1.0); + assert!(close(rgb(&n, 1, 1), encode_normal(want, NormalConvention::OpenGl), 1e-6)); + } + + #[test] + fn zero_and_one_sample_planes() { + let one = Image::gray(1, 1, |_, _| 7.0); + assert_eq!(normals(&one, &HeightNormalOptions { strength: 100.0, ..HeightNormalOptions::default() }).data(), &[0.5, 0.5, 1.0, 1.0]); + let empty = Empty { reads: AtomicUsize::new(0) }; + assert_eq!(try_height_to_normal(&empty, &HeightNormalOptions::default(), &Limits::default()), Err(ImageError::BadSize(0, 0).into())); + assert_eq!(empty.reads.load(Ordering::Relaxed), 0); + } + + /// A source with no samples that counts its reads. + struct Empty { + reads: AtomicUsize, + } + + impl ScalarSource for Empty { + fn dimensions(&self) -> (u32, u32) { + (0, 0) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + self.reads.fetch_add(1, Ordering::Relaxed); + Ok(()) + } + } + + /// A source of any claimed size that fails every read. + struct Failing(u32, u32); + + impl ScalarSource for Failing { + fn dimensions(&self) -> (u32, u32) { + (self.0, self.1) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + Err(SourceError("tile unavailable".into())) + } + } + + #[test] + fn sizes_outside_the_limits_are_rejected_before_reading() { + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + let huge = Failing(u32::MAX, u32::MAX); + let o = HeightNormalOptions::default(); + assert_eq!(try_height_to_normal(&huge, &o, &open), Err(ImageError::TooLarge(u32::MAX, u32::MAX).into())); + let small = Limits { max_pixels: 15, ..Limits::default() }; + assert_eq!(try_height_to_normal(&Failing(4, 4), &o, &small), Err(ImageError::TooLarge(4, 4).into())); + assert_eq!(try_height_to_normal(&Failing(9000, 1), &o, &Limits::default()), Err(ImageError::BadSize(9000, 1).into())); + } + + #[test] + fn read_failures_and_non_finite_input_are_errors() { + let o = HeightNormalOptions::default(); + let l = Limits::default(); + assert!(matches!(try_height_to_normal(&Failing(3, 3), &o, &l), Err(TextureOpError::Source { .. }))); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let Ok(img) = Image::from_data(3, 2, Kind::Gray, vec![0.0, 0.0, 0.0, 0.0, bad, 0.0], &l) else { panic!("valid image") }; + assert_eq!(try_height_to_normal(&img, &o, &l), Err(TextureOpError::NonFiniteSample { x: 1, y: 1 })); + let strength = HeightNormalOptions { strength: bad, ..o }; + assert!(matches!(try_height_to_normal(&Failing(3, 3), &strength, &l), Err(TextureOpError::BadParameter { name: "strength", .. }))); + assert!(matches!(HeightNormalOptions::uv_tiles(bad, 16, 1.0), Err(TextureOpError::BadParameter { name: "height_strength", .. }))); + assert!(matches!(HeightNormalOptions::uv_tiles(1.0, 16, bad), Err(TextureOpError::BadParameter { name: "block_scale", .. }))); + assert_eq!(normal_from_neighborhood([[bad; 3]; 3], 1.0), [0.0, 0.0, 1.0]); + } + assert!(HeightNormalOptions::uv_tiles(1.0, 16, 0.0).is_err()); + assert!(HeightNormalOptions::uv_tiles(1.0, 0, 1.0).is_err()); + assert!(matches!(HeightNormalOptions::uv_tiles(f32::MAX, 16, 1.0), Err(TextureOpError::BadParameter { name: "strength", .. }))); + let block0 = HeightNormalOptions { boundary: BoundaryMode::ClampToBlock { block: 0 }, ..o }; + assert!(matches!(try_height_to_normal(&Failing(3, 3), &block0, &l), Err(TextureOpError::BadParameter { name: "block", .. }))); + } + + #[test] + fn huge_finite_heights_give_unit_normals() { + let l = Limits::default(); + let Ok(img) = Image::from_data(3, 1, Kind::Gray, vec![-f32::MAX, 0.0, f32::MAX], &l) else { panic!("valid image") }; + let n = normals(&img, &HeightNormalOptions { strength: f32::MAX, ..HeightNormalOptions::default() }); + let p = rgb(&n, 1, 0); + assert!(p.iter().all(|c| c.is_finite() && (0.0..=1.0).contains(c)), "{p:?}"); + assert!(p[0] < 1e-6, "the slope points the normal along -x: {p:?}"); + } +} diff --git a/crates/texture/src/packing.rs b/crates/texture/src/packing.rs new file mode 100644 index 000000000..6013c512a --- /dev/null +++ b/crates/texture/src/packing.rs @@ -0,0 +1,230 @@ +//! Occlusion, roughness and metallic packed into one RGBA image. +//! +//! [`try_pack_orm`] writes occlusion to red, roughness to green and metallic to blue, with alpha +//! 1, the channels glTF 2.0 section 3.9 reads its occlusion and metallic-roughness textures from +//! (). Values are linear data copied +//! as the sources give them, with no transfer curve and no clamping. + +use crate::source::{ScalarSource, TextureOpError, read_checked, try_buffer, try_color_image}; +use crate::{Image, Limits}; + +/// Red where no occlusion source is given. +pub const DEFAULT_OCCLUSION: f32 = 1.0; +/// Green where no roughness source is given. +pub const DEFAULT_ROUGHNESS: f32 = 0.5; +/// Blue where no metallic source is given. +pub const DEFAULT_METALLIC: f32 = 0.0; + +/// The planes [`try_pack_orm`] reads. Every given plane has the same size. +/// `#[non_exhaustive]`: start from [`OrmSources::default`], which gives none, and set the fields +/// you use. +#[derive(Clone, Copy, Default)] +#[non_exhaustive] +pub struct OrmSources<'a> { + /// Occlusion, written to red. + pub occlusion: Option<&'a dyn ScalarSource>, + /// A second occlusion plane, such as baked occlusion, multiplied into red when given. Without + /// [`OrmSources::occlusion`], red is this plane alone. + pub occlusion_multiplier: Option<&'a dyn ScalarSource>, + /// Roughness, written to green. + pub roughness: Option<&'a dyn ScalarSource>, + /// Metallic, written to blue. + pub metallic: Option<&'a dyn ScalarSource>, + /// The output size. Required when no plane is given; otherwise every plane must have it. + pub size: Option<(u32, u32)>, +} + +/// The RGBA image `[occlusion, roughness, metallic, 1]` of `sources`. A plane that is not given +/// takes [`DEFAULT_OCCLUSION`], [`DEFAULT_ROUGHNESS`] or [`DEFAULT_METALLIC`]. Rows are read one +/// at a time. +/// +/// Returns [`TextureOpError::SizeMismatch`] when the planes and [`OrmSources::size`] differ in +/// size, [`TextureOpError::NoSize`] when nothing gives a size, an [`crate::ImageError`] when the +/// size is outside `limits` or memory runs out, all before any row is read, +/// [`TextureOpError::NonFiniteSample`] for a NaN or infinite sample, +/// [`TextureOpError::NonFiniteResult`] when the occlusion product overflows, and +/// [`TextureOpError::Source`] when a row cannot be read. +pub fn try_pack_orm(sources: &OrmSources<'_>, limits: &Limits) -> Result { + let mut size = sources.size; + for source in [sources.occlusion, sources.occlusion_multiplier, sources.roughness, sources.metallic].into_iter().flatten() { + let found = source.dimensions(); + match size { + None => size = Some(found), + Some(expected) if expected != found => return Err(TextureOpError::SizeMismatch { expected, found }), + Some(_) => {} + } + } + let (w, h) = size.ok_or(TextureOpError::NoSize)?; + try_color_image(w, h, limits, |y0, rows| fill(sources, w, h, y0, rows)) +} + +/// One plane's current row, or its default when the plane is not given. +struct Plane<'a> { + source: Option<&'a dyn ScalarSource>, + row: Vec, + default: f32, +} + +impl<'a> Plane<'a> { + fn new(source: Option<&'a dyn ScalarSource>, default: f32, w: u32, h: u32) -> Result, TextureOpError> { + let row = if source.is_some() { try_buffer(w as usize, w, h)? } else { Vec::new() }; + Ok(Plane { source, row, default }) + } + + fn load(&mut self, y: u32) -> Result<(), TextureOpError> { + match self.source { + Some(source) => read_checked(source, y, &mut self.row), + None => Ok(()), + } + } + + fn at(&self, x: usize) -> f32 { + self.row.get(x).copied().unwrap_or(self.default) + } +} + +/// Fill the RGBA rows starting at row `y0`. +fn fill(sources: &OrmSources<'_>, w: u32, h: u32, y0: u32, rows: &mut [f32]) -> Result<(), TextureOpError> { + let mut occlusion = Plane::new(sources.occlusion, DEFAULT_OCCLUSION, w, h)?; + let mut multiplier = Plane::new(sources.occlusion_multiplier, 1.0, w, h)?; + let mut roughness = Plane::new(sources.roughness, DEFAULT_ROUGHNESS, w, h)?; + let mut metallic = Plane::new(sources.metallic, DEFAULT_METALLIC, w, h)?; + for (y, out) in (y0..).zip(rows.chunks_exact_mut(w as usize * 4)) { + for plane in [&mut occlusion, &mut multiplier, &mut roughness, &mut metallic] { + plane.load(y)?; + } + for (x, px) in out.as_chunks_mut::<4>().0.iter_mut().enumerate() { + let ao = if sources.occlusion_multiplier.is_some() { occlusion.at(x) * multiplier.at(x) } else { occlusion.at(x) }; + if !ao.is_finite() { + return Err(TextureOpError::NonFiniteResult { x: x as u32, y }); + } + *px = [ao, roughness.at(x), metallic.at(x), 1.0]; + } + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::normal::{HeightNormalOptions, try_height_to_normal}; + use crate::{ImageError, Kind, SourceError}; + + /// An 8-bit channel value, as an 8-bit PNG stores it. + fn byte(v: f32) -> i32 { + (v.clamp(0.0, 1.0) * 255.0).round() as i32 + } + + fn pack(sources: &OrmSources<'_>) -> Image { + match try_pack_orm(sources, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("packing failed: {e}"), + } + } + + fn constant(v: f32) -> Image { + Image::filled(64, 64, Kind::Gray, [v; 4]) + } + + #[test] + fn gltf_png_matches_the_composite() { + let (rough, metal) = (constant(0.25), constant(0.75)); + let s = OrmSources { roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let orm = pack(&s).get(5, 5, false).map(byte); + assert_eq!(orm[0], 255, "no AO anywhere → white"); + assert!((orm[1] - 64).abs() <= 1 && (orm[2] - 191).abs() <= 1, "{orm:?}"); + assert_eq!(orm[3], 255); + // A flat height gives the flat normal. + let Ok(n) = try_height_to_normal(&constant(0.0), &HeightNormalOptions::default(), &Limits::default()) else { panic!("normal map") }; + let n = n.get(5, 5, false).map(byte); + assert!((n[0] - 128).abs() <= 1 && (n[1] - 128).abs() <= 1 && n[2] == 255, "{n:?}"); + } + + #[test] + fn ao_mixes_baked_and_channel() { + let (channel, baked) = (constant(0.5), constant(0.5)); + let mut s = OrmSources { occlusion: Some(&channel), occlusion_multiplier: Some(&baked), ..OrmSources::default() }; + assert!((byte(pack(&s).get(3, 3, false)[0]) - 64).abs() <= 1); + // Without the multiplier the channel is used alone; without the channel the multiplier is. + s.occlusion_multiplier = None; + assert_eq!(pack(&s).get(3, 3, false)[0], 0.5); + s.occlusion = None; + s.occlusion_multiplier = Some(&baked); + assert_eq!(pack(&s).get(3, 3, false)[0], 0.5); + } + + #[test] + fn each_plane_goes_to_its_own_channel() { + let ao = Image::gray(3, 2, |x, y| 0.1 * (x + 3 * y) as f32); + let rough = Image::gray(3, 2, |x, _| 0.2 + 0.01 * x as f32); + let metal = Image::gray(3, 2, |_, y| 0.9 - 0.5 * y as f32); + let s = OrmSources { occlusion: Some(&ao), roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let orm = pack(&s); + for y in 0..2 { + for x in 0..3 { + let want = [ao.get(x, y, false)[0], rough.get(x, y, false)[0], metal.get(x, y, false)[0], 1.0]; + assert_eq!(orm.get(x, y, false), want, "({x}, {y})"); + } + } + // Values outside 0..=1 are kept. + let hdr = Image::filled(1, 1, Kind::Gray, [-0.5; 4]); + let s = OrmSources { metallic: Some(&hdr), ..OrmSources::default() }; + assert_eq!(pack(&s).data(), &[1.0, 0.5, -0.5, 1.0]); + } + + #[test] + fn missing_planes_take_the_defaults() { + let mut s = OrmSources::default(); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::NoSize)); + s.size = Some((2, 1)); + assert_eq!(pack(&s).data(), &[1.0, 0.5, 0.0, 1.0, 1.0, 0.5, 0.0, 1.0]); + s.size = Some((0, 0)); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(ImageError::BadSize(0, 0).into())); + } + + /// A source of any claimed size that fails every read. + struct Failing(u32, u32); + + impl ScalarSource for Failing { + fn dimensions(&self) -> (u32, u32) { + (self.0, self.1) + } + fn read_row(&self, _y: u32, _x0: u32, _out: &mut [f32]) -> Result<(), SourceError> { + Err(SourceError("tile unavailable".into())) + } + } + + #[test] + fn sizes_are_checked_before_reading() { + let (a, b) = (Failing(4, 4), Failing(4, 5)); + let mut s = OrmSources { roughness: Some(&a), metallic: Some(&b), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::SizeMismatch { expected: (4, 4), found: (4, 5) })); + s.metallic = None; + s.size = Some((5, 4)); + assert_eq!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::SizeMismatch { expected: (5, 4), found: (4, 4) })); + s.size = None; + let tiny = Limits { max_bytes: 63, ..Limits::default() }; + assert_eq!(try_pack_orm(&s, &tiny), Err(ImageError::TooLarge(4, 4).into())); + let huge = Failing(u32::MAX, u32::MAX); + s.roughness = Some(&huge); + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + assert_eq!(try_pack_orm(&s, &open), Err(ImageError::TooLarge(u32::MAX, u32::MAX).into())); + s.roughness = Some(&a); + assert!(matches!(try_pack_orm(&s, &Limits::default()), Err(TextureOpError::Source { y: 0, .. }))); + } + + #[test] + fn non_finite_samples_are_errors() { + let l = Limits::default(); + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let Ok(img) = Image::from_data(2, 2, Kind::Gray, vec![0.0, 0.0, 0.0, bad], &l) else { panic!("valid image") }; + let s = OrmSources { occlusion_multiplier: Some(&img), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &l), Err(TextureOpError::NonFiniteSample { x: 1, y: 1 })); + } + // Finite occlusion values whose product overflows. + let Ok(big) = Image::from_data(2, 1, Kind::Gray, vec![1.0, f32::MAX], &l) else { panic!("valid image") }; + let Ok(two) = Image::from_data(2, 1, Kind::Gray, vec![1.0, 2.0], &l) else { panic!("valid image") }; + let s = OrmSources { occlusion: Some(&big), occlusion_multiplier: Some(&two), ..OrmSources::default() }; + assert_eq!(try_pack_orm(&s, &l), Err(TextureOpError::NonFiniteResult { x: 1, y: 0 })); + } +} diff --git a/crates/texture/src/source.rs b/crates/texture/src/source.rs new file mode 100644 index 000000000..f2cf36f68 --- /dev/null +++ b/crates/texture/src/source.rs @@ -0,0 +1,143 @@ +//! Row access to a plane of linear scalar samples, and the errors of the operations that read it. + +use std::sync::Arc; + +#[cfg(feature = "parallel")] +use rayon::prelude::*; + +use crate::{Image, ImageError, Kind, Limits}; + +/// A plane of linear scalar samples that an operation reads one row at a time. +/// +/// An operation keeps a few rows of samples and its output, never a full `f32` copy of the +/// source, so a tiled or encoded image can be read in place: an adapter decodes the samples of a +/// row from whatever storage it has. Samples are data values, such as heights or roughness, read +/// without any transfer curve. +pub trait ScalarSource: Sync { + /// Width and height in samples. + fn dimensions(&self) -> (u32, u32); + + /// Write the samples of row `y` from column `x0` on into `out`, one per element. Operations + /// ask only for rows inside [`ScalarSource::dimensions`] and for `x0 + out.len()` no greater + /// than the width. + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError>; + + /// Whether the sample at `(x, y)` holds data. [`crate::normal::try_height_to_normal`] reads + /// the center sample in place of a neighbor that is not covered. Every sample is covered by + /// default. + fn covered(&self, _x: u32, _y: u32) -> bool { + true + } +} + +/// Why a [`ScalarSource`] could not give a row. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[error("{0}")] +pub struct SourceError(pub String); + +/// Why an operation over [`ScalarSource`]s could not make its image. +#[derive(Debug, Clone, PartialEq, thiserror::Error)] +#[non_exhaustive] +pub enum TextureOpError { + /// The output size is outside the limits, or its memory could not be reserved. + #[error(transparent)] + Image(#[from] ImageError), + /// Two sources, or a source and the requested size, differ in size. + #[error("source size {found:?} differs from {expected:?}")] + SizeMismatch { expected: (u32, u32), found: (u32, u32) }, + /// No source is given and no output size either. + #[error("no source or size gives the output size")] + NoSize, + /// A parameter is NaN, infinite or outside its range. + #[error("parameter {name} is {value}, which is not finite or is out of range")] + BadParameter { name: &'static str, value: f64 }, + /// A source gave a NaN or infinite sample. + #[error("sample at ({x}, {y}) is not finite")] + NonFiniteSample { x: u32, y: u32 }, + /// Finite samples gave a NaN or infinite result, such as two occlusion values whose product + /// overflows `f32`. + #[error("result at ({x}, {y}) is not finite")] + NonFiniteResult { x: u32, y: u32 }, + /// A source could not give a row. + #[error("reading row {y}: {error}")] + Source { y: u32, error: SourceError }, +} + +/// An [`Image`] read as a scalar plane: the gray value, or the Rec. 709 luminance of a color +/// image, as [`Image::get_gray`] gives it. +impl ScalarSource for Image { + fn dimensions(&self) -> (u32, u32) { + (self.w, self.h) + } + + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + let end = u64::from(x0) + out.len() as u64; + if y >= self.h || end > u64::from(self.w) { + return Err(SourceError(format!("row {y} from column {x0} for {} samples is outside the {}x{} image", out.len(), self.w, self.h))); + } + for (x, o) in (x0..).zip(out.iter_mut()) { + *o = self.get_gray(i64::from(x), i64::from(y), false); + } + Ok(()) + } +} + +/// Read row `y` of `source` in full into `out`, which holds one row, and reject a non-finite +/// sample. +pub(crate) fn read_checked(source: &S, y: u32, out: &mut [f32]) -> Result<(), TextureOpError> { + source.read_row(y, 0, out).map_err(|error| TextureOpError::Source { y, error })?; + match out.iter().position(|v| !v.is_finite()) { + Some(x) => Err(TextureOpError::NonFiniteSample { x: x as u32, y }), + None => Ok(()), + } +} + +/// A zeroed buffer of `len` floats, reserved fallibly for a `w × h` operation. +pub(crate) fn try_buffer(len: usize, w: u32, h: u32) -> Result, TextureOpError> { + let mut v = Vec::new(); + v.try_reserve_exact(len).map_err(|_| ImageError::OutOfMemory(w, h))?; + v.resize(len, 0.0); + Ok(v) +} + +/// Rows in each band that a worker fills when rows are filled on several threads. +#[cfg(feature = "parallel")] +const BAND_ROWS: usize = 64; + +/// A `w × h` RGBA image whose rows `fill` writes. `fill(y0, rows)` gets the first row index and +/// the floats of whole rows: every row at once without the `parallel` feature, bands of rows on +/// several threads with it. The size is checked against `limits` and the buffer reserved first. +pub(crate) fn try_color_image(w: u32, h: u32, limits: &Limits, fill: F) -> Result +where + F: Fn(u32, &mut [f32]) -> Result<(), TextureOpError> + Sync, +{ + let len = limits.check(w, h, Kind::Color)?; + let mut data = try_buffer(len, w, h)?; + #[cfg(feature = "parallel")] + { + let band = (w as usize * Kind::Color.channels()).saturating_mul(BAND_ROWS); + data.par_chunks_mut(band).enumerate().try_for_each(|(i, rows)| fill((i * BAND_ROWS) as u32, rows))?; + } + #[cfg(not(feature = "parallel"))] + fill(0, &mut data)?; + Ok(Image { w, h, kind: Kind::Color, integer_sampling: false, data: Arc::new(data) }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn images_read_as_gray_rows() { + let gray = Image::gray(3, 2, |x, y| (x + 10 * y) as f32); + let mut row = [0.0; 2]; + assert_eq!(gray.read_row(1, 1, &mut row), Ok(())); + assert_eq!(row, [11.0, 12.0]); + assert!(gray.read_row(2, 0, &mut row).is_err()); + assert!(gray.read_row(0, 2, &mut row).is_err()); + let color = Image::filled(1, 1, Kind::Color, [1.0, 0.0, 0.0, 1.0]); + let mut one = [0.0]; + assert_eq!(color.read_row(0, 0, &mut one), Ok(())); + assert!((one[0] - 0.2126).abs() < 1e-6); + } +} diff --git a/crates/texture/src/tiled_tests.rs b/crates/texture/src/tiled_tests.rs new file mode 100644 index 000000000..42724a918 --- /dev/null +++ b/crates/texture/src/tiled_tests.rs @@ -0,0 +1,231 @@ +//! Height to normal and ORM packing over a read-only adapter of 256 × 256 copy-on-write tiles of +//! interleaved two-channel U8, U16, F16 or F32 samples, with absent tiles reading a default pixel. + +use std::collections::BTreeMap; +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use crate::normal::{HeightNormalOptions, NormalConvention, encode_normal, normal_from_neighborhood, try_height_to_normal}; +use crate::packing::{OrmSources, try_pack_orm}; +use crate::{Image, Limits, ScalarSource, SourceError}; + +const TILE: u32 = 256; +/// Channels per stored pixel; the adapter reads channel 0. +const CHANNELS: usize = 2; + +#[derive(Clone, Copy, Debug)] +enum SampleType { + U8, + U16, + F16, + F32, +} + +impl SampleType { + fn size(self) -> usize { + match self { + SampleType::U8 => 1, + SampleType::U16 | SampleType::F16 => 2, + SampleType::F32 => 4, + } + } + + fn encode(self, v: f32, out: &mut Vec) { + match self { + SampleType::U8 => out.push((v.clamp(0.0, 1.0) * 255.0).round() as u8), + SampleType::U16 => out.extend(((v.clamp(0.0, 1.0) * 65535.0).round() as u16).to_le_bytes()), + SampleType::F16 => out.extend(half::f16::from_f32(v).to_bits().to_le_bytes()), + SampleType::F32 => out.extend(v.to_le_bytes()), + } + } + + /// The linear value of one stored sample, without a transfer curve. + fn decode(self, b: &[u8]) -> f32 { + match (self, b) { + (SampleType::U8, [v, ..]) => f32::from(*v) / 255.0, + (SampleType::U16, [a, b, ..]) => f32::from(u16::from_le_bytes([*a, *b])) / 65535.0, + (SampleType::F16, [a, b, ..]) => half::f16::from_bits(u16::from_le_bytes([*a, *b])).to_f32(), + (SampleType::F32, [a, b, c, d, ..]) => f32::from_le_bytes([*a, *b, *c, *d]), + _ => panic!("short sample"), + } + } +} + +/// A tiled surface read through [`ScalarSource`] without copying it. +struct Tiled { + w: u32, + h: u32, + ty: SampleType, + tiles: BTreeMap<(u32, u32), Arc>>, + /// One stored pixel, read where a tile is absent. + default: Vec, + reads: AtomicUsize, +} + +impl Tiled { + /// A `w × h` surface whose channel 0 holds `f(x, y)` and channel 1 holds a value that must not + /// be read. The tiles in `absent` are not stored. + fn new(w: u32, h: u32, ty: SampleType, f: impl Fn(u32, u32) -> f32, absent: &[(u32, u32)], default: f32) -> Tiled { + let mut tiles = BTreeMap::new(); + for ty_ in 0..h.div_ceil(TILE) { + for tx in 0..w.div_ceil(TILE) { + if absent.contains(&(tx, ty_)) { + continue; + } + let mut bytes = Vec::with_capacity((TILE * TILE) as usize * CHANNELS * ty.size()); + for y in ty_ * TILE..(ty_ + 1) * TILE { + for x in tx * TILE..(tx + 1) * TILE { + ty.encode(if x < w && y < h { f(x, y) } else { 0.0 }, &mut bytes); + ty.encode(0.37, &mut bytes); + } + } + tiles.insert((tx, ty_), Arc::new(bytes)); + } + } + let mut px = Vec::new(); + ty.encode(default, &mut px); + ty.encode(0.37, &mut px); + Tiled { w, h, ty, tiles, default: px, reads: AtomicUsize::new(0) } + } + + /// The sample at `(x, y)`, looked up on its own. + fn value(&self, x: u32, y: u32) -> f32 { + match self.tiles.get(&(x / TILE, y / TILE)) { + Some(t) => { + let i = (((y % TILE) * TILE + x % TILE) as usize) * CHANNELS * self.ty.size(); + self.ty.decode(&t[i..]) + } + None => self.ty.decode(&self.default), + } + } + + /// The same samples as one untiled gray image. + fn untiled(&self) -> Image { + Image::gray(self.w, self.h, |x, y| self.value(x, y)) + } +} + +impl ScalarSource for Tiled { + fn dimensions(&self) -> (u32, u32) { + (self.w, self.h) + } + + /// Walk the tile segments of the row, holding each tile while its segment is decoded. + fn read_row(&self, y: u32, x0: u32, out: &mut [f32]) -> Result<(), SourceError> { + self.reads.fetch_add(1, Ordering::Relaxed); + if y >= self.h || x0 as usize + out.len() > self.w as usize { + return Err(SourceError("outside the surface".into())); + } + let stride = CHANNELS * self.ty.size(); + let mut x = x0; + let mut rest = out; + while !rest.is_empty() { + let n = ((TILE - x % TILE) as usize).min(rest.len()); + let (seg, tail) = rest.split_at_mut(n); + match self.tiles.get(&(x / TILE, y / TILE)) { + Some(tile) => { + let start = (((y % TILE) * TILE + x % TILE) as usize) * stride; + for (o, px) in seg.iter_mut().zip(tile[start..start + n * stride].chunks_exact(stride)) { + *o = self.ty.decode(px); + } + } + None => seg.fill(self.ty.decode(&self.default)), + } + x += n as u32; + rest = tail; + } + Ok(()) + } +} + +fn normals(src: &S, options: &HeightNormalOptions) -> Image { + match try_height_to_normal(src, options, &Limits::default()) { + Ok(img) => img, + Err(e) => panic!("normal map failed: {e}"), + } +} + +/// A rough, non-planar height in `0..=1`. +fn bumpy(x: u32, y: u32) -> f32 { + ((x * 7 + y * 13 + x * y) % 17) as f32 / 16.0 +} + +/// Normals and ORM values over tiles of `ty` match the same samples untiled, and the samples +/// decode to `0.2`, `0.6` and `1.0` within `tol`. +fn check_sample_type(ty: SampleType, tol: f32) { + let height = Tiled::new(300, 270, ty, bumpy, &[(1, 1)], 0.5); + let opts = HeightNormalOptions { strength: 3.0, ..HeightNormalOptions::default() }; + let tiled = normals(&height, &opts); + assert_eq!(tiled, normals(&height.untiled(), &opts), "{ty:?}"); + // An absent tile reads its default pixel, which is flat. + assert_eq!(tiled.get(280, 260, false), [0.5, 0.5, 1.0, 1.0]); + + let ao = Tiled::new(300, 270, ty, |_, _| 0.2, &[], 0.0); + let rough = Tiled::new(300, 270, ty, |_, _| 0.6, &[], 0.0); + let metal = Tiled::new(300, 270, ty, |_, _| 1.0, &[(0, 0)], 0.6); + let s = OrmSources { occlusion: Some(&ao), roughness: Some(&rough), metallic: Some(&metal), ..OrmSources::default() }; + let Ok(orm) = try_pack_orm(&s, &Limits::default()) else { panic!("packing {ty:?}") }; + // Metallic's tile (0, 0) is absent and reads its default, 0.6. + for (x, y, m) in [(0u32, 0u32, 0.6f32), (299, 269, 1.0), (256, 3, 1.0)] { + let p = orm.get(i64::from(x), i64::from(y), false); + let want = [0.2, 0.6, m, 1.0]; + assert!(p.iter().zip(want).all(|(a, b)| (a - b).abs() <= tol), "{ty:?} ({x}, {y}): {p:?} vs {want:?}"); + assert_eq!(p, [ao.value(x, y), rough.value(x, y), metal.value(x, y), 1.0], "{ty:?} ({x}, {y})"); + } + assert!((orm.get(1, 1, false)[0] - 0.2).abs() <= tol && (orm.get(1, 1, false)[1] - 0.6).abs() <= tol); +} + +#[test] +fn u8_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::U8, 1e-7); +} + +#[test] +fn u16_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::U16, 1e-7); +} + +#[test] +fn f16_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::F16, 1e-3); + // Binary16 rounds 0.2 to 0.199951171875. + assert_eq!(SampleType::F16.decode(&half::f16::from_f32(0.2).to_bits().to_le_bytes()), 0.199_951_17); +} + +#[test] +fn f32_tiles_give_the_untiled_normal_and_orm() { + check_sample_type(SampleType::F32, 0.0); +} + +#[test] +fn storage_tile_seams_read_the_neighbor_tile() { + let (a, b, s) = (0.011f32, -0.004f32, 4.0f32); + let plane = |x: u32, y: u32| a * x as f32 + b * y as f32; + let height = Tiled::new(300, 300, SampleType::F32, plane, &[], 0.0); + let n = normals(&height, &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let untiled = normals(&height.untiled(), &HeightNormalOptions { strength: s, ..HeightNormalOptions::default() }); + let len = ((a * s).powi(2) + (b * s).powi(2) + 1.0).sqrt(); + let want = [-a * s / len, b * s / len, 1.0 / len].map(|c| 0.5 * c + 0.5); + for (x, y) in [(255, 100), (256, 100), (100, 255), (100, 256), (255, 255), (256, 256), (255, 256), (256, 255)] { + let p = n.get(x, y, false); + assert!(p.iter().zip(want).all(|(p, w)| (p - w).abs() < 1e-4), "({x}, {y}): {p:?} vs {want:?}"); + assert_eq!(p, untiled.get(x, y, false), "({x}, {y})"); + let h = |dx: i64, dy: i64| height.value((x + dx) as u32, (y + dy) as u32); + let hood = [[h(-1, -1), h(0, -1), h(1, -1)], [h(-1, 0), h(0, 0), h(1, 0)], [h(-1, 1), h(0, 1), h(1, 1)]]; + let [r, g, b] = encode_normal(normal_from_neighborhood(hood, s), NormalConvention::OpenGl); + assert_eq!(p, [r, g, b, 1.0], "({x}, {y}) reads both tiles"); + } +} + +#[test] +fn rows_are_read_as_needed_without_a_full_copy() { + let height = Tiled::new(300, 270, SampleType::U16, bumpy, &[], 0.0); + let _ = normals(&height, &HeightNormalOptions::default()); + let reads = height.reads.load(Ordering::Relaxed); + // Each row once; with the `parallel` feature each band of 64 rows also reads the row on + // either side of it. + #[cfg(not(feature = "parallel"))] + assert_eq!(reads, 270); + #[cfg(feature = "parallel")] + assert!((270..=270 + 2 * 270usize.div_ceil(64)).contains(&reads), "{reads}"); +}