Files
solidcraft/docs/render-path.md
T
Christian SvenssonandClaude Opus 5.5 30449418ac Render: progressive GPU path-tracing executor (#2067)
Land the unchanged contributor GPU foundation into render under the maintainer policy in #5493. Fresh quick gate 39993339605 passed. Original author and co-author attribution retained; no workflow file changes. Final render-to-main CI and jyviko sign-off remain separate.

Co-Authored-By: Christian Svensson <blue@cmd.nu>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 21:10:55 +02:00

91 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Progressive opaque product images
Native applications can register `solidcraft_gpu::path::host()` alongside the
existing CPU image host. `render.backends` then exposes `builtin/gpu-path` with
Preview, Image, PNG, Pbr and Progressive. The browser keeps its CPU image host.
Device discovery follows `SOLIDCRAFT_GPU` and `WGPU_BACKEND`; a device which cannot
create the compute pipeline does not register an available path executor.
The native UI opens its independent job device on the viewport's selected adapter,
so software fallback and safe mode do not rediscover a failing hardware driver.
An incompatible explicit GPU policy leaves progressive rendering unavailable there.
In the Render workspace, enable **Progressive rendering** and select samples per
pixel before checking or starting an image. These controls are transient image-job
intent. Existing saved setup/camera/material formats are unchanged.
The interactive canvas keeps its existing product preview; this first image-job
integration reports sample progress and exports the completed PNG, without displaying
partial accumulation buffers on the canvas.
```json
{"command":"render.start","params":{"settings":{"width":800,"height":600,"exposure_ev":0},"progressive":true,"samples":64,"max_depth":8,"seed":0}}
```
`render.preflight` accepts the same input. It resolves the Progressive capability
to the installed GPU host and performs admission without reserving memory. Start
checks again and returns the existing session/serial/generation identity. Progress
reports complete samples per pixel; a partially computed sample is not counted.
Cancel, status, retained-image ownership and atomic PNG export use the same host
protocol as CPU jobs. Defaults are 64 samples, depth 8 and seed 0; the bounds are
1–4096 samples and 1–16 bounces. Sampling controls require `progressive: true`.
```sh
solidcraft-cli render examples/render-path-studio.json --out enclosure.png --progressive --samples 64 --max-depth 8 --seed 0 --width 800 --height 600
```
The CLI explicitly fails if a progressive request has no suitable device. Ordinary
CPU requests retain their prior behavior. GPU PNG export averages linear radiance,
applies saved exposure and the existing Reinhard map, then encodes sRGB once. A
transparent background uses straight alpha; background color is independent of
illumination.
The original integrator uses software BVH traversal, opaque GGX/Smith/Schlick and
the symmetric diffuse attenuation defined by `render::surface`. Each hit evaluates
the three existing directional studio lights with shadow visibility. Continuation
samples a mixture of cosine-weighted diffuse and GGX normals with the combined
PDF; Russian roulette begins after four hits. There are indirect bounces, but no
environment illumination in the production profile. All legacy opaque colors use
linear-sRGB base color, metallic 0, roughness 0.5, IOR 1.5. Explicit face appearances
take precedence over body appearances.
This initial executor rejects opacity below one. It does not implement refraction,
absorption, HDRI, area lights, denoising, textures, EXR or Final mode. A path-traced
preview is not a declaration of those capabilities. The uniform environment used
by the numerical furnace test is deliberately not exposed as an HDRI feature.
Each job builds a balanced median-split BVH over its immutable captured meshes;
there is no cross-document cache to confuse scene generations. Positions are
rebased around the camera target before f32 upload. The upload packs indexed 32-byte position/normal vertices, 16-byte triangle records
(including material IDs), 32-byte resolved materials and 32-byte BVH nodes. The
geometry arrays share one buffer so traversal fits baseline storage-binding limits.
Geometry must be
within 1e7 mm of the camera target; ray offsets are max(1e-5 mm, extent × 1e-7).
This is a bounded preview precision policy, not a robust CAD intersection oracle.
Each GPU dispatch computes at most 262,144 pixel paths at one sample index. The
worker waits for that dispatch before checking cancellation and issuing another.
A driver wait has a 30-second timeout; cancellation cannot preempt a stalled GPU
dispatch. Encoding yields every four rows. Invalid indices/normals, nonfinite
geometry, excessive dimensions and sampling controls are errors.
The GPU host admits at most 1,048,576 input triangles, 4096 pixels per side and
4,194,304 pixels in all. The actual storage-buffer limit may lower these caps.
The source geometry cap is 128 MiB and the per-host pool is 512 MiB, including
retained PNG leases. Conservative estimates account for CPU BVH construction,
serialized and device geometry, accumulation, readback, RGBA and PNG buffers.
Allocator/driver bookkeeping is not an OS quota. CPU and GPU workers have separate
pools and each retains the established two-entry queue bound; a document still
has at most two live jobs across both executors.
Validation lives in `gpu::path::tests` and engine render job tests. Set
`SOLIDCRAFT_REQUIRE_GPU=1` to make absence of an adapter fail device tests rather
than skip them. BRDF parity is checked against the f64 oracle with 0.3% relative
plus 2e-5 absolute tolerance. The near-white furnace allows 0.07 absolute error:
the existing single-scattering Schlick model is not a perfectly conserving pure
Lambertian surface, even at IOR 1. Same-adapter determinism compares the actual
linear buffers bit-for-bit; cross-adapter bitwise identity is not promised.
The ignored `path_performance` test builds a 1,048,576-triangle procedural sphere
and measures 1920×1080 dispatches, BVH construction and upload. Select sample count
with `SOLIDCRAFT_PATH_BENCH_SAMPLES` (default 1). Run it explicitly with a clear GPU
timing window; it is excluded from normal CI.