use std::ffi::c_void;
use std::ptr::NonNull;
use std::rc::Rc;
use std::sync::{Arc, Condvar, Mutex};
use std::thread::JoinHandle;
use std::time::{Duration, Instant};
use objc2::rc::{autoreleasepool, Retained};
use objc2::runtime::{NSObject, ProtocolObject};
use objc2::{msg_send, msg_send_id};
use objc2_foundation::{ns_string, CGRect, MainThreadMarker};
use objc2_metal::{
MTLBuffer, MTLCommandBuffer, MTLCommandEncoder, MTLCommandQueue, MTLCreateSystemDefaultDevice,
MTLDevice, MTLDrawable, MTLLibrary, MTLLoadAction, MTLPixelFormat, MTLPrimitiveType, MTLRegion,
MTLRenderCommandEncoder, MTLRenderPassDescriptor, MTLRenderPipelineDescriptor,
MTLRenderPipelineState, MTLResourceOptions, MTLStorageMode, MTLStoreAction, MTLTexture,
MTLTextureDescriptor, MTLTextureUsage, MTLViewport,
};
use objc2_quartz_core::{
kCAGravityBottom, CAAutoresizingMask, CALayer, CAMetalDrawable, CAMetalLayer,
};
use winit::raw_window_handle::{HasWindowHandle, RawWindowHandle};
use winit::window::Window;
use systemless::display::CursorImage;
use systemless::memory::CompactPresentation;
const FRAME_RESOURCE_COUNT: usize = 2;
#[repr(C)]
#[derive(Clone, Copy, Default, Eq, PartialEq)]
struct GuestFrameUniforms {
row_bytes: u32,
width: u32,
height: u32,
pixel_size: u32,
content_left: u32,
content_top: u32,
cursor_kind: u32,
cursor_width: u32,
cursor_height: u32,
cursor_left: i32,
cursor_top: i32,
}
#[repr(C)]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct CompactFrameUniforms {
width: u32,
height: u32,
scale: u32,
crop_left: u32,
crop_top: u32,
crop_width: u32,
crop_height: u32,
dw: u32,
dh: u32,
ox: u32,
oy: u32,
}
#[repr(C)]
#[derive(Clone, Eq, PartialEq)]
struct GuestCursorData {
data_rows: [u32; 16],
mask_rows: [u32; 16],
color_pixels: [u32; 256],
}
#[derive(Clone, Eq, PartialEq)]
struct GuestFrameMetadata {
screen_layout: (u32, u16, u16, u16),
content_rect: (u32, u32, u32, u32),
palette: [u32; 256],
uniforms: GuestFrameUniforms,
cursor: GuestCursorData,
drawable_size: (u32, u32),
}
#[derive(Default)]
struct GuestFrameProfile {
attempts: u64,
unchanged: u64,
forced: u64,
comparison_time: Duration,
presentation_time: Duration,
}
#[derive(Clone, PartialEq, Eq)]
enum FrameMetadata {
Guest(GuestFrameMetadata),
Raster {
layout: RasterLayout,
drawable_size: (u32, u32),
},
Compact(CompactFrameUniforms),
}
pub use super::raster_layout::RasterLayout;
enum FramePixels {
Indexed(Vec<u8>),
Argb(Vec<u32>),
Compact(Arc<CompactPresentation>),
}
impl FramePixels {
fn as_bytes(&self) -> &[u8] {
match self {
Self::Indexed(bytes) => bytes,
Self::Argb(pixels) => argb_bytes(pixels),
Self::Compact(_) => &[],
}
}
}
struct GuestFrameSubmission {
pixels: FramePixels,
metadata: FrameMetadata,
}
#[derive(Default)]
struct GuestFrameMailboxState {
pending: Option<GuestFrameSubmission>,
recycled: Vec<Vec<u8>>,
recycled_argb: Vec<Vec<u32>>,
paused: bool,
active: bool,
drawable_in_use: bool,
shutdown: bool,
error: Option<String>,
submitted: u64,
coalesced: u64,
drawable_wait_time: Duration,
render_time: Duration,
}
impl GuestFrameMailboxState {
fn recycle(&mut self, pixels: FramePixels) {
match pixels {
FramePixels::Indexed(bytes) => self.recycled.push(bytes),
FramePixels::Argb(pixels) => self.recycled_argb.push(pixels),
FramePixels::Compact(_) => {}
}
}
}
#[derive(Default)]
struct GuestFrameMailbox {
state: Mutex<GuestFrameMailboxState>,
changed: Condvar,
}
struct GuestRenderWorker {
layer: Retained<CAMetalLayer>,
device: Retained<ProtocolObject<dyn MTLDevice>>,
command_queue: Retained<ProtocolObject<dyn MTLCommandQueue>>,
pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
guest_buffers: Vec<Retained<ProtocolObject<dyn MTLBuffer>>>,
guest_buffer_size: usize,
next_guest_buffer: usize,
raster_pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
upload_textures: Vec<Retained<ProtocolObject<dyn MTLTexture>>>,
upload_size: (u32, u32),
next_upload_texture: usize,
compact_pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
compact_buffers: CompactBuffers,
}
#[derive(Default)]
struct CompactBuffers {
slots: Vec<[(Retained<ProtocolObject<dyn MTLBuffer>>, usize); 2]>,
next: usize,
}
impl CompactBuffers {
fn upload(
&mut self,
device: &ProtocolObject<dyn MTLDevice>,
frame: &CompactPresentation,
) -> Result<
(
&ProtocolObject<dyn MTLBuffer>,
&ProtocolObject<dyn MTLBuffer>,
),
String,
> {
let allocate = |words: usize| {
let capacity = words.max(1).next_power_of_two();
device
.newBufferWithLength_options(
capacity * size_of::<u32>(),
MTLResourceOptions::MTLResourceStorageModeShared,
)
.map(|buffer| (buffer, capacity))
.ok_or_else(|| "Metal failed to allocate a compact frame buffer".to_string())
};
if self.slots.len() != FRAME_RESOURCE_COUNT {
self.slots.clear();
for _ in 0..FRAME_RESOURCE_COUNT {
self.slots.push([
allocate(frame.cells.len())?,
allocate(frame.detail.len())?,
]);
}
self.next = 0;
}
let index = self.next;
self.next = (index + 1) % self.slots.len();
let slot = &mut self.slots[index];
for ((buffer, capacity), data) in slot
.iter_mut()
.zip([frame.cells.as_slice(), frame.detail.as_slice()])
{
if *capacity < data.len() {
(*buffer, *capacity) = allocate(data.len())?;
}
unsafe {
std::ptr::copy_nonoverlapping(
data.as_ptr(),
buffer.contents().as_ptr().cast::<u32>(),
data.len(),
);
}
}
let [(cells, _), (detail, _)] = &self.slots[index];
Ok((cells, detail))
}
}
unsafe impl Send for GuestRenderWorker {}
struct AsyncGuestPresenter {
mailbox: Arc<GuestFrameMailbox>,
thread: Option<JoinHandle<()>>,
}
impl Default for GuestCursorData {
fn default() -> Self {
Self {
data_rows: [0; 16],
mask_rows: [0; 16],
color_pixels: [0; 256],
}
}
}
fn take_superseded_pending(state: &mut GuestFrameMailboxState) -> Option<FramePixels> {
let previous = state.pending.take()?;
state.coalesced = state.coalesced.saturating_add(1);
Some(previous.pixels)
}
fn indexed_staging_buffer(state: &mut GuestFrameMailboxState) -> Vec<u8> {
match take_superseded_pending(state) {
Some(FramePixels::Indexed(bytes)) => bytes,
Some(other) => {
state.recycle(other);
state.recycled.pop().unwrap_or_default()
}
None => state.recycled.pop().unwrap_or_default(),
}
}
fn replace_pending_guest_frame(
state: &mut GuestFrameMailboxState,
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
metadata: FrameMetadata,
) {
let mut pixels = indexed_staging_buffer(state);
copy_guest_visible_pixels(&mut pixels, framebuffer, layout);
state.pending = Some(GuestFrameSubmission {
pixels: FramePixels::Indexed(pixels),
metadata,
});
}
fn replace_pending_raster_frame(
state: &mut GuestFrameMailboxState,
pixels: Vec<u32>,
layout: RasterLayout,
drawable_size: (u32, u32),
) -> Vec<u32> {
let spare = match take_superseded_pending(state) {
Some(FramePixels::Argb(superseded)) => Some(superseded),
Some(other) => {
state.recycle(other);
None
}
None => None,
};
let spare = spare
.or_else(|| state.recycled_argb.pop())
.unwrap_or_default();
state.pending = Some(GuestFrameSubmission {
pixels: FramePixels::Argb(pixels),
metadata: FrameMetadata::Raster {
layout,
drawable_size,
},
});
spare
}
impl AsyncGuestPresenter {
fn new(worker: GuestRenderWorker) -> Result<Self, String> {
let mailbox = Arc::new(GuestFrameMailbox::default());
let worker_mailbox = Arc::clone(&mailbox);
let thread = std::thread::Builder::new()
.name("systemless-metal-present".to_string())
.spawn(move || worker.run(worker_mailbox))
.map_err(|error| format!("failed to start Metal presenter thread: {error}"))?;
Ok(Self {
mailbox,
thread: Some(thread),
})
}
fn enqueue(
&self,
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
metadata: GuestFrameMetadata,
) -> Result<(), String> {
self.enqueue_frame(framebuffer, layout, FrameMetadata::Guest(metadata))
}
fn enqueue_raster(
&self,
pixels: &[u32],
source_size: (u32, u32),
drawable_size: (u32, u32),
) -> Result<(), String> {
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
if let Some(error) = state.error.as_ref() {
return Err(error.clone());
}
state.paused = false;
let mut staged = state.recycled_argb.pop().unwrap_or_default();
staged.clear();
staged.extend_from_slice(pixels);
let spare = replace_pending_raster_frame(
&mut state,
staged,
RasterLayout::whole(source_size),
drawable_size,
);
state.recycled_argb.push(spare);
self.mailbox.changed.notify_one();
Ok(())
}
fn enqueue_raster_owned(
&self,
pixels: Vec<u32>,
layout: RasterLayout,
drawable_size: (u32, u32),
) -> Result<Vec<u32>, String> {
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
if let Some(error) = state.error.as_ref() {
return Err(error.clone());
}
state.paused = false;
let spare = replace_pending_raster_frame(&mut state, pixels, layout, drawable_size);
self.mailbox.changed.notify_one();
Ok(spare)
}
fn enqueue_compact(
&self,
frame: Arc<CompactPresentation>,
uniforms: CompactFrameUniforms,
) -> Result<(), String> {
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
if let Some(error) = state.error.as_ref() {
return Err(error.clone());
}
state.paused = false;
if let Some(superseded) = take_superseded_pending(&mut state) {
state.recycle(superseded);
}
state.pending = Some(GuestFrameSubmission {
pixels: FramePixels::Compact(frame),
metadata: FrameMetadata::Compact(uniforms),
});
self.mailbox.changed.notify_one();
Ok(())
}
fn enqueue_frame(
&self,
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
metadata: FrameMetadata,
) -> Result<(), String> {
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
if let Some(error) = state.error.as_ref() {
return Err(error.clone());
}
state.paused = false;
replace_pending_guest_frame(&mut state, framebuffer, layout, metadata);
self.mailbox.changed.notify_one();
Ok(())
}
fn pause_and_wait(&self) {
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
state.paused = true;
if let Some(pending) = state.pending.take() {
state.recycle(pending.pixels);
}
self.mailbox.changed.notify_all();
while state.active || state.drawable_in_use {
state = self
.mailbox
.changed
.wait(state)
.unwrap_or_else(|error| error.into_inner());
}
}
fn snapshot(&self) -> (u64, u64, Duration, Duration) {
let state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
(
state.submitted,
state.coalesced,
state.drawable_wait_time,
state.render_time,
)
}
}
impl Drop for AsyncGuestPresenter {
fn drop(&mut self) {
{
let mut state = self
.mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
state.shutdown = true;
state.pending = None;
self.mailbox.changed.notify_all();
}
if let Some(thread) = self.thread.take() {
let _ = thread.join();
}
}
}
impl GuestRenderWorker {
fn run(mut self, mailbox: Arc<GuestFrameMailbox>) {
loop {
let mut state = mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
while !state.shutdown && (state.paused || state.pending.is_none()) {
state = mailbox
.changed
.wait(state)
.unwrap_or_else(|error| error.into_inner());
}
if state.shutdown {
break;
}
state.drawable_in_use = true;
drop(state);
let wait_start = Instant::now();
let drawable = {
let _timing = crate::FramePhaseTimer::new("Metal drawable wait (worker)");
autoreleasepool(|_| unsafe { self.layer.nextDrawable() })
};
let drawable_wait = wait_start.elapsed();
let mut state = mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
state.drawable_wait_time += drawable_wait;
if state.shutdown {
state.drawable_in_use = false;
mailbox.changed.notify_all();
break;
}
if state.paused {
state.drawable_in_use = false;
mailbox.changed.notify_all();
drop(state);
drop(drawable);
continue;
}
let Some(submission) = state.pending.take() else {
state.drawable_in_use = false;
mailbox.changed.notify_all();
drop(state);
drop(drawable);
continue;
};
state.active = true;
drop(state);
let render_start = Instant::now();
let result = autoreleasepool(|_| match drawable {
Some(drawable) => self.submit(&submission, &drawable),
None => Ok(()),
});
let render_time = render_start.elapsed();
let mut state = mailbox
.state
.lock()
.unwrap_or_else(|error| error.into_inner());
state.active = false;
state.drawable_in_use = false;
state.render_time += render_time;
if result.is_ok() {
state.submitted = state.submitted.saturating_add(1);
} else if state.error.is_none() {
state.error = result.err();
}
state.recycle(submission.pixels);
mailbox.changed.notify_all();
}
}
fn submit(
&mut self,
submission: &GuestFrameSubmission,
drawable: &ProtocolObject<dyn CAMetalDrawable>,
) -> Result<(), String> {
let framebuffer = submission.pixels.as_bytes();
let metadata = match &submission.metadata {
FrameMetadata::Guest(metadata) => metadata,
FrameMetadata::Raster {
layout,
drawable_size,
} => {
let source_size = (layout.width, layout.height);
if self.upload_size != source_size {
self.upload_textures =
upload_textures(&self.device, source_size.0, source_size.1)?;
self.upload_size = source_size;
self.next_upload_texture = 0;
}
let index = self.next_upload_texture;
self.next_upload_texture = (index + 1) % self.upload_textures.len();
return encode_raster_frame(
&self.command_queue,
&self.raster_pipeline,
&self.upload_textures[index],
drawable,
framebuffer,
*layout,
*drawable_size,
false,
);
}
FrameMetadata::Compact(uniforms) => {
let FramePixels::Compact(frame) = &submission.pixels else {
return Err("compact metadata without a compact frame".to_string());
};
let buffers = self.compact_buffers.upload(&self.device, frame)?;
return encode_compact_frame(
&self.command_queue,
&self.compact_pipeline,
buffers,
drawable,
uniforms,
false,
);
}
};
self.ensure_guest_buffers(framebuffer.len())?;
let buffer_index = self.next_guest_buffer;
self.next_guest_buffer = (buffer_index + 1) % self.guest_buffers.len();
let guest_buffer = &self.guest_buffers[buffer_index];
unsafe {
std::ptr::copy_nonoverlapping(
framebuffer.as_ptr(),
guest_buffer.contents().as_ptr().cast::<u8>(),
framebuffer.len(),
);
}
encode_guest_frame(
&self.command_queue,
&self.pipeline,
guest_buffer,
drawable,
metadata,
false,
)
}
fn ensure_guest_buffers(&mut self, frame_bytes: usize) -> Result<(), String> {
if self.guest_buffer_size == frame_bytes {
return Ok(());
}
let mut buffers = Vec::with_capacity(FRAME_RESOURCE_COUNT);
for _ in 0..FRAME_RESOURCE_COUNT {
buffers.push(
self.device
.newBufferWithLength_options(
frame_bytes,
MTLResourceOptions::MTLResourceStorageModeShared,
)
.ok_or_else(|| "Metal failed to allocate a guest framebuffer".to_string())?,
);
}
self.guest_buffers = buffers;
self.guest_buffer_size = frame_bytes;
self.next_guest_buffer = 0;
Ok(())
}
}
pub struct MetalPresenter {
_window: Rc<Window>,
root_layer: Retained<CALayer>,
layer: Retained<CAMetalLayer>,
device: Retained<ProtocolObject<dyn MTLDevice>>,
command_queue: Retained<ProtocolObject<dyn MTLCommandQueue>>,
pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
guest_pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
guest_buffers: Vec<Retained<ProtocolObject<dyn MTLBuffer>>>,
guest_buffer_size: usize,
next_guest_buffer: usize,
upload_textures: Vec<Retained<ProtocolObject<dyn MTLTexture>>>,
upload_size: (u32, u32),
drawable_size: (u32, u32),
next_upload_texture: usize,
last_guest_metadata: Option<GuestFrameMetadata>,
last_guest_visible_pixels: Vec<u8>,
skip_unchanged_guest_frames: bool,
profile_guest_frames: bool,
guest_frame_profile: GuestFrameProfile,
compact_pipeline: Retained<ProtocolObject<dyn MTLRenderPipelineState>>,
compact_buffers: CompactBuffers,
compact_enabled: bool,
last_compact: Option<(Arc<CompactPresentation>, CompactFrameUniforms)>,
async_guest_presenter: AsyncGuestPresenter,
}
fn display_metal_device() -> Option<Retained<ProtocolObject<dyn MTLDevice>>> {
#[link(name = "CoreGraphics", kind = "framework")]
extern "C" {
fn CGMainDisplayID() -> u32;
fn CGDirectDisplayCopyCurrentMetalDevice(
display: u32,
) -> *mut ProtocolObject<dyn MTLDevice>;
}
if std::env::var("SYSTEMLESS_METAL_DEVICE")
.map(|v| v == "default")
.unwrap_or(false)
{
return None;
}
unsafe { Retained::from_raw(CGDirectDisplayCopyCurrentMetalDevice(CGMainDisplayID())) }
}
impl MetalPresenter {
pub fn new(window: Rc<Window>) -> Result<Self, String> {
MainThreadMarker::new()
.ok_or_else(|| "Metal presenter must be created on the main thread".to_string())?;
let handle = window
.window_handle()
.map_err(|error| format!("failed to get AppKit window handle: {error}"))?;
let RawWindowHandle::AppKit(handle) = handle.as_raw() else {
return Err("Metal presenter requires an AppKit window".to_string());
};
let view: &NSObject = unsafe { handle.ns_view.cast().as_ref() };
let _: () = unsafe { msg_send![view, setWantsLayer: true] };
let root_layer: Option<Retained<CALayer>> = unsafe { msg_send_id![view, layer] };
let root_layer =
root_layer.ok_or_else(|| "AppKit did not create a root layer".to_string())?;
let device = display_metal_device()
.or_else(|| unsafe { Retained::retain(MTLCreateSystemDefaultDevice()) })
.ok_or_else(|| "this Mac has no Metal device".to_string())?;
let command_queue = device
.newCommandQueue()
.ok_or_else(|| "Metal failed to create a command queue".to_string())?;
let layer = unsafe { CAMetalLayer::new() };
unsafe {
layer.setDevice(Some(&device));
layer.setPixelFormat(MTLPixelFormat::BGRA8Unorm);
layer.setFramebufferOnly(true);
layer.setMaximumDrawableCount(FRAME_RESOURCE_COUNT);
layer.setPresentsWithTransaction(false);
layer.setDisplaySyncEnabled(true);
}
layer.setOpaque(true);
layer.setContentsGravity(unsafe { kCAGravityBottom });
layer.setFrame(root_layer.bounds());
layer.setAutoresizingMask(
CAAutoresizingMask::kCALayerWidthSizable | CAAutoresizingMask::kCALayerHeightSizable,
);
layer.setContentsScale(root_layer.contentsScale());
root_layer.addSublayer(&layer);
#[cfg(feature = "test-support")]
if std::env::var_os("SYSTEMLESS_NATIVE_WINDOW_PROBE").is_some()
&& matches!(
std::env::var("SYSTEMLESS_GPU_FAULT")
.unwrap_or_default()
.as_str(),
"platform-startup" | "platform-fatal"
)
{
return Err(
"qualification: injected platform creation failure after layer attachment".into(),
);
}
let library = device
.newLibraryWithSource_options_error(
ns_string!(include_str!("metal_present.metal")),
None,
)
.map_err(|error| format!("Metal shader compilation failed: {error}"))?;
let vertex = library
.newFunctionWithName(ns_string!("raster_vertex"))
.ok_or_else(|| "Metal vertex function was not found".to_string())?;
let fragment = library
.newFunctionWithName(ns_string!("raster_fragment"))
.ok_or_else(|| "Metal fragment function was not found".to_string())?;
let guest_fragment = library
.newFunctionWithName(ns_string!("guest_raster_fragment"))
.ok_or_else(|| "Metal guest framebuffer function was not found".to_string())?;
let compact_fragment = library
.newFunctionWithName(ns_string!("compact_fragment"))
.ok_or_else(|| "Metal compact coverage function was not found".to_string())?;
let descriptor = MTLRenderPipelineDescriptor::new();
descriptor.setVertexFunction(Some(&vertex));
descriptor.setFragmentFunction(Some(&fragment));
unsafe {
descriptor
.colorAttachments()
.objectAtIndexedSubscript(0)
.setPixelFormat(MTLPixelFormat::BGRA8Unorm);
}
let pipeline = device
.newRenderPipelineStateWithDescriptor_error(&descriptor)
.map_err(|error| format!("Metal pipeline creation failed: {error}"))?;
descriptor.setFragmentFunction(Some(&guest_fragment));
let guest_pipeline = device
.newRenderPipelineStateWithDescriptor_error(&descriptor)
.map_err(|error| format!("Metal guest pipeline creation failed: {error}"))?;
descriptor.setFragmentFunction(Some(&compact_fragment));
let compact_pipeline = device
.newRenderPipelineStateWithDescriptor_error(&descriptor)
.map_err(|error| format!("Metal compact pipeline creation failed: {error}"))?;
let async_command_queue = device
.newCommandQueue()
.ok_or_else(|| "Metal failed to create the presenter command queue".to_string())?;
let async_guest_presenter = AsyncGuestPresenter::new(GuestRenderWorker {
layer: layer.clone(),
device: device.clone(),
command_queue: async_command_queue,
pipeline: guest_pipeline.clone(),
guest_buffers: Vec::new(),
guest_buffer_size: 0,
next_guest_buffer: 0,
raster_pipeline: pipeline.clone(),
upload_textures: Vec::new(),
upload_size: (0, 0),
next_upload_texture: 0,
compact_pipeline: compact_pipeline.clone(),
compact_buffers: CompactBuffers::default(),
})?;
Ok(Self {
_window: window,
root_layer,
layer,
device,
command_queue,
pipeline,
guest_pipeline,
guest_buffers: Vec::new(),
guest_buffer_size: 0,
next_guest_buffer: 0,
upload_textures: Vec::new(),
upload_size: (0, 0),
drawable_size: (0, 0),
next_upload_texture: 0,
last_guest_metadata: None,
last_guest_visible_pixels: Vec::new(),
skip_unchanged_guest_frames: std::env::var_os(
"SYSTEMLESS_DISABLE_UNCHANGED_FRAME_SKIP",
)
.is_none(),
profile_guest_frames: std::env::var_os("SYSTEMLESS_PROFILE_METAL_FRAMES").is_some(),
guest_frame_profile: GuestFrameProfile::default(),
compact_pipeline,
compact_buffers: CompactBuffers::default(),
compact_enabled: std::env::var_os("SYSTEMLESS_METAL_COMPACT")
.is_none_or(|value| value != "0"),
last_compact: None,
async_guest_presenter,
})
}
pub fn set_transactional_presentation(&self, enabled: bool) {
if enabled {
self.async_guest_presenter.pause_and_wait();
}
unsafe { self.layer.setPresentsWithTransaction(enabled) };
}
pub fn present(
&mut self,
pixels: &[u32],
source_width: u32,
source_height: u32,
drawable_width: u32,
drawable_height: u32,
) -> Result<(), String> {
let expected_pixels = source_width as usize * source_height as usize;
if pixels.len() < expected_pixels || expected_pixels == 0 {
return Err("framebuffer dimensions do not match its pixel data".to_string());
}
if drawable_width == 0 || drawable_height == 0 {
return Ok(());
}
self.resize_drawable(drawable_width, drawable_height);
self.last_guest_metadata = None;
self.last_compact = None;
if !unsafe { self.layer.presentsWithTransaction() } {
return self.async_guest_presenter.enqueue_raster(
&pixels[..expected_pixels],
(source_width, source_height),
(drawable_width, drawable_height),
);
}
self.async_guest_presenter.pause_and_wait();
self.ensure_upload_textures(source_width, source_height)?;
let Some(drawable) = (unsafe { self.layer.nextDrawable() }) else {
return Ok(());
};
let upload_index = self.next_upload_texture;
self.next_upload_texture = (upload_index + 1) % self.upload_textures.len();
let upload = &self.upload_textures[upload_index];
encode_raster_frame(
&self.command_queue,
&self.pipeline,
upload,
&drawable,
argb_bytes(pixels),
RasterLayout::whole((source_width, source_height)),
(drawable_width, drawable_height),
true,
)?;
Ok(())
}
pub fn present_owned(
&mut self,
frame: Vec<u32>,
layout: RasterLayout,
drawable_width: u32,
drawable_height: u32,
) -> Result<Vec<u32>, String> {
let byte_len = frame.len().saturating_mul(size_of::<u32>());
if layout.texel_byte_offset(byte_len).is_none() {
return Err("framebuffer dimensions do not match its pixel data".to_string());
}
if drawable_width == 0 || drawable_height == 0 {
return Ok(frame);
}
self.resize_drawable(drawable_width, drawable_height);
self.last_guest_metadata = None;
self.last_compact = None;
if !unsafe { self.layer.presentsWithTransaction() } {
return self.async_guest_presenter.enqueue_raster_owned(
frame,
layout,
(drawable_width, drawable_height),
);
}
self.async_guest_presenter.pause_and_wait();
self.ensure_upload_textures(layout.width, layout.height)?;
let Some(drawable) = (unsafe { self.layer.nextDrawable() }) else {
return Ok(frame);
};
let upload_index = self.next_upload_texture;
self.next_upload_texture = (upload_index + 1) % self.upload_textures.len();
let upload = &self.upload_textures[upload_index];
encode_raster_frame(
&self.command_queue,
&self.pipeline,
upload,
&drawable,
argb_bytes(&frame),
layout,
(drawable_width, drawable_height),
true,
)?;
Ok(frame)
}
pub fn present_guest_frame(
&mut self,
framebuffer: &[u8],
screen_mode: (u32, u32, u16, u16, u16),
content_rect: (u32, u32, u32, u32),
palette: &[u32; 256],
cursor: Option<(&CursorImage, (i16, i16))>,
drawable_size: (u32, u32),
force_present: bool,
) -> Result<bool, String> {
let (_, row_bytes, width, height, pixel_size) = screen_mode;
let screen_width = u32::from(width);
let screen_height = u32::from(height);
let (content_left, content_top, width, height) = content_rect;
let (drawable_width, drawable_height) = drawable_size;
let Some(packed_content_left) = guest_packed_content_left(pixel_size, content_left) else {
return Ok(false);
};
if content_left.saturating_add(width) > screen_width
|| content_top.saturating_add(height) > screen_height
{
return Err("detected content rectangle lies outside the guest screen".to_string());
}
if width == 0 || height == 0 || drawable_width == 0 || drawable_height == 0 {
return Ok(true);
}
let frame_bytes = guest_frame_byte_len(row_bytes, screen_height)
.ok_or_else(|| "guest framebuffer dimensions overflow host size".to_string())?;
if framebuffer.len() < frame_bytes {
return Err("guest framebuffer dimensions do not match its pixel data".to_string());
}
let visible_layout = guest_visible_byte_layout(
row_bytes,
pixel_size,
content_left,
content_top,
width,
height,
)
.ok_or_else(|| "visible guest framebuffer rows are invalid".to_string())?;
let (mut uniforms, cursor_data) = cursor
.map(|(image, position)| guest_cursor_data(Some(image), position))
.unwrap_or_else(|| guest_cursor_data(None, (0, 0)));
let packed_origin_left = content_left - packed_content_left;
uniforms.row_bytes = u32::try_from(visible_layout.visible_row_bytes)
.map_err(|_| "visible guest row stride exceeds Metal's limit".to_string())?;
uniforms.width = width;
uniforms.height = height;
uniforms.pixel_size = u32::from(pixel_size);
uniforms.content_left = packed_content_left;
uniforms.content_top = 0;
uniforms.cursor_left -= i32::try_from(packed_origin_left)
.map_err(|_| "guest crop origin exceeds Metal's limit".to_string())?;
uniforms.cursor_top -= i32::try_from(content_top)
.map_err(|_| "guest crop origin exceeds Metal's limit".to_string())?;
let metadata = GuestFrameMetadata {
screen_layout: (row_bytes, screen_mode.2, screen_mode.3, pixel_size),
content_rect,
palette: *palette,
uniforms,
cursor: cursor_data,
drawable_size,
};
let presentation_start = Instant::now();
self.guest_frame_profile.attempts += 1;
if force_present {
self.guest_frame_profile.forced += 1;
}
let compare_start = Instant::now();
let unchanged = self.skip_unchanged_guest_frames
&& self.last_guest_metadata.as_ref() == Some(&metadata)
&& guest_visible_pixels_equal(
&self.last_guest_visible_pixels,
framebuffer,
visible_layout,
);
if self.skip_unchanged_guest_frames {
self.guest_frame_profile.comparison_time += compare_start.elapsed();
}
if unchanged && !force_present {
self.guest_frame_profile.unchanged += 1;
self.guest_frame_profile.presentation_time += presentation_start.elapsed();
self.maybe_log_guest_frame_profile();
return Ok(true);
}
self.resize_drawable(drawable_width, drawable_height);
self.last_compact = None;
if unsafe { self.layer.presentsWithTransaction() } {
let visible_bytes = visible_layout
.visible_row_bytes
.checked_mul(visible_layout.row_count)
.ok_or_else(|| {
"visible guest framebuffer dimensions overflow host size".to_string()
})?;
self.ensure_guest_buffers(visible_bytes)?;
let Some(drawable) = (unsafe { self.layer.nextDrawable() }) else {
return Ok(true);
};
let buffer_index = self.next_guest_buffer;
self.next_guest_buffer = (buffer_index + 1) % self.guest_buffers.len();
let guest_buffer = &self.guest_buffers[buffer_index];
copy_guest_visible_pixels_to_ptr(
guest_buffer.contents().as_ptr().cast::<u8>(),
framebuffer,
visible_layout,
);
encode_guest_frame(
&self.command_queue,
&self.guest_pipeline,
guest_buffer,
&drawable,
&metadata,
true,
)?;
} else {
self.async_guest_presenter
.enqueue(framebuffer, visible_layout, metadata.clone())?;
}
if self.skip_unchanged_guest_frames {
copy_guest_visible_pixels(
&mut self.last_guest_visible_pixels,
framebuffer,
visible_layout,
);
self.last_guest_metadata = Some(metadata);
}
self.guest_frame_profile.presentation_time += presentation_start.elapsed();
self.maybe_log_guest_frame_profile();
Ok(true)
}
pub fn supports_compact(&self) -> bool {
self.compact_enabled
}
pub fn present_compact(
&mut self,
frame: &Arc<CompactPresentation>,
crop: (u32, u32, u32, u32),
drawable_size: (u32, u32),
force_present: bool,
) -> Result<bool, String> {
let Some(uniforms) = compact_frame_uniforms(frame, crop, drawable_size) else {
return Ok(false);
};
let unchanged = self
.last_compact
.as_ref()
.is_some_and(|(last, last_uniforms)| {
Arc::ptr_eq(last, frame) && *last_uniforms == uniforms
});
if unchanged && !force_present && self.drawable_size == drawable_size {
return Ok(true);
}
self.resize_drawable(drawable_size.0, drawable_size.1);
self.last_guest_metadata = None;
if unsafe { self.layer.presentsWithTransaction() } {
self.async_guest_presenter.pause_and_wait();
let Some(drawable) = (unsafe { self.layer.nextDrawable() }) else {
return Ok(true);
};
let buffers = self.compact_buffers.upload(&self.device, frame)?;
encode_compact_frame(
&self.command_queue,
&self.compact_pipeline,
buffers,
&drawable,
&uniforms,
true,
)?;
} else {
self.async_guest_presenter
.enqueue_compact(frame.clone(), uniforms)?;
}
self.last_compact = Some((frame.clone(), uniforms));
Ok(true)
}
fn maybe_log_guest_frame_profile(&self) {
let profile = &self.guest_frame_profile;
if !self.profile_guest_frames
|| profile.attempts == 0
|| !profile.attempts.is_multiple_of(600)
{
return;
}
let skipped_percent = profile.unchanged as f64 * 100.0 / profile.attempts as f64;
let compare_us =
profile.comparison_time.as_secs_f64() * 1_000_000.0 / profile.attempts as f64;
let presentation_us =
profile.presentation_time.as_secs_f64() * 1_000_000.0 / profile.attempts as f64;
let (async_submitted, coalesced, drawable_wait, render_time) =
self.async_guest_presenter.snapshot();
let submitted = async_submitted;
let drawable_wait_us = if async_submitted == 0 {
0.0
} else {
drawable_wait.as_secs_f64() * 1_000_000.0 / async_submitted as f64
};
let render_us = if async_submitted == 0 {
0.0
} else {
render_time.as_secs_f64() * 1_000_000.0 / async_submitted as f64
};
eprintln!(
"[METAL-PROFILE] attempts={} submitted={} coalesced={} unchanged_skipped={} forced={} skipped={:.1}% compare={:.1}us/frame enqueue={:.1}us/frame drawable_wait={:.1}us/submission render={:.1}us/submission",
profile.attempts,
submitted,
coalesced,
profile.unchanged,
profile.forced,
skipped_percent,
compare_us,
presentation_us,
drawable_wait_us,
render_us,
);
}
fn ensure_upload_textures(&mut self, width: u32, height: u32) -> Result<(), String> {
if self.upload_size == (width, height) {
return Ok(());
}
let textures = upload_textures(&self.device, width, height)?;
self.upload_textures = textures;
self.upload_size = (width, height);
self.next_upload_texture = 0;
Ok(())
}
fn ensure_guest_buffers(&mut self, frame_bytes: usize) -> Result<(), String> {
if self.guest_buffer_size == frame_bytes {
return Ok(());
}
let mut buffers = Vec::with_capacity(FRAME_RESOURCE_COUNT);
for _ in 0..FRAME_RESOURCE_COUNT {
buffers.push(
self.device
.newBufferWithLength_options(
frame_bytes,
MTLResourceOptions::MTLResourceStorageModeShared,
)
.ok_or_else(|| "Metal failed to allocate a guest framebuffer".to_string())?,
);
}
self.guest_buffers = buffers;
self.guest_buffer_size = frame_bytes;
self.next_guest_buffer = 0;
Ok(())
}
fn resize_drawable(&mut self, width: u32, height: u32) {
if self.drawable_size != (width, height) {
self.layer.setFrame(self.root_layer.bounds());
self.layer.setContentsScale(self.root_layer.contentsScale());
unsafe {
self.layer.setDrawableSize(
CGRect::new(
objc2_foundation::CGPoint::new(0.0, 0.0),
objc2_foundation::CGSize::new(width as f64, height as f64),
)
.size,
);
}
self.drawable_size = (width, height);
}
}
}
fn argb_bytes(pixels: &[u32]) -> &[u8] {
unsafe { std::slice::from_raw_parts(pixels.as_ptr().cast(), std::mem::size_of_val(pixels)) }
}
fn upload_textures(
device: &ProtocolObject<dyn MTLDevice>,
width: u32,
height: u32,
) -> Result<Vec<Retained<ProtocolObject<dyn MTLTexture>>>, String> {
let descriptor = unsafe {
MTLTextureDescriptor::texture2DDescriptorWithPixelFormat_width_height_mipmapped(
MTLPixelFormat::BGRA8Unorm,
width as usize,
height as usize,
false,
)
};
descriptor.setStorageMode(MTLStorageMode::Shared);
descriptor.setUsage(MTLTextureUsage::ShaderRead);
let mut textures = Vec::with_capacity(FRAME_RESOURCE_COUNT);
for _ in 0..FRAME_RESOURCE_COUNT {
textures.push(
device
.newTextureWithDescriptor(&descriptor)
.ok_or_else(|| "Metal failed to allocate an upload texture".to_string())?,
);
}
Ok(textures)
}
fn finish_presentation(
command_buffer: &ProtocolObject<dyn MTLCommandBuffer>,
drawable: &ProtocolObject<dyn CAMetalDrawable>,
transactional: bool,
) {
if transactional {
command_buffer.commit();
command_buffer.waitUntilScheduled();
let drawable: &ProtocolObject<dyn objc2_metal::MTLDrawable> =
ProtocolObject::from_ref(drawable);
drawable.present();
} else {
command_buffer.presentDrawable(ProtocolObject::from_ref(drawable));
command_buffer.commit();
}
}
fn upload_raster_region(
upload: &ProtocolObject<dyn MTLTexture>,
pixels: &[u8],
layout: RasterLayout,
) -> Result<(), String> {
let offset = layout
.texel_byte_offset(pixels.len())
.ok_or_else(|| "presented rectangle does not fit its framebuffer".to_string())?;
let region = MTLRegion {
origin: objc2_metal::MTLOrigin { x: 0, y: 0, z: 0 },
size: objc2_metal::MTLSize {
width: layout.width as usize,
height: layout.height as usize,
depth: 1,
},
};
let first_texel = pixels
.get(offset..)
.ok_or_else(|| "presented rectangle starts past its framebuffer".to_string())?;
let source = NonNull::new(first_texel.as_ptr().cast_mut().cast::<c_void>())
.ok_or_else(|| "a non-empty framebuffer has a non-null pointer".to_string())?;
unsafe {
upload.replaceRegion_mipmapLevel_withBytes_bytesPerRow(
region,
0,
source,
layout.buffer_width as usize * size_of::<u32>(),
);
}
Ok(())
}
fn encode_raster_frame(
command_queue: &ProtocolObject<dyn MTLCommandQueue>,
pipeline: &ProtocolObject<dyn MTLRenderPipelineState>,
upload: &ProtocolObject<dyn MTLTexture>,
drawable: &ProtocolObject<dyn CAMetalDrawable>,
pixels: &[u8],
layout: RasterLayout,
drawable_size: (u32, u32),
transactional: bool,
) -> Result<(), String> {
let (source_width, source_height) = (layout.width, layout.height);
let (drawable_width, drawable_height) = drawable_size;
upload_raster_region(upload, pixels, layout)?;
let drawable_texture = unsafe { drawable.texture() };
let pass = unsafe { MTLRenderPassDescriptor::new() };
let color = unsafe { pass.colorAttachments().objectAtIndexedSubscript(0) };
color.setTexture(Some(&drawable_texture));
color.setLoadAction(MTLLoadAction::Clear);
color.setStoreAction(MTLStoreAction::Store);
color.setClearColor(objc2_metal::MTLClearColor {
red: 0.0,
green: 0.0,
blue: 0.0,
alpha: 1.0,
});
let command_buffer = command_queue
.commandBuffer()
.ok_or_else(|| "Metal failed to create a command buffer".to_string())?;
let encoder = command_buffer
.renderCommandEncoderWithDescriptor(&pass)
.ok_or_else(|| "Metal failed to create a render encoder".to_string())?;
encoder.setRenderPipelineState(pipeline);
unsafe { encoder.setFragmentTexture_atIndex(Some(upload), 0) };
let viewport =
aspect_fit_viewport(source_width, source_height, drawable_width, drawable_height);
encoder.setViewport(MTLViewport {
originX: viewport.0,
originY: viewport.1,
width: viewport.2,
height: viewport.3,
znear: 0.0,
zfar: 1.0,
});
unsafe {
encoder.drawPrimitives_vertexStart_vertexCount(MTLPrimitiveType::TriangleStrip, 0, 4)
};
encoder.endEncoding();
finish_presentation(&command_buffer, drawable, transactional);
Ok(())
}
fn encode_compact_frame(
command_queue: &ProtocolObject<dyn MTLCommandQueue>,
pipeline: &ProtocolObject<dyn MTLRenderPipelineState>,
(cells, detail): (&ProtocolObject<dyn MTLBuffer>, &ProtocolObject<dyn MTLBuffer>),
drawable: &ProtocolObject<dyn CAMetalDrawable>,
uniforms: &CompactFrameUniforms,
transactional: bool,
) -> Result<(), String> {
let texture = unsafe { drawable.texture() };
let pass = unsafe { MTLRenderPassDescriptor::new() };
let color = unsafe { pass.colorAttachments().objectAtIndexedSubscript(0) };
color.setTexture(Some(&texture));
color.setLoadAction(MTLLoadAction::Clear);
color.setStoreAction(MTLStoreAction::Store);
color.setClearColor(objc2_metal::MTLClearColor {
red: 0.0,
green: 0.0,
blue: 0.0,
alpha: 1.0,
});
let command_buffer = command_queue
.commandBuffer()
.ok_or_else(|| "Metal failed to create a command buffer".to_string())?;
let encoder = command_buffer
.renderCommandEncoderWithDescriptor(&pass)
.ok_or_else(|| "Metal failed to create a render encoder".to_string())?;
encoder.setRenderPipelineState(pipeline);
unsafe {
encoder.setFragmentBuffer_offset_atIndex(Some(cells), 0, 0);
encoder.setFragmentBuffer_offset_atIndex(Some(detail), 0, 1);
encoder.setFragmentBytes_length_atIndex(
non_null_bytes(uniforms),
size_of::<CompactFrameUniforms>(),
2,
);
}
encoder.setViewport(MTLViewport {
originX: uniforms.ox.into(),
originY: uniforms.oy.into(),
width: uniforms.dw.into(),
height: uniforms.dh.into(),
znear: 0.0,
zfar: 1.0,
});
unsafe {
encoder.drawPrimitives_vertexStart_vertexCount(MTLPrimitiveType::TriangleStrip, 0, 4)
};
encoder.endEncoding();
finish_presentation(&command_buffer, drawable, transactional);
Ok(())
}
fn integer_aspect_fit(source: (u32, u32), drawable: (u32, u32)) -> (u32, u32, u32, u32) {
let (sw, sh) = (u64::from(source.0), u64::from(source.1));
let (dw, dh) = (u64::from(drawable.0), u64::from(drawable.1));
let (width, height) = if dw * sh <= dh * sw {
(dw, dw * sh / sw)
} else {
(dh * sw / sh, dh)
};
(
((dw - width) / 2) as u32,
((dh - height) / 2) as u32,
width as u32,
height as u32,
)
}
fn compact_frame_uniforms(
frame: &CompactPresentation,
crop: (u32, u32, u32, u32),
drawable_size: (u32, u32),
) -> Option<CompactFrameUniforms> {
let (crop_left, crop_top, crop_width, crop_height) = crop;
if !(1..=4).contains(&frame.scale)
|| frame.cells.len() != (frame.width as usize).checked_mul(frame.height as usize)?
|| crop_width == 0
|| crop_height == 0
|| crop_left.checked_add(crop_width)? > frame.width
|| crop_top.checked_add(crop_height)? > frame.height
|| drawable_size.0 == 0
|| drawable_size.1 == 0
{
return None;
}
let (ox, oy, dw, dh) = integer_aspect_fit((crop_width, crop_height), drawable_size);
let sw = u64::from(crop_width) * u64::from(frame.scale);
let sh = u64::from(crop_height) * u64::from(frame.scale);
let total =
(if sw > u64::from(dw) { sw } else { 1 }) * (if sh > u64::from(dh) { sh } else { 1 });
if [sw, sh, u64::from(dw), u64::from(dh)]
.iter()
.any(|&n| n == 0 || n > 16384)
|| total * 255 + total / 2 > u64::from(u32::MAX)
{
return None;
}
debug_assert!(frame.cells.iter().all(|&cell| {
cell >> 31 == 0
|| (cell & 0x7fffffff) as usize + (frame.scale * frame.scale) as usize
<= frame.detail.len()
}));
Some(CompactFrameUniforms {
width: frame.width,
height: frame.height,
scale: frame.scale,
crop_left,
crop_top,
crop_width,
crop_height,
dw,
dh,
ox,
oy,
})
}
fn encode_guest_frame(
command_queue: &ProtocolObject<dyn MTLCommandQueue>,
pipeline: &ProtocolObject<dyn MTLRenderPipelineState>,
guest_buffer: &ProtocolObject<dyn MTLBuffer>,
drawable: &ProtocolObject<dyn CAMetalDrawable>,
metadata: &GuestFrameMetadata,
transactional: bool,
) -> Result<(), String> {
let drawable_texture = unsafe { drawable.texture() };
let pass = unsafe { MTLRenderPassDescriptor::new() };
let color = unsafe { pass.colorAttachments().objectAtIndexedSubscript(0) };
color.setTexture(Some(&drawable_texture));
color.setLoadAction(MTLLoadAction::Clear);
color.setStoreAction(MTLStoreAction::Store);
color.setClearColor(objc2_metal::MTLClearColor {
red: 0.0,
green: 0.0,
blue: 0.0,
alpha: 1.0,
});
let command_buffer = command_queue
.commandBuffer()
.ok_or_else(|| "Metal failed to create a command buffer".to_string())?;
let encoder = command_buffer
.renderCommandEncoderWithDescriptor(&pass)
.ok_or_else(|| "Metal failed to create a render encoder".to_string())?;
encoder.setRenderPipelineState(pipeline);
unsafe {
encoder.setFragmentBuffer_offset_atIndex(Some(guest_buffer), 0, 0);
encoder.setFragmentBytes_length_atIndex(
non_null_bytes(&metadata.palette),
size_of::<[u32; 256]>(),
1,
);
encoder.setFragmentBytes_length_atIndex(
non_null_bytes(&metadata.uniforms),
size_of::<GuestFrameUniforms>(),
2,
);
encoder.setFragmentBytes_length_atIndex(
non_null_bytes(&metadata.cursor),
size_of::<GuestCursorData>(),
3,
);
}
let (_, _, width, height) = metadata.content_rect;
let (drawable_width, drawable_height) = metadata.drawable_size;
let viewport = aspect_fit_viewport(width, height, drawable_width, drawable_height);
encoder.setViewport(MTLViewport {
originX: viewport.0,
originY: viewport.1,
width: viewport.2,
height: viewport.3,
znear: 0.0,
zfar: 1.0,
});
unsafe {
encoder.drawPrimitives_vertexStart_vertexCount(MTLPrimitiveType::TriangleStrip, 0, 4)
};
encoder.endEncoding();
if transactional {
command_buffer.commit();
command_buffer.waitUntilScheduled();
let drawable: &ProtocolObject<dyn objc2_metal::MTLDrawable> =
ProtocolObject::from_ref(drawable);
drawable.present();
} else {
command_buffer.presentDrawable(ProtocolObject::from_ref(drawable));
command_buffer.commit();
}
Ok(())
}
fn non_null_bytes<T>(value: &T) -> NonNull<c_void> {
NonNull::from(value).cast::<c_void>()
}
fn guest_cursor_data(
cursor: Option<&CursorImage>,
mouse_pos: (i16, i16),
) -> (GuestFrameUniforms, GuestCursorData) {
let mut uniforms = GuestFrameUniforms::default();
let mut gpu = GuestCursorData::default();
let Some(cursor) = cursor else {
return (uniforms, gpu);
};
let (mouse_v, mouse_h) = mouse_pos;
match cursor {
CursorImage::Mono {
data,
mask,
hot_v,
hot_h,
} => {
uniforms.cursor_kind = 1;
uniforms.cursor_width = 16;
uniforms.cursor_height = 16;
uniforms.cursor_left = i32::from(mouse_h) - i32::from(*hot_h);
uniforms.cursor_top = i32::from(mouse_v) - i32::from(*hot_v);
for row in 0..16 {
gpu.data_rows[row] =
u32::from(u16::from_be_bytes([data[row * 2], data[row * 2 + 1]]));
gpu.mask_rows[row] =
u32::from(u16::from_be_bytes([mask[row * 2], mask[row * 2 + 1]]));
}
}
CursorImage::Color {
width,
height,
pixels_argb,
mask,
hot_v,
hot_h,
..
} => {
let source_width = *width;
let width = source_width.min(16);
let height = (*height).min(16);
uniforms.cursor_kind = 2;
uniforms.cursor_width = u32::from(width);
uniforms.cursor_height = u32::from(height);
uniforms.cursor_left = i32::from(mouse_h) - i32::from(*hot_h);
uniforms.cursor_top = i32::from(mouse_v) - i32::from(*hot_v);
for row in 0..16 {
gpu.mask_rows[row] =
u32::from(u16::from_be_bytes([mask[row * 2], mask[row * 2 + 1]]));
}
for row in 0..usize::from(height) {
let source_start = row * usize::from(source_width);
let source_end = source_start + usize::from(width);
let destination_start = row * usize::from(width);
if source_end <= pixels_argb.len() {
gpu.color_pixels[destination_start..destination_start + usize::from(width)]
.copy_from_slice(&pixels_argb[source_start..source_end]);
}
}
}
}
(uniforms, gpu)
}
fn aspect_fit_viewport(
source_width: u32,
source_height: u32,
drawable_width: u32,
drawable_height: u32,
) -> (f64, f64, f64, f64) {
let scale = (drawable_width as f64 / source_width as f64)
.min(drawable_height as f64 / source_height as f64);
let width = source_width as f64 * scale;
let height = source_height as f64 * scale;
(
(drawable_width as f64 - width) * 0.5,
(drawable_height as f64 - height) * 0.5,
width,
height,
)
}
fn guest_frame_byte_len(row_bytes: u32, screen_height: u32) -> Option<usize> {
usize::try_from(row_bytes)
.ok()?
.checked_mul(screen_height as usize)
}
fn guest_packed_content_left(pixel_size: u16, content_left: u32) -> Option<u32> {
match pixel_size {
1 => Some(content_left & 7),
2 => Some(content_left & 3),
4 => Some(content_left & 1),
8 => Some(0),
_ => None,
}
}
#[derive(Clone, Copy)]
struct GuestVisibleByteLayout {
first_row_offset: usize,
row_stride: usize,
visible_row_bytes: usize,
row_count: usize,
}
fn guest_visible_byte_layout(
row_bytes: u32,
pixel_size: u16,
left: u32,
top: u32,
width: u32,
height: u32,
) -> Option<GuestVisibleByteLayout> {
let row_stride = usize::try_from(row_bytes).ok()?;
let (first_byte, byte_end) = match pixel_size {
1 | 2 | 4 => {
let pixels_per_byte = 8 / u32::from(pixel_size);
(
usize::try_from(left / pixels_per_byte).ok()?,
usize::try_from(
left.checked_add(width)?.checked_add(pixels_per_byte - 1)? / pixels_per_byte,
)
.ok()?,
)
}
8 => (
usize::try_from(left).ok()?,
usize::try_from(left.checked_add(width)?).ok()?,
),
_ => return None,
};
if byte_end > row_stride || byte_end <= first_byte || height == 0 {
return None;
}
Some(GuestVisibleByteLayout {
first_row_offset: usize::try_from(top)
.ok()?
.checked_mul(row_stride)?
.checked_add(first_byte)?,
row_stride,
visible_row_bytes: byte_end - first_byte,
row_count: usize::try_from(height).ok()?,
})
}
fn guest_visible_pixels_equal(
snapshot: &[u8],
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
) -> bool {
let Some(snapshot_len) = layout.visible_row_bytes.checked_mul(layout.row_count) else {
return false;
};
if snapshot.len() != snapshot_len {
return false;
}
for row in 0..layout.row_count {
let Some(source_start) = row
.checked_mul(layout.row_stride)
.and_then(|offset| layout.first_row_offset.checked_add(offset))
else {
return false;
};
let Some(source_end) = source_start.checked_add(layout.visible_row_bytes) else {
return false;
};
let snapshot_start = row * layout.visible_row_bytes;
if framebuffer.get(source_start..source_end)
!= snapshot.get(snapshot_start..snapshot_start + layout.visible_row_bytes)
{
return false;
}
}
true
}
fn copy_guest_visible_pixels(
snapshot: &mut Vec<u8>,
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
) {
snapshot.clear();
let capacity = layout
.visible_row_bytes
.checked_mul(layout.row_count)
.unwrap_or(0);
snapshot.reserve(capacity);
for row in 0..layout.row_count {
let source_start = layout.first_row_offset + row * layout.row_stride;
let source_end = source_start + layout.visible_row_bytes;
snapshot.extend_from_slice(&framebuffer[source_start..source_end]);
}
}
fn copy_guest_visible_pixels_to_ptr(
destination: *mut u8,
framebuffer: &[u8],
layout: GuestVisibleByteLayout,
) {
for row in 0..layout.row_count {
let source_start = layout.first_row_offset + row * layout.row_stride;
let destination_start = row * layout.visible_row_bytes;
unsafe {
std::ptr::copy_nonoverlapping(
framebuffer.as_ptr().add(source_start),
destination.add(destination_start),
layout.visible_row_bytes,
);
}
}
}
#[cfg(test)]
pub(crate) mod tests {
use super::{
argb_bytes, aspect_fit_viewport, copy_guest_visible_pixels, guest_cursor_data,
guest_packed_content_left, guest_visible_byte_layout, guest_visible_pixels_equal,
replace_pending_guest_frame, FrameMetadata, FramePixels, GuestCursorData,
GuestFrameMailboxState, GuestFrameMetadata, GuestFrameUniforms, RasterLayout,
};
use systemless::display::CursorImage;
fn render_rgba(source: &image::RgbaImage, width: u32, height: u32) -> image::RgbaImage {
use super::*;
autoreleasepool(|_| {
let device = unsafe { Retained::retain(MTLCreateSystemDefaultDevice()) }
.expect("Metal device required");
let library = device
.newLibraryWithSource_options_error(
ns_string!(include_str!("metal_present.metal")),
None,
)
.expect("compile presentation shader");
let descriptor = MTLRenderPipelineDescriptor::new();
descriptor.setVertexFunction(
library
.newFunctionWithName(ns_string!("raster_vertex"))
.as_deref(),
);
descriptor.setFragmentFunction(
library
.newFunctionWithName(ns_string!("raster_fragment"))
.as_deref(),
);
unsafe {
descriptor
.colorAttachments()
.objectAtIndexedSubscript(0)
.setPixelFormat(MTLPixelFormat::RGBA8Unorm);
}
let pipeline = device
.newRenderPipelineStateWithDescriptor_error(&descriptor)
.unwrap();
let texture = |w, h, usage| {
let desc = unsafe {
MTLTextureDescriptor::texture2DDescriptorWithPixelFormat_width_height_mipmapped(
MTLPixelFormat::RGBA8Unorm,
w as usize,
h as usize,
false,
)
};
desc.setStorageMode(MTLStorageMode::Shared);
desc.setUsage(usage);
device.newTextureWithDescriptor(&desc).unwrap()
};
let input = texture(source.width(), source.height(), MTLTextureUsage::ShaderRead);
let output = texture(width, height, MTLTextureUsage::RenderTarget);
let region = |w, h| MTLRegion {
origin: objc2_metal::MTLOrigin { x: 0, y: 0, z: 0 },
size: objc2_metal::MTLSize {
width: w as usize,
height: h as usize,
depth: 1,
},
};
unsafe {
input.replaceRegion_mipmapLevel_withBytes_bytesPerRow(
region(source.width(), source.height()),
0,
NonNull::new(source.as_ptr().cast_mut().cast()).unwrap(),
source.width() as usize * 4,
);
}
let pass = unsafe { MTLRenderPassDescriptor::new() };
let color = unsafe { pass.colorAttachments().objectAtIndexedSubscript(0) };
color.setTexture(Some(&output));
color.setLoadAction(MTLLoadAction::Clear);
color.setStoreAction(MTLStoreAction::Store);
let queue = device.newCommandQueue().unwrap();
let command = queue.commandBuffer().unwrap();
let encoder = command.renderCommandEncoderWithDescriptor(&pass).unwrap();
encoder.setRenderPipelineState(&pipeline);
encoder.setViewport(MTLViewport {
originX: 0.0,
originY: 0.0,
width: width as f64,
height: height as f64,
znear: 0.0,
zfar: 1.0,
});
unsafe {
encoder.setFragmentTexture_atIndex(Some(&input), 0);
encoder.drawPrimitives_vertexStart_vertexCount(
MTLPrimitiveType::TriangleStrip,
0,
4,
);
}
encoder.endEncoding();
command.commit();
unsafe {
command.waitUntilCompleted();
}
let mut result = image::RgbaImage::new(width, height);
unsafe {
output.getBytes_bytesPerRow_fromRegion_mipmapLevel(
NonNull::new(result.as_mut_ptr().cast()).unwrap(),
width as usize * 4,
region(width, height),
0,
);
}
result
})
}
fn render_compact(
frame: &systemless::memory::CompactPresentation,
crop: (u32, u32, u32, u32),
drawable: (u32, u32),
measure: Option<&str>,
) -> Vec<u32> {
use super::*;
autoreleasepool(|_| {
let device = unsafe { Retained::retain(MTLCreateSystemDefaultDevice()) }
.expect("Metal device required");
let library = device
.newLibraryWithSource_options_error(
ns_string!(include_str!("metal_present.metal")),
None,
)
.expect("compile presentation shader");
let descriptor = MTLRenderPipelineDescriptor::new();
descriptor.setVertexFunction(
library
.newFunctionWithName(ns_string!("raster_vertex"))
.as_deref(),
);
descriptor.setFragmentFunction(
library
.newFunctionWithName(ns_string!("compact_fragment"))
.as_deref(),
);
unsafe {
descriptor
.colorAttachments()
.objectAtIndexedSubscript(0)
.setPixelFormat(MTLPixelFormat::BGRA8Unorm);
}
let pipeline = device
.newRenderPipelineStateWithDescriptor_error(&descriptor)
.unwrap();
let desc = unsafe {
MTLTextureDescriptor::texture2DDescriptorWithPixelFormat_width_height_mipmapped(
MTLPixelFormat::BGRA8Unorm,
drawable.0 as usize,
drawable.1 as usize,
false,
)
};
desc.setStorageMode(if measure.is_some() {
MTLStorageMode::Private
} else {
MTLStorageMode::Shared
});
desc.setUsage(MTLTextureUsage::RenderTarget);
let output = device.newTextureWithDescriptor(&desc).unwrap();
let mut buffers = CompactBuffers::default();
let queue = device.newCommandQueue().unwrap();
let mut samples = Vec::new();
let mut submitted = Vec::new();
let mut gpu_time = Vec::new();
let mut alternate = frame.clone();
if measure.is_some() {
alternate.cells[0] ^= 0x010101;
}
for iteration in 0..if measure.is_some() { 420 } else { 1 } {
let frame = if iteration % 2 == 0 {
frame
} else {
&alternate
};
let start = std::time::Instant::now();
let (submit_elapsed, gpu_seconds) = autoreleasepool(|_| {
let uniforms = compact_frame_uniforms(frame, crop, drawable).unwrap();
let pass = unsafe { MTLRenderPassDescriptor::new() };
let color = unsafe { pass.colorAttachments().objectAtIndexedSubscript(0) };
color.setTexture(Some(&output));
color.setLoadAction(MTLLoadAction::Clear);
color.setStoreAction(MTLStoreAction::Store);
color.setClearColor(objc2_metal::MTLClearColor {
red: 0.0,
green: 0.0,
blue: 0.0,
alpha: 1.0,
});
let (cells, detail) = buffers.upload(&device, frame).unwrap();
let command = queue.commandBuffer().unwrap();
let encoder = command.renderCommandEncoderWithDescriptor(&pass).unwrap();
encoder.setRenderPipelineState(&pipeline);
unsafe {
encoder.setFragmentBuffer_offset_atIndex(Some(cells), 0, 0);
encoder.setFragmentBuffer_offset_atIndex(Some(detail), 0, 1);
encoder.setFragmentBytes_length_atIndex(
non_null_bytes(&uniforms),
size_of::<CompactFrameUniforms>(),
2,
);
}
encoder.setViewport(MTLViewport {
originX: uniforms.ox.into(),
originY: uniforms.oy.into(),
width: uniforms.dw.into(),
height: uniforms.dh.into(),
znear: 0.0,
zfar: 1.0,
});
unsafe {
encoder.drawPrimitives_vertexStart_vertexCount(
MTLPrimitiveType::TriangleStrip,
0,
4,
);
}
encoder.endEncoding();
command.commit();
let submit_elapsed = start.elapsed();
unsafe {
command.waitUntilCompleted();
}
let gpu_seconds = unsafe { command.GPUEndTime() - command.GPUStartTime() };
(submit_elapsed, gpu_seconds)
});
if iteration >= 120 {
samples.push(start.elapsed());
submitted.push(submit_elapsed);
gpu_time.push(std::time::Duration::from_secs_f64(gpu_seconds.max(0.)));
}
}
if let Some(name) = measure {
crate::renderer_bench::report(name, "default-metal", &mut samples);
crate::renderer_bench::report(
&format!("{name}-submit"),
"default-metal",
&mut submitted,
);
crate::renderer_bench::report(
&format!("{name}-gpu-time"),
"default-metal",
&mut gpu_time,
);
return Vec::new();
}
let mut result = vec![0u32; (drawable.0 * drawable.1) as usize];
unsafe {
output.getBytes_bytesPerRow_fromRegion_mipmapLevel(
NonNull::new(result.as_mut_ptr().cast()).unwrap(),
drawable.0 as usize * 4,
MTLRegion {
origin: objc2_metal::MTLOrigin { x: 0, y: 0, z: 0 },
size: objc2_metal::MTLSize {
width: drawable.0 as usize,
height: drawable.1 as usize,
depth: 1,
},
},
0,
);
}
result
})
}
pub(crate) fn benchmark_default_presentation(text: bool) {
{
let frame = crate::renderer_bench::presentation_fixture(text);
let name = if text { "present-text" } else { "present-ui" };
render_compact(
&frame,
(0, 0, frame.width, frame.height),
(800, 600),
Some(name),
);
}
}
#[test]
fn compact_shader_matches_cpu_coverage_for_crops_and_drawables() {
use systemless::memory::CompactPresentation;
let mut seed = 0x2545_f491u32;
let mut next = || {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
seed
};
for scale in [2u32, 3, 4] {
let (width, height) = (13u32, 9u32);
let mut frame = CompactPresentation {
width,
height,
scale,
..Default::default()
};
for _ in 0..width * height {
if next() % 4 == 0 {
frame.cells.push(0x80000000 | frame.detail.len() as u32);
for _ in 0..scale * scale {
frame.detail.push(next() & 0xffffff);
}
} else {
frame.cells.push(next() & 0xffffff);
}
}
let sw = width * scale;
let full: Vec<u32> = (0..height * scale)
.flat_map(|y| (0..sw).map(move |x| (x, y)))
.map(|(x, y)| {
let cell = frame.cells[((y / scale) * width + x / scale) as usize];
0xff000000
| if cell >> 31 == 0 {
cell
} else {
frame.detail[(cell & 0x7fffffff) as usize
+ ((y % scale) * scale + x % scale) as usize]
}
})
.collect();
for crop in [(0, 0, width, height), (2, 1, 9, 7), (12, 8, 1, 1)] {
for drawable in [
(crop.2 * scale, crop.3 * scale),
(crop.2 * scale + 7, crop.3 * scale + 3),
(crop.2, crop.3 + 5),
(crop.2 * 5 + 1, crop.3 * 2),
(31, 17),
] {
let (cl, ct, cw, ch) = crop;
let cropped: Vec<u32> = (ct * scale..(ct + ch) * scale)
.flat_map(|y| {
full[(y * sw + cl * scale) as usize..(y * sw + (cl + cw) * scale) as usize]
.iter()
.copied()
})
.collect();
let (ox, oy, dw, dh) =
super::integer_aspect_fit((cw, ch), drawable);
let mut scaled = Vec::new();
systemless::display::resize_argb_coverage(
&cropped,
(cw * scale, ch * scale),
(dw, dh),
&mut scaled,
);
let actual = render_compact(&frame, crop, drawable, None);
for y in 0..drawable.1 {
for x in 0..drawable.0 {
let expected = if x >= ox && x < ox + dw && y >= oy && y < oy + dh {
scaled[((y - oy) * dw + x - ox) as usize]
} else {
0xff000000
};
assert_eq!(
actual[(y * drawable.0 + x) as usize],
expected,
"scale={scale} crop={crop:?} drawable={drawable:?} at ({x},{y})"
);
}
}
}
}
}
}
#[test]
fn compact_uniforms_reject_crops_outside_the_frame_and_inexact_totals() {
use systemless::memory::CompactPresentation;
let frame = CompactPresentation {
width: 4,
height: 3,
scale: 2,
cells: vec![0; 12],
detail: Vec::new(),
};
assert!(super::compact_frame_uniforms(&frame, (0, 0, 4, 3), (8, 6)).is_some());
assert!(super::compact_frame_uniforms(&frame, (1, 0, 4, 3), (8, 6)).is_none());
assert!(super::compact_frame_uniforms(&frame, (0, 0, 0, 3), (8, 6)).is_none());
assert!(super::compact_frame_uniforms(&frame, (0, 0, 4, 3), (0, 6)).is_none());
let large = CompactPresentation {
width: 4096,
height: 4096,
scale: 4,
cells: vec![0; 4096 * 4096],
detail: Vec::new(),
};
assert!(super::compact_frame_uniforms(&large, (0, 0, 4096, 4096), (100, 100)).is_none());
}
#[test]
fn minification_retains_thin_strokes_between_sample_centers() {
let source = image::RgbaImage::from_fn(8, 8, |x, _| {
let shade = if x % 2 == 0 { 0 } else { 255 };
image::Rgba([shade, shade, shade, 255])
});
for (width, expected) in [
(2, vec![128, 128]),
(3, vec![96, 128, 159]),
(5, vec![96, 96, 128, 159, 159]),
] {
let result = render_rgba(&source, width, 3);
let packed: Vec<u32> = source
.pixels()
.map(|p| u32::from_be_bytes([p[3], p[0], p[1], p[2]]))
.collect();
let mut software = Vec::new();
systemless::display::resize_argb_coverage(&packed, (8, 8), (width, 3), &mut software);
for (gpu, cpu) in result.pixels().zip(software) {
let [a, r, g, b] = cpu.to_be_bytes();
for (actual, expected) in gpu.0.into_iter().zip([r, g, b, a]) {
assert!(actual.abs_diff(expected) <= 1);
}
}
for (x, _, pixel) in result.enumerate_pixels() {
assert!(
pixel[0].abs_diff(expected[x as usize]) <= 1,
"lost coverage at width {width}, column {x}"
);
assert_eq!(pixel[3], 255);
}
}
let enlarged = render_rgba(&source, 16, 16);
for (x, y, pixel) in enlarged.enumerate_pixels() {
assert_eq!(pixel, source.get_pixel(x / 2, y / 2));
}
}
#[test]
#[ignore = "writes actual Metal output; set SYSTEMLESS_METAL_FONT_CAPTURE"]
fn capture_showcase_at_mac_window_size() {
let path = std::env::var_os("SYSTEMLESS_METAL_FONT_CAPTURE").expect("capture output path");
let source = image::load_from_memory(include_bytes!(
"../../../tests/toolbox-showcase/outline-fonts/first-paint/textedit-fresh.png"
))
.unwrap()
.into_rgba8();
let scale = systemless::display::outline_output_scale((800, 580), (960, 696));
let pixels = source
.pixels()
.map(|p| u32::from_be_bytes([p[3], p[0], p[1], p[2]]))
.collect::<Vec<_>>();
let mut resolved = Vec::new();
systemless::display::resize_argb_coverage(
&pixels,
source.dimensions(),
(800 * scale, 600 * scale),
&mut resolved,
);
let bytes = resolved
.into_iter()
.flat_map(|p| [(p >> 16) as u8, (p >> 8) as u8, p as u8, (p >> 24) as u8])
.collect();
let source = image::RgbaImage::from_raw(800 * scale, 600 * scale, bytes).unwrap();
let source =
image::imageops::crop_imm(&source, 0, 20 * scale, 800 * scale, 580 * scale).to_image();
render_rgba(&source, 960, 696).save(path).unwrap();
}
#[test]
fn viewport_scales_continuously_and_centers_letterboxing() {
assert_eq!(
aspect_fit_viewport(800, 600, 1920, 1080),
(240.0, 0.0, 1440.0, 1080.0)
);
assert_eq!(
aspect_fit_viewport(800, 600, 1200, 900),
(0.0, 0.0, 1200.0, 900.0)
);
}
#[test]
fn cropped_presentation_packs_only_visible_guest_rows() {
let layout = guest_visible_byte_layout(800, 8, 80, 104, 640, 392).unwrap();
assert_eq!(layout.visible_row_bytes * layout.row_count, 250_880);
}
#[test]
fn cropped_four_bit_presentation_keeps_nibble_aligned_rows() {
let layout = guest_visible_byte_layout(400, 4, 81, 10, 319, 20).unwrap();
assert_eq!(layout.first_row_offset, 4_040);
assert_eq!(layout.row_stride, 400);
assert_eq!(layout.visible_row_bytes, 160);
assert_eq!(layout.row_count, 20);
}
#[test]
fn cropped_two_bit_presentation_keeps_msb_aligned_metadata_and_rows() {
let layout = guest_visible_byte_layout(200, 2, 5, 10, 319, 20).unwrap();
assert_eq!(guest_packed_content_left(2, 5), Some(1));
assert_eq!(layout.first_row_offset, 2_001);
assert_eq!(layout.row_stride, 200);
assert_eq!(layout.visible_row_bytes, 80);
assert_eq!(layout.row_count, 20);
}
#[test]
fn guest_shader_decodes_two_bit_and_monochrome_pixels_through_the_palette() {
let shader = include_str!("metal_present.metal");
let (_, after_two_bit_header) = shader
.split_once("} else if (frame.pixel_size == 2) {")
.expect("guest shader must have an explicit 2bpp branch");
let (two_bit_branch, monochrome_branch) = after_two_bit_header
.split_once("} else {")
.expect("guest shader must retain a final 1bpp branch");
assert!(two_bit_branch.contains("x / 4"));
assert!(two_bit_branch.contains("6 - 2 * (x & 3)"));
assert!(two_bit_branch.contains("& 0x03"));
assert!(two_bit_branch.contains("argb = palette[index]"));
assert!(monochrome_branch.contains("x / 8"));
assert!(monochrome_branch.contains("7 - (x & 7)"));
assert!(monochrome_branch.contains("argb = palette[index]"));
}
#[test]
fn raster_frames_enqueue_while_drawable_is_blocked_and_keep_latest_pixels() {
use super::{argb_bytes, AsyncGuestPresenter, GuestFrameMailbox};
use std::{sync::Arc, time::Duration};
let mailbox = Arc::new(GuestFrameMailbox::default());
{
let mut state = mailbox.state.lock().unwrap();
state.drawable_in_use = true;
state.active = true;
}
let producer_mailbox = Arc::clone(&mailbox);
let (sent, received) = std::sync::mpsc::channel();
let producer = std::thread::spawn(move || {
let presenter = AsyncGuestPresenter {
mailbox: producer_mailbox,
thread: None,
};
let mut pixels = vec![0xff123456; 16];
for color in [0xff123456, 0xffabcdef] {
pixels.fill(color);
presenter.enqueue_raster(&pixels, (4, 4), (8, 8)).unwrap();
}
pixels.fill(0); sent.send(presenter).unwrap();
});
let presenter = received
.recv_timeout(Duration::from_secs(2))
.expect("raster enqueue must not wait for a drawable or an active frame");
producer.join().unwrap();
{
let state = mailbox.state.lock().unwrap();
assert!(state.drawable_in_use && state.active);
assert_eq!(state.coalesced, 1);
let frame = state.pending.as_ref().unwrap();
assert_eq!(frame.pixels.as_bytes(), argb_bytes(&[0xffabcdef; 16]));
assert!(
frame.metadata
== FrameMetadata::Raster {
layout: RasterLayout::whole((4, 4)),
drawable_size: (8, 8),
}
);
}
let metadata = GuestFrameMetadata {
screen_layout: (2, 2, 1, 8),
content_rect: (0, 0, 2, 1),
palette: [0; 256],
uniforms: GuestFrameUniforms::default(),
cursor: GuestCursorData::default(),
drawable_size: (8, 8),
};
presenter
.enqueue(
&[7, 8],
guest_visible_byte_layout(2, 8, 0, 0, 2, 1).unwrap(),
metadata,
)
.unwrap();
let state = mailbox.state.lock().unwrap();
assert_eq!(state.coalesced, 2);
assert_eq!(state.pending.as_ref().unwrap().pixels.as_bytes(), &[7u8, 8]);
}
#[test]
fn busy_presenter_mailbox_keeps_only_the_latest_complete_frame() {
let metadata = GuestFrameMetadata {
screen_layout: (4, 4, 2, 8),
content_rect: (0, 0, 4, 2),
palette: [0; 256],
uniforms: GuestFrameUniforms::default(),
cursor: GuestCursorData::default(),
drawable_size: (8, 4),
};
let mut state = GuestFrameMailboxState::default();
let layout = guest_visible_byte_layout(4, 8, 0, 0, 4, 1).unwrap();
replace_pending_guest_frame(
&mut state,
&[1, 2, 3, 4],
layout,
FrameMetadata::Guest(metadata.clone()),
);
replace_pending_guest_frame(
&mut state,
&[5, 6, 7, 8],
layout,
FrameMetadata::Guest(metadata.clone()),
);
assert_eq!(state.coalesced, 1);
let pending = state.pending.as_ref().unwrap();
assert_eq!(pending.pixels.as_bytes(), &[5u8, 6, 7, 8]);
assert!(pending.metadata == FrameMetadata::Guest(metadata));
}
#[test]
fn raster_present_bytes_borrow_the_caller_pixels() {
let pixels = vec![0xff00_0000u32, 0x0012_3456];
let bytes = argb_bytes(&pixels);
assert_eq!(bytes.as_ptr(), pixels.as_ptr().cast());
assert_eq!(bytes.len(), pixels.len() * std::mem::size_of::<u32>());
}
#[test]
fn presenter_mailbox_packs_cropped_rows_without_surrounding_pixels() {
let metadata = GuestFrameMetadata {
screen_layout: (6, 6, 3, 8),
content_rect: (2, 1, 3, 2),
palette: [0; 256],
uniforms: GuestFrameUniforms::default(),
cursor: GuestCursorData::default(),
drawable_size: (6, 4),
};
let framebuffer = [
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, ];
let layout = guest_visible_byte_layout(6, 8, 2, 1, 3, 2).unwrap();
let mut state = GuestFrameMailboxState::default();
replace_pending_guest_frame(
&mut state,
&framebuffer,
layout,
FrameMetadata::Guest(metadata),
);
assert_eq!(
state.pending.unwrap().pixels.as_bytes(),
&[8u8, 9, 10, 14, 15, 16]
);
}
#[test]
fn unchanged_detection_compares_only_cropped_visible_rows() {
let mut framebuffer = vec![0u8; 8 * 6];
let layout = guest_visible_byte_layout(8, 8, 2, 1, 4, 3).unwrap();
let mut snapshot = Vec::new();
copy_guest_visible_pixels(&mut snapshot, &framebuffer, layout);
assert!(guest_visible_pixels_equal(&snapshot, &framebuffer, layout));
framebuffer[0] = 1;
assert!(
guest_visible_pixels_equal(&snapshot, &framebuffer, layout),
"pixels outside the crop must not trigger a GPU submission"
);
framebuffer[2 * 8 + 4] = 1;
assert!(!guest_visible_pixels_equal(&snapshot, &framebuffer, layout));
}
#[test]
fn monochrome_visible_comparison_includes_boundary_bytes() {
let mut framebuffer = vec![0u8; 4 * 3];
let layout = guest_visible_byte_layout(4, 1, 7, 1, 10, 1).unwrap();
let mut snapshot = Vec::new();
copy_guest_visible_pixels(&mut snapshot, &framebuffer, layout);
assert_eq!(snapshot.len(), 3);
framebuffer[4 + 2] = 0x80;
assert!(!guest_visible_pixels_equal(&snapshot, &framebuffer, layout));
}
#[test]
#[ignore = "measurement harness; prints raster mailbox path timings"]
fn mailbox_raster_copy_microbench() {
use super::{AsyncGuestPresenter, GuestFrameMailbox};
use std::sync::Arc;
use std::time::{Duration, Instant};
const WIDTH: u32 = 800;
const HEIGHT: u32 = 600;
const CROP: (u32, u32, u32, u32) = (0, 40, 800, 520);
const FRAMES: usize = 600;
let (crop_left, crop_top, crop_width, crop_height) = CROP;
let crop_texels = (crop_width * crop_height) as usize;
let full = vec![0u32; (WIDTH * HEIGHT) as usize];
let presenter = AsyncGuestPresenter {
mailbox: Arc::new(GuestFrameMailbox::default()),
thread: None,
};
let mut staged_borrowed = Vec::new();
for _ in 0..FRAMES {
let start = Instant::now();
presenter
.enqueue_raster(&full, (WIDTH, HEIGHT), (WIDTH, HEIGHT))
.unwrap();
staged_borrowed.push(start.elapsed());
}
let layout = RasterLayout {
left: crop_left,
top: crop_top,
width: crop_width,
height: crop_height,
buffer_width: WIDTH,
};
let mut handoff_owned = Vec::new();
let mut scratch = full.clone();
for _ in 0..FRAMES {
let start = Instant::now();
scratch = presenter
.enqueue_raster_owned(scratch, layout, (WIDTH, HEIGHT))
.unwrap();
handoff_owned.push(start.elapsed());
std::hint::black_box(&scratch);
}
drop(presenter);
let mut crop_move = Vec::new();
let mut frame = full.clone();
for _ in 0..FRAMES {
frame.extend_from_slice(&full[..(WIDTH * HEIGHT) as usize - frame.len()]);
let start = Instant::now();
for row in 0..crop_height as usize {
let source = (crop_top as usize + row) * WIDTH as usize + crop_left as usize;
frame.copy_within(
source..source + crop_width as usize,
row * crop_width as usize,
);
}
frame.truncate(crop_texels);
crop_move.push(start.elapsed());
std::hint::black_box(&frame);
}
let full_bytes_per_frame = (WIDTH * HEIGHT) as usize * size_of::<u32>();
let crop_bytes_per_frame = crop_texels * size_of::<u32>();
eprintln!(
"frame={WIDTH}x{HEIGHT} crop={crop_width}x{crop_height}@{crop_left},{crop_top} \
full_bytes={full_bytes_per_frame} crop_bytes={crop_bytes_per_frame}"
);
summarise("staged_borrowed_frame", staged_borrowed);
summarise("handoff_owned_frame", handoff_owned);
summarise("materialised_crop", crop_move);
eprintln!(
"main-thread bytes/frame: cropped software frame before={} after={}",
crop_bytes_per_frame * 2,
0
);
fn summarise(name: &str, mut samples: Vec<Duration>) {
samples.sort();
let total: Duration = samples.iter().copied().sum();
eprintln!(
"{name}: mean={:?} p50={:?} p95={:?}",
total / samples.len() as u32,
samples[samples.len() / 2],
samples[samples.len() * 95 / 100]
);
}
}
#[test]
fn raster_handoff_lends_the_frame_and_recycles_it_through_the_mailbox() {
use super::{AsyncGuestPresenter, GuestFrameMailbox};
let presenter = AsyncGuestPresenter {
mailbox: std::sync::Arc::new(GuestFrameMailbox::default()),
thread: None,
};
let layout = RasterLayout {
left: 1,
top: 2,
width: 2,
height: 2,
buffer_width: 4,
};
let first: Vec<u32> = (0..16).collect();
let first_pixels = first.as_ptr();
let spare = presenter
.enqueue_raster_owned(first, layout, (8, 8))
.unwrap();
assert!(
spare.is_empty(),
"nothing has been presented yet, so there is no spare to hand back"
);
{
let state = presenter.mailbox.state.lock().unwrap();
let pending = state.pending.as_ref().unwrap();
match &pending.pixels {
FramePixels::Argb(pixels) => assert_eq!(
pixels.as_ptr(),
first_pixels,
"the queued frame is the caller's own allocation"
),
FramePixels::Indexed(_) | FramePixels::Compact(_) => {
panic!("raster frames queue ARGB words")
}
}
assert!(
pending.metadata
== FrameMetadata::Raster {
layout,
drawable_size: (8, 8),
}
);
}
let second: Vec<u32> = (100..116).collect();
let second_pixels = second.as_ptr();
let spare = presenter
.enqueue_raster_owned(second, layout, (8, 8))
.unwrap();
assert_eq!(
spare.as_ptr(),
first_pixels,
"the superseded frame becomes the caller's next scratch buffer"
);
assert_eq!(spare, (0..16).collect::<Vec<u32>>());
let state = presenter.mailbox.state.lock().unwrap();
assert_eq!(state.coalesced, 1);
match &state.pending.as_ref().unwrap().pixels {
FramePixels::Argb(pixels) => assert_eq!(pixels.as_ptr(), second_pixels),
FramePixels::Indexed(_) | FramePixels::Compact(_) => {
panic!("raster frames queue ARGB words")
}
}
}
#[test]
fn raster_layout_rejects_rectangles_past_the_buffer() {
let inside = RasterLayout {
left: 2,
top: 3,
width: 2,
height: 1,
buffer_width: 4,
};
let buffer_bytes = 4 * 4 * size_of::<u32>();
assert_eq!(
inside.texel_byte_offset(buffer_bytes),
Some((3 * 4 + 2) * size_of::<u32>())
);
assert_eq!(inside.texel_byte_offset(buffer_bytes - 1), None);
let past_the_row = RasterLayout {
left: 3,
width: 2,
..inside
};
assert_eq!(past_the_row.texel_byte_offset(buffer_bytes), None);
assert_eq!(
RasterLayout::whole((0, 4)).texel_byte_offset(buffer_bytes),
None
);
assert_eq!(
RasterLayout::whole((4, 0)).texel_byte_offset(buffer_bytes),
None
);
assert_eq!(
RasterLayout::whole((4, 4)).texel_byte_offset(buffer_bytes),
Some(0)
);
}
#[test]
fn cropped_upload_matches_a_materialised_crop() {
use super::*;
const WIDTH: u32 = 6;
const HEIGHT: u32 = 4;
let frame: Vec<u32> = (0..WIDTH * HEIGHT).map(|i| 0xff00_0000 | i).collect();
let layout = RasterLayout {
left: 1,
top: 1,
width: 3,
height: 2,
buffer_width: WIDTH,
};
let mut materialised = Vec::new();
for row in 0..layout.height as usize {
let start = (layout.top as usize + row) * WIDTH as usize + layout.left as usize;
materialised.extend_from_slice(&frame[start..start + layout.width as usize]);
}
assert_eq!(materialised.len(), 6);
autoreleasepool(|_| {
let device = unsafe { Retained::retain(MTLCreateSystemDefaultDevice()) }
.expect("Metal device required");
let texture = |width: u32, height: u32| {
let descriptor = unsafe {
MTLTextureDescriptor::texture2DDescriptorWithPixelFormat_width_height_mipmapped(
MTLPixelFormat::RGBA8Unorm,
width as usize,
height as usize,
false,
)
};
descriptor.setStorageMode(MTLStorageMode::Shared);
descriptor.setUsage(MTLTextureUsage::ShaderRead);
device.newTextureWithDescriptor(&descriptor).unwrap()
};
let read = |texture: &ProtocolObject<dyn MTLTexture>| {
let mut bytes = vec![0u8; (layout.width * layout.height) as usize * 4];
let region = MTLRegion {
origin: objc2_metal::MTLOrigin { x: 0, y: 0, z: 0 },
size: objc2_metal::MTLSize {
width: layout.width as usize,
height: layout.height as usize,
depth: 1,
},
};
unsafe {
texture.getBytes_bytesPerRow_fromRegion_mipmapLevel(
NonNull::new(bytes.as_mut_ptr().cast()).unwrap(),
layout.width as usize * 4,
region,
0,
);
}
bytes
};
let size = (layout.width, layout.height);
let strided = texture(size.0, size.1);
upload_raster_region(&strided, argb_bytes(&frame), layout).unwrap();
let packed = texture(size.0, size.1);
upload_raster_region(
&packed,
argb_bytes(&materialised),
RasterLayout::whole(size),
)
.unwrap();
let strided = read(&strided);
assert_eq!(strided, read(&packed));
let mut expected = Vec::new();
for pixel in &materialised {
expected.extend_from_slice(&pixel.to_ne_bytes());
}
assert_eq!(strided, expected);
});
}
#[test]
fn monochrome_cursor_is_packed_for_metal_without_bit_reversal() {
let mut data = [0u8; 32];
let mut mask = [0u8; 32];
data[0..2].copy_from_slice(&0x8001u16.to_be_bytes());
mask[0..2].copy_from_slice(&0xC003u16.to_be_bytes());
let cursor = CursorImage::Mono {
data,
mask,
hot_v: 3,
hot_h: 4,
};
let (uniforms, gpu) = guest_cursor_data(Some(&cursor), (20, 30));
assert_eq!(uniforms.cursor_kind, 1);
assert_eq!((uniforms.cursor_left, uniforms.cursor_top), (26, 17));
assert_eq!(gpu.data_rows[0], 0x8001);
assert_eq!(gpu.mask_rows[0], 0xC003);
}
}