Review: preserve active display field during interlaced drawing

[Alexbeav]

When 480i drawing prohibits the active display area, raster primitives currently overwrite both row parities. A guest field-detection loop can then stay black at startup. Preserve the selected parity through native-row clipping, restore the caller clip and re-arm precision/perspective metadata on each submission. Fills, copies and transfers remain unmasked. The facade counts each original perspective triangle once, so row metadata re-arms do not inflate diagnostics. No title detection or guest code changes.

This is the required fork review; do not merge into fork main. Intended upstream: mstan/psxrecomp.

Base 155e269ba5d50fe36523846f908cf124dc1561a0; review head 6fcfb8adbdcd666a2fc8ba419dd4e2aa7ee1faaa; five focused commits; 11 changed files:

• docs/GPU_INTERLACED_RASTER.md
• runtime/CMakeLists.txt
• runtime/include/gpu.h
• runtime/include/gpu_interlace.h
• runtime/include/gpu_render.h
• runtime/include/gpu_sw_renderer.h
• runtime/src/gpu.c
• runtime/src/gpu_render.c
• runtime/src/gpu_sw_renderer.c
• runtime/src/gpu_vk_renderer.c
• runtime/tests/test_gpu_interlace_render.c

Runtime files implement the field rule and facade-owned counter; backend metadata setters remain side-effect-free with respect to counting, and backend wide-overlay policy remains unchanged outside field masking; the C fixture tests mode/parity, all nine primitive families, native/4x output, clip restoration, transfers and metadata consumption and logical-triangle counts; CMake registers it; the document describes the invariant and prior behavioral evidence. Source-owned synthetic data only.

Validation on this review head, Windows x64 / WinLibs GCC16.1:

• Runtime CTest: 69 enabled pass; 2 pre-existing disabled. The initial review head fails 8 added counter assertions. The pre-bounds head fails exactly 2 bounded-row checks while pixel comparisons pass. Both fields at native/4x match unmasked pixel oracles even when precise vertices cross integer bounds. A tiny precise triangle submits 3 row clips instead of 256. A backend that intentionally ignores the clip reproduces 40 wrong field rows on the previous facade. Field-masked flat rectangles now submit one-row geometry, while the ordinary overlay geometry and backend policies stay unchanged. Both parities, no duplicate writes and clip restoration pass. This is a backend-contract fixture, not Vulkan hardware pixel qualification. Focused command: ctest --test-dir <runtime-build> -R gpu_interlace_render_test --output-on-failure.
• Recompiler suite:58/61 enabled pass;3 disabled. The three failures also reproduce from pristine upstream source: dirty_text_continuation_guards expects an absent source fragment; release_zip expects LF bytes on Windows; aot_overlay_discovery fails its hardcoded MSYS gcc subprocess. Recompiler sources are unchanged by this PR. Python tests ran with PYTHONUTF8=1.
• Owned Pro Pinball: Timeshock! USA SLUS-00639: fresh process through game frontend, start player game, launch ball, flipper/ball interaction and normal TCP quit at frame 6925. Exact build identifies this head. Digital pad, software/native, existing owned generated game/SCPH5552 code reused unchanged; no emitter-regeneration claim. The title is a private local port, so no public game source or copyrighted payload is attached.
• Repeat evidence: unchanged exact executable also completed a second fresh player route at frame 6923. One earlier attempt on this head stayed in the startup pixel-test loop through frame 6925 and then exited by TCP request. Its cause is unestablished; a prior-head comparison passed, and the exact edge-pixel synthetic case passes. Do not read the successful repeats as proof that startup is free of intermittent failures. The private staging failure in a separate control never launched a runtime and is excluded.
• Current upstream runtime does not compile with public recomp-ui/master773155ae: unrelated new lobby/spectator fields are missing. Retail qualification therefore uses supported PSX_RECOMP_UI=OFF, direct runtime launch into the game frontend. This is not launcher compatibility acceptance.

Field selection uses the existing vertical-blank latch, not scanline-accurate timing. Row clipping can increase hardware submissions; a separate readback correction addresses the measured GL synchronization cost. No Vulkan-wide, netplay, full-game, all-audio or save/load acceptance is claimed. Runtime-only consumer pin update is required; no game regeneration is required by this correction.

