feat(graphics): migrate native target to 640x360
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Centralize the fixed 640x360 RGBA8888/60 Hz contract in the existing HAL.
Preserve 8/16/32 tiles and composition, cover partial edges and mixed-size
camera movement, and adapt firmware, fixtures, hosts and native tests.

Share nearest-neighbor presentation geometry with pointer input. Measure
actual framebuffer publications and successful host presentations separately
from VM ticks, with bounded opt-in diagnostics and release harnesses.

Validated with the complete tooling verify gate, native rendering tests,
GPU readback, headless/process integration, formatting and strict clippy.
The existing synchronous session path is documented; no worker/session
architecture replacement or format compatibility layer is introduced.

Work: WRK-0016 / DEC-0001 / PLN-0001
Commit and push explicitly authorized by the user after completion.
This commit is contained in:
2026-11-20 10:34:45 +00:00
parent f1adf86dd5
commit a32f834b2b
36 changed files with 1345 additions and 165 deletions
+82
View File
@@ -0,0 +1,82 @@
# Graphics measurement
The fixed machine target is 640×360 RGBA8888 at 60 Hz, defined by
`prometeu_hal::graphics_contract`. A frame is 921,600 bytes; this is not the total
graphics memory cost. The desktop constructs hardware and an asynchronous local
backend, each with front/back storage. Those four surfaces alone occupy
3,686,400 bytes before published frames, CPU staging, caches, assets and GPU memory.
Measure three different quantities:
| Quantity | Meaning |
|---|---|
| Host ticks and completed VM frames | Logic scheduling; a logical frame can span several host ticks |
| New published frames | Newly produced images identified by frame ID and ownership/epoch; identical pixels still count as new production |
| First presentations and repeats | Host submission of a new identity or the same identity; neither proves physical scanout time or display refresh |
The desktop title labels its existing slice counter as host ticks/s. Successful
worker presentations classify identities including ownership, so frame zero in a
new session is not a repeat. Occluded surface acquisition and failed render calls
do not mark a successful presentation. Existing bounded handoff, frame repetition
and VM pacing remain unchanged.
For opt-in desktop diagnostics set `PROMETEU_GRAPHICS_METRICS` to an output JSON
path and close the application normally. Host statistics export API presentation
latency; the render worker appends `.renderer.jsonl` records containing counters
and bounded `(frame_id, render_us, publish_us)` samples on shutdown. Render time
includes the backend's owned-frame copy; sink publication is separate. Sampling
retains at most the last 16,384 measurements. Clock/storage overhead is present
only when detailed sampling is enabled, except for the host API timer. API timing
includes upload/submit/present calls, not physical scanout latency. A synchronous
headless or Studio path is not an asynchronous worker measurement.
The current session-based desktop also composes synchronously: the worker is
installed on the OS's global runtime, while guest sessions own separate runtimes.
Consequently its worker report can correctly contain zero submissions even when
the active session produces images. Do not interpret those zeros as renderer FPS.
The desktop observes the hardware's completed front-buffer swap count for local
redraw, including native Hub/Shell publications that execute no VM frame, and
host presentation counters cover both the synchronous surface and worker frames.
Connecting the worker to session lifecycles is a separate architectural change.
For a bounded run of the actual desktop runner (including boot, without discarded
warmup), build and run the measurement executable from `runtime/`:
```sh
cargo build --release -p prometeu-host-desktop-winit --example desktop_measure
PROMETEU_GRAPHICS_METRICS=/tmp/desktop.json ./target/release/examples/desktop_measure test-cartridges/dummy-boy 10
```
The duration controls only termination of this example, not VM timing. It uses
the production host implementation and normal teardown to flush diagnostics.
On macOS it activates its window to permit visible-surface measurement. The
summary reports active-session completed frames and synchronous publications;
`desktop.json` reports first/repeated API submissions and presentation latency.
An occluded window may make API calls without submitting an image: compare the
counters, and do not report those calls as successful presentations. Repeated
physical scanouts of a retained image are not observable with these counters.
The reproducible controlled scenario and headless VM harness are invoked through
`tooling/scripts/graphics-measure.py` from the workspace. The wrapper builds
release, emits JSON/CSV, records source/environment, and uses `wait4` for the exact
measured process's peak resident memory (not the compiler's peak). Allocation
instrumentation in the controlled executable measures requested live/peak heap
bytes and allocations, not allocator overhead or GPU memory.
The controlled scenario renders four tile layers, 512 accepted sprites distributed
across the target, and an overlay. It times rasterization, owned publication, RGBA
staging and their total including cache materialization. It deliberately
materializes the cache fully to keep the workload reproducible; this is not a
claim about normal incremental-cache throughput. The optional mixed scenario
uses 8/16/32/8 tiles. Warmup is 120 frames; the default measured count is 600.
The headless scenario instead boots a real cartridge, advances logical frames and
captures owned output without realtime pacing. It does not measure a GPU.
Compare matching workloads/builds and report mean, p95, p99, maximum, counts over
the approximately 16.67 ms budget, process memory, buffer bytes and limitations.
Do not infer battery life, physical display frequency, ARM64 handheld qualification
or universal performance from desktop results. H700/RK3566 remain future physical
qualification candidates. The existing cartridge stress generator is only
minimally adapted to this target; its broader redesign is separate work. Its
requested sprite count exceeds the 512 accepted slots, so requests must not be
reported as rendered sprites.