dusk/.claude/display-refactor.md

# Display Layer Refactor

## Vision

The goal is to remove the implicit assumption that all platforms render
through a GL-like API, and replace it with a system where each platform
owns its rendering stack completely. The scene describes *what* to draw
in platform-neutral terms; the platform decides *how* to draw it.

This unlocks:
- Saturn (VDP1/VDP2 command-list, no Z-buffer, affine-only)
- PlayStation 1 (ordering table, affine textures, GTE fixed-point, CMake SDK)
- Nintendo 64 (RSP display list, hardware Z-buffer, perspective-correct,
  real FPU -- closer to modern GL than to Saturn)
- SNES (PPU tile engine, Mode7 for overworld, no real 3D)
- Vulkan (explicit, modern, no legacy GL baggage)
- Native PSP GU (drop PSPGL which is just a compatibility shim)
- Legacy fixed-function GL as its own standalone target
- A real first-class 2D UI system not bolted onto 3D space

---

## Why

### The current abstraction assumes GPU-style rendering

The current display layer was designed around a GL-like mental model:
vertex buffers, shaders, Z-buffered triangle rasterization, and texture
objects. `duskgl` implements this with real OpenGL. `duskdolphin` does its
own GX thing but still matches the same interface (mesh, shader, texture,
framebuffer). PSP uses PSPGL -- a library that *emulates* GL on top of
the PSP's native GE/GU hardware, which is entirely different underneath.

Problems this creates:

**PSPGL is a lie.** The PSP has a native graphics engine (GE/GU) with its
own command list, its own vertex formats, and its own display list model.
PSPGL translates GL calls into GU calls, but imperfectly -- and we end up
paying the abstraction cost without getting GL correctness. Writing directly
to GU gives better performance, access to native formats, and correct
behavior on edge cases that PSPGL gets wrong.

**Legacy GL should not share code with modern GL.** The fixed-function
pipeline (no shaders, matrix stacks via glMatrixMode, glTexEnv) is
meaningfully different from modern GL (VAO/VBO, GLSL, explicit uniform
locations). Treating them as "the same thing with a flag" creates a tangle
of `#ifdef DUSK_OPENGL_LEGACY` guards throughout the rendering code.
They are separate targets and should be separate platform directories.

**Saturn cannot fit the model at all.** VDP1 is a command-list processor:
you write 32-byte command structs (sprites, quads, lines) into VRAM, then
poke a register to trigger execution. There are no vertex buffers, no
shaders, no Z-buffer. Depth is pure painter's algorithm -- command order
IS the depth. VDP2 composites up to 6 background planes at scanline time;
these are tile maps and rotation parameter tables, not meshes. Nothing
about the current API maps onto this hardware.

**SNES is even further removed.** The PPU renders tiles. VRAM holds 8x8
or 16x16 pixel tiles and tile maps; the PPU references these during
scanline rendering. There are no draw calls. Mode7 is an affine transform
applied to a single background layer (the basis for the overworld map and
road perspective effects). Sprites are entries in OAM (Object Attribute
Memory). The 65816 CPU writes to memory-mapped registers and VRAM; the
PPU does the rest. The concept of "mesh" or "shader" is meaningless here.

