solvecraft/docs/render-raytrace-image.md

CPU ray visibility and hard shadows (RT2)

Current combined integration boundary (2026-10-17)

The sections below describe the original RT2 direct-image stage. In the combined source, HDR/reflection integration adds selected ideal/rough-specular reflections and certified planar anisotropy. Environment sampling describes the earlier standalone direct estimator; the combined page specifies the connected reflection path and its disjoint HDR estimators. HDR input remains the bounded decoder route. Only explicit sRGB/D65 primaries are admitted for lighting. HDR plus rough reflections requires fully metallic selected bodies and all effective face responses. HDR plus anisotropy requires the supported rough reflection combination; direct anisotropic HDR and anisotropic delta mirrors refuse. Those additions do not imply MIS, GI or unrestricted material transport.

The opt-in solidcraft-engine/raytrace-cpu feature forwards the render feature. The native host selects cpu-raytrace only for explicit integrator: "raytrace"; raster remains the default, and cooperative/browser hosts refuse ray tracing. Use the same preflight/start/status/cancel/export commands and job identity described in product-image jobs. Preflight does not reserve a queue slot or memory; start repeats admission.

The CLI render wrapper accepts settings, output and timeout options, but no --integrator or --raytrace-options flags. It submits settings and transparency through the default raster route, waits for the job and exports within that process. Jobs do not survive the host process exiting. Ray tracing commands can instead use a persistent native MCP session with the compiled feature and an installed image host, or the optional desktop image controls described below.

Primary rays default to fixed pixel centres. Explicit primary_samples values of 4 or 16 use bounded pixel-box quadrature in primary AA. Reflection samples and viewport MSAA are separate controls. The retained raster scratch estimate does not mean ray tracing performs raster supersampling. The light union connects bounded rectangle and point/spot sources to this same ImageTask; continuous LED strip recipes lower to a rectangle before capture. These source integrations require their own revision-specific qualification. Texture sampling and glass/refraction/transmission remain outside this consumer. Output remains opaque Preview/Image/PNG, without EXR or GPU ray tracing.

Existing shared-host limits remain: 262,144 triangles, 128 MiB retained source geometry, 384 MiB job admission and a 512 MiB shared pool. These are not total CAD-process RSS limits. HDR buffers, reflection selectors, light options and actual retained capacities join the same ownership/accounting; the common cumulative work cap remains 1,000,000,000.

Desktop CPU/AA controls

The optional desktop feature solidcraft/raytrace-cpu forwards the engine feature and enables the Render image-method choice when the installed image host supports ray tracing. Raster remains the default. CPU Edge samples offers exactly 1× (the original fixed centre), 4× or 16×. Preset lighting, cast shadows and exposure are temporary per-document editor choices. More samples cost more work and can exhaust the unchanged limits.

Check and Start use the same request builder, native image host and captured-job commands. CPU images require an opaque background. Missing, stopped, cooperative and compiled-out CPU hosts refuse before image scene capture; the selector does not install a fallback or another host. A stale model must be explicitly refreshed or its modelling gesture finished before Check or Start.

The current Check badge is advisory. It invalidates on document identity, revision, visibility, camera/options or host changes. Start rebuilds the current request and repeats admission. The global status message is not a current Check identity. Export uses the retained completed job selected when its file picker opens; changing options does not rerender that image. A failed or cancelled new job preserves the previous successful frame.

Runtime method, AA, preset, shadows and exposure are not persisted by Save Setup or added to document undo. Switching to Raster discards CPU options and resets the next CPU choice to 1×; a new or reopened document starts with Raster. Existing Record and navigation routes are unchanged. This panel does not expose HDR, reflection selection, explicit directional/area/punctual lights, LED recipes or anisotropy authoring. It rejects non-panel raytrace options instead of silently forwarding them. Engine/MCP lighting support is a separate interface.

Qualification and historical evidence

Qualification belongs to a specific source revision and build configuration. Report the exact source, feature-on/off checks, wasm and full CI results, native executable identity and visible evidence in the accompanying PR. Earlier scoped CPU/AA results belong to their recorded source snapshot; they do not certify a later merge with main or changes to lighting and host contracts.

For this UI consumer, evidence must exercise the actual method and AA controls, Check, a new Start/completion for both 4× and 16×, and native PNG export. Check that those requests reach the same host, the exported bytes belong to the selected completed frame, and repeated export does not rerender it. Preserve document geometry, physical properties and history during rendering; save and reopen the design to verify that the transient CPU/AA choices are absent. Include refusal, preflight invalidation and cancellation coverage, with the CPU feature both on and off. These are acceptance criteria, not a claim that this combined revision has passed them. Broader HDR/reflection/light changes require their own evidence.

The combined path includes the exact-coordinate-plane depth correction. On an earlier isolated source, the Rust witness failed before the correction and passed afterwards; that source passed 222 feature-on and 147 feature-off render tests plus scoped Clippy/wasm. Those historical results do not qualify later main integration, primary-shading reuse or reflection-sequence changes. General oblique and near-edge robustness remain outside the coordinate-plane correction's scope.

