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,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) {