mirror of
https://github.com/bherbruck/solidcraft.git
synced 2026-11-16 21:51:01 +00:00
240 lines
10 KiB
Rust
240 lines
10 KiB
Rust
//! Bounded linear RGB statistics, independent of rendering and display transforms.
|
|
//! Samples use the renderer's linear-sRGB primaries; source HDR conversion is a
|
|
//! caller prerequisite. Display-sRGB primary backgrounds need a separate coverage
|
|
//! policy before camera samples can be mixed; this module does not invent one.
|
|
//!
|
|
//! The caller reserves `required_bytes` in its EXISTING job/host lease before
|
|
//! construction, and supplies a charge callback debiting that job's cumulative
|
|
//! work budget. This module creates no pool, thread, cache or cancellation token.
|
|
//! Fallible allocation checks actual capacity against that same admission.
|
|
//!
|
|
//! Samples for each pixel must arrive in the same order for bitwise reproducible
|
|
//! results. Splitting contiguous updates into smaller calls preserves that order;
|
|
//! arbitrary floating-point reductions or reordered samples are not equivalent.
|
|
//!
|
|
//! `complete_pass` borrows the film immutably and refuses uneven/empty counts.
|
|
//! Its iterator exposes linear means only; the consumer applies exposure, tone
|
|
//! mapping and encoding ONCE, in bounded cancellable chunks. Publishing requires
|
|
//! a fully resolved owned snapshot with its own host lease, generation check and
|
|
//! cancellation/publication lock. Neither a partial update nor this borrowed view
|
|
//! is a publishable frame. Progressive host/UI wiring is a separate integration.
|
|
|
|
use crate::job::{CancelToken, ErrorCode, JobError, Result};
|
|
|
|
// Standalone adaptive camera-film foundation. No CPU request/producer is installed.
|
|
#[path = "film_adaptive.rs"]
|
|
pub mod adaptive;
|
|
|
|
#[path = "film_png.rs"]
|
|
pub mod png;
|
|
|
|
// Camera passes additionally retain coverage. Their scanline protocol proves a
|
|
// uniform complete pass incrementally, without borrowing a self-owned resolver.
|
|
#[cfg(feature = "raytrace-cpu")]
|
|
#[path = "film_primary.rs"]
|
|
pub(crate) mod primary;
|
|
|
|
pub const MAX_DIMENSION: u32 = 16_384;
|
|
pub const MAX_PIXELS: usize = 16_777_216;
|
|
pub const MAX_SAMPLES: u32 = 1_048_576;
|
|
pub const MAX_UPDATE: usize = 256;
|
|
pub const MAX_BYTES: u64 = 384 * 1024 * 1024;
|
|
|
|
#[derive(Clone, Copy, Debug, Default, PartialEq)]
|
|
struct Pixel {
|
|
mean: [f64; 3],
|
|
m2: [f64; 3],
|
|
count: u32,
|
|
}
|
|
|
|
/// Unbiased sample variance, zero by convention before two samples.
|
|
#[derive(Clone, Copy, Debug, PartialEq)]
|
|
pub struct PixelStatistics {
|
|
pub mean: [f64; 3],
|
|
pub variance: [f64; 3],
|
|
pub count: u32,
|
|
}
|
|
|
|
/// Storage stays private so callers cannot bypass finite/count invariants.
|
|
pub struct FilmAccumulator {
|
|
width: u32,
|
|
height: u32,
|
|
sample_limit: u32,
|
|
pixels: Vec<Pixel>,
|
|
}
|
|
|
|
/// An immutable uniform pass; not an owned or publishable preview image.
|
|
pub struct CompletePass<'a> {
|
|
film: &'a FilmAccumulator,
|
|
samples_per_pixel: u32,
|
|
}
|
|
|
|
fn invalid(message: &'static str) -> JobError {
|
|
JobError::new(ErrorCode::InvalidRequest, message)
|
|
}
|
|
fn limit(message: &'static str) -> JobError {
|
|
JobError::new(ErrorCode::LimitExceeded, message)
|
|
}
|
|
|
|
fn dimensions(width: u32, height: u32, sample_limit: u32) -> Result<usize> {
|
|
if width == 0 || height == 0 || width > MAX_DIMENSION || height > MAX_DIMENSION || sample_limit == 0 || sample_limit > MAX_SAMPLES {
|
|
return Err(invalid("invalid film dimensions or sample limit"));
|
|
}
|
|
let pixels = u64::from(width).checked_mul(u64::from(height)).ok_or_else(|| limit("film dimensions overflow"))?;
|
|
usize::try_from(pixels).ok().filter(|n| *n <= MAX_PIXELS).ok_or_else(|| limit("film pixel limit exceeded"))
|
|
}
|
|
|
|
fn bytes_for_capacity(capacity: usize) -> Result<u64> {
|
|
let bytes = u64::try_from(capacity)
|
|
.ok()
|
|
.and_then(|n| n.checked_mul(std::mem::size_of::<Pixel>() as u64))
|
|
.and_then(|n| n.checked_add(std::mem::size_of::<FilmAccumulator>() as u64))
|
|
.and_then(|n| n.checked_add(std::mem::size_of::<[Pixel; MAX_UPDATE]>() as u64))
|
|
.filter(|n| *n <= MAX_BYTES)
|
|
.ok_or_else(|| limit("film storage limit exceeded"))?;
|
|
Ok(bytes)
|
|
}
|
|
|
|
impl Pixel {
|
|
fn updated(self, rgb: [f64; 3], sample_limit: u32) -> Result<Self> {
|
|
if rgb.iter().any(|c| !c.is_finite() || *c < 0.0) {
|
|
return Err(invalid("film samples must be finite nonnegative linear RGB"));
|
|
}
|
|
let count = self.count.checked_add(1).filter(|n| *n <= sample_limit).ok_or_else(|| limit("film sample limit exceeded"))?;
|
|
let mut result = self;
|
|
for ((mean, m2), value) in result.mean.iter_mut().zip(result.m2.iter_mut()).zip(rgb) {
|
|
let delta = value - *mean;
|
|
*mean += delta / f64::from(count);
|
|
*m2 += delta * (value - *mean);
|
|
if !mean.is_finite() || !m2.is_finite() || *mean < 0.0 || *m2 < 0.0 {
|
|
return Err(invalid("film statistics exceed finite numeric range"));
|
|
}
|
|
}
|
|
result.count = count;
|
|
Ok(result)
|
|
}
|
|
|
|
fn statistics(self) -> PixelStatistics {
|
|
let denominator = f64::from(self.count.saturating_sub(1).max(1));
|
|
PixelStatistics { mean: self.mean, variance: self.m2.map(|m2| m2 / denominator), count: self.count }
|
|
}
|
|
}
|
|
|
|
impl FilmAccumulator {
|
|
/// Required host-admitted storage, including the film object and the bounded
|
|
/// atomic-update stack scratch used while this film is alive. Allocator
|
|
/// bookkeeping is outside this byte contract; actual Vec capacity is checked.
|
|
pub fn required_bytes(width: u32, height: u32, sample_limit: u32) -> Result<u64> {
|
|
bytes_for_capacity(dimensions(width, height, sample_limit)?)
|
|
}
|
|
|
|
/// `admitted_bytes` is an existing host lease amount, not a second pool.
|
|
/// The caller must preserve that lease for this object's entire lifetime.
|
|
pub fn new(
|
|
width: u32,
|
|
height: u32,
|
|
sample_limit: u32,
|
|
admitted_bytes: u64,
|
|
cancel: &CancelToken,
|
|
charge: &mut impl FnMut(u64) -> Result<()>,
|
|
) -> Result<Self> {
|
|
cancel.check()?;
|
|
let count = dimensions(width, height, sample_limit)?;
|
|
let required = bytes_for_capacity(count)?;
|
|
if admitted_bytes < required || admitted_bytes > MAX_BYTES {
|
|
return Err(limit("film is not covered by caller admission"));
|
|
}
|
|
let mut pixels = Vec::new();
|
|
pixels.try_reserve_exact(count).map_err(|_| JobError::new(ErrorCode::AllocationFailed, "could not reserve film storage"))?;
|
|
if bytes_for_capacity(pixels.capacity())? > admitted_bytes {
|
|
return Err(limit("actual film capacity exceeds caller admission"));
|
|
}
|
|
for _ in 0..count {
|
|
cancel.check()?;
|
|
charge(1)?;
|
|
pixels.push(Pixel::default());
|
|
}
|
|
cancel.check()?;
|
|
Ok(Self { width, height, sample_limit, pixels })
|
|
}
|
|
|
|
pub fn dimensions(&self) -> (u32, u32) {
|
|
(self.width, self.height)
|
|
}
|
|
|
|
/// Actual retained capacity plus object and maximum update scratch allowance.
|
|
pub fn allocated_bytes(&self) -> Result<u64> {
|
|
bytes_for_capacity(self.pixels.capacity())
|
|
}
|
|
|
|
/// For diagnostics/variance decisions, not partially published image output.
|
|
pub fn pixel_statistics(&self, index: usize) -> Result<PixelStatistics> {
|
|
self.pixels.get(index).copied().map(Pixel::statistics).ok_or_else(|| invalid("film pixel index out of range"))
|
|
}
|
|
|
|
/// One sample per consecutive pixel, at most MAX_UPDATE. Validate the whole
|
|
/// update before mutation. Validation/commit work is charged up front; failed
|
|
/// work/cancel/input checks leave the film unchanged (budget stays consumed).
|
|
/// After the last cancellation check, bounded commit is the linearization
|
|
/// point: cancellation during commit is observed by the caller before publish.
|
|
pub fn add_range(&mut self, start: usize, samples: &[[f64; 3]], cancel: &CancelToken, charge: &mut impl FnMut(u64) -> Result<()>) -> Result<()> {
|
|
cancel.check()?;
|
|
if samples.is_empty() || samples.len() > MAX_UPDATE {
|
|
return Err(invalid("film update must contain 1..256 samples"));
|
|
}
|
|
let end = start.checked_add(samples.len()).ok_or_else(|| invalid("film update range overflow"))?;
|
|
let pixels = self.pixels.get(start..end).ok_or_else(|| invalid("film update range out of bounds"))?;
|
|
// Fixed bounded stack scratch gives atomic commit without a second heap
|
|
// buffer or recomputation that might fail after earlier pixels mutated.
|
|
let mut staged = [Pixel::default(); MAX_UPDATE];
|
|
for ((pixel, sample), target) in pixels.iter().zip(samples).zip(staged.iter_mut()) {
|
|
cancel.check()?;
|
|
charge(2)?;
|
|
*target = pixel.updated(*sample, self.sample_limit)?;
|
|
}
|
|
cancel.check()?;
|
|
let target = self.pixels.get_mut(start..end).ok_or_else(|| invalid("film update range changed"))?;
|
|
target.copy_from_slice(staged.get(..samples.len()).ok_or_else(|| invalid("film staging range invalid"))?);
|
|
Ok(())
|
|
}
|
|
|
|
/// No allocation and no display transform. Each checked pixel charges one
|
|
/// unit to the same job and checks its cancellation token.
|
|
pub fn complete_pass<'a>(&'a self, cancel: &CancelToken, charge: &mut impl FnMut(u64) -> Result<()>) -> Result<CompletePass<'a>> {
|
|
cancel.check()?;
|
|
let count = self.pixels.first().map(|p| p.count).ok_or_else(|| invalid("film has no pixels"))?;
|
|
if count == 0 {
|
|
return Err(invalid("film has no complete pass"));
|
|
}
|
|
for pixel in &self.pixels {
|
|
cancel.check()?;
|
|
charge(1)?;
|
|
if pixel.count != count {
|
|
return Err(invalid("film pass is incomplete"));
|
|
}
|
|
}
|
|
cancel.check()?;
|
|
Ok(CompletePass { film: self, samples_per_pixel: count })
|
|
}
|
|
}
|
|
|
|
impl CompletePass<'_> {
|
|
pub fn samples_per_pixel(&self) -> u32 {
|
|
self.samples_per_pixel
|
|
}
|
|
|
|
pub fn dimensions(&self) -> (u32, u32) {
|
|
self.film.dimensions()
|
|
}
|
|
|
|
/// Borrowed immutable linear means. Resolving/copying/encoding and its work
|
|
/// accounting/cancellation remain caller-owned; no output buffer is allocated.
|
|
pub fn pixels(&self) -> impl ExactSizeIterator<Item = [f64; 3]> + '_ {
|
|
self.film.pixels.iter().map(|p| p.mean)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
#[path = "film_tests.rs"]
|
|
mod tests;
|