feat(render): add bounded linear film accumulation (#1696) (#1697)

Extract the independent FilmAccumulator from owned donor 3b892eab5e. Keep the existing job cancellation and caller-owned admission/work contracts. PNG resolution, primary camera coverage and progressive consumer wiring remain separate. Add analytic statistics, atomic refusal, allocation/range boundaries and real 4096/1048576-count tests. No kernel, document schema, workflow or capability change.
This commit is contained in:
selune authored and GitHub committed 2026-10-24 08:48:08 +02:00
1 parent ce1c8db7fb
commit 5c0e48ed2b
5 files changed
+433

No files matched your search

+2
View File
@@ -143,6 +143,8 @@ completed drawings publish atomically. The browser still exports synchronously.
## Render foundation
- Bounded linear film accumulation (#1696) supplies caller-admitted mean/variance storage and complete-pass views; actual progressive consumers remain separate. See [the film contract](docs/render-film.md).
- Definition-local visual mapping (#1214) supplies a bounded numerical frame, physical repeat coordinates and a deterministic one-time grain-axis suggestion. It adds no saved record or texture consumer; see [the mapping contract](docs/render-visual-mapping.md).
- Explicit texture normalization (#1218) produces completed float RGBA with
+226
View File
@@ -0,0 +1,226 @@
//! 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};
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;
+191
View File
@@ -0,0 +1,191 @@
use super::*;
fn film(width: u32, height: u32, limit: u32) -> FilmAccumulator {
let bytes = FilmAccumulator::required_bytes(width, height, limit).unwrap();
FilmAccumulator::new(width, height, limit, bytes, &CancelToken::default(), &mut |_| Ok(())).unwrap()
}
fn add(film: &mut FilmAccumulator, start: usize, values: &[[f64; 3]]) {
film.add_range(start, values, &CancelToken::default(), &mut |_| Ok(())).unwrap();
}
#[test]
fn constant_and_alternating_samples_have_analytic_statistics() {
let mut film = film(2, 1, 4);
for value in [0.0, 2.0, 0.0, 2.0] {
add(&mut film, 0, &[[7.0, 3.0, 1.0], [value; 3]]);
}
assert_eq!(film.pixel_statistics(0).unwrap(), PixelStatistics { mean: [7.0, 3.0, 1.0], variance: [0.0; 3], count: 4 });
let statistics = film.pixel_statistics(1).unwrap();
assert_eq!(statistics.mean, [1.0; 3]);
assert_eq!(statistics.variance, [4.0 / 3.0; 3]);
}
#[test]
fn complete_pass_refuses_empty_or_uneven_counts_and_keeps_linear_values() {
let mut film = film(2, 1, 3);
assert!(film.complete_pass(&CancelToken::default(), &mut |_| Ok(())).is_err());
add(&mut film, 0, &[[20.0, 2.0, 0.0]]);
assert!(film.complete_pass(&CancelToken::default(), &mut |_| Ok(())).is_err());
add(&mut film, 1, &[[4.0, 8.0, 16.0]]);
let pass = film.complete_pass(&CancelToken::default(), &mut |_| Ok(())).unwrap();
assert_eq!(pass.samples_per_pixel(), 1);
assert_eq!(pass.dimensions(), (2, 1));
assert_eq!(pass.pixels().collect::<Vec<_>>(), vec![[20.0, 2.0, 0.0], [4.0, 8.0, 16.0]]);
}
#[test]
fn invalid_sample_at_end_leaves_entire_update_unchanged() {
for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -1.0] {
let mut film = film(2, 1, 3);
add(&mut film, 0, &[[1.0; 3], [2.0; 3]]);
let before = film.pixels.clone();
assert_eq!(film.add_range(0, &[[3.0; 3], [bad; 3]], &CancelToken::default(), &mut |_| Ok(())).unwrap_err().code, ErrorCode::InvalidRequest);
assert_eq!(film.pixels, before);
}
}
#[test]
fn sample_limit_and_numeric_overflow_refuse_atomically() {
let mut limited = film(2, 1, 1);
add(&mut limited, 1, &[[1.0; 3]]);
let before = limited.pixels.clone();
assert_eq!(limited.add_range(0, &[[1.0; 3]; 2], &CancelToken::default(), &mut |_| Ok(())).unwrap_err().code, ErrorCode::LimitExceeded);
assert_eq!(limited.pixels, before);
let mut extreme = film(2, 1, 3);
add(&mut extreme, 0, &[[1.0; 3], [f64::MAX; 3]]);
let before = extreme.pixels.clone();
assert!(extreme.add_range(0, &[[2.0; 3], [0.0; 3]], &CancelToken::default(), &mut |_| Ok(())).is_err());
assert_eq!(extreme.pixels, before);
}
#[test]
fn dimensions_bytes_and_actual_capacity_are_checked() {
for (width, height, samples) in [(0, 1, 1), (1, 0, 1), (u32::MAX, u32::MAX, 1), (1, 1, 0), (1, 1, MAX_SAMPLES + 1)] {
assert!(FilmAccumulator::required_bytes(width, height, samples).is_err());
}
assert!(FilmAccumulator::required_bytes(MAX_DIMENSION, MAX_DIMENSION, 1).is_err());
assert!(bytes_for_capacity(usize::MAX).is_err());
let bytes = FilmAccumulator::required_bytes(2, 2, 1).unwrap();
assert!(FilmAccumulator::new(2, 2, 1, bytes - 1, &CancelToken::default(), &mut |_| Ok(())).is_err());
let film = film(2, 2, 1);
assert!(film.allocated_bytes().unwrap() <= bytes);
assert_eq!(film.allocated_bytes().unwrap(), bytes_for_capacity(film.pixels.capacity()).unwrap());
assert!(film.allocated_bytes().unwrap() >= (std::mem::size_of::<Pixel>() * (4 + MAX_UPDATE)) as u64);
}
#[test]
fn invalid_ranges_and_oversized_updates_preserve_state() {
let mut film = film(2, 1, 1);
for (start, values) in [(0, Vec::new()), (usize::MAX, vec![[1.0; 3]]), (2, vec![[1.0; 3]]), (0, vec![[1.0; 3]; MAX_UPDATE + 1])] {
assert!(film.add_range(start, &values, &CancelToken::default(), &mut |_| Ok(())).is_err());
assert!(film.pixels.iter().all(|p| *p == Pixel::default()));
}
assert!(film.pixel_statistics(2).is_err());
}
#[test]
fn incremental_partitions_preserve_bitwise_results_in_sample_order() {
let mut whole = film(4, 1, 3);
let mut partitioned = film(4, 1, 3);
for values in [
[[1.0; 3], [1e12; 3], [0.25; 3], [4.0; 3]],
[[2.0; 3], [1e12 + 1.0; 3], [0.5; 3], [2.0; 3]],
[[4.0; 3], [1e12 - 1.0; 3], [0.75; 3], [0.0; 3]],
] {
add(&mut whole, 0, &values);
add(&mut partitioned, 0, &values[..1]);
add(&mut partitioned, 1, &values[1..3]);
add(&mut partitioned, 3, &values[3..]);
}
assert_eq!(whole.pixels, partitioned.pixels);
assert_eq!(whole.pixel_statistics(1).unwrap().variance, [1.0; 3]);
}
#[test]
fn cancellation_and_work_failure_preserve_all_pixels() {
let mut film = film(2, 1, 3);
let cancel = CancelToken::default();
let observer = cancel.clone();
assert_eq!(
film.add_range(0, &[[1.0; 3]; 2], &cancel, &mut |_| {
observer.cancel();
Ok(())
})
.unwrap_err()
.code,
ErrorCode::Cancelled
);
assert!(film.pixels.iter().all(|p| *p == Pixel::default()));
let mut charged = 0;
assert_eq!(
film.add_range(0, &[[1.0; 3]; 2], &CancelToken::default(), &mut |units| {
charged += units;
if charged > 2 { Err(limit("job work exhausted")) } else { Ok(()) }
})
.unwrap_err()
.code,
ErrorCode::LimitExceeded
);
assert_eq!(charged, 4);
assert!(film.pixels.iter().all(|p| *p == Pixel::default()));
}
#[test]
fn construction_and_complete_pass_share_caller_work_and_cancel() {
let bytes = FilmAccumulator::required_bytes(2, 1, 1).unwrap();
let cancel = CancelToken::default();
cancel.cancel();
assert!(FilmAccumulator::new(2, 1, 1, bytes, &cancel, &mut |_| panic!("cancelled construction charged work")).is_err());
let mut charged = 0;
let mut film = FilmAccumulator::new(2, 1, 1, bytes, &CancelToken::default(), &mut |n| {
charged += n;
Ok(())
})
.unwrap();
assert_eq!(charged, 2);
add(&mut film, 0, &[[1.0; 3]; 2]);
assert!(film.complete_pass(&CancelToken::default(), &mut |_| Err(limit("job exhausted"))).is_err());
let pass = film
.complete_pass(&CancelToken::default(), &mut |n| {
charged += n;
Ok(())
})
.unwrap();
assert_eq!(charged, 4);
assert_eq!(pass.samples_per_pixel(), 1);
}
#[test]
fn sample_counts_reach_4096_and_the_declared_cap_without_truncation() {
for samples in [4096, MAX_SAMPLES] {
let mut film = film(1, 1, samples);
let cancel = CancelToken::default();
let mut charged = 0u64;
for _ in 0..samples {
film.add_range(0, &[[7.0, 3.0, 1.0]], &cancel, &mut |n| {
charged += n;
Ok(())
})
.unwrap();
}
assert_eq!(charged, u64::from(samples) * 2);
let expected = PixelStatistics { mean: [7.0, 3.0, 1.0], variance: [0.0; 3], count: samples };
assert_eq!(film.pixel_statistics(0).unwrap(), expected);
assert_eq!(film.complete_pass(&cancel, &mut |_| Ok(())).unwrap().samples_per_pixel(), samples);
assert_eq!(film.add_range(0, &[[1.0; 3]], &cancel, &mut |_| Ok(())).unwrap_err().code, ErrorCode::LimitExceeded);
assert_eq!(film.pixel_statistics(0).unwrap(), expected);
}
}
#[test]
fn construction_stops_on_exhausted_caller_work() {
let bytes = FilmAccumulator::required_bytes(4, 1, 1).unwrap();
let mut charged = 0u64;
let result = FilmAccumulator::new(4, 1, 1, bytes, &CancelToken::default(), &mut |n| {
charged += n;
if charged > 2 { Err(limit("existing job budget exhausted")) } else { Ok(()) }
});
assert!(matches!(result, Err(JobError { code: ErrorCode::LimitExceeded, .. })));
assert_eq!(charged, 3);
}
+1
View File
@@ -10,6 +10,7 @@ mod backend;
mod camera;
pub mod clear_coat;
mod curve_display;
pub mod film;
mod gif;
pub mod job;
pub mod lighting;
+13
View File
@@ -0,0 +1,13 @@
# Bounded linear film accumulation
`solidcraft_render::film` is the independent accumulator for #1696. It is extracted from the original renderer donor at `3b892eab`; it does not install a CPU integrator, PNG resolver, camera coverage buffer or progressive UI.
Samples are nonnegative finite linear RGB. Per-pixel running means and unbiased sample variance remain linear: no exposure, denoising, tone mapping or display conversion occurs here. A later consumer applies its output transform exactly once after resolving a complete pass. Sample order is significant; splitting the same ordered samples into bounded contiguous calls preserves identical results, while arbitrary floating-point reordering is not promised.
The caller reserves `required_bytes` in the existing image-job lease and retains it throughout the film lifetime. Allocation is fallible and actual capacity is checked. Dimensions, pixel count, sample count, storage and update sizes are bounded. This module creates no second pool, thread, cache or cancellation token. Initialization and updates debit the same caller-provided cumulative work budget.
`add_range` stages at most 256 pixel updates before committing. Invalid input, range/count overflow, exhausted work or cancellation before the bounded commit leaves prior pixels unchanged; consumed work is not refunded. Cancellation after commit must still be checked by the consumer before publication.
`complete_pass` refuses empty or uneven sample counts and returns an immutable borrowed view, not an owned or publishable image. The caller must separately admit any output snapshot and enforce its existing generation/cancellation publication lock. Camera background coverage and actual progressive image delivery remain separate integration work.
No design data is newly saved, so no format descriptor is introduced. No extra dependency, asset, geometry operation or renderer capability is advertised.