Files
Triforce-Source/docs/capture-slot-ownership.md
ruckus7382sfgsgdf 34b3683441 Triforce v0.2.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:32:48 -06:00

34 lines
2.1 KiB
Markdown

# Pending screenshot slot ownership
Normal debug screenshots use two readback buffers, selected by present parity.
A pending capture may outlive the next non-shot present when the GPU is behind.
Another shot two presents later selects the same buffer. Submitting that new copy
before reading the old capture lets a fast GPU replace the pixels, even though
the later read waits for the older timeline value. The filename/flash analysis
then identifies the old frame while consuming the new frame's bytes.
Before recording a new copy into a pending capture's slot, snapshot that capture
into CPU-owned pixels. Its existing consumer moves the snapshot instead of reading
the reused buffer. Another slot still follows the asynchronous path, and no
pending capture adds no wait. Re-arming starts with no saved snapshot, so the old
pixels cannot be attached to the new frame. The generated-shot path and capture
format/metadata remain unchanged.
`do_present` is serialized by the replay job consumer; synchronous replay calls
hold `sync_order_mu`. The pending state remains in that producer/consumer flow.
There is at most one pending snapshot, with the same pixel allocation the normal
consumer already makes, moved earlier only when slot reuse requires it.
`tests/test_capture_slot_ownership.py` compiles the actual copy-selection, snapshot,
read and pending-consume statements with a queued GPU model. It covers a deferred
capture across a non-shot frame, same/opposite parity, fast/late new completion,
no-pending captures and re-arming across sparse intervals. It checks pixels and
metadata together, and verifies that different slots do not wait before submit.
This models legal GPU ordering; it does not claim to reproduce a hardware race.
This change concerns buffer lifetime. Host-cache visibility is the separate
`invalidate_mapped` contract tracked in PR1502; if that change lands first, retain
its normal-shot invalidation inside `shot_pixels`, after the wait and before the
copy into CPU-owned storage. PR1025's on-demand path still needs the same lifetime
rule when integrated; request paths do not change readback ownership.