**Textures loaded as RGBA waste memory and exclude platforms.** Loading
every texture as 32-bit RGBA and converting at runtime is expensive on
memory-constrained platforms (Saturn has ~1 MB total RAM; SNES has 64 KB
VRAM) and simply wrong for platforms that have native formats incompatible
with RGBA (e.g., PSP's ABGR8888 / BGR5650, Saturn's RGB555 / CI4 / CI8,
SNES's 2bpp/4bpp/8bpp indexed). The asset pipeline must compile textures
to platform-native formats at build time.

**UI in 3D space is wasteful and limiting.** Currently UI elements are
rendered as geometry projected into screen space, going through the full
3D pipeline. On platforms with dedicated 2D hardware (Saturn VDP2,
SNES BG layers), this is actively wrong -- UI should map to a hardware
plane, not a 3D draw call. On modern platforms it should be a clean
screen-space pass that never touches the 3D depth buffer.

---

## Current Model (Summary)

```
Scene
  -> shaderBind(shader)
  -> textureBind(texture)
  -> meshDraw(mesh)          <-- immediate draw call per object
  -> meshDraw(mesh)
  -> ...
Platform receives each draw call immediately.
Depth is handled by Z-buffer hardware.
All textures live in GPU memory as RGBA (or Dolphin's tiled RGBA).
UI is rendered as 3D geometry with an orthographic projection.
```

Key current concepts:
- `mesh_t` -- vertex array (triangles/quads), in GPU VBO (GL) or CPU
  memory (Dolphin)
- `shader_t` -- GLSL program (modern GL), GL fixed-function state
  (legacy GL), or GX matrix + TEV config (Dolphin)
- `texture_t` -- GPU texture handle (GL) or tiled CPU buffer (Dolphin);
  always RGBA at the engine level
- `framebuffer_t` -- FBO (GL) or fixed hardware XFB (Dolphin)
- `spritebatch_t` -- accumulates 2D quads and flushes in batches of 32;
  the only existing deferred-submission system in the engine

The spritebatch hints at the right model. Everything needs to work this way.

---

## The Core Shift: Platform-Native Rendering

### Before

```
src/dusk/       Core engine + GL-like rendering API definition
src/duskgl/     OpenGL implementation
src/dusksdl2/   SDL2 window/input (shared)
src/duskpsp/    PSP via PSPGL (shim over GU)
src/duskvita/   Vita via GL ES (similar path to duskgl)
src/duskdolphin/ GameCube/Wii via GX (already custom)
src/dusklinux/  Linux (uses dusksdl2 + duskgl)
```

### After

```
src/dusk/          Core engine logic + render intent API ONLY
src/dusksdl2/      SDL2 window/input (unchanged)
src/duskgl/        Modern OpenGL (Linux, Vita modern path)
src/duskgllegacy/  Fixed-function OpenGL (older hardware, PSP with PSPGL
                   as a last resort)
src/duskvulkan/    Vulkan (Linux modern, future)
src/duskpsp/       PSP native GU (no PSPGL, direct command lists)
src/duskvita/      Vita native GXM (TBD)
src/duskdolphin/   GameCube/Wii GX (already custom, mostly kept)
src/dusksaturn/    Saturn VDP1/VDP2 (new)
src/duskps1/       PlayStation 1 ordering table + GTE (new)
src/duskn64/       Nintendo 64 RSP/RDP display list (new)
src/dusksnes/      SNES PPU/Mode7 (new, extremely constrained)
```

`src/dusk/` no longer knows about meshes, shaders, or framebuffers.
It defines the *render intent* system: what the scene wants to draw.
Each platform directory is entirely self-contained and responsible for
translating intents to its native API.

---

## Render Intent System (new)

Instead of the scene calling `meshDraw()` or `shaderBind()`, it submits
render intents into a `renderqueue_t`. An intent describes what should
appear on screen without prescribing how to draw it.

### Primitive intents (3D world)

```
RENDER_INTENT_QUAD      -- textured quad, 4 vertices or transform + size
RENDER_INTENT_POLYGON   -- filled polygon (convex, up to N vertices)
RENDER_INTENT_LINE      -- line segment or polyline
RENDER_INTENT_SPRITE    -- 2D billboard (always faces camera)
RENDER_INTENT_MESH      -- arbitrary vertex array (GL/GX only; degraded
                           on command-list platforms)
```

Each intent carries: texture reference, color/tint, depth hint (for
painter's algorithm sorting), blend mode, and cull flags.

### Background plane intents (2D layers)

```
RENDER_INTENT_BGPLANE   -- configure a background/tilemap layer
```

Carries: layer index, tile map data reference, scroll offset, palette,
and transform (for Mode7-style affine).

### UI intents (screen space)

```
RENDER_INTENT_UI_RECT   -- solid colored rectangle
RENDER_INTENT_UI_SPRITE -- textured rectangle (UI image)
RENDER_INTENT_UI_TEXT   -- text string at screen position
```

UI intents are always screen-space. They are never mixed into the 3D
world queue. See UI System section below.

### Platform translation

| Intent | Modern GL | PSP GU | Saturn VDP1 | PS1 OT | N64 RSP | SNES PPU |
|---|---|---|---|---|---|---|
| QUAD | VAO + glDraw | GU display list | distorted-sprite cmd | GPU quad packet | RSP display list | OAM + BG tile |
| POLYGON | VAO + glDraw | GU display list | polygon cmd | GPU poly packet | RSP display list | OAM |
| BGPLANE | fullscreen quad | fullscreen quad | VDP2 config | fullscreen quad | fullscreen quad | BG layer config |
| UI_SPRITE | 2D ortho quad | 2D GU quad | VDP2 BG plane | GPU rect packet | RDP rectangle | BG layer tile |
| MESH | VAO/VBO | GU buffers | (degrade: quads) | (degrade: tris/quads) | RSP display list | (not supported) |

Note: N64 supports both triangles and axis-aligned rectangles natively via
RDP. PS1 supports triangles and quads (4-vertex) natively, so neither needs
the dead-vertex trick that Saturn requires.

---

## Asset Pipeline: Platform-Native Formats

### The problem

All textures currently enter the engine as RGBA and are converted at
runtime by each platform (Dolphin retiles to 4x4 blocks; GL uploads as-is).
This wastes memory and CPU time, and is impossible for platforms where RGBA
is not a valid intermediate format at all.

### The solution

The asset compiler (offline, run at build time) produces platform-specific
binary bundles. A texture asset has one source (PNG or similar) but N
compiled outputs, one per target.

### Texture formats by platform

| Platform | Native Formats | Notes |
|---|---|---|
| Modern GL | RGBA8, RGB8, BC1-BC7 (compressed) | Upload directly, GPU handles |
| Legacy GL | RGBA8, RGB8, CI8 (palette via extension) | No compressed formats |
| Vulkan | VkFormat variants (RGBA8, BC, ASTC) | Chosen at compile time |
| PSP GU | ABGR8888, BGR5650, ABGR1555, ABGR4444, CI4, CI8 | Native swizzled format |
| Saturn VDP1/VDP2 | RGB555, CI4, CI8 (15-bit palette in CRAM) | Big-endian, packed |
| PlayStation 1 | RGB555 / CI4 / CI8 (CLUT in VRAM) | Little-endian; VRAM flat; CLUT at coord |
| Nintendo 64 | RGBA16, RGBA32, IA4-IA16, I4-I8, CI4, CI8 | 4 KB TMEM; tiles must fit in TMEM banks |
| GameCube/Wii GX | I4, I8, IA4, IA8, RGB565, RGB5A3, RGBA8, CMPR | 4x4 tiled, big-endian |
| SNES PPU | 2bpp, 4bpp, 8bpp indexed (CGRAM palette) | Tile-packed, no direct access |

### Asset bundle structure

The `.dsk` bundle gains a platform tag. The loader picks the right section
at runtime (or the build produces a single-platform bundle for constrained
targets like SNES/Saturn where there is no spare storage for unused data).

---

## UI System (first-class)

### Current problem

UI elements go through the 3D pipeline: they are meshes with an orthographic
shader, rendered in the same pass as the world. This means:
- UI competes for Z-buffer depth with world geometry
- On Saturn/SNES, UI cannot use dedicated hardware planes
- Text rendering is tied to the sprite batch which is tied to the 3D pass
- No separation between "draw the world" and "draw the HUD"

### New model

UI is a completely separate rendering context. The world renders first,
then the UI renders on top. They share no state.

UI coordinates are always in screen space (pixels or a logical resolution
that the platform scales to its native display size). No camera matrix,
no projection, no depth buffer involvement.

### Platform mapping

| Platform | UI implementation |
|---|---|
| Modern GL | Separate 2D ortho pass, screen-space quads, no depth test |
| Legacy GL | Same, using fixed-function |
| PSP GU | Separate GU display list, 2D mode |
| Saturn | VDP2 background plane(s) dedicated to UI |
| PlayStation 1 | Separate GPU packet chain, no Z; ordered after world OT |
| Nintendo 64 | RDP rectangle commands in a separate display list segment |
| GameCube/Wii | GX 2D mode or dedicated GX pass |
| SNES | Dedicated BG layer(s) for HUD tiles |

On Saturn, the UI occupying VDP2 planes is a genuine hardware win -- the
PPU composites it for free at scanline time, costing zero VDP1 commands.
On SNES, the HUD must live in a BG layer because there is no alternative.

### UI API (proposed)

```c
uiBegin();
  uiDrawRect(x, y, w, h, color);
  uiDrawSprite(x, y, w, h, texture, uvMin, uvMax);
  uiDrawText(x, y, font, string);
uiEnd();   // platform flushes UI to hardware
```

The `uiBegin`/`uiEnd` block collects intents; the platform submits them
at frame end in whatever way is appropriate.

---

## SNES / Mode7

SNES is the most constrained platform the engine will ever support and
needs its own section because it breaks assumptions that even Saturn keeps.

### Hardware

- **CPU**: 65816 @ ~3.58 MHz (16-bit, no FPU, no cache)
- **PPU**: Tile-based scanline renderer. VRAM holds tile graphics and
  tile maps. BG layers reference tiles by index.
- **Mode7**: A single BG layer with a 2D affine matrix applied per
  scanline. Used for overworld maps, road perspective (F-Zero), rotation
  effects. The matrix is set via HDMA (scanline DMA) for per-scanline
  variation, enabling horizon-perspective effects.
- **Sprites/OAM**: Up to 128 sprites (8x8, 16x16, 32x32, 64x64 pixels),
  4bpp indexed, up to 8 per scanline.
- **Palette**: CGRAM holds 256 entries of 15-bit RGB (512 bytes total).
  BG layers use sub-palettes of 4/16/256 colors depending on bit depth.
- **VRAM**: 64 KB (tiles + tile maps)
- **WRAM**: 128 KB work RAM + usually 8 KB SRAM on cart for saves
- **No frame buffer.** The PPU renders scanlines directly. You cannot
  read back what was drawn.
- **No general-purpose draw calls.** You configure registers and VRAM
  before the frame and the PPU does the rest.

### What "3D" means on SNES

True 3D is not possible. What can be approximated:
- **Overworld map**: Mode7 with a flat texture and HDMA scroll gives a
  top-down perspective with a horizon line (the classic JRPG overworld).
- **Depth illusion**: Mode7 matrix manipulation can simulate a moving
  camera over flat terrain. Objects are sprites placed at screen positions
  calculated by software perspective projection.
- **Sprite scaling**: Software-scaled sprites using pre-rendered frames
  or the RSP-style tricks used in Super FX games (Star Fox). Super FX
  is a co-processor on the cartridge -- base SNES cannot do this.
- **Basic 3D effects**: Some games use HDMA color gradient + Mode7 floor
  with overlaid sprites to create a pseudo-3D look.

The engine plan for SNES: Mode7 overworld (confirmed), sprite-based world
objects, BG layer UI. "Basic 3D effects" (pseudo-perspective with sprites)
is aspirational -- implementation complexity TBD.

### SNES constraints on the engine

- **No dynamic allocation.** With 128 KB WRAM, a general-purpose allocator
  is risky. The engine memory system may need a static pool mode for SNES.
- **No floating point.** `float_t` must resolve to integer or fixed-point.
- **No scripting (JerryScript).** The JS engine requires far more than
  128 KB RAM. SNES scenes must be compiled C.
- **Asset data in ROM, not a .dsk bundle.** SNES loads from cartridge ROM
  mapped into the address space. The asset system needs a ROM-mapped loader.
- **Tile pipeline.** Textures must be pre-converted to SNES tile format
  (2bpp/4bpp/8bpp, 8x8 pixel tiles, CGRAM palette) at build time. This
  is a completely different asset output from every other platform.

---

## Platform Inventory

A summary of what each platform's native rendering looks like after the
refactor, for reference when designing the intent API.

### Modern OpenGL (duskgl)

VAO + VBO mesh storage, GLSL shaders, FBO render targets, Z-buffer.
No fixed-function. Targets: Linux, possibly Vita (GXM is preferred).

### Legacy OpenGL (duskgllegacy)

Fixed-function pipeline: `glMatrixMode`, `glTexEnv`, client-side vertex
arrays. No VAO/VBO. Used for: very old desktop hardware, maybe PSP as
last resort (PSPGL is this). Targets: legacy desktop, embedded Linux.

### Vulkan (duskvulkan)

Explicit pipeline state objects, render passes, descriptor sets, command
buffers. Highest ceiling for performance and control. Targets: Linux
(modern), future platforms. Not immediate priority but the architecture
should not block it.

### PSP native GU (duskpsp)

The GE/GU is a display-list GPU. You build a command list in memory and
the GU DMA engine processes it asynchronously. Native vertex formats are
PSP-specific (ABGR byte order, swizzled textures for cache efficiency).
No PSPGL. Targets: PSP hardware and emulators.

### Vita (duskvita)

GXM is Sony's Vita GPU API -- closer to modern GL than GU, with explicit
shader binaries (.gxp), ring buffers, and GPU sync primitives.

### GameCube/Wii GX (duskdolphin)

Already a custom renderer. GX uses immediate-mode vertex submission
(`GX_Begin` / `GX_Position1x16` loops), TEV for texture compositing, and
hardware XFB double-buffering. Big-endian. Mostly kept as-is; may benefit
from being expressed in terms of render intents for consistency.

### Saturn VDP1/VDP2 (dusksaturn)

VDP1: command-list (32-byte structs), quad-based, affine texture mapping,
no Z-buffer (painter's algorithm). VDP2: up to 6 background planes
composited at scanline time. Big-endian dual SH-2, no FPU. Fixed-point
math required throughout.

### PlayStation 1 (duskps1)

MIPS R3000A @ 33.87 MHz, little-endian, no FPU. GTE (coprocessor 2)
handles fixed-point matrix math, perspective divide, and lighting.
GPU receives packets via DMA linked-list (the Ordering Table). Primitives:
triangles and quads natively (no dead-vertex needed). Texture mapping:
affine, same limitation as Saturn. No Z-buffer; depth is OT slot order.
VRAM is 1 MB flat (frame buffers + textures + CLUTs share it). SDK:
PSn00bSDK, which is CMake-native -- a direct fit for the dusk build system.

### Nintendo 64 (duskn64)

VR4300 @ 93.75 MHz, big-endian, real IEEE 754 FPU. Rendering is split
between the RSP (geometry: programmable MIPS SIMD, runs microcode up to
~1000 instructions in 4 KB IMEM) and the RDP (rasterization: fixed
hardware). RSP produces triangle commands from a CPU-built display list
in RDRAM. RDP features: perspective-correct texture mapping, bilinear
filtering, hardware Z-buffer. Primitives: triangles and axis-aligned rects.
TMEM is 4 KB on-chip texture cache; textures must be loaded into tiles
before drawing -- a significant memory management constraint.
SDK: libdragon (Unlicense, GCC 14, Makefile-based -- not CMake; this
requires a wrapper toolchain file for dusk's build system).

### SNES PPU/Mode7 (dusksnes)

Tile-based. VRAM holds tiles and tile maps. Mode7 provides affine transform
for one BG layer. Sprites via OAM. No frame buffer. All configuration is
memory-mapped registers. 65816 CPU, no FPU, extremely limited RAM.

---

## Threading Model

### Current model

The engine uses OS threads for async asset loading (`assetXxxLoaderAsync`).
Platforms that have pthreads or an equivalent RTOS (Linux, PSP, Vita) run
worker threads that load data in the background while the game loop runs.
The main thread polls or blocks on completion.

### The problem

Several target platforms have no OS threading whatsoever, and others have
hardware-specific async mechanisms that are nothing like pthreads.

### Per-platform reality

| Platform | Threading | Async mechanism |
|---|---|---|
| Linux | pthreads | Worker threads (current) |
| Vita | SceKernelThread | Per-SDK threads |
| PSP | SceKernelThread | Per-SDK threads |
| GameCube/Wii | libogc LWP | Lightweight processes |
| Saturn | None (OS) | Slave SH-2 for fixed jobs; CD-ROM via interrupt/callback |
| PlayStation 1 | None (OS) | V-blank ISR, 7 DMA channels, CD-ROM callbacks |
| Nintendo 64 | libdragon preview only | PI DMA for cartridge; RSP for parallel compute |
| SNES | None | DMA (GPDMA/HDMA); NMI V-blank; SPC700 audio is a separate CPU |

**Saturn slave SH-2**: The second SH-2 is not a general-purpose thread.
It runs a fixed subroutine you hand-load. The typical use is offloading
heavy per-frame computation (geometry transforms, depth sort) while the
master SH-2 handles game logic. Communication is via shared WRAM with
cache-through addresses to avoid coherency bugs. There is no scheduler
and no yield -- it runs to completion.

**SNES DMA**: GPDMA copies blocks of data (ROM to WRAM, WRAM to VRAM)
and halts the CPU for the duration -- it is synchronous from the game's
perspective. HDMA runs per-scanline during H-blank, writing to PPU
registers without CPU involvement; this is how Mode7 perspective is
achieved. Neither is "async" in the programming sense.

**SNES NMI**: The V-blank NMI fires at the start of every V-blank period.
This is the only safe window to write to VRAM and PPU registers. All
critical PPU updates must complete within ~1.2ms (the V-blank window).

### Proposed model

Introduce a compile-time threading capability flag:

```
DUSK_THREAD_PTHREAD    -- Linux, maybe Vita
DUSK_THREAD_SCEKERNEL  -- PSP, Vita SDK
DUSK_THREAD_LWP        -- GameCube/Wii libogc
DUSK_THREAD_SLAVE_SH2  -- Saturn slave CPU (job dispatch only)
DUSK_THREAD_NONE       -- SNES (and Saturn master thread view)
```

The asset loader's async path is gated on having a threading capability.
When `DUSK_THREAD_NONE` is defined, `assetXxxLoaderAsync` either does not
exist or is an alias for the synchronous version. On Saturn, the slave SH-2
is exposed as a distinct API (`sh2JobDispatch`, `sh2JobWait`) used only for
compute-heavy work, not for I/O.

### Asset loading without threads

**Saturn**: CD-ROM access is initiated via SBL/CDC routines and completes
via interrupt callback. The engine's asset loading loop can poll the
callback flag in the main loop rather than blocking a thread. This is
interrupt-driven cooperative async, not preemptive.

**SNES**: There is no loading. Assets live in ROM, mapped directly into the
65816 address space. "Loading a texture" means computing a pointer into ROM
and copying the tile data to VRAM during V-blank via GPDMA. The asset system
on SNES is essentially a VRAM/CGRAM allocator and a DMA scheduler, not a
file loader.

### Asset system changes

The asset pipeline needs to accommodate three loading models:

1. **File-based** (Linux, PSP, Vita, Saturn CD): open file, read bytes,
   close. Can be sync or thread-async.
2. **DMA/interrupt** (Saturn CD-ROM, GC DVD): initiate transfer, poll or
   callback on completion, no thread blocked.
3. **ROM-mapped** (SNES): data is already in the address space; "loading"
   is a VRAM DMA copy scheduled for V-blank, not file I/O.

The `assetstream_t` abstraction that currently wraps file I/O needs a third
backend for ROM-mapped data, and the async path needs to support
callback-based completion as an alternative to thread-based blocking.

---

## What Needs to Change

### 1. Render intent API (new, in src/dusk/)

Replace `mesh_t` / `shader_t` / `meshDraw()` as scene-facing APIs with
`renderqueue_t` and intent submission functions. `src/dusk/` defines the
intent types and submission API; platforms implement the flush.

### 2. Platform renderer directories

Move rendering implementations out of `duskgl/` as a shared layer and
into fully self-contained platform directories. `duskgl/` becomes the
*modern GL* platform only. Add `duskgllegacy/`, `duskvulkan/` as peers.

### 3. Asset pipeline: platform-native texture formats

The offline asset compiler must produce per-platform texture bundles in
native formats. The runtime texture loader expects pre-converted data,
not RGBA. `textureformat_t` grows to cover all platform formats but each
platform only ever sees the formats it natively supports.

### 4. UI system (first-class, separate from 3D)

New `src/dusk/ui/` subsystem with `uiBegin` / `uiEnd` and intent types
for rects, sprites, and text. Platforms implement the flush independently.
The 3D spritebatch is retired or scoped to world-space billboards only.

### 5. Fixed-point / no-FPU math

`float_t` needs a fixed-point mode. Proposed: define `fixed_t` as a
16.16 signed integer; define `DUSK_MATH_FIXED` for platforms that require
it (Saturn, SNES). Engine math utilities (`mathSin`, `mathCos`, etc.)
have fixed-point implementations selected by this flag. `float_t` on
FPU-less platforms becomes a typedef for `fixed_t`.

### 6. Background plane abstraction (bgplane_t)

New concept in `src/dusk/display/bgplane/`. A BG plane has a tile map or
bitmap source, scroll offsets, a palette reference, and optional affine
parameters (for Mode7-style use). On GL platforms: rendered as a
fullscreen textured quad or shader pass. On Saturn: VDP2 config. On SNES:
PPU BG layer config.

### 7. Memory system: static pool mode

For SNES (and possibly Saturn), the general-purpose allocator may be
unviable. A compile-time static pool mode (`DUSK_MEMORY_STATIC`) that uses
a fixed-size arena instead of dynamic allocation. All `memoryAllocate`
calls hit the pool; `memoryFree` is a no-op or a stack pop.

### 8. Script runtime: optional

JerryScript requires too much RAM for SNES and is marginal on Saturn.
The scripting system should be compile-time optional (`DUSK_SCRIPTING`),
not assumed present. SNES/Saturn scenes would be compiled C.

---

## What to Keep

- Platform macro abstraction pattern (`displayplatform.h`, etc.) -- works,
  no reason to change.
- Directory structure convention for platform directories.
- Entity-component system -- platform-agnostic, unaffected.
- Asset loading + `.dsk` bundle concept (extended for platform formats).
- The broad subsystem layout: asset, input, display, log, network, save,
  system, time.

---

## Open Questions

1. **Render intent granularity**: How much does the intent API need to
   express? A MESH intent works on GL/N64 but degrades poorly on Saturn
   (must split into quads) and is impossible on SNES. Should MESH be a
   valid intent with a "best effort" contract, or excluded from the portable
   API entirely?

2. **Threading abstraction depth**: Should `DUSK_THREAD_SLAVE_SH2` be a
   first-class concept in the engine's job system, or a Saturn-internal
   implementation detail the core never sees? Same question applies to N64's
   RSP as a compute co-processor.

3. **Asset loading async contract**: When a platform has no threads, should
   `assetLoadAsync` be a no-op alias for `assetLoadSync`, or return
   immediately with a completion flag to poll? The polling model is more
   honest but requires all call sites to handle it.

4. **N64 build system**: libdragon uses GNU Make, not CMake. Options are:
   (a) write a CMake toolchain file that wraps n64.mk, (b) maintain a
   parallel Makefile just for N64, or (c) wait for upstream CMake support.
   Which is acceptable long-term?

5. **N64 RSP microcode**: Standard libdragon microcodes (Fast3D/F3DEX2) or
   Tiny3D (community microcode with full T&L + skinning)? Writing custom
   microcode is powerful but limited to ~1000 MIPS SIMD instructions.
   This decision gates what 3D features the N64 port can support.

6. **PSPGL fate**: Drop immediately in favor of native GU, or keep as a
   fallback (`duskgllegacy`) while native GU is built? The two can coexist
   during transition.

7. **Vulkan priority**: Design the intent API with Vulkan in mind from the
   start, or add it later? Vulkan's explicit pipeline state model may
   conflict with how stateful platforms (Saturn, SNES) expect things to work.

8. **Background planes on modern platforms**: Does `bgplane_t` degrade to a
   fullscreen textured quad on GL/Vulkan/N64, or should modern platforms
   support actual background scene rendering (3D world behind the foreground)?

9. **PS1 ordering table depth**: The OT is a fixed-size array (e.g. 4096
   slots). Depth precision = number of slots. How deep should the engine's
   default OT be, and should this be configurable per-scene?

10. **Fixed-point strategy**: Does `float_t` transparently become `fixed_t`
    on FPU-less platforms (Saturn, PS1, SNES), or do we require explicit
    `fixed_t` in math-heavy paths? Transparent is easiest to port; explicit
    is faster.

11. **SNES V-blank budget**: All VRAM writes must finish within ~1.2ms.
    Does the engine need a V-blank work queue with a budget checker, or is
    this left to the game to manage manually?

12. **SNES scripting**: JerryScript is out. Pure compiled C, or a lighter
    scripting layer (Lua is ~100 KB -- tight but possible)?

13. **Asset compiler**: New standalone tool, or an extension of the existing
    asset pipeline? Part of the CMake build or a separate pre-build step?

---

## Proposed Sequence (Draft)

### Phase 1 -- Intent API (no behavior change)
1. Design and stabilize `renderqueue_t` and intent types
2. Refactor modern GL path to submit through render intents (same output,
   new plumbing)
3. Refactor Dolphin path the same way
4. Validate no regressions on Linux + GameCube

### Phase 2 -- UI system
5. Extract UI rendering from the 3D path into `src/dusk/ui/`
6. Implement UI flush for GL and Dolphin
7. Wire existing UI elements through the new system

### Phase 3 -- Platform splits
8. Split `duskgl/` into `duskgl/` (modern) and `duskgllegacy/` (fixed-func)
9. Port PSP to native GU (`duskpsp/display/` rewrite, drop PSPGL dependency)
10. Stub `duskvulkan/` structure for future implementation

### Phase 4 -- Asset pipeline
11. Design platform-native texture format system
12. Extend asset compiler for per-platform output
13. Update texture loader to expect pre-converted data

### Phase 5 -- Saturn
14. CMake toolchain for SH-2 cross-compile (yaul / libyaul toolchain)
15. `src/dusksaturn/` -- input (SMPC), asset (CD-ROM), log, system
16. VDP1 backend for render queue (quads, polygons, painter's sort)
17. VDP2 backend for bgplane_t (tile maps, scroll, palette)
18. Fixed-point math mode (`DUSK_MATH_FIXED`)
19. UI backend (VDP2 plane(s))

### Phase 6 -- PlayStation 1
20. CMake toolchain wrapping PSn00bSDK (already CMake-native)
21. `src/duskps1/` -- input (BIOS pad), asset (CD-ROM libpsxcd), log, system
22. GTE integration for fixed-point math (reuse `DUSK_MATH_FIXED` path)
23. Ordering table builder for render queue (painter's sort, DMA linked-list)
24. GPU packet backend for intents (tris, quads, rects)
25. UI backend (separate GPU packet chain after world OT)

### Phase 7 -- Nintendo 64
26. CMake toolchain wrapping libdragon (n64.mk wrapper or toolchain file)
27. `src/duskn64/` -- input (N64 controller via PIF), asset (PI DMA /
    DragonFS), log, system
28. RSP display list builder for render queue (Z-buffer path, no sorting)
29. TMEM tile management for textures
30. RDP rectangle backend for UI
31. Decide on RSP microcode (Tiny3D vs standard F3DEX2)

### Phase 8 -- SNES
32. SNES toolchain (cc65 or llvm-mos 65816 target)
33. Static memory pool mode (`DUSK_MEMORY_STATIC`)
34. PPU tile pipeline + VRAM management
35. Mode7 overworld implementation
36. OAM sprite system
37. BG layer UI
38. Scripting-optional build (`DUSK_SCRIPTING` off)