mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-17 15:55:14 +00:00
craft-texture: add height to normal and ORM packing over row-read sources (#1403)
This commit is contained in:
1 parent
93598bc018
commit
e36f7973da
8 files changed
+1079
-4
No files matched your search
Generated
+1
@@ -2989,6 +2989,7 @@ version = "0.1.0"
|
||||
dependencies = [
|
||||
"bytemuck",
|
||||
"dds",
|
||||
"half",
|
||||
"rayon",
|
||||
"thiserror 2.0.21",
|
||||
]
|
||||
|
||||
@@ -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 }
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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:?}");
|
||||
}
|
||||
}
|
||||
@@ -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 }));
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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}");
|
||||
}
|
||||
Reference in new issue
Block a user