Skip to content

refactor(scene): one readback for the compositor's small GPU reads - #211

Merged
kixelated merged 5 commits into
mainfrom
quest/m1/readback
Nov 20, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m1/readback

Conversation

@kixelated

@kixelated kixelated commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

The dark-capture probe (dark.rs) and the keep-clear look (place.rs) landed separately with the same GPU readback plumbing. They now share one helper, rs/moq-scene/src/readback.rs, and each keeps only its pipeline, bindings, and what it makes of the tiles.

Changes

  • New readback::Readback<T> owns what both had: the storage and mapped buffers sized to the reader's largest grid, the rate cap (due, at most every readback::INTERVAL = 250 ms, as both had), the copy after the compute pass, the submit, the map_async in flight, and dropping a read whose picture stopped mattering (discard, or restart, which also makes the next read due at once). T carries what a read is of (() for the probe, the picture's size and whether it was compared for the look).
  • dark::Probe keeps the capture copy, the good picture, and judge; place::Look keeps the ping-ponging pictures and the GAP check, reading Readback::last().
  • dark::INTERVAL is gone (the module is private); its note on which pictures get read moved onto Probe::step. place::INTERVAL stays as an alias of readback::INTERVAL.

This is behavior-preserving: the same dispatches, buffer sizes, copies, rate, and discard rules run each frame, so it needs no user-facing pick.

