Move Doom palette expansion to an indexed-texture shader

[frostney]

Summary

• upload DOOM's 320x200 indexed framebuffer as a grayscale texture and resolve
  its 256-colour palette in a small fragment shader
• upload the palette texture only when the active PLAYPAL slot changes, while
  retaining the current packed RGBA path as a capability fallback
• extend palette equivalence coverage across all 14 palette slots and document
  the controlled current-main performance result

The five-pair steady-state comparison discarded 12 warm-up frames and measured
the next 24 frames per run. On an Apple M1 Max, the packed fallback averaged
4.97 FPS (201.22 ms/frame) and the shader averaged 6.32 FPS
(158.33 ms/frame): 1.27x higher FPS and 21.31% lower whole-frame time.

The frame-8 shader and fallback gameplay captures are byte-identical when only
the live FPS overlay is disabled.

Testing

• npm ci
• npm run generate
• npm test
• npm run check:generated
• npm run test:types
• npm run test:abi
• npm run test:ffi
• npm run pack:check
• make -C examples/doom-gpl verify-source
• make -C examples/doom-gpl test-palette
• make -C examples/doom-gpl smoke
• forced-fallback and shader Freedoom frame comparison
• five alternating paired steady-state Freedoom runs per display path
• git diff --check

The Docker/Xvfb Linux lane was not run locally because no Docker daemon was
available.

Linked issues

None.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b9022577-4b10-4cde-9be4-61cd5d88e770

📥 Commits

Reviewing files that changed from the base of the PR and between 128354f and d10d0a0.

📒 Files selected for processing (1)

• examples/doom-gpl/src/i_video.ts

---

📝 Walkthrough

Walkthrough

The DOOM example now supports indexed-texture shader rendering with an RGBA fallback. Palette tests cover all 14 palettes and 256 entries, build regeneration tracks palette changes, and performance documentation reports updated measurements.

Changes

DOOM rendering and palette pipeline

Layer / File(s)	Summary
Indexed shader rendering and fallback examples/doom-gpl/src/i_video.ts, examples/doom-gpl/Makefile	Graphics initialization, frame updates, palette uploads, fallback selection, shutdown, and generation prerequisites now support indexed shader and RGBA rendering paths.
Full palette validation examples/doom-gpl/tests/palette.test.ts, examples/doom-gpl/README.md	Palette validation covers all 14 PLAYPAL slots and 256 entries, including RGB, alpha, execution-mode, and endianness details.
Performance evidence and reporting benchmarks/application-performance.md, README.md	Documentation adds packed-RGBA versus indexed-shader benchmark results and updates reported steady-state FPS measurements.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DoomFrame
  participant I_FinishUpdate
  participant IndexedTexture
  participant PaletteTexture
  participant Shader
  participant RgbaTexture

  DoomFrame->>I_FinishUpdate: submit indexed frame
  I_FinishUpdate->>IndexedTexture: upload frame indices
  I_FinishUpdate->>PaletteTexture: upload changed palette
  IndexedTexture->>Shader: provide indexed pixels
  PaletteTexture->>Shader: provide palette lookup
  Shader-->>I_FinishUpdate: render palette-mapped frame
  I_FinishUpdate->>RgbaTexture: expand and upload frame on fallback path

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: moving Doom palette expansion to an indexed-texture shader.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the shader path, fallback, testing, and performance updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/doom-gpl/src/i_video.ts`:
- Around line 133-166: Reset uploadedPaletteIndex whenever
initializeIndexedShader creates a new paletteTexture, so the first
I_FinishUpdate after graphics reinitialization uploads the current
packedPaletteBytes. Ensure this reset occurs only after successful texture
creation and preserves the existing palette-index comparison and upload
behavior.
- Around line 212-222: Update both DrawTexture calls in the indexedShaderActive
branches to use WHITE instead of RAYWHITE as the tint, preserving the existing
texture selection and rendering flow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6c440cc1-bef2-4f24-8bbb-2121fff93081

📥 Commits

Reviewing files that changed from the base of the PR and between 21c3641 and 128354f.

📒 Files selected for processing (6)

• README.md
• benchmarks/application-performance.md
• examples/doom-gpl/Makefile
• examples/doom-gpl/README.md
• examples/doom-gpl/src/i_video.ts
• examples/doom-gpl/tests/palette.test.ts