solvecraft/docs/render-cpu-path.md

CPU indirect lighting

CPU indirect lighting and general Glass are in published source 00edaf6a/tree 38a7f0af. CI7 passed 744 renderer tests and all 433 Render workspace tests; the full project gate remains red. Native evidence is an opaque Sample Plate, so native Glass and image-quality acceptance remain pending. See the parity and qualification record.

CPU Sampling can explicitly enable Indirect lighting. Runtime intent is raytrace.path: {"max_depth": 8}; saved CPU intent is job.options.path with the same contract. Omission preserves the existing direct/selected-reflection algorithm, pixels and work. It adds no path allocation when omitted; the fixed task metadata remains within the existing allowance, subject to compilation guards. Path depth is 1–64 shaded opaque surfaces or Glass boundaries, starting with the first hit. A depth of 1 uses direct lighting only; higher values allow more light bounces and may take longer. Finite depth truncates longer paths; this is not a certified convergence or speed guarantee. No automatic quality, profile, size, seed, camera, default or method change is made.

The mode requires progressive camera sampling, primary_samples: 1 and traced shadows. It evaluates the complete existing isotropic opaque BRDF, including its existing clear-coat approximation, and uses an exactly matched cosine/visible-GGX/coat mixture. Null proposals retain their probability mass. Secondary hits preserve captured body/face appearance and existing surface effects; visible surface emission can illuminate diffuse neighbors through actual path continuation. Small mesh emitters have no next-event sampling and may remain noisy.

Directional and point/spot sources retain their delta direct estimates. Rectangles become intersectable one-sided emitters. Rectangular and HDR/constant environment estimates use light/BSDF power weights with the actual direct sample counts, previous-scatter density/position and no nonexistent continuation competitor at the depth endpoint. Geometry wins equal-distance emitter ties. Finite shadow intervals exclude their sampled source; other rectangles occlude both strategies consistently. Uniform-solid-angle HDR sampling preserves the existing explicit sRGB/D65 policy; no importance-distribution quality claim is made.

A primary miss remains the separate unexposed display background. Complete paths add scene-linear radiance to the existing primary film exactly once. Existing every-pass publication, presentation, raw final EXR, final ownership and exact export routes remain authoritative. A partial path cannot advance film coverage/SPP or publish a completed result. Guided noise reduction and transparent PNG coverage compose with this opaque transport without entering raw EXR radiance or changing primary coverage. Composition regressions check an analytic partial-coverage emitter, every checkpoint, worker quanta and unchanged raw masters; these renderer regressions have executed.

The general Glass route adds certified closed meshes, nested media, inside-eye/pupil classification and delta transport when Path is explicit. Selected reflection overrides and certified anisotropy remain refused with Path; authored values are retained. Selected-medium subsurface scattering, bounded Atmosphere, Sun/Sky and independent-pilot adaptive sampling are implemented and included in the published test suites. Active Atmosphere cannot combine with Glass/SSS or surface Denoise. Active selected-medium scattering also requires disabled surface Denoise. Optional Glass material models add GGX rough transmission, three-band dispersion, one lossless coherent film and finite-radius hard-source photon caustics. Emissive-mesh next-event sampling remains separate work. Native CPU workers support parallel camera and photon transport. Every request still has its own geometry, memory, work and compatibility admission. The CPU Sampling control and CPU Glass transport entry point require explicit progressive adoption for saved fixed choices. Disabling path lighting preserves existing settings and returns to the original sheet/box or opaque transports.

The serial path owns one exact-capacity fallible continuation, prepaid in CPU job admission. Native camera and photon workers add bounded continuations, stacks and scratch for their admitted count while sharing the scene, BVH and film. Auto selects available parallelism once, capped at 64, and records it in the admission receipt's cpu_workers field. Execution keeps that count even if host parallelism changes before pool creation. Single creates no parallel pool; explicit counts from 2 through 64 remain exact. Browser execution supports Auto and Single only and preserves an unsupported saved custom count on refusal.