Validation

  • just ci: passed (lints and 460 tests).
  • GPU tests on Mesa lavapipe (just render-sw's moq-scene filter plus place::): 67/67 passed, including dark::tests::*, compositor::tests::a_camera_keeping_clear_glides_off_what_moves and a_moment_of_dark_draws_the_last_good_picture. Only test edit: probe.reading.is_some() reads probe.readback.busy().
  • The same five readback tests on the real AMD iGPU (Mesa RADV), 5 runs each: all passed. Their wall times (0.3 to 0.4 s branch, 0.4 to 1.1 s base) are dominated by device setup and the host's load (average about 20), so they are no frame-time measurement; a later rerun under heavier load timed out in the machine-wide test scheduler's wait before starting, not in the tests. Frame time cannot grow from GPU work since the recorded commands are the same; the CPU side adds one 9 KiB copy of the probe's grid per read (at most 4 a second) where it used to judge the mapped range in place.

Public API and wire

None. place::INTERVAL keeps its value and type; everything else touched is crate-private.

Decisions

Taken while the maintainer was away; each is easy to undo in review:

  • One readback::INTERVAL for both readers, rather than Readback::new taking an interval. Recommended: both read at 250 ms, and a parameter for a difference nobody needs is weight.
  • Buffers share one label, moq-scene readback, instead of moq-scene dark tiles / moq-scene place tiles. Recommended: keeps new at three arguments; the pipelines and bind groups keep their own labels, which is what a GPU capture shows by pass.
  • A failed map on a stale probe read is now dropped silently, as the look already did, instead of logging a warning. Recommended: the read was being thrown away anyway; a real device fault still warns on the next live read.
  • finish copies the tiles out (Vec<[u8; 4]>) rather than handing a borrowed mapped view, so no guard or callback crosses the API. Recommended: at most 9 KiB, 4 times a second.

Follow-ups

None.

Models

Size: S
Implementer: Claude Code, claude-opus-5-5, medium effort (arm A)

(Written by Opus 5.5 with medium)

Review

Rewritten by quest review after each round.

  • Head: 8bb0bba

  • Base: origin/main at c104a26

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1f37e-c061-7261-8b95-97063d462e50, round 1

  • Score: 9/10, Source review found no actionable regressions, but runtime validation remains unverified because builds and tests were not run.

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, low effort, shadow

  • Session: 01a1f37e-c060-74b3-87d1-b799d938997d, round 1

  • Score: 9/10, The refactor preserves scheduling, buffer handling, and stale-read behavior with no actionable regressions identified, subject to CI validation.

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

kixelated and others added 2 commits November 19, 2026 02:13
Quest-Claim: bbc26dae2b778c4b
The dark-capture probe and the keep-clear look each kept their own storage
and mapped buffers, rate cap, map in flight, and stale-read discard. Both
now share readback::Readback and keep only their pipeline and what they
make of the tiles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title One readback for the compositor's small GPU reads refactor(scene): one readback for the compositor's small GPU reads Nov 19, 2026
@kixelated
kixelated marked this pull request as ready for review November 19, 2026 11:09

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ No correctness issues. One small nit inline.

Approach: sound. It does the one-helper extraction the maintainer settled on #194. The plumbing both readers duplicated moves into Readback<T>, and each reader keeps only its pipeline and what it makes of the tiles. The generic T carries the per-read metadata without forcing a trait on either side.

Reviewed changes I read the whole diff and both readers in full against the base to check that the extraction preserves behavior.

  • New readback::Readback<T>: owns the storage and mapped buffers, the due rate cap, submit/map_async, and finish. discard drops a read that has gone stale. restart does the same and also clears last. I checked each against the code it replaces and they match.
  • dark::Probe: forget still marks the read in flight stale without resetting last. The step gate (changed && due) is the same as the old reading.is_none() && changed && due. judge now runs on the copied Vec flattened back to bytes, which covers the same COUNT * 4 bytes as before. The only behavior change is the one the PR lists: a failed map on a stale read no longer warns.
  • place::Look: restart, due, the recent/GAP check (now via Readback::last()), and the per-read tile count are all unchanged. place::INTERVAL stays as a public alias and is only used inside place.rs.
  • Quest file removed: quest/m1/readback.md is deleted, as the convention for a finished quest requires.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-opus-5-5 | 𝕏

Comment thread rs/moq-scene/src/dark.rs Resolved
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Explain Change →

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 51 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 0f4d6d56-e246-47eb-867f-5050d0c23935
Commits

Reviewing files that changed from the base of the PR and between 8bb0bba and af66f2f.

Files selected for processing: 6

  • quest/m1/readback.md
  • rs/moq-scene/src/compositor.rs
  • rs/moq-scene/src/dark.rs
  • rs/moq-scene/src/lib.rs
  • rs/moq-scene/src/place.rs
  • rs/moq-scene/src/readback.rs

No actionable comments were generated in the recent review.

Walkthrough

The change adds a shared GPU tile-readback abstraction with interval scheduling, asynchronous mapping, stale-read handling, and completion results. The dark probe and item-picture look now use this abstraction instead of maintaining separate readback buffers and state. Their storage binding sizes and tests were updated. Documentation and a test now refer to the shared interval.

Merge Risk: Minimal · previous review 8bb0b

This refactor shares one GPU readback helper between the dark-capture probe and the keep-clear look, with no stated change in behavior, API or wire format. I found no concrete defect, and the change is easy to revert. The remaining uncertainty is that I did not independently run the GPU tests.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: a refactor that consolidates the dark-capture probe and keep-clear look's GPU readback code into one shared helper in the compositor. It is specific and matches the ch…
Description check Passed The description states that the dark-capture probe and keep-clear look shared the same GPU readback code, and that both now use one helper, readback.rs. It lists the helper's responsibilities, the rem…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: a refactor that consolidates the dark-capture probe and keep-clear look's GPU readback code into one shared helper in the compositor. It is specific and matches the changeset, which adds readback.rs and removes duplicated buffer, mapping, and rate-cap logic from dark.rs and place.rs.

Full details: Description check

Explanation

The description states that the dark-capture probe and keep-clear look shared the same GPU readback code, and that both now use one helper, readback.rs. It lists the helper's responsibilities, the removed dark::INTERVAL, the test edit, and validation results, all of which match the changeset.

Finishing Touches

Simplify code

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 34cd1232-c0f6-481a-bfa2-a12896ff4a36
Commits

Reviewing files that changed from the base of the PR and between c104a26 and 8bb0bba.

Files selected for processing: 6

  • quest/m1/readback.md
  • rs/moq-scene/src/compositor.rs
  • rs/moq-scene/src/dark.rs
  • rs/moq-scene/src/lib.rs
  • rs/moq-scene/src/place.rs
  • rs/moq-scene/src/readback.rs
Files with no reviewable changes: 1

  • quest/m1/readback.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found. The earlier nit is fixed and nothing else changed.

Reviewed changes Since the review of 8bb0bba, there is one comment-only commit and a merge of main.

  • Rewrapped the Probe::step doc comment (3cc8a87): wrapped at about 78 columns, as the earlier nit suggested. The text is the same.
  • Merged main (9264387): brings in 5ae83b0. It does not change the PR's net diff, and nothing new on main uses the removed dark::INTERVAL or the Look fields that moved into Readback.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated
kixelated enabled auto-merge (squash) November 20, 2026 01:08
@kixelated
kixelated merged commit 8daa605 into main Nov 20, 2026
4 checks passed
@kixelated
kixelated deleted the quest/m1/readback branch November 20, 2026 01:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant