Files
solidcraft/docs/render-raytrace-image.md
T
lillith bb2fff8e14 Render: integrate optional CPU ray tracing, reflections and HDR lighting (#1693)
Publish the reviewed fa8c1206 source as a draft work-in-progress checkpoint.
Finish the actual merge of pinned upstream 04b4381b while preserving published
claim 28414b51 and all real ancestors. Exact staged tested tree: 8388e395.

Adopt the original RT2 (#1640), reflection (#1658), HDR (#1698), planar
anisotropy (#1699), planar-depth, deterministic-primary and stratified-source
contributions documented in the existing source-overlay receipts. Those
receipts are source provenance, not fictional implementation commit parents.

Actual cargo xtask ci: exit 1, 4344 passed, three golden groups failed,
52 existing ignored. Pristine 04b separately reproduces all seven seed lines.
Affected feature-on render/engine checks, Clippy/wasm and production native
MCP/PNG reopening passed on identical precommit source. No full-CI pass,
latest-main qualification, presentation readiness or merge approval claimed.
2026-10-17 04:00:39 +02:00

10 KiB

CPU ray visibility and hard shadows (RT2)

Current combined integration boundary (2026-10-16)

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 current 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 existing CLI render wrapper does not accept --integrator or --raytrace-options; it submits settings and transparency through the default raster route. Use engine commands through a persistent native MCP session with the compiled feature and installed host for this ray tracing workflow. A one-shot CLI process is not a durable asynchronous job host. The current Render workspace UI also submits settings and transparency without selecting the ray tracing integrator. Its ordinary buttons do not establish a ray tracing UI workflow; that UI and GPU ray tracing are not qualified by the headless MCP evidence.

Primary rays still use fixed pixel centers. More reflection samples do not provide geometric antialiasing. The retained raster scratch estimate does not mean ray tracing performs raster supersampling. This consumer does not connect texture sampling, glass/refraction/transmission, area lights, point/spot lights or LED strips; separate modules are not evidence of integration. 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 and actual retained capacities join the same ownership/accounting; the common cumulative work cap remains 1,000,000,000.

This combined candidate has not been compiled, tested or rendered. It includes the exact-coordinate-plane depth correction. On its 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 this candidate after main integration, primary-shading reuse and 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 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, and presentation readiness remains pending.

Before publication, execute the relevant regressions, complete current cargo xtask ci and wasm checks, and inspect exact-build native visibility, shadow, reflection and HDR output. Historical results and source review alone do not qualify the final combined revision. The stage-specific validation text below is historical scope, not a current pass/fail report.

This opt-in slice of #1368 follows the phased render design in #620. It connects SolidCraft's original RT1 triangle/BVH core to immutable product captures and the existing image-job host. The raytrace-cpu Cargo feature is off by default. Implementation is under review; tests, native PNG acceptance and full CI for this integration remain pending. Historical RT1 results do not qualify this new consumer.

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. The draft PR stays unqualified until those gates complete.

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.