SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
render: add opaque CPU sampling and bounded mip chains (#1459)
selune845f4913cf1e
diff --git a/crates/render/src/lib.rs b/crates/render/src/lib.rsindex 9a1af147d1..126ecf9c55 100644--- a/crates/render/src/lib.rs+++ b/crates/render/src/lib.rs@@ -16,6 +16,7 @@ pub mod surface;pub mod texture_input;pub mod texture_interpolation;pub mod texture_lod;+pub mod texture_sampling;pub use backend::{Availability, BackendDescriptor, BackendId, ExecutorDescriptor, ExecutorId, MAX_RENDER_ID_BYTES, RenderFeature, RenderFormat, RenderLimits,diff --git a/crates/render/src/texture_sampling.rs b/crates/render/src/texture_sampling.rsnew file mode 100644index 0000000000..72efd4616f--- /dev/null+++ b/crates/render/src/texture_sampling.rs@@ -0,0 +1,95 @@+//! Allocation-free periodic reference sampling of already normalized, linear RGBA.+//! No decoding, transfer function, normal interpretation or renderer capability is implied.++use crate::texture_input::MAX_TEXTURE_EDGE;++pub mod mips;++/// CPU reference bound: beyond this, fractional repeat precision is deliberately refused.+/// This is not a GPU/f32 coordinate precision guarantee.+pub const MAX_REPEAT_COORDINATE: f64 = 1_048_576.0;++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum SamplingError {+ Dimensions,+ Length,+ Values,+ Coordinates,+}+impl std::fmt::Display for SamplingError {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.write_str(match self {+ Self::Dimensions => "texture dimensions must be positive and at most 2048",+ Self::Length => "texture storage must be exactly width * height * 4 floats",+ Self::Values => "normalized texture channels must be finite and in [0, 1]",+ Self::Coordinates => "repeat coordinates must be finite and within the CPU reference bound",+ })+ }+}+impl std::error::Error for SamplingError {}++/// Validated borrowed normalized RGBA. Construction scans the bounded input once;+/// sampling does constant work, without allocations. The caller retains ownership.+#[derive(Clone, Copy, Debug)]+pub struct TextureView<'a> {+ rgba: &'a [f32],+ width: usize,+ height: usize,+}+impl<'a> TextureView<'a> {+ pub fn new(rgba: &'a [f32], dimensions: [u32; 2]) -> Result<Self, SamplingError> {+ let [width, height] = dimensions;+ if width == 0 || height == 0 || width > MAX_TEXTURE_EDGE || height > MAX_TEXTURE_EDGE {+ return Err(SamplingError::Dimensions);+ }+ let width = usize::try_from(width).map_err(|_| SamplingError::Dimensions)?;+ let height = usize::try_from(height).map_err(|_| SamplingError::Dimensions)?;+ let length = width.checked_mul(height).and_then(|n| n.checked_mul(4)).ok_or(SamplingError::Length)?;+ if rgba.len() != length {+ return Err(SamplingError::Length);+ }+ if rgba.iter().any(|v| !v.is_finite() || !(0.0..=1.0).contains(v)) {+ return Err(SamplingError::Values);+ }+ Ok(Self { rgba, width, height })+ }++ /// Bilinear level-zero RGB for an explicitly opaque consumer. Alpha is validated+ /// but deliberately ignored (even zero-alpha RGB participates). This is NOT+ /// transparent compositing or premultiplied-alpha filtering.+ /// UV (0,0) is the top-left image boundary, and v increases downwards. Texel+ /// centers are ((x+.5)/width, (y+.5)/height). Both axes repeat, without a Y flip.+ /// Inputs must already be linear color or linear data; no transfer is applied.+ pub fn sample_repeat_opaque(&self, uv: [f64; 2]) -> Result<[f64; 3], SamplingError> {+ if uv.iter().any(|v| !v.is_finite() || v.abs() > MAX_REPEAT_COORDINATE) {+ return Err(SamplingError::Coordinates);+ }+ let [u, v] = uv;+ let (x0, x1, tx) = axis(u, self.width);+ let (y0, y1, ty) = axis(v, self.height);+ let mut rgb = [0.0; 3];+ for (channel, output) in rgb.iter_mut().enumerate() {+ let a = self.channel(x0, y0, channel)?;+ let b = self.channel(x1, y0, channel)?;+ let c = self.channel(x0, y1, channel)?;+ let d = self.channel(x1, y1, channel)?;+ *output = (a * (1.0 - tx) + b * tx) * (1.0 - ty) + (c * (1.0 - tx) + d * tx) * ty;+ }+ Ok(rgb)+ }++ fn channel(&self, x: usize, y: usize, channel: usize) -> Result<f64, SamplingError> {+ self.rgba.get((y * self.width + x) * 4 + channel).copied().map(f64::from).ok_or(SamplingError::Length)+ }+}++fn axis(coordinate: f64, size: usize) -> (usize, usize, f64) {+ // Reduce before scaling: no huge-coordinate multiplication or unbounded index.+ let position = coordinate.rem_euclid(1.0) * size as f64 - 0.5;+ let lower = position.floor();+ let first = (lower as i64).rem_euclid(size as i64) as usize;+ (first, (first + 1) % size, position - lower)+}++#[cfg(test)]+mod tests;diff --git a/crates/render/src/texture_sampling/mips.rs b/crates/render/src/texture_sampling/mips.rsnew file mode 100644index 0000000000..c0bffec106--- /dev/null+++ b/crates/render/src/texture_sampling/mips.rs@@ -0,0 +1,191 @@+//! Bounded linear area-filtered mip preparation for opaque CPU reference sampling.+//! Call from the existing preparation host; row cancellation does not yield a browser event loop.+use super::{SamplingError, TextureView};++/// Derived pixel storage only, excluding the borrowed base and small level metadata.+pub const MAX_MIP_TAIL_BYTES: usize = 32 * 1024 * 1024;+/// Include this recipe in preparation/cache identity, alongside source/role/policies.+/// V1 means floor-halved linear area filtering, opaque RGB and generated alpha=1.+pub const MIP_RECIPE_ID: &str = "solidcraft.opaque-linear-area-mips/1";+const MAX_LEVELS: usize = 12;++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum MipError {+ Budget,+ Allocation,+ Cancelled,+ Lod,+ Sampling(SamplingError),+}+impl std::fmt::Display for MipError {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ match self {+ Self::Budget => f.write_str("mip tail storage exceeds the admitted budget"),+ Self::Allocation => f.write_str("cannot allocate mip tail storage"),+ Self::Cancelled => f.write_str("mip preparation cancelled"),+ Self::Lod => f.write_str("LOD must be finite and within the prepared level range"),+ Self::Sampling(e) => e.fmt(f),+ }+ }+}+impl std::error::Error for MipError {}+impl From<SamplingError> for MipError {+ fn from(value: SamplingError) -> Self {+ Self::Sampling(value)+ }+}++struct Level {+ rgba: Vec<f32>,+ width: usize,+ height: usize,+}+impl Level {+ fn view(&self) -> TextureView<'_> {+ // Private levels are created only from admitted pixels and convex averages.+ // Reuse validation rather than rescan every stored pixel on each sample.+ TextureView { rgba: &self.rgba, width: self.width, height: self.height }+ }+}++/// Immutable derived levels; level zero borrows the admitted base without copying it.+/// Generated levels have alpha=1, matching the explicitly opaque RGB sampler.+pub struct MipChain<'a> {+ base: TextureView<'a>,+ tail: Vec<Level>,+ tail_bytes: usize,+ retained_bytes: usize,+}+impl<'a> MipChain<'a> {+ /// Generate all floor-halved levels through 1x1, or return no chain on failure.+ /// `max_tail_bytes` bounds derived pixel capacity, not total process memory.+ /// Preparation is synchronous and must run in the caller-owned preparation host.+ pub fn prepare(base: TextureView<'a>, max_tail_bytes: usize, cancelled: impl Fn() -> bool) -> Result<Self, MipError> {+ if max_tail_bytes > MAX_MIP_TAIL_BYTES {+ return Err(MipError::Budget);+ }+ check_cancel(&cancelled)?;+ let required = required_bytes(base.width, base.height)?;+ if required > max_tail_bytes {+ return Err(MipError::Budget);+ }+ let mut chain = Self { base, tail: Vec::new(), tail_bytes: 0, retained_bytes: size_of::<Self>() };+ chain.tail.try_reserve_exact(MAX_LEVELS - 1).map_err(|_| MipError::Allocation)?;+ let metadata_bytes =+ chain.tail.capacity().checked_mul(size_of::<Level>()).and_then(|n| n.checked_add(size_of::<Self>())).ok_or(MipError::Budget)?;+ chain.retained_bytes = metadata_bytes;+ while chain.level_count() < MAX_LEVELS {+ check_cancel(&cancelled)?;+ let source = chain.level(chain.level_count() - 1).ok_or(MipError::Budget)?;+ if source.width == 1 && source.height == 1 {+ break;+ }+ let width = (source.width / 2).max(1);+ let height = (source.height / 2).max(1);+ let length = width.checked_mul(height).and_then(|n| n.checked_mul(4)).ok_or(MipError::Budget)?;+ let mut rgba = Vec::new();+ rgba.try_reserve_exact(length).map_err(|_| MipError::Allocation)?;+ let bytes = rgba.capacity().checked_mul(size_of::<f32>()).ok_or(MipError::Budget)?;+ let next_bytes = chain.tail_bytes.checked_add(bytes).ok_or(MipError::Budget)?;+ if next_bytes > max_tail_bytes {+ return Err(MipError::Budget);+ }+ let retained_bytes = metadata_bytes.checked_add(next_bytes).ok_or(MipError::Budget)?;+ for y in 0..height {+ check_cancel(&cancelled)?;+ for x in 0..width {+ let rgb = area_average(source, x, y, width, height)?;+ rgba.extend(rgb.map(|v| v as f32));+ rgba.push(1.0);+ }+ }+ check_cancel(&cancelled)?;+ chain.tail.push(Level { rgba, width, height });+ chain.tail_bytes = next_bytes;+ chain.retained_bytes = retained_bytes;+ }+ check_cancel(&cancelled)?;+ Ok(chain)+ }++ pub fn level_count(&self) -> usize {+ self.tail.len() + 1+ }+ pub fn tail_bytes(&self) -> usize {+ self.tail_bytes+ }+ /// Retained pixel/level Vec capacities plus the chain value. Charge to the+ /// existing host pool; borrowed base ownership and allocator overhead are separate.+ pub fn retained_bytes(&self) -> usize {+ self.retained_bytes+ }+ /// Borrow a prepared level without allocation or another full-image admission scan.+ pub fn level(&self, index: usize) -> Option<TextureView<'_>> {+ if index == 0 { Some(self.base) } else { self.tail.get(index - 1).map(Level::view) }+ }+ pub fn dimensions(&self, index: usize) -> Option<[u32; 2]> {+ self.level(index).map(|v| [v.width as u32, v.height as u32])+ }++ /// Explicit LOD only: bilinear within each level, linear between adjacent levels.+ /// This does not choose a footprint, provide anisotropy or certify GPU parity.+ /// Out-of-range LOD refuses rather than silently clamping to a different policy.+ pub fn sample_repeat_lod_opaque(&self, uv: [f64; 2], lod: f64) -> Result<[f64; 3], MipError> {+ let last = self.level_count() - 1;+ if !lod.is_finite() || lod < 0.0 || lod > last as f64 {+ return Err(MipError::Lod);+ }+ let low = lod.floor() as usize;+ let high = (low + 1).min(last);+ let t = lod - low as f64;+ let a = self.level(low).ok_or(MipError::Lod)?.sample_repeat_opaque(uv)?;+ let b = self.level(high).ok_or(MipError::Lod)?.sample_repeat_opaque(uv)?;+ let mut rgb = [0.0; 3];+ for ((output, a), b) in rgb.iter_mut().zip(a).zip(b) {+ *output = a * (1.0 - t) + b * t;+ }+ Ok(rgb)+ }+}++fn check_cancel(cancelled: &impl Fn() -> bool) -> Result<(), MipError> {+ if cancelled() { Err(MipError::Cancelled) } else { Ok(()) }+}++fn required_bytes(mut width: usize, mut height: usize) -> Result<usize, MipError> {+ let mut bytes = 0usize;+ for _ in 1..MAX_LEVELS {+ if width == 1 && height == 1 {+ return Ok(bytes);+ }+ width = (width / 2).max(1);+ height = (height / 2).max(1);+ let level_bytes = width.checked_mul(height).and_then(|n| n.checked_mul(4 * size_of::<f32>())).ok_or(MipError::Budget)?;+ bytes = bytes.checked_add(level_bytes).ok_or(MipError::Budget)?;+ }+ if width == 1 && height == 1 { Ok(bytes) } else { Err(MipError::Budget) }+}++fn area_average(source: TextureView<'_>, x: usize, y: usize, width: usize, height: usize) -> Result<[f64; 3], MipError> {+ // Integer overlap numerators avoid dropping the final row/column at odd sizes.+ // All factors are bounded by the validated 2048 edge; at most 3x3 source cells.+ let x_start = x * source.width;+ let x_end = (x + 1) * source.width;+ let y_start = y * source.height;+ let y_end = (y + 1) * source.height;+ let mut rgb = [0.0; 3];+ for sy in y_start / height..y_end.div_ceil(height) {+ let wy = ((sy + 1) * height).min(y_end) - (sy * height).max(y_start);+ for sx in x_start / width..x_end.div_ceil(width) {+ let wx = ((sx + 1) * width).min(x_end) - (sx * width).max(x_start);+ let weight = wx as f64 * wy as f64 / (source.width as f64 * source.height as f64);+ for (channel, output) in rgb.iter_mut().enumerate() {+ *output += source.channel(sx, sy, channel)? * weight;+ }+ }+ }+ Ok(rgb)+}++#[cfg(test)]+mod tests;diff --git a/crates/render/src/texture_sampling/mips/tests.rs b/crates/render/src/texture_sampling/mips/tests.rsnew file mode 100644index 0000000000..417f228a3f--- /dev/null+++ b/crates/render/src/texture_sampling/mips/tests.rs@@ -0,0 +1,115 @@+use super::*;+use std::cell::Cell;++fn close(actual: [f64; 3], expected: [f64; 3]) {+ for (a, b) in actual.into_iter().zip(expected) {+ assert!((a - b).abs() < 1e-7, "{actual:?} != {expected:?}");+ }+}++#[test]+fn linear_checkerboard_mean_and_fractional_lod() {+ let pixels = [0., 0., 0., 0., 1., 1., 1., 1., 1., 1., 1., 1., 0., 0., 0., 0.];+ let base = TextureView::new(&pixels, [2, 2]).unwrap();+ let chain = MipChain::prepare(base, 16, || false).unwrap();+ assert_eq!(chain.level_count(), 2);+ assert_eq!(chain.tail_bytes(), 16);+ assert_eq!(chain.retained_bytes(), chain.tail_bytes() + chain.tail.capacity() * size_of::<Level>() + size_of::<MipChain<'_>>());+ assert_eq!(MIP_RECIPE_ID, "solidcraft.opaque-linear-area-mips/1");+ close(chain.sample_repeat_lod_opaque([0.25, 0.25], 0.).unwrap(), [0.; 3]);+ close(chain.sample_repeat_lod_opaque([0.25, 0.25], 1.).unwrap(), [0.5; 3]);+ close(chain.sample_repeat_lod_opaque([0.25, 0.25], 0.25).unwrap(), [0.125; 3]);+ close(chain.sample_repeat_lod_opaque([0.25, 0.25], 0.5).unwrap(), [0.25; 3]);+}++#[test]+fn odd_edges_contribute_by_area_instead_of_being_dropped_or_overweighted() {+ // Five pixels reduce to two equal-width cells: [0,0,0] and [0,0,1].+ // The middle pixel straddles the boundary, the last pixel weighs 1/2.5.+ let mut pixels = [0., 0., 0., 1.].repeat(5);+ pixels[16] = 1.;+ let chain = MipChain::prepare(TextureView::new(&pixels, [5, 1]).unwrap(), 48, || false).unwrap();+ assert_eq!(chain.dimensions(1), Some([2, 1]));+ close(chain.level(1).unwrap().sample_repeat_opaque([0.75, 0.5]).unwrap(), [0.4, 0., 0.]);+ close(chain.sample_repeat_lod_opaque([0., 0.], 2.).unwrap(), [0.2, 0., 0.]);+}++#[test]+fn rectangular_odd_pyramid_preserves_independent_mean() {+ let mut pixels = Vec::new();+ for i in 0..15 {+ pixels.extend([i as f32 / 16., 0.25, (14 - i) as f32 / 16., (i % 2) as f32]);+ }+ let chain = MipChain::prepare(TextureView::new(&pixels, [5, 3]).unwrap(), 48, || false).unwrap();+ assert_eq!(chain.level_count(), 3);+ assert_eq!(chain.dimensions(0), Some([5, 3]));+ assert_eq!(chain.dimensions(1), Some([2, 1]));+ assert_eq!(chain.dimensions(2), Some([1, 1]));+ assert_eq!(chain.dimensions(usize::MAX), None);+ close(chain.sample_repeat_lod_opaque([-9.5, 12.], 2.).unwrap(), [7. / 16., 0.25, 7. / 16.]);+}++#[test]+fn single_texel_borrows_base_and_needs_no_pixel_budget() {+ let pixels = [0.25, 0.5, 0.75, 0.];+ let chain = MipChain::prepare(TextureView::new(&pixels, [1, 1]).unwrap(), 0, || false).unwrap();+ assert_eq!(chain.level_count(), 1);+ assert_eq!(chain.tail_bytes(), 0);+ assert!(std::ptr::eq(chain.level(0).unwrap().rgba.as_ptr(), pixels.as_ptr()));+ close(chain.sample_repeat_lod_opaque([-0.1, 0.7], 0.).unwrap(), [0.25, 0.5, 0.75]);+}++#[test]+fn constant_images_and_single_axes_are_invariant_at_all_lods() {+ for dimensions in [[1, 7], [7, 1], [7, 5]] {+ let pixels = [0.25, 0.5, 0.75, 0.].repeat((dimensions[0] * dimensions[1]) as usize);+ let chain = MipChain::prepare(TextureView::new(&pixels, dimensions).unwrap(), MAX_MIP_TAIL_BYTES, || false).unwrap();+ for quarter in 0..=(chain.level_count() - 1) * 4 {+ close(chain.sample_repeat_lod_opaque([-2.34, 1.92], quarter as f64 / 4.).unwrap(), [0.25, 0.5, 0.75]);+ }+ }+}++#[test]+fn hostile_lod_and_uv_refuse_without_changing_the_chain() {+ let pixels = [0., 0., 0., 1.].repeat(4);+ let chain = MipChain::prepare(TextureView::new(&pixels, [2, 2]).unwrap(), 16, || false).unwrap();+ for lod in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, -0.001, 1.001, f64::MAX] {+ assert_eq!(chain.sample_repeat_lod_opaque([0., 0.], lod), Err(MipError::Lod));+ }+ assert_eq!(chain.sample_repeat_lod_opaque([f64::NAN, 0.], 0.5), Err(MipError::Sampling(SamplingError::Coordinates)));+ close(chain.sample_repeat_lod_opaque([0.25, 0.25], 0.).unwrap(), [0.; 3]);+}++#[test]+fn exact_budget_and_global_cap_are_admitted_before_work() {+ let pixels = [0., 0., 0., 1.].repeat(4);+ let base = TextureView::new(&pixels, [2, 2]).unwrap();+ assert!(matches!(MipChain::prepare(base, 15, || false), Err(MipError::Budget)));+ assert!(MipChain::prepare(base, 16, || false).is_ok());+ assert!(matches!(MipChain::prepare(base, MAX_MIP_TAIL_BYTES + 1, || false), Err(MipError::Budget)));+ assert!(matches!(MipChain::prepare(base, usize::MAX, || false), Err(MipError::Budget)));+ assert_eq!(required_bytes(2048, 2048).unwrap(), 22_369_616);+ assert!(required_bytes(2048, 2048).unwrap() < MAX_MIP_TAIL_BYTES);+}++#[test]+fn cancellation_before_during_and_after_preparation_never_returns_a_partial_chain() {+ let pixels = [0.25, 0.5, 0.75, 0.].repeat(64);+ let base = TextureView::new(&pixels, [8, 8]).unwrap();+ let successful_calls = Cell::new(0);+ MipChain::prepare(base, MAX_MIP_TAIL_BYTES, || {+ successful_calls.set(successful_calls.get() + 1);+ false+ })+ .unwrap();+ for stop in 1..=successful_calls.get() {+ let calls = Cell::new(0);+ let result = MipChain::prepare(base, MAX_MIP_TAIL_BYTES, || {+ calls.set(calls.get() + 1);+ calls.get() == stop+ });+ assert!(matches!(result, Err(MipError::Cancelled)));+ }+ assert!(MipChain::prepare(base, MAX_MIP_TAIL_BYTES, || false).is_ok());+}diff --git a/crates/render/src/texture_sampling/tests.rs b/crates/render/src/texture_sampling/tests.rsnew file mode 100644index 0000000000..93040acf22--- /dev/null+++ b/crates/render/src/texture_sampling/tests.rs@@ -0,0 +1,94 @@+use super::*;++const PIXELS: [f32; 16] = [1., 0., 0., 0., 0., 1., 0., 1., 0., 0., 1., 1., 1., 1., 1., 1.];++fn close(actual: [f64; 3], expected: [f64; 3]) {+ for (a, b) in actual.into_iter().zip(expected) {+ assert!((a - b).abs() < 1e-9, "{actual:?} != {expected:?}");+ }+}++#[test]+fn centers_orientation_and_explicit_opaque_alpha() {+ let view = TextureView::new(&PIXELS, [2, 2]).unwrap();+ for (uv, rgb) in [([0.25, 0.25], [1., 0., 0.]), ([0.75, 0.25], [0., 1., 0.]), ([0.25, 0.75], [0., 0., 1.]), ([0.75, 0.75], [1., 1., 1.])] {+ close(view.sample_repeat_opaque(uv).unwrap(), rgb);+ }+ close(view.sample_repeat_opaque([0.5, 0.5]).unwrap(), [0.5; 3]);+ close(view.sample_repeat_opaque([0.5, 0.25]).unwrap(), [0.5, 0.5, 0.]);+ close(view.sample_repeat_opaque([0.375, 0.625]).unwrap(), [0.375, 0.25, 0.75]);+}++#[test]+fn linear_black_white_mixing_is_not_encoded_srgb_averaging() {+ let pixels = [0., 0., 0., 1., 1., 1., 1., 1.];+ let view = TextureView::new(&pixels, [2, 1]).unwrap();+ // Linear 0.5, which would encode to about sRGB 0.735, not encoded 0.5.+ close(view.sample_repeat_opaque([0.5, 0.5]).unwrap(), [0.5; 3]);+}++#[test]+fn signed_repeats_and_both_periodic_seams() {+ let view = TextureView::new(&PIXELS, [2, 2]).unwrap();+ for uv in [[0., 0.], [1., 1.], [-1., -1.], [MAX_REPEAT_COORDINATE, -MAX_REPEAT_COORDINATE]] {+ close(view.sample_repeat_opaque(uv).unwrap(), [0.5; 3]);+ }+ close(view.sample_repeat_opaque([-0.75, -0.25]).unwrap(), [0., 0., 1.]);+ for uv in [[0.13, 0.92], [0., 0.25], [0.75, 0.]] {+ close(view.sample_repeat_opaque(uv).unwrap(), view.sample_repeat_opaque([uv[0] - 7., uv[1] + 9.]).unwrap());+ }+ for epsilon in [-1e-12, 0., 1e-12] {+ close(view.sample_repeat_opaque([epsilon, 0.25]).unwrap(), [0.5, 0.5, 0.]);+ close(view.sample_repeat_opaque([0.25, epsilon]).unwrap(), [0.5, 0., 0.5]);+ }+}++#[test]+fn constant_and_single_texel_invariance() {+ for dimensions in [[1, 1], [1, 3], [3, 1], [3, 5]] {+ let pixels = [0.25, 0.5, 0.75, 0.].repeat((dimensions[0] * dimensions[1]) as usize);+ let view = TextureView::new(&pixels, dimensions).unwrap();+ for uv in [[0., 0.], [-12.125, 3.25], [1., 1.], [MAX_REPEAT_COORDINATE - 0.125, 0.5]] {+ close(view.sample_repeat_opaque(uv).unwrap(), [0.25, 0.5, 0.75]);+ }+ }+}++#[test]+fn rejects_hostile_storage_and_channels() {+ for dimensions in [[0, 1], [1, 0], [MAX_TEXTURE_EDGE + 1, 1], [u32::MAX, u32::MAX]] {+ assert_eq!(TextureView::new(&[], dimensions).unwrap_err(), SamplingError::Dimensions);+ }+ for pixels in [&[][..], &[0.; 3][..], &[0.; 5][..]] {+ assert_eq!(TextureView::new(pixels, [1, 1]).unwrap_err(), SamplingError::Length);+ }+ for invalid in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, -0.01, 1.01] {+ for channel in 0..4 {+ let mut pixels = [0.; 4];+ pixels[channel] = invalid;+ assert_eq!(TextureView::new(&pixels, [1, 1]).unwrap_err(), SamplingError::Values);+ }+ }+}++#[test]+fn rejects_nonfinite_and_extreme_coordinates() {+ let view = TextureView::new(&PIXELS, [2, 2]).unwrap();+ for invalid in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, f64::MAX, MAX_REPEAT_COORDINATE + 0.001, -MAX_REPEAT_COORDINATE - 0.001] {+ for uv in [[invalid, 0.], [0., invalid]] {+ assert_eq!(view.sample_repeat_opaque(uv), Err(SamplingError::Coordinates));+ }+ }+}++#[test]+fn reference_bound_retains_fractional_centers_and_maximum_edge() {+ let view = TextureView::new(&PIXELS, [2, 2]).unwrap();+ close(view.sample_repeat_opaque([MAX_REPEAT_COORDINATE - 0.75, -MAX_REPEAT_COORDINATE + 0.25]).unwrap(), [1., 0., 0.]);+ let mut pixels = [0., 0., 0., 1.].repeat(MAX_TEXTURE_EDGE as usize);+ pixels[0] = 1.;+ let view = TextureView::new(&pixels, [MAX_TEXTURE_EDGE, 1]).unwrap();+ let half_texel = 0.5 / f64::from(MAX_TEXTURE_EDGE);+ close(view.sample_repeat_opaque([half_texel, 0.]).unwrap(), [1., 0., 0.]);+ close(view.sample_repeat_opaque([half_texel - MAX_REPEAT_COORDINATE, 0.]).unwrap(), [1., 0., 0.]);+}diff --git a/docs/render-texture-mips.md b/docs/render-texture-mips.mdnew file mode 100644index 0000000000..33dc6378b2--- /dev/null+++ b/docs/render-texture-mips.md@@ -0,0 +1,69 @@+# Opaque CPU mip reference++The numerical follow-up #1332 reuses the reference sampler in #1327 through+`solidcraft_render::texture_sampling::mips`. It adds no installed renderer,+resource storage, normalization, file decoder, worker, cache or GPU capability.+The visible wood consumer remains separate work.++`MipChain::prepare(base, max_tail_bytes, cancelled)` borrows a validated+`TextureView` as level zero. Each following level has dimensions+`[max(1, width / 2), max(1, height / 2)]` until 1x1, at most 12 levels including+the base. All derived levels are immutable and allocated through fallible reserve.+The base is not copied. `level` borrows a prepared view without another whole-image+admission scan; `dimensions`, `level_count` and `tail_bytes` expose its accounting.++The caller chooses a derived pixel capacity budget no larger than 32 MiB.+The complete required pixel size is checked before work, and retained Vec capacity+is checked before filling each level. A maximum admitted 2048x2048 base requires+22,369,616 derived pixel bytes. The borrowed base (up to 64 MiB), small bounded+level metadata, allocator overhead and other normalization/preparation allocations+are separate. This is not a total process-memory bound. The existing resource host+must count both the retained base lease and derived levels against its cache budget.+`retained_bytes()` includes the actual pixel and level-vector capacities and the+chain value. The host must also budget allocator overhead conservatively; this+helper's cap is not an additional allowance outside #1237's shared preparation pool.+Keep the borrowed base alive through its existing prepared-result/lease.++`MIP_RECIPE_ID` is `solidcraft.opaque-linear-area-mips/1`: include it in preparation+and cache identity alongside source digest, role, normalization policies and host+generation. This recipe fixes floor-halving, linear area filtering and opaque alpha.+It must not alias level-zero-only output, a normal filter or another alpha policy.+Future changes to those semantics need a new recipe identity.++Every destination texel is an area average over its equal-sized cell in the source+image, treating source texels as piecewise constant. Integer overlap numerators+include partial source cells. Thus odd edges are neither discarded nor given the+weight of a complete destination cell. For example, [0,0,0,0,1] reduces to [0,0.4]+then [0.2], preserving its original mean. Intermediates use f64 and each generated+level is stored in f32, so successive levels include f32 rounding. No transfer+function is applied; the input must already be linear normalized color/data.++The API is deliberately opaque: alpha is ignored in RGB filtering and generated+levels have alpha=1. This is not premultiplied filtering or transparent compositing.+Normal maps need a separate role-aware vector filtering policy and must not use+this helper as though scalar averaging produced valid unit normals. There is no+hidden Y flip, tangent basis, grain-axis inference or source orientation transform.++Cancellation is checked before work, at each level, before every destination row,+after a level and before returning the complete chain. Failure/cancellation drops+local partial results; callers receive no partial chain. Preparation is synchronous+and belongs to the existing caller-owned host. Cancellation polls do not yield the+browser event loop, schedule a worker or establish browser responsiveness.++`sample_repeat_lod_opaque(uv, lod)` applies the #1327 periodic bilinear convention+within each level and interpolates adjacent levels in linear space. LOD must be+finite in [0, level_count - 1]; out-of-range values refuse. Signed/unwrapped UVs+keep the sampler's existing finite 2^20 repeat bound. Sampling performs no+allocation or full-image validation scan. GPU/f32 parity is not inferred from+the CPU arithmetic.++LOD is supplied explicitly. Screen-space derivatives, footprint selection,+anisotropic filtering and grazing-angle grain remain consumer work; a mip chain+alone is not a proof of alias-free wood. Typed bindings, local mm mapping and+inverse-instance placement, CPU/GPU consumers, PNG/offline reopen and real native+visual evidence are still required. HDRI and final rendering are not enabled.++Original generated tests cover linear checkerboard and fractional LOD values,+area-weighted odd/rectangular means, 1x1 and single-axis images, budget boundaries,+hostile LOD/UVs and cancellation at every publication checkpoint. No third-party+assets, code or dependencies are added. This numerical helper has no app screenshot.diff --git a/docs/render-texture-sampling.md b/docs/render-texture-sampling.mdnew file mode 100644index 0000000000..ee1be1f474--- /dev/null+++ b/docs/render-texture-sampling.md@@ -0,0 +1,47 @@+# CPU texture reference sampler++`solidcraft_render::texture_sampling` supplies the independent numerical unit in+#1327. It does not install a texture consumer or close the wood rendering work.++Construct `TextureView::new(rgba, [width, height])` from immutable normalized float+RGBA. Dimensions must be positive and no larger than the existing admission edge+limit (2048); storage is exactly `width * height * 4` floats, at most 64 MiB.+Every channel, including alpha, must be finite and within [0, 1]. Construction+scans once and borrows the caller's storage. Sampling does constant work without+allocating. The sampler neither decodes nor converts color, and owns no cache.++The normalization contribution #1267 can provide the inputs directly through+`NormalizedTexture::rgba()` and `receipt().output_dimensions`; no normalization+implementation or dependency is copied into this module. Raw encoded RGBA8 from+the older admission utility is not interchangeable with normalized linear color.++`sample_repeat_opaque([u, v])` returns three f64 channels. Both axes use periodic+bilinear level-zero addressing. UV (0, 0) is the top-left image boundary; v grows+downwards. Texel (x, y) is centered at ((x + 0.5) / width, (y + 0.5) / height).+An integer coordinate lies halfway between the last and first texels. Negative+and unwrapped coordinates repeat; nothing clamps UVs or flips rows a second time.++Interpolation is in the supplied linear color or data space, with f64 arithmetic+on f32 input samples. The helper applies no sRGB transfer, normal-vector decoding,+tangent basis or engineering grain-axis interpretation. Alpha is deliberately+ignored for this opaque API: even zero-alpha RGB participates. It must not be used+as a transparent compositor; there is no claim of premultiplied-alpha filtering.++Coordinates must be finite and have magnitude at most 2^20 repeats. Reduction+precedes multiplication by dimensions. Around this bound, f64 input spacing is+at most 2^-32 repeats, or 2^-21 texels at maximum width. Smaller sub-ULP offsets+cannot be recovered. Tests use a 1e-9 absolute channel tolerance for analytic+fixtures; this is not a universal error bound or f32 GPU parity certification.+Consumers must reject or explicitly reconcile larger mapping ranges rather than+silently clamp them. GPU upload/filtering precision requires separate evidence.++Original generated 1x1/2x2 and rectangular constant fixtures check centers, row+orientation, linear black/white mixing, interpolation, both seams, signed/integer+repeats, alpha policy and hostile storage/coordinate refusal. No third-party+assets or code are added. This invisible helper has no useful app screenshot.++Still required for visible wood: typed bindings and persistence, local millimetre+mapping with one inverse-instance transform, resource lifetime/budgets, product+CPU/GPU integration, minification/mips, PNG and offline reopen evidence. Bilinear+level-zero filtering alone does not prevent aliasing of oblique/minified grain.+HDRI, glass, final integration and mechanical wood properties are separate work.