craft-texture: add height to normal and ORM packing over row-read sources (#1403)

This commit is contained in:
.CooCoo authored and GitHub committed 2026-11-16 21:32:18 -05:00
1 parent 93598bc018
commit e36f7973da
8 files changed
+1079 -4

No files matched your search

Generated
+1
View File
@@ -2989,6 +2989,7 @@ version = "0.1.0"
dependencies = [
"bytemuck",
"dds",
"half",
"rayon",
"thiserror 2.0.21",
]
+1
View File
@@ -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 }
+29 -4
View File
@@ -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:
+12
View File
@@ -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;
+432
View File
@@ -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
//! (<https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html>), 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<Self, TextureOpError> {
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<S: ScalarSource + ?Sized>(source: &S, options: &HeightNormalOptions, limits: &Limits) -> Result<Image, TextureOpError> {
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, 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<u32>,
w: u32,
h: u32,
}
impl<S: ScalarSource + ?Sized> 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<u32>, Vec<f32>); 3],
}
impl RowCache {
fn new(w: u32, h: u32) -> Result<RowCache, TextureOpError> {
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<S: ScalarSource + ?Sized>(&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:?}");
}
}
+230
View File
@@ -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
//! (<https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html>). 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<Image, TextureOpError> {
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<f32>,
default: f32,
}
impl<'a> Plane<'a> {
fn new(source: Option<&'a dyn ScalarSource>, default: f32, w: u32, h: u32) -> Result<Plane<'a>, 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 }));
}
}
+143
View File
@@ -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<S: ScalarSource + ?Sized>(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<Vec<f32>, 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<F>(w: u32, h: u32, limits: &Limits, fill: F) -> Result<Image, TextureOpError>
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);
}
}
+231
View File
@@ -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<u8>) {
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<Vec<u8>>>,
/// One stored pixel, read where a tile is absent.
default: Vec<u8>,
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<S: ScalarSource + ?Sized>(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}");
}