mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-18 16:24:38 +00:00
231 lines
10 KiB
Rust
231 lines
10 KiB
Rust
//! 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 }));
|
|
}
|
|
}
|