docs: add MoonRay comparison and adoption plan - #114
Open
doubleailes wants to merge 6 commits into
Open
Conversation
Subsystem-by-subsystem study of DreamWorks MoonRay (openmoonray, Apache-2.0) against crust, read from the MoonRay sources: render driver and pass/tile scheduling, vectorized shading and XPU, sampling and adaptive stopping, checkpoint/resume, light sampling, materials, geometry, volumes, texturing, AOVs/LPEs, and denoising. Takeaways select three items for adoption in this pass — a unified Morton-ordered 8x8 tile/pass scheduler, split-buffer (odd/even) adaptive sampling with a per-tile state machine, and bit-exact checkpoint/resume — and record the rest as documented-only future work. Concepts are ported, not code. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
Adopt MoonRay's driver shape (concepts, not code — docs/moonray_comparison.md):
fixed 8x8 tiles visited in a precomputed permutation (Morton by default;
spiral, scanline, random via --tile-order / crust:tileOrder), distributed
through a virtual work queue — one atomic cursor synthesizing tile groups,
drained by every Rayon pool thread. This replaces both previous drivers:
the scanline mode paid a Rayon barrier per row, and the bucket mode
hard-coded unordered 16x16 tiles; -b/--bucket is now a hidden deprecated
no-op. Guiding training-sample merge order is pinned to tile order, so
renders stay deterministic under any thread scheduling.
Also lands the pass machinery the next commits consume: Pass{pixel range,
sample range} over a Bayer-dispersed 64-slot fill order, PassSchedule (a
pure function of (spp, min_spp) — the resume-alignment contract, with
suffix and global-sample-id-range constructors after MoonRay's
convertSampleIdRangeToPasses), all pinned by unit tests (permutation,
exactly-once coverage, suffix invariant, head/body/tail roundtrip).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
Replace the per-pixel stop test that lived inside the sampling loop — a numerically fragile luminance sum-of-squares checked every 4th sample — with the Dammertz-style split-buffer estimator MoonRay uses: a new Film accumulator keeps a second buffer of odd-indexed samples per pixel, and the distance between the full-rate and half-rate means (which vanishes as 1/sqrt(n)) is the stopping error, normalized to preserve the historical relative-standard-error meaning of crust:varianceThreshold (folded-normal calibration factor 0.798, derived in film.rs). Rendering now walks the PassSchedule: dispersed coarse passes for sample 0, then doubling fine passes, with adaptive decisions made between passes per tile — a Uniform -> Adaptive -> Completed state machine that only retires a tile when every pixel of the tile plus a one-pixel neighbour ring has converged (the cheap stand-in for MoonRay's overlapping adaptive regions). render_pixel becomes render_pixel_samples over an absolute sample range, so a range renders identically whether taken in one pass, split across passes, or (next commit) resumed from a checkpoint. PassStats (variance + var_map) is now computed from Film moments with the same formulas as before, so guiding's inverse-variance pass blending and efficiency estimate are unchanged; training passes run through the same driver, non-adaptive. Progress totals shrink as tiles converge. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
The engine side of MoonRay-style resumable rendering. A new
render_with_options entry point takes RenderOptions {progress,
checkpoint_interval, on_checkpoint, resume}: at uniform pass boundaries,
once the interval has elapsed, the driver thread hands a CheckpointState
(raw radiance sums, odd-sample sums, per-pixel counts, the boundary's
sample index, and a settings fingerprint) to the callback — plain data,
no encoding, so crust-core keeps its no-image-deps rule and the CLI owns
serialization.
Resume restores the film, validates dimensions and fingerprint
(RenderSettings::fingerprint — stable FNV-1a over every setting that
changes what a (pixel, sample) evaluates to, deliberately excluding
samples_per_pixel so a resume can extend the budget), re-enters the pass
schedule at the checkpoint's boundary, and re-derives tile stages from
the restored counts — a tile frozen below the boundary was retired
earlier, a tile at the boundary gets exactly the convergence check the
straight run performed there on identical film state. Resume is
therefore bit-exact, adaptive or not, which the new integration tests
pin: straight render == checkpointed render == interrupted-and-resumed
render, pixel for pixel. Guided renders refuse to resume
(Error::CheckpointUnsupported) and warn-ignore checkpoint options.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
Persist the engine's pass-boundary snapshots as multi-channel EXRs: R/G/B carry the raw radiance sums (the file previews count-times bright, but raw f32 sums are what round-trip bit-exactly), crust.oddR/G/B the odd-sample sums, crust.count the per-pixel counts (exact through f32 up to 2^24 spp, enforced), with the resume metadata (contract version, next sample boundary, settings fingerprint) as EXR header attributes. Writes go to a sibling temp file and rename into place, so a checkpoint is never observed half-written — a render killed mid-write still resumes from the previous snapshot. New flags: --checkpoint-interval <SECS> enables snapshots (and refreshes the tone-mapped preview PNG on each one), --checkpoint-file overrides the default <output>.checkpoint.exr location, --resume [PATH] restores and continues — raising -s/--samples extends the interrupted render, and a checkpoint already at or past the target is returned as-is. Mismatched scene/settings are rejected with the engine's fingerprint diagnostics. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
Flip the moonray_comparison takeaways from planned to as-built (with the final calibration factor, the neighbour-ring convergence rule, and the adaptive-inclusive bit-exact resume guarantee), and update CLAUDE.md: commands and CLI flags, the pass/tile driver and Film in the pipeline overview, the split-buffer adaptive sampling section, checkpoint/resume, and the crust:tileOrder settings attr. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna
Contributor
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Subsystem-by-subsystem study of DreamWorks MoonRay (openmoonray,
Apache-2.0) against crust, read from the MoonRay sources: render driver
and pass/tile scheduling, vectorized shading and XPU, sampling and
adaptive stopping, checkpoint/resume, light sampling, materials, geometry,
volumes, texturing, AOVs/LPEs, and denoising.
Takeaways select three items for adoption in this pass — a unified
Morton-ordered 8x8 tile/pass scheduler, split-buffer (odd/even) adaptive
sampling with a per-tile state machine, and bit-exact checkpoint/resume —
and record the rest as documented-only future work. Concepts are ported,
not code.
Co-Authored-By: Claude Fable 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_014NCtYASYFsjNLTQXeWvkna