Write down why the animated array's draws still merge

The rule and its cost are not obvious from the code: the substitution is per
draw, so the merge test is too, and getting that wrong is worth 6 ms of GPU time
a frame in a race.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

OPENXR.md

@@ -407,6 +407,13 @@ the copy (for 30 frames running; the race's opening pan does this) a separate VR
 which is also what `native_steering_wheel = false` draws. The copy keeps being published, so the
 vehicle's own wheel returns as soon as draws take it again, and the log notes both switches.
 
+The substitution is decided per draw, and a draw that folds into a neighbour renders through that
+neighbour's array binding, so only draws that reached the same decision may merge. Deciding this
+per array instead, and so refusing to merge every primitive that binds the vehicle's array, cost 6 ms
+of GPU time a frame on a Quest 3 (a race frame has 228 such primitives, recorded once and replayed in
+the mono pass and both eyes) and took a 56 FPS race down to 42. `debug.wiicompiled.fpslog 1` reports
+the draw calls a frame and the primitives merged away, which is where that shows up first.
+
 The copy is matched against the race camera's view (`RaceCamera::GetViewMtx` with no dolly offset),
 because the scene camera is only set once the draws run. The log reports, once a second, how far
 that view is from the scene camera at the seal (`[mkw-vr] cockpit: race camera view vs scene view`)

docs/quest-port.md

@@ -633,7 +633,7 @@ the app:
 | `debug.wiicompiled.validation 1` | Keeps WebGPU validation and robustness on in release builds |
 | `debug.wiicompiled.panel_layer 0` | Draws the headset settings panel into the eye images instead of on its own quad layer (`OPENXR.md`, Settings in the headset); read about once a second, so it can be switched while the panel is open |
 | `debug.wiicompiled.inject <n>:<button>` | Presses `a`, `b`, `x`, `y`, `start`, `up`, `down`, `left` or `right` for 12 XR frames each time `<n>` changes. As a Wii Remote, `x`/`y`/`start` are 1/2/+, the directions push the Nunchuk stick, and `home`, `c` and `z` also exist. `panel` presses the settings panel's button (left Y, or both thumbsticks as a gamepad), opening or closing it (see `OPENXR.md`) |
-| `debug.wiicompiled.fpslog 1` | Logs the game's rendered frame rate every 5 s, with per-frame averages of the producer's waits for the frame worker's DONE and SEALED phases and of the worker's seal, permit wait, prepare and encode stretches. A third line reports the GX thread's command ring (records, waits, busy share). A second line gives the GPU time per frame from timestamp queries on every pass (`mono` native render, `eyeL`/`eyeR` replays, `screen`, `panel`, `efbcopy`, `palette`, `peek`, plus `passes-span` from the first pass begin to the last pass end and `between-passes` for copies and idle gaps). The compositor's `VrApi` log line gives headset FPS, `GPU%`, `CPU%`, clock levels and app GPU time (`App=`) |
+| `debug.wiicompiled.fpslog 1` | Logs the game's rendered frame rate every 5 s, with per-frame averages of the producer's waits for the frame worker's DONE and SEALED phases and of the worker's seal, permit wait, prepare and encode stretches, and of the draw calls the recorded frame holds and the primitives that merged into them (an overlay that stops draws merging shows up there first). A third line reports the GX thread's command ring (records, waits, busy share). A second line gives the GPU time per frame from timestamp queries on every pass (`mono` native render, `eyeL`/`eyeR` replays, `screen`, `panel`, `efbcopy`, `palette`, `peek`, plus `passes-span` from the first pass begin to the last pass end and `between-passes` for copies and idle gaps). The compositor's `VrApi` log line gives headset FPS, `GPU%`, `CPU%`, clock levels and app GPU time (`App=`) |
 
 A `Config.toml` written with `adb push` (or `sed -i` in `adb shell`) belongs
 to the shell user afterwards, and the app then fails every save with EACCES