Sampler/source/emitter scans, traversal, shading and the final film commit remain bounded continuations sharing one cumulative work budget and cancellation token. Workstation's image/preparation admission envelope is 128 GiB. Its limits are 2^43 total camera samples and 2^60 work units; Compact and Studio keep their smaller envelopes. BVH preparation retains its separate 12 GiB cap. The fixed host metadata/task-state size guards still apply.

Native CPU and registered GPU hosts share a reservation ledger with a 256 GiB software ceiling and a separate available-RAM snapshot. CPU hosts also retain their own finite 256 GiB software pool. Retained request and resource metadata are charged in addition to the image/preparation estimate, against both the host pool and shared ledger. Working buffers, previews and final artifacts also hold leases; split/transfer/shrink/cancel/drop preserve their accounting.

The snapshot funds one allocation epoch. It stays fixed while capture, prepared or queued jobs, running work, or reusable checkpoint credit can still allocate. Once no unsettled allocation promises or active work remain, the next admission refreshes it even if immutable images, previews or metadata remain alive. Those objects keep their software leases; their old physical debits are excluded from the new epoch because the fresh OS observation includes the machine's current memory state.

Native preflight reports the full required_bytes, already-held credited_bytes, new additional_bytes and other held software admitted_bytes. The remaining available_bytes applies to additional bytes: it is capacity_bytes minus the current physical_debit_bytes, saturating at zero. The receipt also reports the software limit, source and policy. An unavailable query uses a labeled allowance of at most 512 MiB, bounded by any reported cgroup limit, and keeps all held leases in the physical debit. Retained objects cannot renew that fallback allowance. See quality controls for the full receipt contract.

The default AvailableRam policy also enforces the epoch's remaining physical allowance. The machine Graphics preference Use previous render memory checks (render_legacy_memory_admission, default false), CLI --legacy-memory-admission, or host API NativeMemoryPolicy::SoftwarePoolOnly restores admission based on software budgets. It skips only the RAM-fit refusal: shared and host software limits, device checks and fallible allocations remain. Legacy leases remain in software accounting, and their current-epoch physical debits reduce the allowance for a host using the RAM gate. The receipt continues to report actual observed capacity, including zero. A policy switch applies to future checks/reservations without releasing current leases. The snapshot cannot account for future allocations by unrelated processes. A refusal does not lower samples, output size or workers. See CPU resource profiles for the full envelopes and quality controls for the shared UI contract.

Executed renderer regressions cover analytic Lambert density/furnace, full coat PDF consistency, projected-solid-angle rectangle means, real diffuse red bounce and blocker, every-prefix/quanta/raw-master invariants, exact admission delta and cancellation/work exhaustion. Published document, engine and workspace tests also cover saved/runtime capture and Sampling click/Undo/reopen. These test results do not qualify a native Glass image or complete image-quality acceptance.

Rectangle support uses the full admitted two-vector basis, including the common near-orthogonal tolerance and extreme aspect ratios. Geometry wins model/emitter equal-distance ties in both continuation and direct visibility. Positive-area overlapping, same-facing coplanar rectangle supports refuse before capture; the bounded projected-bounds guard is conservative for rotated supports and retains all authored sources. Adjacent supports and opposite one-sided emitters remain valid. Stratified HDR/area source inputs alone are made representably open at floating-point endpoints; the camera counter stream is unchanged.

The CPU denoising prepass tests each admitted analytic rectangle only when this path mode is enabled. A strictly closer, front-facing emitter produces a bypass guide instead of borrowing the diffuse body behind it; geometry keeps exact distance ties. Each of at most four source scans has its own cumulative work debit and cancellation check. Its scalar continuation state is prepaid in the existing exact guide-state size, with no additional image plane. The absent-path guide algorithm performs no new source scans. Combined numerical and lifecycle renderer tests for these invariants have executed; native image-quality acceptance remains pending.

The optional finite Sun and gradient Sky use the shared saved radiance domains, separate emitter MIS and bounded cooperative stages. They require explicit Path transport and preserve default-absent behavior; see CPU celestial lighting for the source contract and the shared qualification limits.