Developed with AI assistance; validated as described (test evidence in PR body). AI writes the code and the PR, but I always test before I send something up. Happy to iterate on this process with your feedback.

[Alexbeav]

@cubic-dev-ai review this PR

[cubic-dev-ai]

@cubic-dev-ai review this PR

@Alexbeav I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files

<sub>Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[Alexbeav]

Both findings are valid and fixed in 4390971. The GPUSTAT comment is restored to its register-read function. Logical perspective counting now belongs to the facade, while per-row backend metadata setup does not count another triangle. The old head fails 8 new counter assertions; the updated runtime suite passes all 69 enabled tests. The exact updated game build repeats the fresh frontend/player/ball/flipper route and exits normally at frame 6922. The accepted private product is unchanged.

@cubic-dev-ai review this PR

[cubic-dev-ai]

Both findings are valid and fixed in 4390971. The GPUSTAT comment is restored to its register-read function. Logical perspective counting now belongs to the facade, while per-row backend metadata setup does not count another triangle. The old head fails 8 new counter assertions; the updated runtime suite passes all 69 enabled tests. The exact updated game build repeats the fresh frontend/player/ball/flipper route and exits normally at frame 6922. The accepted private product is unchanged.

@cubic-dev-ai review this PR

@Alexbeav I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

All reported issues were addressed across 11 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 9 files (changes from recent commits).

<sub>Requires human review: Auto-approval blocked by 2 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[Alexbeav]

All findings from reviews 5125053585, 5125055760, 5125091450 and 5125096465 are addressed on 5aee9c8.

• GPUSTAT and perspective-setter comments now describe their own APIs.
• Original perspective triangles are counted once, including a second valid triangle; degenerate weights have a separate boundary check. Initial source fails the added counter checks.
• Precise row bounds retain integer and fixed-point coverage with a rounding margin. Both fields/native/4x match unmasked pixel oracles; old source fails the two submission-count checks.
• Vulkan wide overlays keep the existing vertical band scissor. The old source fails the extended source guard. This is not Vulkan hardware pixel qualification.
• All 69 enabled runtime tests pass; the exact-head software/native fresh player route closes normally at frame 6920. Broader baseline failures and limits are in the updated body.

The branch update requests the automatic exact-head Cubic review; no second manual review run is requested.

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[Alexbeav]

Review5125143037 is valid: changing the Vulkan Y scissor in every mode broadened the correction. Commit 6fcfb8a restores the original Vulkan overlay path and applies the field mask to flat-rectangle geometry in the facade. GL and Vulkan both have wide-overlay paths that intentionally replace scissors, so row-height geometry protects both while progressive overlays keep their original dimensions. A backend fixture ignores the scissor on purpose: the prior facade fails40 field-row checks; the new source passes both parities, exactly one write per retained row, progressive full-overlay coverage and clip restoration. All69 enabled runtime tests pass. The exact fresh software/native player route result follows in the updated PR body. The branch push requests one automatic exact-head review. No duplicate manual review is requested.

Exact-head retail repeats completed at frames 6923 and 6925 with actual player/ball/flipper play and normal TCP exits. The updated body also discloses the real earlier startup-loop attempt; its cause remains unestablished and it is not discarded as a harness error. The independent 1020,511 pixel case passes. No universal startup, Vulkan driver or timing acceptance is claimed.

[Alexbeav]

Re-scoped against the upstream revert. This change went upstream as RetroPortingToolKit#327 (merge b775d3e, 2026-09-07) and was then reverted by RetroPortingToolKit#336 (merge 2026-09-07T20:00:47Z). Matched Ape Escape retail-BIOS runs (PSX_BIOS_HLE=0, identical generated game/BIOS code, disc, config) stall hard around frames 375-376 with it, versus a normal boot and close at frame 2192 on the parent. Root cause from the revert: per-row backend submission/flushes amplify a pre-existing malformed DMA list into massive GL work. The revert restored the previous missing active-field preservation, so a replacement is still needed with two explicit requirements: bounded per-row rendering cost, and real retail BIOS boot coverage (Ape Escape, PSX_BIOS_HLE=0). Closing this review PR; any future attempt should be a new branch implementing the bounded-cost approach.