solidcraft-upstream/docs/render-texture-mips.md

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.