The original combined source's full CI ended incomplete at its fixed deadline. Known modelling golden failures remain recorded separately; do not attribute their cause to rendering or carry them over as a verdict on another revision without paired baseline evidence. An earlier optional 960x540 request exhausted the billion-unit cap without producing a PNG; smaller drafts do not qualify that request. No cap, assertion, tolerance, ignore or golden-baseline change is implied.

The stage-specific descriptions below record the original direct-image scope, not a current pass/fail report. This opt-in slice of #1368 follows the phased render design in #620 and connects SolidCraft's original RT1 triangle/BVH core to immutable product captures and the existing image-job host. The raytrace-cpu Cargo feature stays off by default.

Original RT2 runtime contract

render.preflight and render.start accept integrator: "raster" (the default) or "raytrace". Optional raytrace settings contain lights, exposure_ev and shadows, plus an optional preset (neutral, warm_cool, key_rim). A preset and an explicit lights list are mutually exclusive, including an empty list. Presets use original hard directional-light compositions, not calibrated color-temperature claims. These values belong to the request, not the saved document or render setup. A build without the feature refuses raytracing before geometry capture. The initial image executor is native-only; no browser performance is claimed.

Each light has a world-space direction: [x,y,z] pointing towards the light, linear-sRGB color: [r,g,b] and relative intensity. Directions are normalized; all numbers must be finite. At most eight lights and eight retained slots are accepted, colors are in [0,1], intensity in [0,64], exposure in [-16,16] EV. Omitting lights uses the existing three-light studio. An empty list is darkness. These are relative radiances, not measured lux or watts. Background color remains independent of illumination and exposure.

The scene must be opaque, including face overrides; transparent backgrounds are refused. Captured world positions are used once, preserving occurrence placement. Scalar colors become linear-sRGB opaque dielectric surfaces (roughness 0.7, IOR 1.5); explicit opaque surfaces retain their metal fraction, roughness and IOR. This scalar fallback differs from the legacy raster shading and is not a measured material fit. Density and engineering properties do not change.

The camera uses the existing pixel rays and the same scene-radius near/far policy as product rasterization. Primary rays start on the near plane; shadow rays have independent finite intervals. There is one center sample per output pixel, so edge quality can differ from the supersampled raster image. Shading uses interpolated normals with a geometric-normal fallback and hemisphere checks.

Per-light BVH visibility supplies hard shadows to the existing opaque BRDF. Linear contributions are summed, exposure is applied once, then Reinhard and the piecewise sRGB transfer are applied once. Shadows can be disabled without changing the BRDF. No SSAO is multiplied into this output. No indirect lighting, soft shadows, reflection transport, texture sampling, HDRI lighting, refraction, absorption, emission transport or denoising is implemented here. IOR controls opaque Fresnel; it does not make glass. Unsupported requested capabilities must fail explicitly.

Work and memory

The same native queue, worker, cancellation token and 512 MiB host reservation are used. There is no additional worker pool. Admission retains the conservative raster geometry/pixel/codec estimate and adds BVH input/nodes/order/build stack, per-triangle surface/normals/vertices and 8 KiB for task/light/traversal state. Total admission must remain within 384 MiB including the checked sum of work and retained request allocations. Original directional-light capacities keep a separate lease from the same pool for the job-handle lifetime, even after PNG eviction. Actual buffer capacities may not exceed the planned capacities; the builder's actual reservation is checked before continuing.

One cumulative maximum of one billion work units covers preparation, BVH build, primary and all shadow traversal. Builder operations are debited into that same budget. Exhaustion and cancellation are typed failures, never truncated visibility or a partial successful image. Each traversal step visits at most one node or primitive; each preparation step examines at most one face override. A task call performs at most four such units, or four PNG rows. These are work bounds, not a hard real-time or operating-system memory guarantee.

Shadow origins are reconstructed from triangle barycentrics. Component-wise floating-point rounding bounds projected onto the geometric normal and one outward representable step replace a fixed world-space epsilon. Secondary intervals require a strictly positive representable distance to exclude signed zero after subnormal interpolation. This avoids displacing a Z-plane merely because X is large. Floating-point geometry still has finite resolution; thin blockers, self-intersection and translated scenes require tests.

PNG encoding reuses the bounded cancellable row encoder. Captured geometry, acceleration data, pixels and light buffers are released before successful output is returned; the host drops task state before shrinking to the retained PNG lease. Cancelled or failed jobs preserve the previous successful frame.

Provenance and acceptance

RT1 was copied, with its owner's authorization, from the existing isolated rt1-raytrace-core contribution. Its original source remains untouched. The new resumable cursor and image consumer are original Rust additions; the source receipt records the exact adopted hashes. No external rendering engine, shader source, commercial CAD asset or new dependency is introduced.

Regressions cover typed cumulative-work exhaustion, resumable traversal parity, near/far camera policy in both projections/up axes, translated thin occluders, self-shadow avoidance, runtime refusal and captured-resource release. Lighting tests use analytic Lambert values and independently masked colored lights. Actual test counts, compiler results and original-scene PNG review must be reported only after execution. Qualification of the integrated revision requires those gates and the PR evidence described above.

Beyond the original direct-image stage, HDR/reflection connections are described at the top of this page. Qualified texture resources, role-correct material maps, progressive transport and explicit glass/medium semantics remain separate work. Community feedback is welcome on bounded latency, normal handling, energy loss in the preview BRDF and reproducible acceptance scenes.