feat(graphics): migrate native target to 640x360
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
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:
@@ -51,10 +51,26 @@ The current 2D graphics model is based on:
|
||||
|
||||
### Base resolution
|
||||
|
||||
- **480 × 270 pixels**
|
||||
- aspect ratio close to 16:9
|
||||
- **640 × 360 pixels**
|
||||
- aspect ratio exactly 16:9
|
||||
- scalable by the host (nearest-neighbor)
|
||||
|
||||
This is the machine's only native target, at **60 Hz**. The authoritative Rust
|
||||
definitions live in `prometeu_hal::graphics_contract` in the existing HAL crate.
|
||||
Hosts MUST NOT choose a VM resolution from their physical display dimensions.
|
||||
No 480×270 compatibility mode, runtime resolution switch or legacy-content
|
||||
adapter is provided.
|
||||
|
||||
A packed native surface contains **230,400 pixels**, **921,600 bytes** and a
|
||||
stride of **640 pixels / 2,560 bytes**. Stride units remain explicit in each
|
||||
interface: `OwnedRgba8888Frame::stride_pixels` is measured in pixels.
|
||||
|
||||
At 1280×720 the host presents at integer 2×. Otherwise it uses the largest
|
||||
integer scale that fits, centered with bars, or proportional reduction if the
|
||||
surface cannot fit 1×. Reduction also uses nearest-neighbor. The aspect ratio
|
||||
MUST remain 16:9. Physical surface coordinates, including HiDPI and resize,
|
||||
determine the presentation rectangle and its inverse input transform.
|
||||
|
||||
### Pixel format
|
||||
|
||||
- **RGBA8888**
|
||||
@@ -368,9 +384,16 @@ The cache is a window of tiles around the camera.
|
||||
|
||||
Example:
|
||||
|
||||
- Screen: 480×270
|
||||
- 16×16 tiles → approximately 30×17 visible
|
||||
- Current runtime cache sizing with 16×16 layers: 35×21 tiles
|
||||
- Screen: 640×360
|
||||
- 16×16 tiles → approximately 40×23 visible (the last tile row has 8 visible pixels)
|
||||
- Current runtime cache sizing with 16×16 layers: 45×27 tiles
|
||||
|
||||
The final 16×16 tile row has eight visible pixels. With 32×32 tiles the aligned
|
||||
viewport is 20 columns and 11 complete rows plus eight pixels. With 8×8 tiles it
|
||||
is 80×45. Camera offsets may expose partial tiles at any edge. Mixed-size layers
|
||||
remain supported; the resolver's movement threshold must not oscillate between
|
||||
adjacent anchors when a layer tile is larger than the scene's minimum tile.
|
||||
Native height is always 360, never rounded to 352 or 368.
|
||||
|
||||
It stores tiles already resolved from the tilemap.
|
||||
|
||||
|
||||
@@ -20,17 +20,26 @@ Core contract:
|
||||
## 2 Coordinate Space
|
||||
|
||||
- TOUCH coordinates use **the same space as the framebuffer**
|
||||
- Resolution: **480×270**
|
||||
- Resolution: **640×360**
|
||||
- Origin: top-left corner `(0,0)`
|
||||
- Ranges:
|
||||
- `x ∈ [0, 479]`
|
||||
- `y ∈ [0, 269]`
|
||||
- `x ∈ [0, 639]`
|
||||
- `y ∈ [0, 359]`
|
||||
|
||||
TOUCH is **absolute**:
|
||||
|
||||
- `(x, y)` represents the current contact position after normalization;
|
||||
- the runtime does not apply dynamic transformation to that coordinate pair.
|
||||
|
||||
The host MUST apply the inverse of the actual presentation rectangle and scale,
|
||||
including bars, proportional reduction, resize and HiDPI. A press outside that
|
||||
rectangle MUST NOT capture a pointer. An active pointer leaving the image MUST
|
||||
release, with `released` exposed for one logical frame under the existing button
|
||||
contract. Returning while the physical button remains held MUST NOT recapture;
|
||||
a new press inside is required. Releasing or losing focus must neutralize the
|
||||
active pointer. Coordinates while `down == false` retain their existing invalid
|
||||
status; no new guest-visible sentinel is introduced.
|
||||
|
||||
## 3 TOUCH Peripheral API
|
||||
|
||||
### 3.1 Exposed Structure
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user