mirror of
https://github.com/bherbruck/solidcraft.git
synced 2026-11-06 20:02:16 +00:00
0xlillith
78 lines
4.7 KiB
Markdown
78 lines
4.7 KiB
Markdown
# Runtime surface patterns for the opaque CPU preview
|
||
|
||
`raytrace.surface_effects` is an optional bounded runtime request field. Each
|
||
entry names one uniquely resolved captured body, an explicit right-handed world
|
||
frame in millimetres, three positive repeats in millimetres, roughness amplitude,
|
||
and bump amplitude in millimetres. No field is saved into the design, native file,
|
||
physical material, texture catalog, or appearance preset.
|
||
|
||
The original periodic field changes only the opaque surface roughness and shading
|
||
normal. It does not change vertices, geometric normals, intersections, bounding
|
||
boxes, body mass, volume, inertia, or shadow occlusion geometry. This is a periodic
|
||
preview field; it does not load a texture or displace a surface.
|
||
|
||
## Consumer contract
|
||
|
||
At most 32 effects and reserved slots are admitted. Names are 1–256 UTF-8 bytes,
|
||
without control characters, and must resolve to exactly one captured mesh. The
|
||
frame must be finite and orthonormal with positive handedness. Repeats are within
|
||
0.001–1,000,000 mm; roughness amplitude is within 0–1; bump amplitude is within
|
||
0–1,000 mm, with a maximum analytic gradient L1 bound of 4. Sampling beyond the
|
||
world/periodic precision bounds refuses. Duplicate and ambiguous selectors,
|
||
explicit JSON null, nonfinite values, and oversized capacities refuse.
|
||
|
||
Absent effects preserve the existing path. An explicit empty list stays distinct
|
||
in the request. Zero-amplitude entries are validated but excluded from the
|
||
prepared scan and preserve the completed image bytes. Dynamic name/vector
|
||
capacities in both task options copies and the prepared vector are included in
|
||
the existing admission sum; the retained request uses its original host budget
|
||
lease and remains accounted after frame eviction or while handles are held.
|
||
|
||
The current image consumer scans one prepared binding per continuation and checks
|
||
cancel/work before mutating the cursor. A completed selection precedes every
|
||
lighting stage. Each directional, point/spot, rectangular/LED, HDR and isotropic
|
||
reflection consumer receives the same changed surface and shading normal through
|
||
the shared hit contract. Original geometric normals still govern ray offsets,
|
||
visibility and emission sidedness. Emission is added through the existing path
|
||
throughput and receives no new direct-light sampling behavior.
|
||
|
||
The state resets at each reflected hit and each new primary sample. Fixed-primary
|
||
AA reuse is valid only after the effect scan and all shading stages have finished.
|
||
S/R sampling, sample denominators, coverage, linear accumulation and the final
|
||
display transform remain in the existing consumer. No alternate pixel encoder,
|
||
renderer, timer, or host pool is introduced. Public steps retain the four-work-unit
|
||
bound and existing task/job memory caps.
|
||
|
||
A nonidentity effect on a body selected for certified planar anisotropy refuses:
|
||
that model's orientation/rough-axis contract does not yet include these fields.
|
||
Identity effects remain allowed there. The integrated CPU dielectric consumer
|
||
also refuses nonidentity effects on its optical boundaries before transport;
|
||
Snell/Fresnel keeps the original geometric normal. An existing clear-coat layer
|
||
is preserved when changing substrate roughness for direct lighting. Selecting a
|
||
coated body for CPU reflection, anisotropy or dielectric transport refuses until
|
||
a matching layered transport estimator is available.
|
||
|
||
## UI and validation scope
|
||
|
||
This consumer change admits the field through the existing shared runtime request
|
||
and documents it in engine preflight. The current visible image controls continue
|
||
to refuse unexposed effect options. The separately recovered surface/emission
|
||
editor needs its own port and native acceptance before visible controls can be
|
||
claimed.
|
||
|
||
The recovered original source checkpoint authored five math/JSON tests, two
|
||
completed-image/admission tests, and a host lease lifecycle test. Those original
|
||
tests are retained. The current port adds strict name/capacity and aggregate
|
||
lease checks; all analytic-light/HDR combinations against an equivalent constant
|
||
shared surface; mirror/rough reflection through an emitting secondary hit; a real
|
||
32-binding scan with cancellation/work exhaustion; anisotropy overlap refusal;
|
||
and AA ordered-prefix/coverage/PNG/quantum checks. Existing malformed AA completion
|
||
cases are retained and extended for surface state.
|
||
|
||
At the recovery handoff these were source contracts and written regressions.
|
||
The combined CPU renderer has since executed analytic gradients, zero identity,
|
||
shared-surface lighting, ordered AA, binding and cancellation/work checks. Current
|
||
combined engine/UI contracts and visible/native flows still need qualification,
|
||
alongside default-feature/platform, Clippy, wasm and full-project gates.
|
||
Historical results remain attached to their original source revisions.
|