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
@@ -0,0 +1,185 @@
//! Controlled graphics measurement. This is not a cartridge stress-suite replacement.
use prometeu_drivers::{Gfx, GlyphBankPoolInstaller, MemoryBanks, hardware::Hardware};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::sprite::Sprite;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{FrameId, OwnedRgba8888Frame, RenderOwnership, app_mode::AppMode};
use std::alloc::{GlobalAlloc, Layout, System};
use std::sync::{
Arc,
atomic::{AtomicUsize, Ordering},
};
use std::time::Instant;
struct CountingAllocator;
static LIVE: AtomicUsize = AtomicUsize::new(0);
static PEAK: AtomicUsize = AtomicUsize::new(0);
static ALLOCATIONS: AtomicUsize = AtomicUsize::new(0);
// Only the measurement executable pays the atomic allocation instrumentation cost.
unsafe impl GlobalAlloc for CountingAllocator {
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
let ptr = unsafe { System.alloc(layout) };
if !ptr.is_null() {
let live = LIVE.fetch_add(layout.size(), Ordering::Relaxed) + layout.size();
PEAK.fetch_max(live, Ordering::Relaxed);
ALLOCATIONS.fetch_add(1, Ordering::Relaxed);
}
ptr
}
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
LIVE.fetch_sub(layout.size(), Ordering::Relaxed);
unsafe { System.dealloc(ptr, layout) };
}
}
#[global_allocator]
static ALLOCATOR: CountingAllocator = CountingAllocator;
fn summary(samples: &mut [u64]) -> serde_json::Value {
samples.sort_unstable();
let n = samples.len();
serde_json::json!({"mean_us": samples.iter().sum::<u64>() as f64 / n as f64 / 1000.0,
"p95_us": samples[(n * 95).div_ceil(100) - 1] as f64 / 1000.0,
"p99_us": samples[(n * 99).div_ceil(100) - 1] as f64 / 1000.0,
"max_us": samples[n-1] as f64 / 1000.0,
"over_60hz_budget": samples.iter().filter(|&&v| v > 1_000_000_000 / 60).count()})
}
fn main() {
let count: usize =
std::env::args().nth(1).map(|v| v.parse().expect("frame count")).unwrap_or(600);
assert!(count > 0);
let (w, h) = (Hardware::W, Hardware::H);
let banks = Arc::new(MemoryBanks::new());
let mixed = std::env::args().nth(2).as_deref() == Some("mixed");
let sizes = if mixed {
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8]
} else {
[TileSize::Size16; 4]
};
for (i, size) in sizes.iter().enumerate() {
let edge = *size as usize;
let mut bank = GlyphBank::new(*size, edge, edge);
bank.palettes[0][1] = Color::rgba((i * 47 + 30) as u8, 120, 210, 255);
// Transparent holes make all four layers participate in the visible output.
for (p, pixel) in bank.pixel_indices.iter_mut().enumerate() {
*pixel = u8::from(i == 0 || (p + i) % 3 != 0);
}
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 100,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: false,
flip_y: false,
};
160 * 100
],
},
}),
};
let min_tile = if mixed { 8 } else { 16 };
let (cw, ch) = (w.div_ceil(min_tile) + 5, h.div_ceil(min_tile) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
w as i32,
h as i32,
cw,
ch,
min_tile as i32 - 4,
min_tile as i32 + 4,
);
let mut gfx = Gfx::new(w, h, banks);
let sprites: Vec<_> = (0..512)
.map(|i| Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 0 },
x: ((i * 37) % w) as i32,
y: ((i * 53) % h) as i32,
layer: (i % 4) as u8,
bank_id: (i % 4) as u8,
active: true,
flip_x: i % 2 == 0,
flip_y: i % 3 == 0,
priority: (i % 4) as u8,
})
.collect();
gfx.load_frame_sprites(&sprites);
let mut compose = Vec::with_capacity(count);
let mut publish = Vec::with_capacity(count);
let mut upload = Vec::with_capacity(count);
let mut total = Vec::with_capacity(count);
let mut rgba = vec![0u8; w * h * 4];
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
let mut checksum = 0u32;
for frame_id in 0..(count + 120) {
// Resolve/materialize cache outside the raster timing; total includes it.
let start = Instant::now();
let update = resolver.update(&scene, (frame_id % 71) as i32, (frame_id % 43) as i32);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
let t = Instant::now();
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.fill_rect(0, h as i32 - 8, w as i32, 8, Color::WHITE);
let raster = t.elapsed().as_nanos() as u64;
let t = Instant::now();
gfx.present();
let frame = OwnedRgba8888Frame::packed(
FrameId::new(frame_id as u64),
ownership,
w,
h,
gfx.front_buffer().to_vec(),
)
.unwrap();
let publication = t.elapsed().as_nanos() as u64;
let t = Instant::now();
for (pixel, bytes) in frame.pixels.iter().zip(rgba.as_chunks_mut::<4>().0.iter_mut()) {
bytes.copy_from_slice(&pixel.to_be_bytes());
}
std::hint::black_box(&rgba);
let staging = t.elapsed().as_nanos() as u64;
checksum ^= frame.pixels[(frame_id * 173) % (w * h)];
if frame_id >= 120 {
compose.push(raster);
publish.push(publication);
upload.push(staging);
total.push(start.elapsed().as_nanos() as u64);
}
}
let live = LIVE.load(Ordering::Relaxed);
let peak = PEAK.load(Ordering::Relaxed);
let allocations = ALLOCATIONS.load(Ordering::Relaxed);
println!(
"{}",
serde_json::json!({"schema":1,"width":w,"height":h,"frames":count,
"warmup_frames":120,"tiles":sizes.map(|s|s as u32),"sprites_accepted":512,"layers":4,
"framebuffer_bytes":w*h*4,"front_back_bytes":w*h*8,"host_staging_bytes":rgba.len(),
"compose":summary(&mut compose),"publish_owned":summary(&mut publish),
"rgba_staging":summary(&mut upload),"total":summary(&mut total),
"allocated_live_bytes":live,"allocated_peak_bytes":peak,"allocation_count":allocations,
"checksum":checksum,"vm_hz":null,"physical_display_hz":null,
"limitations":"unpaced controlled raster/cache/owned publication/staging; no VM, IPC or GPU present; allocator instrumented; RSS is measured by the process wrapper"})
);
}
@@ -664,7 +664,7 @@ mod tests {
assert!(frame_composer.bind_scene(0));
let cache = frame_composer.cache().expect("cache should exist for bound scene");
assert_eq!((cache.width(), cache.height()), (65, 38));
assert_eq!((cache.width(), cache.height()), (85, 49));
}
#[test]
@@ -43,6 +43,8 @@ pub struct Gfx {
front: Vec<u32>,
/// Back buffer: the working buffer where canonical game frames are composed
back: Vec<u32>,
/// Complete local framebuffer publications, including native Hub/Shell output.
publication_count: u64,
/// Shared access to graphical memory banks (tiles and palettes).
pub glyph_banks: Arc<dyn GlyphBankPoolAccess>,
@@ -321,6 +323,7 @@ impl Gfx {
h,
front: vec![0; len],
back: vec![0; len],
publication_count: 0,
glyph_banks,
sprites: [EMPTY_SPRITE; 512],
sprite_count: 0,
@@ -570,6 +573,11 @@ impl Gfx {
/// Typically called by the Host when it's time to display the finished frame.
pub fn present(&mut self) {
std::mem::swap(&mut self.front, &mut self.back);
self.publication_count = self.publication_count.wrapping_add(1);
}
pub fn publication_count(&self) -> u64 {
self.publication_count
}
pub fn load_frame_sprites(&mut self, sprites: &[Sprite]) {
@@ -28,7 +28,7 @@ use std::sync::Arc;
/// for easier testing and different host implementations (Desktop, Web, etc.).
///
/// ### Console Specifications:
/// - **Resolution**: 480x270 (16:9 Aspect Ratio).
/// - **Resolution**: 640x360 (16:9 Aspect Ratio).
/// - **Color Format**: RGBA8888.
/// - **Audio**: Stereo, Command-based mixing.
/// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse.
@@ -201,9 +201,9 @@ impl RuntimePlatform for Hardware {
impl Hardware {
/// Internal hardware width in pixels.
pub const W: usize = 480;
pub const W: usize = prometeu_hal::graphics_contract::WIDTH;
/// Internal hardware height in pixels.
pub const H: usize = 270;
pub const H: usize = prometeu_hal::graphics_contract::HEIGHT;
/// Creates a fresh hardware instance with default settings.
pub fn new(wall_clock: Arc<dyn WallClock>) -> Self {
@@ -5,6 +5,8 @@ mod gfx;
pub mod hardware;
mod local_render_backend;
mod memory_banks;
#[cfg(test)]
mod native_graphics_tests;
mod pad;
mod test_platform;
mod touch;
@@ -0,0 +1,109 @@
use crate::{Gfx, GlyphBankPoolInstaller, MemoryBanks};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::graphics_contract::{FRAME_BYTES, HEIGHT, PIXELS, WIDTH};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use std::sync::Arc;
#[test]
fn native_allocation_stride_corners_and_external_coordinates() {
let mut gfx = Gfx::new(WIDTH, HEIGHT, Arc::new(MemoryBanks::new()));
assert_eq!(gfx.publication_count(), 0);
gfx.clear(Color::BLACK);
for (x, y) in [(0, 0), (639, 0), (0, 359), (639, 359)] {
gfx.draw_pixel(x, y, Color::RED);
}
for (x, y) in [(-1, 0), (640, 359), (639, 360), (0, -1)] {
gfx.draw_pixel(x, y, Color::GREEN);
}
assert_eq!(gfx.publication_count(), 0, "drawing is not a complete publication");
gfx.present();
assert_eq!(gfx.publication_count(), 1);
let front = gfx.front_buffer();
assert_eq!(gfx.size(), (640, 360));
assert_eq!(front.len(), PIXELS);
assert_eq!(std::mem::size_of_val(front), FRAME_BYTES);
for index in [0, 639, 359 * WIDTH, PIXELS - 1] {
assert_eq!(front[index], Color::RED.raw());
}
assert_eq!(front.iter().filter(|&&p| p == Color::RED.raw()).count(), 4);
gfx.present();
assert_eq!(gfx.publication_count(), 2, "each complete swap is a publication");
}
#[test]
fn native_tile_edges_and_mixed_camera_layers_cover_every_corner() {
for sizes in [
[TileSize::Size8; 4],
[TileSize::Size16; 4],
[TileSize::Size32; 4],
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8],
] {
let banks = Arc::new(MemoryBanks::new());
let colors = [Color::RED, Color::GREEN, Color::BLUE, Color::WHITE];
for i in 0..4 {
let n = sizes[i] as usize;
let mut bank = GlyphBank::new(sizes[i], n, n);
bank.palettes[0][1] = colors[i];
bank.pixel_indices.fill(1);
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 120,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: true,
flip_y: true,
};
160 * 120
],
},
}),
};
let min = sizes.iter().map(|s| *s as usize).min().unwrap();
let (cw, ch) = (WIDTH.div_ceil(min) + 5, HEIGHT.div_ceil(min) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
WIDTH as i32,
HEIGHT as i32,
cw,
ch,
min as i32 - 4,
min as i32 + 4,
);
let mut gfx = Gfx::new(WIDTH, HEIGHT, banks);
for (x, y) in [(0, 0), (1, 1), (7, 7), (15, 15), (31, 31), (400, 300), (2, 3)] {
let update = resolver.update(&scene, x, y);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.present();
// Every pixel, including rows 352..359, must be supplied by the last layer.
assert!(
gfx.front_buffer().iter().all(|&p| p == Color::WHITE.raw()),
"sizes={sizes:?}, camera=({x},{y})"
);
}
}
}
@@ -609,7 +609,7 @@ mod tests {
}
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
const FRAMEBUFFER_WIDTH: usize = 480;
const FRAMEBUFFER_WIDTH: usize = prometeu_hal::graphics_contract::WIDTH;
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
platform.local_hardware().gfx.front_buffer()[index]
}
@@ -1094,7 +1094,9 @@ mod tests {
assert_eq!(dummy_ownership.app_id, 2);
let front = platform.local_hardware().gfx.front_buffer();
let center = 240 + 135 * 480;
let center = prometeu_hal::graphics_contract::WIDTH / 2
+ (prometeu_hal::graphics_contract::HEIGHT / 2)
* prometeu_hal::graphics_contract::WIDTH;
assert_eq!(front[center], Color::GREEN.raw());
firmware.request_home_from_host();
@@ -1512,8 +1514,12 @@ mod tests {
#[test]
fn shell_running_close_click_uses_lifecycle_and_returns_hub_home() {
let (mut firmware, mut platform, _signals, task_id) = load_shell_running_firmware();
let close_signals =
InputSignals { f_signal: true, x_pos: 420, y_pos: 24, ..Default::default() };
let close_signals = InputSignals {
f_signal: true,
x_pos: prometeu_hal::graphics_contract::WIDTH as i32 - 60,
y_pos: 24,
..Default::default()
};
firmware.tick(&close_signals, &mut platform);
@@ -47,7 +47,12 @@ impl HubHomeStep {
let id = ctx.os.windows().add_window(
app.title().to_string(),
WindowOwner::Task(task_id),
Rect { x: 40, y: 20, w: 400, h: 220 },
Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
},
app.color(),
);
ctx.os.windows().set_focus(id);
@@ -0,0 +1,20 @@
//! Fixed machine graphics contract. Host surfaces never change these dimensions.
pub const WIDTH: usize = 640;
pub const HEIGHT: usize = 360;
pub const REFRESH_HZ: u32 = 60;
/// Canonical RGBA8888, with tightly packed native rows.
pub const BYTES_PER_PIXEL: usize = 4;
pub const PIXELS: usize = WIDTH * HEIGHT;
pub const STRIDE_PIXELS: usize = WIDTH;
pub const STRIDE_BYTES: usize = STRIDE_PIXELS * BYTES_PER_PIXEL;
pub const FRAME_BYTES: usize = STRIDE_BYTES * HEIGHT;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn native_graphics_contract_is_fixed() {
assert_eq!((WIDTH, HEIGHT, REFRESH_HZ), (640, 360, 60));
assert_eq!((PIXELS, STRIDE_BYTES, FRAME_BYTES), (230_400, 2_560, 921_600));
}
}
+1
View File
@@ -12,6 +12,7 @@ pub mod debugger_protocol;
pub mod gfx_bridge;
pub mod glyph;
pub mod glyph_bank;
pub mod graphics_contract;
pub mod host_context;
pub mod host_return;
pub mod input_signals;
+1 -1
View File
@@ -64,7 +64,7 @@ pub trait RuntimePlatform {
fn wall_clock(&self) -> &dyn WallClock;
fn display_size(&self) -> (usize, usize) {
(480, 270)
(crate::graphics_contract::WIDTH, crate::graphics_contract::HEIGHT)
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink;
@@ -224,6 +224,8 @@ impl SceneViewportResolver {
scene_height_tiles: usize,
) -> TileAnchor {
let mut next = current;
// Mixed layers must not step past the center and immediately step back.
let trigger = self.hysteresis_trigger_px.max(tile_size_px / 2);
loop {
let center_x_px = next.x * tile_size_px + tile_size_px / 2;
@@ -231,11 +233,11 @@ impl SceneViewportResolver {
if drift_x.abs() <= self.hysteresis_safe_px {
break;
}
if drift_x > self.hysteresis_trigger_px {
if drift_x > trigger {
next.x += 1;
continue;
}
if drift_x < -self.hysteresis_trigger_px {
if drift_x < -trigger {
next.x -= 1;
continue;
}
@@ -248,11 +250,11 @@ impl SceneViewportResolver {
if drift_y.abs() <= self.hysteresis_safe_px {
break;
}
if drift_y > self.hysteresis_trigger_px {
if drift_y > trigger {
next.y += 1;
continue;
}
if drift_y < -self.hysteresis_trigger_px {
if drift_y < -trigger {
next.y -= 1;
continue;
}
@@ -433,20 +435,34 @@ mod tests {
#[test]
fn first_update_initializes_master_and_layer_anchors() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 0, 0);
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 17, y: 10 });
assert_eq!(update.layer_anchors[1], TileAnchor { x: 17, y: 10 });
assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[1], TileAnchor { x: 22, y: 13 });
assert_eq!(update.refresh_requests.len(), 4);
}
#[test]
fn per_layer_copy_requests_follow_parallax_factor() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 32, 48);
@@ -461,24 +477,38 @@ mod tests {
#[test]
fn hysteresis_prevents_small_back_and_forth_refresh_churn() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 8, 0);
assert!(update.refresh_requests.is_empty());
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 });
assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
}
#[test]
fn repeated_high_speed_movement_advances_in_tile_steps() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 0);
assert!(update.master_anchor.x > 17);
assert!(update.master_anchor.x > 22);
assert!(update.refresh_requests.iter().any(|request| matches!(
request,
CacheRefreshRequest::RefreshColumn { layer_index: 0, .. }
@@ -489,18 +519,32 @@ mod tests {
#[test]
fn anchors_clamp_near_scene_edges() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 10_000, 10_000);
assert_eq!(update.master_anchor, TileAnchor { x: 46, y: 53 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 46, y: 53 });
assert_eq!(update.master_anchor, TileAnchor { x: 41, y: 50 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 41, y: 50 });
}
#[test]
fn corner_trigger_converts_to_non_overlapping_region_requests() {
let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 80);
@@ -515,15 +559,22 @@ mod tests {
.collect();
assert_eq!(regions.len(), 2);
assert_eq!(regions[0].x + regions[0].width, 35);
assert_eq!(regions[0].height, 21);
assert_eq!(regions[1].width, 34);
assert_eq!(regions[0].x + regions[0].width, 45);
assert_eq!(regions[0].height, 27);
assert_eq!(regions[1].width, 44);
assert_eq!(regions[1].height, 2);
}
#[test]
fn reset_scene_requests_full_invalidation_for_all_layers() {
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20);
let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let requests = resolver.reset_scene();
@@ -385,6 +385,14 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
}
pub fn record_presented_render_worker_frame(
&self,
ownership: RenderOwnership,
frame_id: FrameId,
) {
self.os.vm_runtime.record_presented_render_worker_frame(ownership, frame_id);
}
pub fn active_render_ownership(&self) -> RenderOwnership {
if let Some(task_id) = self.foreground_session_task_id()
&& let Some(session) = self.os.vm_sessions.for_task(task_id)
@@ -10,19 +10,41 @@ use prometeu_hal::{
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 };
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 };
const CLOSE_BUTTON: Rect = Rect { x: 420, y: 24, w: 16, h: 16 };
const VIEWPORT: Rect = Rect { x: 0, y: 0, w: 480, h: 270 };
const HOME_PANEL: Rect = Rect { x: 48, y: 58, w: 384, h: 154 };
const TITLE_PANEL: Rect = Rect { x: 72, y: 34, w: 336, h: 28 };
const CLOSE_BUTTON: Rect =
Rect { x: prometeu_hal::graphics_contract::WIDTH as i32 - 60, y: 24, w: 16, h: 16 };
const VIEWPORT: Rect = Rect {
x: 0,
y: 0,
w: prometeu_hal::graphics_contract::WIDTH as i32,
h: prometeu_hal::graphics_contract::HEIGHT as i32,
};
const HOME_PANEL: Rect = Rect {
x: 48,
y: 58,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 96,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 116,
};
const TITLE_PANEL: Rect =
Rect { x: 72, y: 34, w: prometeu_hal::graphics_contract::WIDTH as i32 - 144, h: 28 };
const GAME_ROW_X: i32 = 72;
const GAME_ROW_Y: i32 = 90;
const GAME_ROW_W: i32 = 336;
const GAME_ROW_W: i32 = prometeu_hal::graphics_contract::WIDTH as i32 - 144;
const GAME_ROW_H: i32 = 22;
const GAME_ROW_GAP: i32 = 6;
const MAX_HOME_GAME_ROWS: usize = 3;
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 };
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect {
x: prometeu_hal::graphics_contract::WIDTH as i32 - 192,
y: prometeu_hal::graphics_contract::HEIGHT as i32 - 40,
w: 168,
h: 24,
};
#[cfg(test)]
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 };
const SHELL_FRAME: Rect = Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
};
const COLOR_BG: Color = Color::rgb(12, 14, 22);
const COLOR_PANEL: Color = Color::rgb(25, 31, 48);
@@ -187,6 +187,16 @@ impl VirtualMachineRuntime {
self.render_worker_ownership.set(self.render_manager.active_ownership());
}
pub fn record_presented_render_worker_frame(
&self,
ownership: prometeu_hal::RenderOwnership,
frame_id: FrameId,
) {
if let Some(controller) = self.render_worker_controller.as_ref() {
controller.record_presented_frame(ownership, frame_id);
}
}
pub fn record_repeated_render_worker_frame(&self, frame_id: FrameId) {
if let Some(controller) = self.render_worker_controller.as_ref() {
controller.record_repeated_frame(frame_id);
@@ -25,6 +25,7 @@ impl Default for RenderWorkerConfig {
struct RenderWorkerState {
telemetry: RenderWorkerTelemetry,
last_error: Option<RenderWorkerError>,
last_presented: Option<(RenderOwnership, FrameId)>,
}
#[derive(Clone, Debug, Default)]
@@ -157,6 +158,7 @@ impl RenderWorkerController {
let mut telemetry = self.handoff.telemetry();
let state = self.state.lock().unwrap();
telemetry.published_frames = state.telemetry.published_frames;
telemetry.presented_frames = state.telemetry.presented_frames;
telemetry.render_failures = state.telemetry.render_failures;
telemetry.publish_failures = state.telemetry.publish_failures;
telemetry.present_failures = state.telemetry.present_failures;
@@ -179,6 +181,17 @@ impl RenderWorkerController {
self.ownership.snapshot()
}
/// Record only after a successful host presentation, never on publication.
pub fn record_presented_frame(&self, ownership: RenderOwnership, frame_id: FrameId) {
let mut state = self.state.lock().unwrap();
if state.last_presented == Some((ownership, frame_id)) {
state.telemetry.record_repeated_frame(frame_id.get());
} else {
state.telemetry.record_presented(frame_id.get());
}
state.last_presented = Some((ownership, frame_id));
}
pub fn record_repeated_frame(&self, frame_id: FrameId) {
let mut state = self.state.lock().unwrap();
state.telemetry.record_repeated_frame(frame_id.get());
@@ -203,13 +216,13 @@ fn run_worker_loop<B, S>(
B: RenderWorkerBackend,
S: RenderWorkerFrameSink,
{
loop {
let submission = match handoff.wait_take() {
RenderWorkerHandoffWait::Submission(submission) => submission,
RenderWorkerHandoffWait::Shutdown => return,
};
let report_path = std::env::var_os("PROMETEU_GRAPHICS_METRICS").map(std::path::PathBuf::from);
let mut measurements = Vec::new();
let mut measured_frames = 0usize;
while let RenderWorkerHandoffWait::Submission(submission) = handoff.wait_take() {
let frame_id = submission.frame_id;
let render_begin = report_path.as_ref().map(|_| std::time::Instant::now());
let render_result = catch_unwind(AssertUnwindSafe(|| backend.render(&submission)))
.map_err(|_| RenderWorkerError::WorkerPanic);
let frame = match render_result {
@@ -225,13 +238,45 @@ fn run_worker_loop<B, S>(
continue;
}
let render_us = render_begin.map(|start| start.elapsed().as_micros() as u64);
let publish_begin = report_path.as_ref().map(|_| std::time::Instant::now());
let publish_result = catch_unwind(AssertUnwindSafe(|| sink.publish(frame)))
.map_err(|_| RenderWorkerError::WorkerPanic);
if let (Some(render_us), Some(begin)) = (render_us, publish_begin) {
let sample = (frame_id.get(), render_us, begin.elapsed().as_micros() as u64);
if measurements.len() < 16384 {
measurements.push(sample);
} else {
measurements[measured_frames % 16384] = sample;
}
measured_frames += 1;
}
match publish_result {
Ok(Ok(())) => record_published(&state, frame_id),
Ok(Err(error)) | Err(error) => record_error(&state, error, frame_id),
}
}
if let Some(path) = report_path {
use std::io::Write;
let worker = state.lock().unwrap();
let handoff = handoff.telemetry();
let report = serde_json::json!({"schema":1,"source":"async_render_worker",
"produced_submissions":handoff.produced_submissions,"consumed_submissions":handoff.consumed_submissions,
"replaced_before_consume":handoff.replaced_before_consume,
"published_frames":worker.telemetry.published_frames,"first_presentations":worker.telemetry.presented_frames,
"repeated_presentations":worker.telemetry.repeated_frames,
"render_failures":worker.telemetry.render_failures,"publish_failures":worker.telemetry.publish_failures,
"measured_frames":measured_frames,"samples_frame_render_publish_us":measurements,
"physical_display_hz":null,
"limitations":"last 16384 successful-render samples; render includes owned-frame copy; sink publication is not scanout; opt-in clock and storage overhead"});
if let Ok(mut file) = std::fs::OpenOptions::new()
.create(true)
.append(true)
.open(path.with_extension("renderer.jsonl"))
{
let _ = writeln!(file, "{report}");
}
}
}
fn record_published(state: &Arc<Mutex<RenderWorkerState>>, frame_id: FrameId) {
@@ -346,6 +391,14 @@ mod tests {
SharedFakeBackend(backend),
);
let first_session = RenderOwnership::new(1, AppMode::Game, 7);
controller.record_presented_frame(first_session, FrameId::ZERO);
controller.record_presented_frame(first_session, FrameId::ZERO);
// Frame zero in a new epoch is a new image, not a repeat of the old session.
controller.record_presented_frame(RenderOwnership::new(2, AppMode::Game, 7), FrameId::ZERO);
assert_eq!(controller.telemetry().presented_frames, 2);
assert_eq!(controller.telemetry().repeated_frames, 1);
assert_eq!(controller.stop(), Ok(()));
assert_eq!(controller.last_error(), None);
}
@@ -0,0 +1,89 @@
//! Bounded run of the production desktop host, with normal teardown for metrics.
//! No machine timing or rendering loop is replaced by this measurement harness.
use prometeu_host_desktop_winit::{audio, fs_backend, log_sink, stats, utilities, wall_clock};
#[allow(dead_code)]
#[path = "../src/debugger.rs"]
mod debugger;
#[path = "../src/input.rs"]
mod input;
#[path = "../src/presentation_blit.rs"]
mod presentation_blit;
#[allow(dead_code)]
#[path = "../src/studio/mod.rs"]
mod studio;
#[path = "../src/viewport.rs"]
mod viewport;
// Compile the actual host implementation; its non-desktop entry points are unused
// by this executable. Keep measurement access out of the product's public API.
#[allow(dead_code)]
mod runner {
include!("../src/runner.rs");
impl HostRunner {
pub(super) fn measured_state(&mut self) -> serde_json::Value {
serde_json::json!({
"host_vm_ticks": self.firmware.os.vm().tick_index(),
"completed_vm_frames": self.firmware.os.vm().completed_logical_frames(),
"logical_frame_index": self.firmware.os.vm().logical_frame_index(),
"synchronous_publications": self.firmware.os.vm().telemetry_snapshot().presented_frames,
"front_buffer_publications": self.hardware.gfx.publication_count(),
"physical_display_hz": null,
})
}
}
}
use std::time::{Duration, Instant};
use winit::{
application::ApplicationHandler,
event::WindowEvent,
event_loop::{ActiveEventLoop, EventLoop},
window::WindowId,
};
struct Measure {
runner: runner::HostRunner,
started: Option<Instant>,
duration: Duration,
}
impl ApplicationHandler for Measure {
fn resumed(&mut self, events: &ActiveEventLoop) {
self.runner.resumed(events);
self.started = Some(Instant::now());
}
fn window_event(&mut self, events: &ActiveEventLoop, id: WindowId, event: WindowEvent) {
self.runner.window_event(events, id, event);
}
fn about_to_wait(&mut self, events: &ActiveEventLoop) {
if self.started.is_some_and(|start| start.elapsed() >= self.duration) {
events.exit();
} else {
self.runner.about_to_wait(events);
}
}
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let path = std::env::args().nth(1).expect("cartridge directory");
let seconds: u64 = std::env::args().nth(2).map(|s| s.parse().expect("seconds")).unwrap_or(10);
assert!(seconds > 0);
let mut runner = runner::HostRunner::new(None, None);
runner.set_boot_target(prometeu_firmware::BootTarget::Cartridge {
path,
debug: false,
debug_port: 0,
});
let mut app = Measure { runner, started: None, duration: Duration::from_secs(seconds) };
let mut events = EventLoop::builder();
#[cfg(target_os = "macos")]
{
use winit::platform::macos::EventLoopBuilderExtMacOS;
events.with_activate_ignoring_other_apps(true);
}
events.build()?.run_app(&mut app)?;
println!(
"{}",
serde_json::json!({"schema":1,"source":"production_desktop_host",
"elapsed_seconds":app.started.map(|s|s.elapsed().as_secs_f64()),
"state":app.runner.measured_state(),
"limitation":"includes boot, no discarded warmup; host/API submission is not physical scanout"})
);
Ok(())
}
@@ -0,0 +1,148 @@
//! GPU readback qualification of the actual host blit, not a software geometry mirror.
#[path = "../src/presentation_blit.rs"]
mod presentation_blit;
#[path = "../src/viewport.rs"]
mod viewport;
use pixels::{PixelsBuilder, SurfaceTexture, wgpu};
use winit::{
application::ApplicationHandler,
event_loop::{ActiveEventLoop, EventLoop},
window::Window,
};
#[derive(Default)]
struct Probe;
impl ApplicationHandler for Probe {
fn resumed(&mut self, events: &ActiveEventLoop) {
let window = Box::leak(Box::new(
events
.create_window(
Window::default_attributes()
.with_title("PROMETEU graphics qualification")
.with_inner_size(winit::dpi::PhysicalSize::new(640, 360)),
)
.unwrap(),
));
let size = window.inner_size();
let mut pixels =
PixelsBuilder::new(640, 360, SurfaceTexture::new(size.width, size.height, &*window))
.build()
.unwrap();
for (i, p) in pixels.frame_mut().as_chunks_mut::<4>().0.iter_mut().enumerate() {
let (x, y) = (i % 640, i / 640);
// Single-pixel checkerboard detects smoothing; all channels equal avoid channel-order ambiguity.
let value = if (x + y) % 2 == 0 { 255 } else { 0 };
p.copy_from_slice(&[value, value, value, 255]);
}
// Exercise real surface acquisition/upload/shader validation too.
let blit = presentation_blit::PresentationBlit::new(&pixels);
pixels
.render_with(|e, t, _| {
blit.render(
e,
t,
viewport::Viewport::new((size.width, size.height), (640, 360)).unwrap(),
);
Ok(())
})
.unwrap();
let ctx = pixels.context();
// A newly created macOS surface may be occluded: render_with then returns
// without uploading. Offscreen verification must establish its own input.
ctx.queue.write_texture(
wgpu::TexelCopyTextureInfo {
texture: &ctx.texture,
mip_level: 0,
origin: wgpu::Origin3d::ZERO,
aspect: wgpu::TextureAspect::All,
},
pixels.frame(),
wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(640 * 4),
rows_per_image: Some(360),
},
ctx.texture_extent,
);
for (w, h) in [(1280u32, 720u32), (1000, 700), (320, 240), (641, 361)] {
let view = viewport::Viewport::new((w, h), (640, 360)).unwrap();
let texture = ctx.device.create_texture(&wgpu::TextureDescriptor {
label: Some("blit-readback"),
size: wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
mip_level_count: 1,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: pixels.render_texture_format(),
usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
view_formats: &[],
});
let stride = (w * 4).div_ceil(256) * 256;
let buffer = ctx.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("readback"),
size: u64::from(stride) * u64::from(h),
usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
mapped_at_creation: false,
});
let mut encoder = ctx.device.create_command_encoder(&Default::default());
blit.render(&mut encoder, &texture.create_view(&Default::default()), view);
encoder.copy_texture_to_buffer(
wgpu::TexelCopyTextureInfo {
texture: &texture,
mip_level: 0,
origin: wgpu::Origin3d::ZERO,
aspect: wgpu::TextureAspect::All,
},
wgpu::TexelCopyBufferInfo {
buffer: &buffer,
layout: wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(stride),
rows_per_image: Some(h),
},
},
wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
);
ctx.queue.submit([encoder.finish()]);
let (tx, rx) = std::sync::mpsc::channel();
buffer.slice(..).map_async(wgpu::MapMode::Read, move |result| tx.send(result).unwrap());
ctx.device.poll(wgpu::PollType::wait_indefinitely()).unwrap();
rx.recv().unwrap().unwrap();
let data = buffer.slice(..).get_mapped_range();
let mut checked = 0;
for y in 0..h {
for x in 0..w {
let offset = (y * stride + x * 4) as usize;
let rgb = &data[offset..offset + 3];
// Every output pixel is black or white: any intermediate value means smoothing.
assert!(
rgb == [0, 0, 0] || rgb == [255, 255, 255],
"filtered pixel at {w}x{h}:({x},{y})={rgb:?}"
);
if let Some((nx, ny)) = view.inverse(x as f64 + 0.5, y as f64 + 0.5) {
let expected = if (nx + ny) % 2 == 0 { 255 } else { 0 };
assert_eq!(
rgb, [expected; 3],
"GPU/input transform mismatch at {w}x{h}:({x},{y})"
);
checked += 1;
} else {
assert_eq!(rgb, [0, 0, 0], "bar");
}
}
}
assert!(checked > 0);
println!("GPU_NEAREST_PASS={w}x{h} checked={checked}");
}
events.exit();
}
fn window_event(
&mut self,
_: &ActiveEventLoop,
_: winit::window::WindowId,
_: winit::event::WindowEvent,
) {
}
}
fn main() {
EventLoop::new().unwrap().run_app(&mut Probe).unwrap();
}
@@ -3,48 +3,11 @@ use winit::event::{ElementState, MouseButton, WindowEvent};
use winit::keyboard::{KeyCode, PhysicalKey};
use winit::window::Window;
#[derive(Debug, Clone, Copy)]
struct FbViewport {
pub x: f32,
pub y: f32,
pub w: f32,
pub h: f32,
pub scale: f32,
}
impl FbViewport {
fn framebuffer_viewport(window: &Window, display_size: (usize, usize)) -> Option<FbViewport> {
let size = window.inner_size();
let win_w = size.width as f32;
let win_h = size.height as f32;
if win_w <= 0.0 || win_h <= 0.0 {
return None;
}
let fb_w = display_size.0 as f32;
let fb_h = display_size.1 as f32;
let scale_x = (win_w / fb_w).floor();
let scale_y = (win_h / fb_h).floor();
let scale = scale_x.min(scale_y).max(1.0);
let viewport_w = fb_w * scale;
let viewport_h = fb_h * scale;
let viewport_x = ((win_w - viewport_w) * 0.5).floor();
let viewport_y = ((win_h - viewport_h) * 0.5).floor();
Some(FbViewport { x: viewport_x, y: viewport_y, w: viewport_w, h: viewport_h, scale })
}
}
pub struct HostInputHandler {
pub signals: InputSignals,
system_controls: HostSystemControls,
display_size: (usize, usize),
cursor: Option<(f64, f64)>,
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
@@ -66,7 +29,7 @@ impl HostSystemControls {
impl Default for HostInputHandler {
fn default() -> Self {
Self::new((480, 270))
Self::new((prometeu_hal::graphics_contract::WIDTH, prometeu_hal::graphics_contract::HEIGHT))
}
}
@@ -76,6 +39,7 @@ impl HostInputHandler {
signals: InputSignals::default(),
system_controls: HostSystemControls::default(),
display_size,
cursor: None,
}
}
@@ -121,50 +85,34 @@ impl HostInputHandler {
}
WindowEvent::CursorMoved { position, .. } => {
if let Some((x, y)) =
window_to_fb(position.x as f32, position.y as f32, window, self.display_size)
{
self.signals.x_pos = x;
self.signals.y_pos = y;
}
self.cursor = Some((position.x, position.y));
let size = window.inner_size();
self.update_pointer((size.width, size.height));
}
WindowEvent::CursorLeft { .. } | WindowEvent::Focused(false) => {
self.signals.f_signal = false;
self.cursor = None;
}
WindowEvent::Resized(size) => self.update_pointer((size.width, size.height)),
WindowEvent::MouseInput { state, button, .. } if *button == MouseButton::Left => {
match state {
ElementState::Pressed => {
self.signals.f_signal = true;
}
ElementState::Released => {
self.signals.f_signal = false;
}
}
let size = window.inner_size();
let inside = self.pointer_position((size.width, size.height)).is_some();
self.signals.f_signal = *state == ElementState::Pressed && inside;
}
_ => {}
}
fn window_to_fb(
wx: f32,
wy: f32,
window: &Window,
display_size: (usize, usize),
) -> Option<(i32, i32)> {
let viewport = FbViewport::framebuffer_viewport(window, display_size)?;
let local_x = wx - viewport.x;
let local_y = wy - viewport.y;
if local_x < 0.0 || local_y < 0.0 || local_x >= viewport.w || local_y >= viewport.h {
return None;
}
let fb_x = (local_x / viewport.scale).floor() as i32;
let fb_y = (local_y / viewport.scale).floor() as i32;
Some((
fb_x.clamp(0, display_size.0 as i32 - 1),
fb_y.clamp(0, display_size.1 as i32 - 1),
))
}
fn pointer_position(&self, surface: (u32, u32)) -> Option<(i32, i32)> {
let (x, y) = self.cursor?;
crate::viewport::Viewport::new(surface, self.display_size)?.inverse(x, y)
}
fn update_pointer(&mut self, surface: (u32, u32)) {
if let Some((x, y)) = self.pointer_position(surface) {
self.signals.x_pos = x;
self.signals.y_pos = y;
} else {
self.signals.f_signal = false;
}
}
}
@@ -173,6 +121,23 @@ impl HostInputHandler {
mod tests {
use super::*;
#[test]
fn drag_cancels_outside_and_cannot_recapture_on_reentry() {
let mut input = HostInputHandler {
cursor: Some((200.0, 200.0)),
signals: InputSignals { f_signal: true, ..Default::default() },
..Default::default()
};
input.update_pointer((1000, 700));
assert_eq!((input.signals.x_pos, input.signals.y_pos), (20, 30));
input.cursor = Some((10.0, 200.0)); // left letterbox
input.update_pointer((1000, 700));
assert!(!input.signals.f_signal);
input.cursor = Some((200.0, 200.0));
input.update_pointer((1000, 700));
assert!(!input.signals.f_signal);
}
fn assert_no_pad_signal(signals: InputSignals) {
assert!(!signals.up_signal);
assert!(!signals.down_signal);
@@ -4,10 +4,12 @@ pub mod debugger;
pub mod fs_backend;
pub mod input;
pub mod log_sink;
mod presentation_blit;
pub mod runner;
pub mod stats;
pub mod studio;
pub mod utilities;
mod viewport;
pub mod wall_clock;
use cap::load_cap_config;
@@ -0,0 +1,107 @@
//! Host-only blit: pixels' built-in PixelPerfect path crops below 1x and Fill smooths.
use crate::viewport::Viewport;
use pixels::{Pixels, wgpu};
pub(crate) struct PresentationBlit {
pipeline: wgpu::RenderPipeline,
texture: wgpu::BindGroup,
geometry: wgpu::Buffer,
queue: wgpu::Queue,
}
impl PresentationBlit {
pub fn new(pixels: &Pixels<'_>) -> Self {
let device = pixels.device();
let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("native-nearest-blit"),
source: wgpu::ShaderSource::Wgsl(
r#"
struct Vertex { @builtin(position) position: vec4f, @location(0) uv: vec2f }
@vertex fn vs(@builtin(vertex_index) i: u32) -> Vertex {
let p = array<vec2f,3>(vec2f(-1,-1),vec2f(3,-1),vec2f(-1,3));
var v: Vertex; v.position=vec4f(p[i],0,1); v.uv=vec2f((p[i].x+1)*0.5,(1-p[i].y)*0.5); return v;
}
@group(0) @binding(0) var image: texture_2d<f32>;
@group(0) @binding(1) var<uniform> geometry: vec4f;
@fragment fn fs(v: Vertex) -> @location(0) vec4f {
let size=vec2i(textureDimensions(image));
let pixel=clamp(vec2i(floor((v.position.xy-geometry.xy)/geometry.z)),vec2i(0),size-vec2i(1));
return textureLoad(image,pixel,0);
}"#
.into(),
),
});
let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
label: Some("native-nearest-blit"),
layout: None,
vertex: wgpu::VertexState {
module: &shader,
entry_point: Some("vs"),
buffers: &[],
compilation_options: Default::default(),
},
fragment: Some(wgpu::FragmentState {
module: &shader,
entry_point: Some("fs"),
compilation_options: Default::default(),
targets: &[Some(wgpu::ColorTargetState {
format: pixels.render_texture_format(),
blend: Some(wgpu::BlendState::ALPHA_BLENDING),
write_mask: wgpu::ColorWrites::ALL,
})],
}),
primitive: Default::default(),
depth_stencil: None,
multisample: Default::default(),
multiview_mask: None,
cache: None,
});
let view = pixels.context().texture.create_view(&Default::default());
let geometry = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("native-viewport"),
size: 16,
usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let texture = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("native-nearest-texture"),
layout: &pipeline.get_bind_group_layout(0),
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: wgpu::BindingResource::TextureView(&view),
},
wgpu::BindGroupEntry { binding: 1, resource: geometry.as_entire_binding() },
],
});
Self { pipeline, texture, geometry, queue: pixels.context().queue.clone() }
}
pub fn render(
&self,
encoder: &mut wgpu::CommandEncoder,
target: &wgpu::TextureView,
viewport: Viewport,
) {
let geometry = [viewport.x, viewport.y, viewport.scale, 0.0].map(f32::to_ne_bytes);
self.queue.write_buffer(&self.geometry, 0, geometry.as_flattened());
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some("native-nearest-present"),
color_attachments: &[Some(wgpu::RenderPassColorAttachment {
view: target,
resolve_target: None,
ops: wgpu::Operations {
load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
store: wgpu::StoreOp::Store,
},
depth_slice: None,
})],
depth_stencil_attachment: None,
timestamp_writes: None,
occlusion_query_set: None,
multiview_mask: None,
});
pass.set_pipeline(&self.pipeline);
pass.set_bind_group(0, &self.texture, &[]);
pass.set_viewport(viewport.x, viewport.y, viewport.width, viewport.height, 0.0, 1.0);
pass.draw(0..3, 0..1);
}
}
@@ -118,6 +118,7 @@ pub struct HostRunner {
window: Option<&'static Window>,
/// The pixel buffer interface for rendering to the GPU.
pixels: Option<Pixels<'static>>,
blit: Option<crate::presentation_blit::PresentationBlit>,
/// The instance of the virtual hardware peripherals.
hardware: Hardware,
@@ -195,7 +196,7 @@ impl HostRunner {
/// Creates a new desktop runner instance.
pub(crate) fn new(fs_root: Option<String>, cap_config: Option<CertificationConfig>) -> Self {
let target_fps = 60;
let target_fps = prometeu_hal::graphics_contract::REFRESH_HZ;
let mut firmware = Firmware::new(cap_config);
if let Some(root) = &fs_root {
@@ -225,12 +226,13 @@ impl HostRunner {
Self {
window: None,
pixels: None,
blit: None,
hardware,
firmware,
input: HostInputHandler::new(display_size),
fs_root,
log_sink: HostConsoleSink::new(),
frame_target_dt: Duration::from_nanos(1_000_000_000 / target_fps),
frame_target_dt: Duration::from_nanos(1_000_000_000 / u64::from(target_fps)),
last_frame_time: Instant::now(),
accumulator: Duration::ZERO,
@@ -430,15 +432,32 @@ impl HostRunner {
fn machine_running(&mut self) -> bool {
!self.firmware.os.vm().paused() && !self.debugger.waiting_for_start
}
fn observe_latest_frame(&mut self) {
let active_ownership = self.firmware.os.vm().active_render_ownership();
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
{
self.presentation
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
} else {
// Observe the actual front-buffer swap, including native Hub/Shell
// publications which do not execute a VM frame.
let publication = self.hardware.gfx.publication_count();
if publication > 0 {
self.presentation.note_published_frame(active_ownership, publication);
}
}
}
}
impl ApplicationHandler for HostRunner {
fn resumed(&mut self, event_loop: &ActiveEventLoop) {
let attrs = WindowAttributes::default()
.with_title(format!(
"PROMETEU | GFX: {:.1} KB | FPS: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
"PROMETEU | GFX: {:.1} KB | Host ticks/s: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
0.0, 0.0, 0.0, 0, 0, 0, 0))
.with_inner_size(LogicalSize::new(960.0, 540.0))
.with_inner_size(LogicalSize::new((prometeu_hal::graphics_contract::WIDTH * 2) as f64, (prometeu_hal::graphics_contract::HEIGHT * 2) as f64))
.with_min_inner_size(LogicalSize::new(320.0, 180.0));
let window = event_loop.create_window(attrs).expect("failed to create window");
@@ -460,6 +479,7 @@ impl ApplicationHandler for HostRunner {
pixels.frame_mut().fill(0);
self.blit = Some(crate::presentation_blit::PresentationBlit::new(&pixels));
self.pixels = Some(pixels);
if let Err(err) = self.audio.init(self.hardware.audio.transport()) {
@@ -490,9 +510,16 @@ impl ApplicationHandler for HostRunner {
self.request_redraw_if_needed();
}
WindowEvent::Occluded(false) => {
self.invalidate_host_surface();
self.request_redraw_if_needed();
}
WindowEvent::RedrawRequested => {
let pixels = self.pixels.as_mut().expect("pixels not initialized");
let mut presented_worker = None;
let mut presented_frame = None;
{
let frame = pixels.frame_mut();
@@ -504,20 +531,47 @@ impl ApplicationHandler for HostRunner {
active_ownership,
)
{
self.firmware
.os
.vm()
.record_repeated_render_worker_frame(worker_frame.frame_id);
presented_worker = Some((worker_frame.ownership, worker_frame.frame_id));
presented_frame =
Some((worker_frame.ownership, worker_frame.frame_id.get()));
draw_owned_rgba8888_frame_to_rgba8(&worker_frame, frame);
} else {
let src = self.hardware.gfx.front_buffer();
draw_rgba8888_to_rgba8(src, frame);
let publication = self.hardware.gfx.publication_count();
if publication > 0 {
presented_frame = Some((active_ownership, publication));
}
}
}
if pixels.render().is_err() {
let size = self.window.expect("window").inner_size();
let rendered = std::cell::Cell::new(false);
let viewport = crate::viewport::Viewport::new(
(size.width, size.height),
self.hardware.display_size(),
);
let present_start = Instant::now();
let result = pixels.render_with(|encoder, target, _| {
if let Some(viewport) = viewport {
self.blit.as_ref().expect("blit").render(encoder, target, viewport);
rendered.set(true);
}
Ok(())
});
self.stats.record_present_time(present_start.elapsed());
if result.is_err() {
event_loop.exit();
} else {
} else if rendered.get() {
if let Some((ownership, frame_id)) = presented_frame {
self.stats.record_presented(ownership, frame_id);
}
if let Some((ownership, frame_id)) = presented_worker {
self.firmware
.os
.vm()
.record_presented_render_worker_frame(ownership, frame_id);
}
self.presentation.mark_presented();
}
}
@@ -594,17 +648,6 @@ impl ApplicationHandler for HostRunner {
self.stats.record_frame();
}
let active_ownership = self.firmware.os.vm().active_render_ownership();
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
{
self.presentation
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
} else {
self.presentation
.note_published_frame(active_ownership, self.firmware.os.frame_index());
}
if was_debugger_connected != self.debugger.stream.is_some()
|| was_waiting_for_start != self.debugger.waiting_for_start
|| was_paused != self.firmware.os.vm().paused()
@@ -613,6 +656,7 @@ impl ApplicationHandler for HostRunner {
}
// 4. Feedback and Synchronization.
self.observe_latest_frame();
self.audio.update_stats(&mut self.stats);
// Update technical statistics displayed in the window title.
@@ -753,6 +797,15 @@ mod tests {
for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware);
}
// Successful session publications must drive redraw even when the
// physical surface has not otherwise been invalidated.
let completed = runner.firmware.os.vm().logical_frame_index();
assert!(completed > 0, "session published a frame in boot {cycle}");
runner.observe_latest_frame();
runner.presentation.mark_presented();
runner.firmware.tick(&signals, &mut runner.hardware);
runner.observe_latest_frame();
assert!(runner.presentation.needs_redraw(), "new session frame must redraw");
runner.firmware.request_home_from_host();
for _ in 0..32 {
runner.firmware.tick(&signals, &mut runner.hardware);
@@ -761,6 +814,16 @@ mod tests {
}
}
assert!(matches!(runner.firmware.state, FirmwareState::HubHome(_)), "home {cycle}");
runner.observe_latest_frame();
runner.presentation.mark_presented();
let vm_frame = runner.firmware.os.vm().logical_frame_index();
runner.firmware.tick(&signals, &mut runner.hardware);
assert_eq!(runner.firmware.os.vm().logical_frame_index(), vm_frame);
runner.observe_latest_frame();
assert!(
runner.presentation.needs_redraw(),
"native Hub publication must redraw without a VM frame"
);
assert!(runner.firmware.resume_resident_game_from_home());
for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware);
@@ -4,6 +4,13 @@ use winit::window::Window;
pub struct HostStats {
pub last_stats_update: Instant,
metrics_path: Option<std::path::PathBuf>,
present_us: Vec<u64>,
present_count: u64,
ticks_total: u64,
first_presentations: u64,
repeated_presentations: u64,
last_presented: Option<(prometeu_hal::RenderOwnership, u64)>,
pub frames_since_last_update: u64,
pub current_fps: f64,
pub audio_load_accum_us: u64,
@@ -23,6 +30,13 @@ impl HostStats {
pub fn new() -> Self {
Self {
last_stats_update: Instant::now(),
metrics_path: std::env::var_os("PROMETEU_GRAPHICS_METRICS").map(Into::into),
present_us: Vec::new(),
present_count: 0,
ticks_total: 0,
first_presentations: 0,
repeated_presentations: 0,
last_presented: None,
frames_since_last_update: 0,
current_fps: 0.0,
audio_load_accum_us: 0,
@@ -33,8 +47,31 @@ impl HostStats {
}
}
/// API latency, including texture upload/submit; not a physical scanout timestamp.
pub fn record_present_time(&mut self, duration: Duration) {
self.present_count += 1;
if self.metrics_path.is_some() {
let value = duration.as_micros() as u64;
if self.present_us.len() < 16384 {
self.present_us.push(value);
} else {
self.present_us[(self.present_count as usize - 1) % 16384] = value;
}
}
}
pub fn record_frame(&mut self) {
self.frames_since_last_update += 1;
self.ticks_total += 1;
}
pub fn record_presented(&mut self, ownership: prometeu_hal::RenderOwnership, frame_id: u64) {
let marker = (ownership, frame_id);
if self.last_presented == Some(marker) {
self.repeated_presentations += 1;
} else {
self.first_presentations += 1;
}
self.last_presented = Some(marker);
}
pub fn record_audio_perf(&mut self, us: u64) {
@@ -66,7 +103,8 @@ impl HostStats {
if let Some(window) = window {
// Fixed comparison always against 60Hz, keep even when doing CPU stress tests
let frame_budget_us = 16666.0;
let frame_budget_us =
1_000_000.0 / prometeu_hal::graphics_contract::REFRESH_HZ as f64;
let cpu_load_core = (self.average_host_cpu_ms() * 1000.0 / frame_budget_us) * 100.0;
let cpu_load_audio = if self.audio_load_samples > 0 {
@@ -76,7 +114,7 @@ impl HostStats {
};
let title = format!(
"PROMETEU | GFX: {:.1} KB | FPS: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
"PROMETEU | GFX: {:.1} KB | Host ticks/s: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
0,
self.current_fps,
cpu_load_core,
@@ -95,3 +133,41 @@ impl HostStats {
}
}
}
impl Drop for HostStats {
fn drop(&mut self) {
if let Some(path) = &self.metrics_path {
self.present_us.sort_unstable();
let n = self.present_us.len();
let percentile =
|p: usize| if n == 0 { 0 } else { self.present_us[(n * p).div_ceil(100) - 1] };
let report = serde_json::json!({"schema":1,"host_ticks":self.ticks_total,
"first_presentations":self.first_presentations,"repeated_presentations":self.repeated_presentations,
"present_api_calls":self.present_count,"samples":n,
"present_api_mean_us":if n==0 {0.0} else {self.present_us.iter().sum::<u64>() as f64/n as f64},
"present_api_p95_us":percentile(95),"present_api_p99_us":percentile(99),
"present_api_max_us":self.present_us.last().copied().unwrap_or(0),
"present_api_over_budget":self.present_us.iter().filter(|&&v|v > 1_000_000 / u64::from(prometeu_hal::graphics_contract::REFRESH_HZ)).count(),
"physical_display_hz":null,"limitation":"bounded last 16384 API samples; API upload/submit/present time is not scanout latency"});
if let Err(error) = std::fs::write(path, report.to_string()) {
eprintln!("graphics metrics: {error}");
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use prometeu_hal::{RenderOwnership, app_mode::AppMode};
#[test]
fn host_counts_actual_submissions_by_identity_and_epoch() {
let mut stats = HostStats::new();
let first = RenderOwnership::new(1, AppMode::Game, 2);
stats.record_presented(first, 0);
stats.record_presented(first, 0);
stats.record_presented(RenderOwnership::new(2, AppMode::Game, 2), 0);
assert_eq!(stats.first_presentations, 2);
assert_eq!(stats.repeated_presentations, 1);
}
}
@@ -80,7 +80,9 @@ pub(crate) fn run(mut runner: HostRunner, boot: Bootstrap) -> io::Result<()> {
let mut signals = InputSignals::default();
let mut next_tick = Instant::now();
let boot_deadline = Instant::now() + Duration::from_secs(10);
let slice = Duration::from_nanos(1_000_000_000 / 60);
let slice = Duration::from_nanos(
1_000_000_000 / u64::from(prometeu_hal::graphics_contract::REFRESH_HZ),
);
let mut last_request = 0;
let mut last_frame = None;
let outcome = (|| -> io::Result<()> {
@@ -225,7 +227,12 @@ pub(crate) fn run(mut runner: HostRunner, boot: Bootstrap) -> io::Result<()> {
if ready {
runner.studio_pause(true);
let mut p = Vec::new();
for n in [width as u32, height as u32, 60, RGBA8] {
for n in [
width as u32,
height as u32,
prometeu_hal::graphics_contract::REFRESH_HZ,
RGBA8,
] {
p.extend_from_slice(&n.to_le_bytes());
}
p.extend_from_slice(env!("CARGO_PKG_VERSION").as_bytes());
@@ -203,8 +203,8 @@ mod tests {
.is_err()
);
assert!(frame_bytes(u32::MAX, u32::MAX, u32::MAX).is_err());
assert!(frame_bytes(480, 270, 481).is_err());
assert_eq!(frame_bytes(480, 270, 480).unwrap(), 518400);
assert!(frame_bytes(640, 360, 641).is_err());
assert_eq!(frame_bytes(640, 360, 640).unwrap(), 921600);
}
#[test]
fn fragmented_reads_and_writes_preserve_messages() {
@@ -0,0 +1,71 @@
//! Physical surface geometry shared by the nearest blit and pointer normalization.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Viewport {
pub x: f32,
pub y: f32,
pub width: f32,
pub height: f32,
pub scale: f32,
native: (usize, usize),
}
impl Viewport {
pub fn new(surface: (u32, u32), native: (usize, usize)) -> Option<Self> {
if surface.0 == 0 || surface.1 == 0 || native.0 == 0 || native.1 == 0 {
return None;
}
let fit = (surface.0 as f32 / native.0 as f32).min(surface.1 as f32 / native.1 as f32);
let scale = if fit >= 1.0 { fit.floor() } else { fit };
let width = native.0 as f32 * scale;
let height = native.1 as f32 * scale;
Some(Self {
x: ((surface.0 as f32 - width) / 2.0).floor(),
y: ((surface.1 as f32 - height) / 2.0).floor(),
width,
height,
scale,
native,
})
}
pub fn inverse(self, x: f64, y: f64) -> Option<(i32, i32)> {
let (x, y) = (x - self.x as f64, y - self.y as f64);
if !x.is_finite()
|| !y.is_finite()
|| x < 0.0
|| y < 0.0
|| x >= self.width as f64
|| y >= self.height as f64
{
return None;
}
Some((
((x / self.scale as f64).floor() as i32).min(self.native.0 as i32 - 1),
((y / self.scale as f64).floor() as i32).min(self.native.1 as i32 - 1),
))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn physical_scaling_and_inverse_share_bounds() {
for (surface, scale, offset) in [
((1280, 720), 2.0, (0.0, 0.0)),
((1920, 1080), 3.0, (0.0, 0.0)),
((1000, 700), 1.0, (180.0, 170.0)),
((320, 240), 0.5, (0.0, 30.0)),
((2560, 1440), 4.0, (0.0, 0.0)),
] {
let v = Viewport::new(surface, (640, 360)).unwrap();
assert_eq!((v.scale, v.x, v.y), (scale, offset.0, offset.1));
assert_eq!(v.inverse(v.x as f64, v.y as f64), Some((0, 0)));
assert_eq!(
v.inverse((v.x + v.width - 0.01) as f64, (v.y + v.height - 0.01) as f64),
Some((639, 359))
);
assert_eq!(v.inverse((v.x + v.width) as f64, v.y as f64), None);
assert_eq!(v.inverse(v.x as f64, (v.y + v.height) as f64), None);
assert_eq!(v.inverse(v.x as f64 - 0.01, v.y as f64), None);
}
assert!(Viewport::new((0, 0), (640, 360)).is_none());
}
}
@@ -92,7 +92,7 @@ impl Session {
};
let ready = session.control.receive().unwrap();
assert_eq!(ready.header.kind, READY, "{:?}", session.logs.lock().unwrap());
assert_eq!(u32::from_le_bytes(ready.payload[..4].try_into().unwrap()), 480);
assert_eq!(u32::from_le_bytes(ready.payload[..4].try_into().unwrap()), 640);
session
}
fn command(&mut self, kind: u16, request: u64) -> Message {
@@ -119,7 +119,7 @@ impl Session {
.receive()
.unwrap_or_else(|e| panic!("video: {e}; logs: {:?}", self.logs.lock().unwrap()));
assert_eq!(m.header.kind, FRAME);
assert_eq!(m.payload.len(), 48 + 480 * 270 * 4);
assert_eq!(m.payload.len(), 48 + 640 * 360 * 4);
m
}
fn ack(&mut self, frame: &Message) {
@@ -0,0 +1,56 @@
//! Unpaced logical-frame and capture timing through the real headless host.
use prometeu_host_headless::{AdvanceFrameOutcome, HeadlessHost};
use std::time::Instant;
fn stats(mut times: Vec<u64>) -> serde_json::Value {
times.sort_unstable();
let n = times.len();
serde_json::json!({"mean_us":times.iter().sum::<u64>() as f64/n as f64/1000.0,
"p95_us":times[(n*95).div_ceil(100)-1] as f64/1000.0,
"p99_us":times[(n*99).div_ceil(100)-1] as f64/1000.0,
"max_us":times[n-1] as f64/1000.0,
"over_60hz_budget":times.iter().filter(|&&t|t>1_000_000_000/60).count()})
}
fn main() {
let mut args = std::env::args().skip(1);
let cartridge = args.next().expect("cartridge directory");
let count: usize = args.next().map(|s| s.parse().expect("frame count")).unwrap_or(600);
assert!(count > 0);
let mut host = HeadlessHost::new();
host.boot(cartridge).expect("boot");
let mut advance = Vec::with_capacity(count);
let mut capture = Vec::with_capacity(count);
let mut previous = None;
let mut published = 0;
let mut checksum = 0;
for i in 0..count + 120 {
let start = Instant::now();
assert!(matches!(
host.advance_frame().expect("advance"),
AdvanceFrameOutcome::FrameCompleted { .. }
));
let elapsed = start.elapsed().as_nanos() as u64;
let start = Instant::now();
let frame = host.capture_frame().expect("published frame").frame;
let capture_ns = start.elapsed().as_nanos() as u64;
assert_eq!((frame.width, frame.height, frame.stride_pixels), (640, 360, 640));
assert_ne!(previous, Some((frame.ownership, frame.frame_id)));
previous = Some((frame.ownership, frame.frame_id));
checksum ^= frame.pixels[(i * 173) % frame.pixels.len()];
if i >= 120 {
advance.push(elapsed);
capture.push(capture_ns);
published += 1;
}
}
let state = host.get_state();
println!(
"{}",
serde_json::json!({"schema":1,"width":640,"height":360,"frames":count,"warmup_frames":120,
"completed_logical_frames_total":state.frame_index,"host_ticks_total":state.tick_index,
"published_frames_measured":published,"repeated_publications_measured":0,
"advance_including_vm_render_publish":stats(advance),"owned_capture":stats(capture),"checksum":checksum,
"vm_hz":null,"physical_display_hz":null,
"limitations":"unpaced real VM/headless; capture copies owned pixels; no GPU, realtime cadence or physical display"})
);
}
@@ -171,7 +171,7 @@ fn one_frame_returns_and_captures_the_exact_published_frame() {
assert_eq!(captured.frame.ownership.app_mode, AppMode::Game);
assert_eq!(captured.frame.ownership.app_id, 41);
assert_eq!(captured.frame.stride_pixels, captured.frame.width);
assert_eq!(captured.frame.pixels.len(), 480 * 270);
assert_eq!(captured.frame.pixels.len(), 640 * 360);
assert_eq!(host.capture_frame().expect("repeat capture"), captured);
let mut mutated_clone = captured.clone();
@@ -477,8 +477,8 @@ fn assert_completed(outcome: prometeu_host_headless::AdvanceFramesOutcome, expec
}
fn assert_color(captured: &CapturedFrame, color: u32) {
assert_eq!(captured.frame.width, 480);
assert_eq!(captured.frame.height, 270);
assert_eq!(captured.frame.width, 640);
assert_eq!(captured.frame.height, 360);
assert!(captured.frame.pixels.iter().all(|pixel| *pixel == color));
}
+5 -3
View File
@@ -50,15 +50,17 @@ pub fn build_program() -> Vec<u8> {
let draw = rom.len() as u32;
rom.extend(asm(&format!(
"PUSH_I32 180\n\
PUSH_I32 75\n\
"PUSH_I32 {x}\n\
PUSH_I32 {y}\n\
PUSH_I32 120\n\
PUSH_I32 120\n\
PUSH_I64 {}\n\
GET_LOCAL 0\n\
HOSTCALL 1\n\
RET",
Color::WHITE.raw()
Color::WHITE.raw(),
x = (prometeu_hal::graphics_contract::WIDTH - 120) / 2,
y = (prometeu_hal::graphics_contract::HEIGHT - 120) / 2
)));
patch_jump(&mut rom, jump_to_green_case_offset, green_case);
+2 -2
View File
@@ -27,8 +27,8 @@ use std::path::PathBuf;
const STRESS_GLYPH_ASSET_ID: AssetId = 100;
const STRESS_SCENE_ASSET_ID: AssetId = 1;
const STRESS_VIEWPORT_W: i32 = 480;
const STRESS_VIEWPORT_H: i32 = 270;
const STRESS_VIEWPORT_W: i32 = prometeu_hal::graphics_contract::WIDTH as i32;
const STRESS_VIEWPORT_H: i32 = prometeu_hal::graphics_contract::HEIGHT as i32;
const STRESS_SPRITE_COLS: i32 = 48;
const STRESS_SPRITE_ROWS: i32 = 24;
const STRESS_SPRITE_SPACING_PX: i32 = 10;
+28 -5
View File
@@ -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.
+12 -3
View File
@@ -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
+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.
Binary file not shown.
Binary file not shown.