845f4913cf
Co-Authored-By: selune <[email protected]> Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
70 lines
4.5 KiB
Markdown
70 lines
4.5 KiB
Markdown
# 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.
|