retroDE_ps2/docs/ch416_subpixel_xy_prefit.md

Ch416 — native XYZ 12.4 coverage

Objective

Carry the captured GS fractional screen coordinates through the fixture, primitive FIFO, and raster coverage test. This is a fidelity chapter: draw population, texture state, fog fold, bilinear filtering, Z behavior, and chronological ordering remain the Ch415 baseline.

RTL cut

• gs_stub has an opt-in SUBPIXEL_XY path that retains each vertex's four X/Y fractional bits alongside the existing small primitive FIFO.
• Edge equations use 12.4 endpoints and sample the pixel center at +8 in that domain. The operands are bounded to signed 17-bit coordinates and signed 35-bit edge results.
• The production GS_SH3_LPDDR_FB profile enables the path. Legacy profiles retain integer corner-sampled coverage.
• Attribute gradients remain on the proven integer coordinate basis for this first structural cut. Moving gradient setup to 12.4 is explicitly deferred and is not hidden inside this coverage change.

Fixture and generator controls

--subpixel-xy emits native XYZ2 low-half 12.4 coordinates. Capacity scheduling measures the same 12.4 pixel-center coverage so narrow visible triangles cannot be discarded after integer collapse. Runtime-CLUT fixtures retain the proven single staging CBP and adjacent identical assets without the obsolete preloaded-palette uniqueness gate.

The full zsrt139f17 fixture uses --legacy-strip-kicks to preserve the exact Ch415 strip population. This makes the experiment one-variable: changing the newer strip-population interpretation at the same time would remove broad scene layers and invalidate the A/B comparison.

Evidence so far

• Legacy raster regression: 16/16 pixels PASS.
• Directed subpixel raster regression: 3/3 pixel-center samples PASS.
• Authentic three-draw integration: 5,909 fragments fed, 5,907 Z-passing, zero drops, 0/307,200 Z mismatches, and 0/5,858 color mismatches.
• Full software reconstruction versus PCSX2 improves from Ch415 MAE 21.0852 / RMSE 32.3385 to Ch416 MAE 19.8099 / RMSE 28.8334. Lit RGB pixels rise from 174,167 to 212,915.
• Full 263-epoch RTL integration PASS: 1,139,213 fragments fed, 969,301 Z-passing, zero drops, 263 markers and ordered drains, no color FIFO or AXI response errors, 0/307,200 final Z mismatches, and 0/235,942 final color mismatches.
• The Ch416 RTL framebuffer improves against PCSX2 to MAE 20.4941 / RMSE 30.0163 with 199,104 lit RGB pixels. This is a large improvement over the Ch415 board result at MAE 23.6438 / RMSE 35.0255 and 110,329 lit RGB pixels.
• RTL versus the Ch416 software reconstruction measures MAE 10.1578 / RMSE 19.1650. Native coverage closes a substantial part of the hardware/software gap, but fractional attribute-gradient setup remains visible fidelity debt.

Artifact SHA-256 identities:

• full epoch descriptor: ba1484d23cc9a0caba9d4f82af7ed157fbe692c54a9138d5c0aa02f5ca9f3d87;
• RTL framebuffer MEM: 6aa98a68ee59b5df8457b651baf12decbbb7b71c70c4029ff2cb144a3defa1de;
• RTL framebuffer PNG: 709d6a1438355531b38723654f27b0b07e49524af10d33388fdbb744739cf7b3;
• software reference PNG: 63944f31b8c5f55b70bbddbb89db4ac0ed782a4daf8bd6dad8bb8ad8ec9ad006.

First owner fit and timing repair

The first owner-controlled Quartus 26.1 GUI fit completed, but is not eligible for deployment. EMIF user-clock setup was -0.433 ns WNS / -6.069 ns TNS; hold was 0.000 ns with zero TNS, and recovery, removal, and minimum-pulse checks were clean. The top-ten setup failures were one physical family from the EMIF lock_sync_inst|dreg[1] reset source into duplicated u_zc_emit|u_req|...|address_reg_b[2] registers. This was reset routing into the request FIFO's synchronous-read RAM implementation, not the new subpixel coverage datapath.

gs_async_fifo no longer resets rdata_q in REGISTERED_READ mode. That value is invalid until an accepted read and every consumer already qualifies it with the read transaction, so the reset value had no functional meaning. The cut removes the 5,331-fanout EMIF lock/reset route from the duplicated RAM registers without adding a timing exception or changing FIFO latency.

Post-repair evidence:

• generic asynchronous FIFO scoreboard PASS: 3,284 writes and reads, zero duplicate/drop/order errors;
• Z/color emitter PASS: 1,500 fragments across three epochs plus directed ZTST=ALWAYS, exact final Z/color, col_ovf=0, bresp_err=0;
• three-epoch native-subpixel integration PASS: 5,909 fed, 5,907 passed, zero drops, exact 0/307,200 Z and 0/5,858 color mismatches.

Owner fit gate

The repaired owner-controlled Quartus 26.1 GUI fit closed cleanly: EMIF setup is +0.047 ns WNS / 0.000 ns TNS, hold is 0.000 ns WNS / 0.000 ns TNS, and recovery, removal, and minimum-pulse checks are clean. The fit uses 37,959 / 46,800 ALMs (81%), 5,261,744 / 7,331,840 memory bits (72%), 336 / 358 RAM blocks (94%), and 157 / 376 DSP blocks (42%). The deployed RBF SHA-256 is 965e15eabdba5260a8d3c795b39a39bebc707d31fee70e3af857ec7e03f94f82.

Board acceptance

The full 263-epoch board run passed every texture CRC, runtime-palette sum, staging-record count, ordered drain, and fragment-drop gate. The scheduler finished rc=0; the FPGA manager remained operating. The captured board framebuffer has 235,346 nonzero words, bounds (0,0)..(511,479), sum32 0x19291e79, and xor32 0x05d6395b.

Most importantly, the board framebuffer is bit-for-bit identical to the full RTL simulation. Both MEM files have SHA-256 6aa98a68ee59b5df8457b651baf12decbbb7b71c70c4029ff2cb144a3defa1de, and both PNG files have SHA-256 709d6a1438355531b38723654f27b0b07e49524af10d33388fdbb744739cf7b3. Board versus the bilinearly resized PCSX2 frame measures MAE 20.4941 / RMSE 30.0163 with 199,104 lit RGB pixels. Ch416 therefore realizes its simulated fidelity gain on hardware and is accepted.