Files
makeCAD/docs/render-path.md
T
brett19 054392abbe Wave 509/509: Kernel rig: assembly cases for mass properties, align, find limits and moving items between parts (and 38 more)
39 commits, squashed; the originals stay reachable from tag archive/merge-main-develop. These commits sit on several merged branches, so the wave holds their combined result.

- 1b17dd7f5 brett19: Merge fixes: every crate and test target compiles on the merged tree, but for crates/geom's hlr
- 8f2c11da2 brett19: Drawings hidden lines: read develop's B-rep records
- c30ca0216 brett19: Hidden-line fixtures: build develop's records from the fixtures' data
- 5dd2509ae brett19: Hidden lines: tests of the bounded edges, face charts and placed revolutions
- 1642df0ea brett19: drawing-hlr doc: what is drawn and refused on develop's records
- ddcb80c8e brett19: hlr tests: a placed revolution is refused when its placement is not rigid
- e4977721f brett19: Hidden lines: a traced intersection is drawn only where its spline lies on both surfaces
- b3ef6ae52 brett19: Hidden lines: kernel bodies through the production prepare against closed forms
- 4cd2ae062 brett19: Tests from main: the world state is a Result here
- 51d7ad09e brett19: A blend's pick measures close edges on their curves, not their polylines
- 11a89713c brett19: Merge fixes from the first SMLib test pass
- 48fcb7aac brett19: Merge fixes from the ui test pass and the gates
- abd739855 brett19: A silhouette takes its facing from the surface's normals
- 85114c5a2 brett19: Clippy and rustfmt on the merged tree
- 55a46569f brett19: Stepwise open checks every feature under the session's mode
- 4627402e4 brett19: Clippy without SMLib: the planar-sheet edge reader is built only with it
- 5fbece0ac brett19: STEP import: a ball's halves whose seams are off each other's quarter lines each form within one turn
- eb78d20b0 brett19: Lid ring sketch test: find the ring under the pick, not by main's kernel's name
- 3048d8c49 brett19: Viewport culling test: each box's triangles from its mesh, not 12
- dc88b80e2 brett19: Timeline chip test: a fillet that really reduces
- 876203621 brett19: Edge names: a seam names its one face once; the curve-id test reads every edge kernel-neutrally
- 900635710 brett19: rustfmt on the merged tree
- b7e83cd7c brett19: Known failing on SMLib: two of main's new tests assume truck's box mesh and fillet torus
- 63bde053a jyviko: Locales: Vietnamese for the setback-too-short refusal, now that vi is a complete catalog
- 967a1caa6 brett19: Kernel rig: exact volumes for 1213's bent-tube round and 4782's bar round, rel 1e-6
- 82c821d2a brett19: After the merge: clippy's auto-deref, and the mesh-decisions list for the merged tree
- 5862ee223 brett19: After the merge: main's new tests on the SMLib kernel
- be78372b2 brett19: Twisted sweep: circles about a straight path are exact cylinders (solidcore#2184)
- 312d14500 jyviko: After the merge: a hole that misses is found by exact boxes; a face is a one-face patch; main's mesh-box helpers gone
- 6f7e51acb jyviko: After the merge: split_move's Result reaches its callers; to_local's duplicated move check goes
- 8f0c79b20 jyviko: After the merge: main's two new tests take world_state's Result, as the rest of their files do
- 5f4d70061 jyviko: After the merge with main: its new code on develop's exact bounds, types and thread fields
- 2b2ab6627 jyviko: Cargo.lock: develop's profile, smlib and step crates at main's 0.30.1
- e6a4b0a9a jyviko: Kernel rig: main's six new sketch-only commands are exempt from a kernel case
- 5acbd2e71 jyviko: Cuts leave the bodies their tools can't reach, by exact boxes (#10225 on exact geometry)
- d2b202307 jyviko: Kernel rig: main's new view, rendering, appearance and settings commands are exempt from a case
- 21db090ba jyviko: Kernel rig: construct.plane.axis_point gets construction cases
- c1f45cae2 jyviko: Kernel rig: assembly cases for mass properties, align, find limits and moving items between parts
- 084695416 jyviko: Kernel rig: export and print face cases in the import area

Co-authored-by: jyviko <2501648+jyviko@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DtL5M41G8Nua7HvuFPZkmJ
2026-11-02 17:34:24 -05:00

10 KiB
Raw Blame History

Progressive product images

This integration is a draft. Final combined CPU, wasm and GPU verification and full-resolution showcase acceptance remain incomplete. Test descriptions below state intended coverage, not a claim that every backend has passed.

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, Progressive and Refraction. 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 retains a factory for the viewport's selected adapter at installation, without opening another device or compiling path shaders in Design (including safe-mode startup). The first entry into Render starts preparation once, asynchronously; if the viewport arrives later, that installation starts the already-requested preparation. Document changes retain the pending/ready/failed host, and failures are not retried on each viewport installation. It 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. The path tracer runs on Vulkan, or on Metal on macOS (#3217). A viewport on D3D12 is reopened on the same GPU through Vulkan. Where there is no Vulkan or Metal driver (Windows over Remote Desktop or on the WARP software adapter, older drivers), the path executor reports itself unavailable and images render on the CPU. On an RTX 4090, D3D12 was never faster: equal per sample with DXC and about 55% slower with FXC, and it compiles the path shader at every start (about 82 s with DXC, about 2 hours with FXC), where Vulkan's compiled pipelines persist between runs.

In the Render workspace, select GPU path tracing and samples per pixel before checking or starting an image. These controls are transient image-job intent that can also be retained in typed saved setups. Each new saved concept uses the pending-format mechanism, without manually changing a version number. The canvas switches between live product preview and a large completed-image result, with Fit and 100% framing. Jobs report sample progress and export the completed PNG; partial accumulation buffers are not displayed on the canvas.

{"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.

Runtime request-only glass overrides and an optional thin-lens camera and clear coat are available through those same commands. Neither adds saved document fields. Positive aperture requires perspective.

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 selected tone map (Reinhard by default), then encodes sRGB once. Runtime aces_fitted is described in studio lighting. 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 default legacy lighting 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.

Explicit optical appearances can now select smooth dielectric reflection, refraction, Beer–Lambert absorption and ideal thin sheets; see the transmission contract. Preview opacity remains a separate scalar-alpha approximation. Opacity below one without an explicit transmission record is rejected by the path executor. Runtime area lights, sun/HDR environment lighting and opaque planar color/normal maps are available through explicit job inputs. They do not add saved document fields. An optional bounded edge-aware a-trous denoiser filters the final output while preserving raw accumulation. Texture LOD/mipmap selection, EXR and Final mode remain unimplemented by this executor; a path-traced preview does not declare those capabilities.

Each job builds a BVH over its immutable captured meshes with a sixteen-bin surface-area heuristic on triangle centres; there is no cross-document cache to confuse scene generations. A split is accepted only when a median split of its larger side would still keep the tree within 30 levels, the shader's 32-entry traversal stack; otherwise that node falls back to the median split. Traversal tests both child boxes at their parent and visits the nearer first. On the exploded coffee machine at 1080p and 8 samples per pixel, this halves render time on an NVIDIA GB10 (opaque 4.95 s to 2.49 s, closed glass 5.65 s to 2.79 s) with bit-identical images. 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), 64-byte resolved materials, four-byte planar patch IDs and 32-byte BVH nodes. Geometry arrays share one buffer. The progressive executor requires six storage buffers per stage for geometry, BVH, accumulation, environment, textures and medium-failure counts; raster device requirements remain unchanged. Geometry must be within 1e7 mm of the camera target. Opaque and thin-sheet ray offsets use max(1e-5 mm, extent × 1e-7); closed glass instead retains an anchor and local displacement with strictly positive intersections, as described in closed-glass boundaries. These are bounded preview precision policies, 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.

Dispatch and device-loss behavior

Each new path job begins with 64 paths. Completed submissions target approximately 20 ms and grow at most twofold, bounded to 64–16384 paths; a short image tail is smaller. Denoiser guide/filter passes use the same controller. Measured wall time includes scheduling contention, so this is a conservative responsiveness policy, not a promised GPU deadline or a substitute for the OS watchdog. Sample/seed and pixel identities are unchanged by tile boundaries.

Actual device-loss callbacks, uncaptured device errors and failed completion waits retire that native executor. Existing and new jobs refuse further device work; preflight/session metadata reports it unavailable without inventing new capabilities. The application must deliberately recreate a host to recover. Merely registering the same cached host or opening another document does not advertise it as healthy again.

Shared index-matched base response

The opaque base lobe uses the same Fresnel limit as OpaqueSurface: when the base IOR is exactly one, the dielectric fraction has no interface reflection at any angle. A metallic mixture retains its independently weighted conductor fraction. This applies to the specular term and both diffuse transmission factors. The existing actual-GPU BRDF oracle checks the limit at normal, oblique and grazing angles against the f64 surface, including mixed metallic values. Clear-coat and physical transmission contracts are unchanged by this base-lobe correction.