Files
prometeu-runtime/docs/vm-arch/graphics-measurement.md
T
bquarkz a32f834b2b
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
feat(graphics): migrate native target to 640x360
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.
2026-11-20 10:34:45 +00:00

5.1 KiB
Raw Blame History

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/:

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.