mod color;
#[cfg(windows)]
mod d3d11;
#[cfg(windows)]
mod d3d12;
mod display;
pub(crate) mod feedback;
#[cfg(target_os = "macos")]
mod metal;
pub(crate) mod node;
#[cfg(windows)]
mod shared;
#[cfg(windows)]
pub use d3d12::{D3D12Lease, D3D12Provider};
pub use feedback::monotonic_ns;
#[cfg(windows)]
pub fn install_d3d12_provider(provider: D3D12Provider) {
d3d12::install(provider);
}
#[cfg(target_os = "macos")]
const NO_D3D: &str = "Direct3D is Windows-only; on macOS present a Metal texture \
(present_metal_texture), an IOSurface (SharedTexture::from_iosurface) or a \
CVPixelBuffer (present_cv_pixel_buffer)";
#[cfg(windows)]
const NO_METAL: &str = "Metal is macOS-only; on Windows present a D3D11 or D3D12 texture, or a \
SharedTexture opened from an NT handle";
#[cfg(not(any(windows, target_os = "macos")))]
const NO_D3D: &str =
"GPU surfaces are Windows and macOS only for now; present CPU frames with present_bgra";
#[cfg(not(any(windows, target_os = "macos")))]
const NO_METAL: &str = NO_D3D;
use std::collections::HashMap;
use std::ffi::c_void;
use std::fmt;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, MutexGuard, Weak};
use std::time::Duration;
const MAX_SIDE: u32 = 16384;
const _: () = {
const fn send_sync<T: Send + Sync>() {}
const fn send<T: Send>() {}
send_sync::<SurfaceHandle>();
send_sync::<D3D11Device>();
send_sync::<D3D12Device>();
send_sync::<D3D12Fence>();
send_sync::<MetalDevice>();
send_sync::<MetalEvent>();
send::<SharedTexture>();
};
pub fn surface(name: &str) -> SurfaceHandle {
let mut map = lock(registry());
let shared = map
.entry(name.to_string())
.or_insert_with(|| {
ANY.store(true, Ordering::Relaxed);
let shared = Arc::new(Shared {
name: name.into(),
state: Mutex::new(State::default()),
watchers: Mutex::new(Vec::new()),
frames: Mutex::new(Vec::new()),
});
lock(&shared.state).key = feedback::key(&shared);
shared
})
.clone();
SurfaceHandle { shared }
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum SurfaceError {
NotSupported(&'static str),
NoDevice(String),
DeviceChanged,
WrongDevice,
Format(String),
Size(String),
Timeout,
Busy,
Platform(String),
FormatMismatch {
surface: SurfaceFormat,
frame: SurfaceFormat,
},
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SurfaceFormat {
#[default]
Bgra8,
Rgba16Float,
}
impl fmt::Display for SurfaceFormat {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(match self {
Self::Bgra8 => "Bgra8",
Self::Rgba16Float => "Rgba16Float",
})
}
}
fn check_format(surface: SurfaceFormat, frame: SurfaceFormat) -> Result<(), SurfaceError> {
if surface == frame {
Ok(())
} else {
Err(SurfaceError::FormatMismatch { surface, frame })
}
}
impl fmt::Display for SurfaceError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NotSupported(why) => f.write_str(why),
Self::NoDevice(why) => write!(f, "the renderer has no GPU device: {why}"),
Self::DeviceChanged => f.write_str(
"the renderer recreated its device; get it again (d3d11_device, d3d12_device, \
metal_device) and recreate the textures",
),
Self::WrongDevice => f.write_str(
"the texture is not on the renderer's device (d3d11_device, d3d12_device, \
metal_device); share it (CreateSharedHandle, or an IOSurface on macOS) and \
present it as a SharedTexture",
),
Self::Format(why) | Self::Size(why) => f.write_str(why),
Self::Timeout => f.write_str(
"the producer did not release the keyed mutex to the acquire key, or signal the \
fence, in time",
),
Self::Busy => f.write_str(
"every surface texture is still in use: the producer presents faster than the \
window draws, or a fence it waits on is never signalled; drop this frame",
),
Self::Platform(why) => f.write_str(why),
Self::FormatMismatch { surface, frame } => write!(
f,
"a {frame} frame on a surface set to {surface}: present {surface} frames, or call \
set_format(SurfaceFormat::{frame}) first"
),
}
}
}
impl std::error::Error for SurfaceError {}
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct SurfaceInfo {
pub width: u32,
pub height: u32,
pub scale: f32,
pub visible: bool,
pub display: SurfaceDisplay,
pub dynamic_range_limit: sk_css::DynamicRangeLimit,
}
impl SurfaceInfo {
pub fn content_headroom(&self) -> f32 {
self.dynamic_range_limit
.headroom(self.display.output_headroom)
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SurfaceDisplay {
pub known: bool,
pub hdr: bool,
pub headroom: f32,
pub potential_headroom: f32,
pub output_headroom: f32,
pub sdr_white_nits: Option<f32>,
pub peak_nits: Option<f32>,
pub full_frame_nits: Option<f32>,
pub refresh_hz: Option<f32>,
pub variable_refresh: Option<bool>,
pub refresh_period: Option<Duration>,
pub last_vblank: Option<u64>,
}
impl Default for SurfaceDisplay {
fn default() -> Self {
Self {
known: false,
hdr: false,
headroom: 1.0,
potential_headroom: 1.0,
output_headroom: 1.0,
sdr_white_nits: None,
peak_nits: None,
full_frame_nits: None,
refresh_hz: None,
variable_refresh: None,
refresh_period: None,
last_vblank: None,
}
}
}
impl SurfaceDisplay {
pub fn nits(&self, value: f32) -> Option<f32> {
self.sdr_white_nits.map(|white| value * white)
}
fn differs(&self, other: &SurfaceDisplay) -> bool {
let level = |a: f32, b: f32| (a - b).abs() > 0.01 * a.abs().max(b.abs()).max(1.0);
let maybe = |a: Option<f32>, b: Option<f32>| match (a, b) {
(Some(a), Some(b)) => level(a, b),
(a, b) => a.is_some() != b.is_some(),
};
self.known != other.known
|| self.hdr != other.hdr
|| self.variable_refresh != other.variable_refresh
|| level(self.headroom, other.headroom)
|| level(self.potential_headroom, other.potential_headroom)
|| level(self.output_headroom, other.output_headroom)
|| maybe(self.sdr_white_nits, other.sdr_white_nits)
|| maybe(self.peak_nits, other.peak_nits)
|| maybe(self.full_frame_nits, other.full_frame_nits)
|| maybe(self.refresh_hz, other.refresh_hz)
}
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum SurfaceEvent {
Changed(SurfaceInfo),
DeviceLost,
DisplayChanged(SurfaceDisplay),
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct SurfaceStats {
pub presented: u64,
pub shown: u64,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FrameEvent {
Presented {
frame: u64,
shown_at: u64,
refresh_interval: Duration,
precision: FramePrecision,
},
Dropped { frame: u64, reason: FrameDropReason },
}
impl FrameEvent {
pub fn frame(&self) -> u64 {
match *self {
Self::Presented { frame, .. } | Self::Dropped { frame, .. } => frame,
}
}
fn dropped(frame: u64, reason: FrameDropReason) -> Self {
Self::Dropped { frame, reason }
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FramePrecision {
Exact,
Estimated,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FrameDropReason {
Superseded,
Hidden,
DeviceLost,
Closed,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct FramePresent {
pub frame: u64,
pub release: u64,
}
type FrameCallback = Arc<Mutex<Box<dyn FnMut(FrameEvent) + Send>>>;
#[derive(Clone)]
pub struct SurfaceHandle {
shared: Arc<Shared>,
}
impl fmt::Debug for SurfaceHandle {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("SurfaceHandle")
.field("name", &self.shared.name)
.finish()
}
}
type Watcher = Arc<dyn Fn(&SurfaceHandle, SurfaceEvent) + Send + Sync>;
pub(crate) struct Shared {
name: Arc<str>,
state: Mutex<State>,
watchers: Mutex<Vec<(u64, Watcher)>>,
frames: Mutex<Vec<(u64, FrameCallback)>>,
}
impl Shared {
fn frame_event(&self, event: FrameEvent) {
let callbacks: Vec<FrameCallback> =
lock(&self.frames).iter().map(|(_, f)| f.clone()).collect();
for callback in callbacks {
(lock(&callback))(event);
}
}
}
#[derive(Default)]
pub(crate) struct State {
pub(crate) seq: u64,
pub(crate) frame: Option<Frame>,
pub(crate) frame_id: u64,
key: feedback::Key,
watched: bool,
pub(crate) lost: &'static str,
presented: u64,
shown: u64,
shown_seq: u64,
info: SurfaceInfo,
pub(crate) format: SurfaceFormat,
#[cfg(windows)]
gpu: d3d11::SurfaceGpu,
#[cfg(windows)]
gpu12: d3d12::SurfaceGpu,
#[cfg(target_os = "macos")]
metal: metal::SurfaceGpu,
}
#[derive(Clone)]
pub(crate) enum Frame {
Cpu {
width: u32,
height: u32,
bgra: Arc<[u8]>,
halves: Option<Arc<[u16]>>,
},
#[cfg(windows)]
Gpu { width: u32, height: u32 },
#[cfg(windows)]
D3D12 { width: u32, height: u32 },
#[cfg(target_os = "macos")]
Metal { width: u32, height: u32 },
}
impl Frame {
pub(crate) fn size(&self) -> (u32, u32) {
match self {
Frame::Cpu { width, height, .. } => (*width, *height),
#[cfg(windows)]
Frame::Gpu { width, height } | Frame::D3D12 { width, height } => (*width, *height),
#[cfg(target_os = "macos")]
Frame::Metal { width, height } => (*width, *height),
}
}
}
impl State {
fn put(&mut self, frame: Frame) -> u64 {
self.seq += 1;
self.presented += 1;
self.frame = Some(frame);
self.lost = "";
self.frame_id += 1;
if self.watched {
let (key, id, visible) = (self.key, self.frame_id, self.info.visible);
feedback::with(|t| t.put(key, id, visible));
}
self.frame_id
}
pub(crate) fn note_shown(&mut self, seq: u64) {
if seq > self.shown_seq {
self.shown_seq = seq;
self.shown += 1;
}
}
#[cfg(windows)]
pub(crate) fn gpu_texture(
&mut self,
hdr: bool,
) -> Result<Option<d3d11::Texture>, SurfaceError> {
self.gpu.texture(hdr)
}
}
fn registry() -> &'static Mutex<HashMap<String, Arc<Shared>>> {
static REGISTRY: std::sync::OnceLock<Mutex<HashMap<String, Arc<Shared>>>> =
std::sync::OnceLock::new();
REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
}
static ANY: AtomicBool = AtomicBool::new(false);
pub(crate) fn dynamic_range_high(key: crate::windows::WinKey) -> bool {
display::dynamic_range_high(key)
}
pub(crate) fn any() -> bool {
ANY.load(Ordering::Relaxed)
}
pub(crate) fn all() -> Vec<SurfaceHandle> {
lock(registry())
.values()
.map(|shared| SurfaceHandle {
shared: shared.clone(),
})
.collect()
}
fn lock<T>(m: &Mutex<T>) -> MutexGuard<'_, T> {
m.lock().unwrap_or_else(|p| p.into_inner())
}
impl SurfaceHandle {
pub fn name(&self) -> &str {
&self.shared.name
}
pub fn info(&self) -> SurfaceInfo {
let mut info = self.state().info;
info.display = self.with_clock(info.display);
info
}
fn with_clock(&self, mut display: SurfaceDisplay) -> SurfaceDisplay {
if display.known {
(display.last_vblank, display.refresh_period) =
feedback::display_clock(feedback::key(&self.shared), display.refresh_hz);
}
display
}
pub fn on_frame(&self, f: impl FnMut(FrameEvent) + Send + 'static) -> FrameWatch {
static NEXT: AtomicU64 = AtomicU64::new(1);
let id = NEXT.fetch_add(1, Ordering::Relaxed);
lock(&self.shared.frames).push((id, Arc::new(Mutex::new(Box::new(f)))));
let mut st = self.state();
if !st.watched {
st.watched = true;
feedback::watch(&self.shared);
}
FrameWatch {
shared: Arc::downgrade(&self.shared),
id,
}
}
pub fn stats(&self) -> SurfaceStats {
let st = self.state();
SurfaceStats {
presented: st.presented,
shown: st.shown,
}
}
pub fn on_change(
&self,
f: impl Fn(&SurfaceHandle, SurfaceEvent) + Send + Sync + 'static,
) -> SurfaceWatch {
static NEXT: AtomicU64 = AtomicU64::new(1);
let id = NEXT.fetch_add(1, Ordering::Relaxed);
lock(&self.shared.watchers).push((id, Arc::new(f)));
SurfaceWatch {
shared: Arc::downgrade(&self.shared),
id,
}
}
pub fn set_format(&self, format: SurfaceFormat) {
self.state().format = format;
}
pub fn format(&self) -> SurfaceFormat {
self.state().format
}
pub fn present_bgra(
&self,
pixels: &[u8],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError> {
self.present_cpu(pixels, width, height, stride, false)
}
pub fn present_rgba16f(
&self,
pixels: &[u16],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError> {
check_format(self.format(), SurfaceFormat::Rgba16Float)?;
check_size(width, height)?;
let row = width as usize * 4;
let need = stride * (height as usize - 1) + row;
if stride < row || pixels.len() < need {
return Err(SurfaceError::Size(format!(
"a {width}x{height} half-float frame with stride {stride} needs {need} values and \
a stride of at least {row}; got {}",
pixels.len()
)));
}
let bgra = color::rgba16f_to_bgra8(pixels, width, height, stride);
let halves = display::any_capable().then(|| {
(0..height as usize)
.flat_map(|y| &pixels[y * stride..y * stride + row])
.copied()
.collect()
});
let frame = self.state().put(Frame::Cpu {
width,
height,
bgra: bgra.into(),
halves,
});
sk_runtime::frames::wake();
Ok(frame)
}
pub fn present_bgrx(
&self,
pixels: &[u8],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError> {
self.present_cpu(pixels, width, height, stride, true)
}
fn present_cpu(
&self,
pixels: &[u8],
width: u32,
height: u32,
stride: usize,
opaque: bool,
) -> Result<u64, SurfaceError> {
check_format(self.format(), SurfaceFormat::Bgra8)?;
check_size(width, height)?;
let row = width as usize * 4;
let need = stride * (height as usize - 1) + row;
if stride < row || pixels.len() < need {
return Err(SurfaceError::Size(format!(
"a {width}x{height} BGRA frame with stride {stride} needs {need} bytes and a stride \
of at least {row}; got {} bytes",
pixels.len()
)));
}
let mut packed = Vec::with_capacity(row * height as usize);
for y in 0..height as usize {
packed.extend_from_slice(&pixels[y * stride..y * stride + row]);
}
if opaque {
for alpha in packed.iter_mut().skip(3).step_by(4) {
*alpha = 255;
}
}
let frame = self.state().put(Frame::Cpu {
width,
height,
bgra: packed.into(),
halves: None,
});
sk_runtime::frames::wake();
Ok(frame)
}
pub fn clear(&self) {
let mut st = self.state();
if st.frame.take().is_some() {
st.seq += 1;
st.lost = "cleared";
if st.watched {
let key = st.key;
feedback::with(|t| t.cleared(key));
}
}
drop(st);
sk_runtime::frames::wake();
}
pub fn d3d11_device(&self) -> Result<D3D11Device, SurfaceError> {
#[cfg(windows)]
{
d3d11::device(&self.shared.state).map(|inner| D3D11Device { inner })
}
#[cfg(not(windows))]
{
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub unsafe fn present_d3d11_texture(&self, texture: *mut c_void) -> Result<u64, SurfaceError> {
#[cfg(windows)]
{
let frame = unsafe { d3d11::present_texture(&self.shared.state, texture) }?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(not(windows))]
{
let _ = texture;
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub fn d3d12_device(&self) -> Result<D3D12Device, SurfaceError> {
#[cfg(windows)]
{
d3d12::device(&self.shared.state).map(|inner| D3D12Device { inner })
}
#[cfg(not(windows))]
{
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub fn release_fence(&self) -> Result<D3D12Fence, SurfaceError> {
#[cfg(windows)]
{
d3d12::release_fence().map(|inner| D3D12Fence { inner })
}
#[cfg(not(windows))]
{
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub unsafe fn present_d3d12(
&self,
resource: *mut c_void,
resource_state: i32,
ready: Option<(*mut c_void, u64)>,
) -> Result<FramePresent, SurfaceError> {
#[cfg(windows)]
{
let (frame, release) =
unsafe { d3d12::present(&self.shared.state, resource, resource_state, ready) }?;
sk_runtime::frames::wake();
Ok(FramePresent { frame, release })
}
#[cfg(not(windows))]
{
let _ = (resource, resource_state, ready);
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub fn present_shared(&self, texture: &SharedTexture) -> Result<u64, SurfaceError> {
#[cfg(windows)]
{
if texture.inner.fenced {
return Err(SurfaceError::Format(
"the shared texture has a fence: present it with present_shared_fenced".into(),
));
}
let sync = match texture.keys {
Some((acquire, release)) => d3d11::SharedSync::Keyed(acquire, release),
None => d3d11::SharedSync::None,
};
let frame = texture
.inner
.present(&self.shared.state, sync, texture.timeout_ms)?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(target_os = "macos")]
{
if texture.keyed {
return Err(SurfaceError::NotSupported(
"a keyed mutex is a Direct3D object; on macOS synchronise with an \
MTLSharedEvent (SharedTexture::with_shared_event)",
));
}
if texture.inner.fenced() {
return Err(SurfaceError::Format(
"the shared texture has a shared event: present it with present_shared_fenced"
.into(),
));
}
let frame = metal::present_shared(&self.shared.state, &texture.inner, None)?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(not(any(windows, target_os = "macos")))]
{
match texture.never {}
}
}
pub fn present_shared_fenced(
&self,
texture: &SharedTexture,
wait: u64,
release: u64,
) -> Result<u64, SurfaceError> {
#[cfg(windows)]
{
if !texture.inner.fenced {
return Err(SurfaceError::Format(
"the shared texture has no fence: open it with SharedTexture::with_fence"
.into(),
));
}
let frame = texture.inner.present(
&self.shared.state,
d3d11::SharedSync::Fence(wait, release),
texture.timeout_ms,
)?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(target_os = "macos")]
{
if !texture.inner.fenced() {
return Err(SurfaceError::Format(
"the shared texture has no shared event: open it with \
SharedTexture::with_shared_event"
.into(),
));
}
let frame =
metal::present_shared(&self.shared.state, &texture.inner, Some((wait, release)))?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = (wait, release);
match texture.never {}
}
}
pub fn metal_device(&self) -> Result<MetalDevice, SurfaceError> {
#[cfg(target_os = "macos")]
{
metal::device(&self.shared.state).map(|inner| MetalDevice { inner })
}
#[cfg(not(target_os = "macos"))]
{
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub fn release_event(&self) -> Result<MetalEvent, SurfaceError> {
#[cfg(target_os = "macos")]
{
metal::release_event().map(|inner| MetalEvent { inner })
}
#[cfg(not(target_os = "macos"))]
{
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub unsafe fn present_metal_texture(
&self,
texture: *mut c_void,
ready: Option<(*mut c_void, u64)>,
) -> Result<FramePresent, SurfaceError> {
#[cfg(target_os = "macos")]
{
let (frame, release) = unsafe { metal::present(&self.shared.state, texture, ready) }?;
sk_runtime::frames::wake();
Ok(FramePresent { frame, release })
}
#[cfg(not(target_os = "macos"))]
{
let _ = (texture, ready);
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub unsafe fn present_cv_pixel_buffer(&self, buffer: *mut c_void) -> Result<u64, SurfaceError> {
#[cfg(target_os = "macos")]
{
let cpu = |cpu: metal::Cpu<'_>| match cpu.format {
SurfaceFormat::Bgra8 => {
self.present_cpu(cpu.pixels, cpu.width, cpu.height, cpu.stride, false)
}
SurfaceFormat::Rgba16Float => {
if cpu.pixels.as_ptr().align_offset(2) != 0 || cpu.stride % 2 != 0 {
return Err(SurfaceError::Platform(
"a misaligned RGhA CVPixelBuffer".into(),
));
}
let halves = unsafe {
std::slice::from_raw_parts(
cpu.pixels.as_ptr().cast::<u16>(),
cpu.pixels.len() / 2,
)
};
self.present_rgba16f(halves, cpu.width, cpu.height, cpu.stride / 2)
}
};
let frame = unsafe { metal::present_pixel_buffer(&self.shared.state, buffer, cpu) }?;
sk_runtime::frames::wake();
Ok(frame)
}
#[cfg(not(target_os = "macos"))]
{
let _ = buffer;
Err(SurfaceError::NotSupported(NO_METAL))
}
}
fn state(&self) -> MutexGuard<'_, State> {
lock(&self.shared.state)
}
pub(crate) fn shared(&self) -> &Arc<Shared> {
&self.shared
}
pub(crate) fn lock_state(&self) -> MutexGuard<'_, State> {
self.state()
}
pub(crate) fn set_info(&self, mut info: SurfaceInfo) {
let (changed, display) = {
let mut st = self.state();
let old = st.info;
let display = info.display.known && info.display.differs(&old.display);
if !display {
info.display = old.display;
}
st.info = info;
if st.watched {
let key = st.key;
feedback::with(|t| t.visibility(key, info.visible));
}
(
info != SurfaceInfo {
display: info.display,
..old
},
display,
)
};
if changed {
self.notify(SurfaceEvent::Changed(info));
}
if display {
self.notify(SurfaceEvent::DisplayChanged(self.with_clock(info.display)));
}
}
pub(crate) fn notify(&self, event: SurfaceEvent) {
let watchers: Vec<Watcher> = lock(&self.shared.watchers)
.iter()
.map(|(_, w)| w.clone())
.collect();
for watcher in watchers {
watcher(self, event);
}
}
pub(crate) fn device_lost(&self) {
#[cfg(windows)]
{
let mut st = self.state();
if matches!(st.frame, Some(Frame::Gpu { .. } | Frame::D3D12 { .. })) {
st.frame = None;
st.seq += 1;
st.lost = "device";
}
st.gpu.forget();
st.gpu12.forget();
}
#[cfg(target_os = "macos")]
{
let mut st = self.state();
if matches!(st.frame, Some(Frame::Metal { .. })) {
st.frame = None;
st.seq += 1;
st.lost = "device";
}
st.metal.forget();
}
self.notify(SurfaceEvent::DeviceLost);
}
}
fn check_size(width: u32, height: u32) -> Result<(), SurfaceError> {
if width == 0 || height == 0 || width > MAX_SIDE || height > MAX_SIDE {
return Err(SurfaceError::Size(format!(
"a {width}x{height} frame: each side must be 1 to {MAX_SIDE} pixels"
)));
}
Ok(())
}
#[must_use = "dropping the guard ends the subscription"]
pub struct SurfaceWatch {
shared: Weak<Shared>,
id: u64,
}
impl Drop for SurfaceWatch {
fn drop(&mut self) {
if let Some(shared) = self.shared.upgrade() {
lock(&shared.watchers).retain(|(id, _)| *id != self.id);
}
}
}
#[must_use = "dropping the guard ends the subscription"]
pub struct FrameWatch {
shared: Weak<Shared>,
id: u64,
}
impl Drop for FrameWatch {
fn drop(&mut self) {
let Some(shared) = self.shared.upgrade() else {
return;
};
let mut st = lock(&shared.state);
let mut frames = lock(&shared.frames);
frames.retain(|(id, _)| *id != self.id);
if frames.is_empty() && st.watched {
st.watched = false;
feedback::unwatch(&shared);
}
}
}
pub struct D3D11Device {
#[cfg(windows)]
inner: d3d11::Device,
#[cfg(not(windows))]
never: std::convert::Infallible,
}
impl D3D11Device {
pub fn as_raw(&self) -> *mut c_void {
#[cfg(windows)]
{
self.inner.as_raw()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
pub fn generation(&self) -> u64 {
#[cfg(windows)]
{
self.inner.generation()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
}
impl fmt::Debug for D3D11Device {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("D3D11Device")
.field("raw", &self.as_raw())
.field("generation", &self.generation())
.finish()
}
}
pub struct D3D12Device {
#[cfg(windows)]
inner: d3d12::Device,
#[cfg(not(windows))]
never: std::convert::Infallible,
}
impl D3D12Device {
pub fn as_raw(&self) -> *mut c_void {
#[cfg(windows)]
{
self.inner.as_raw()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
pub fn queue(&self) -> *mut c_void {
#[cfg(windows)]
{
self.inner.queue()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
pub fn generation(&self) -> u64 {
#[cfg(windows)]
{
self.inner.generation()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
}
impl fmt::Debug for D3D12Device {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("D3D12Device")
.field("raw", &self.as_raw())
.field("generation", &self.generation())
.finish()
}
}
pub struct D3D12Fence {
#[cfg(windows)]
inner: d3d12::Fence,
#[cfg(not(windows))]
never: std::convert::Infallible,
}
impl D3D12Fence {
pub fn as_raw(&self) -> *mut c_void {
#[cfg(windows)]
{
self.inner.as_raw()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
pub fn completed_value(&self) -> u64 {
#[cfg(windows)]
{
self.inner.completed()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
pub fn wait(&self, value: u64, timeout: Duration) -> bool {
#[cfg(windows)]
{
self.inner.wait(value, timeout)
}
#[cfg(not(windows))]
{
let _ = (value, timeout);
match self.never {}
}
}
pub fn generation(&self) -> u64 {
#[cfg(windows)]
{
self.inner.generation()
}
#[cfg(not(windows))]
{
match self.never {}
}
}
}
impl fmt::Debug for D3D12Fence {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("D3D12Fence")
.field("raw", &self.as_raw())
.field("completed", &self.completed_value())
.finish()
}
}
pub struct MetalDevice {
#[cfg(target_os = "macos")]
inner: metal::Device,
#[cfg(not(target_os = "macos"))]
never: std::convert::Infallible,
}
impl MetalDevice {
pub fn as_raw(&self) -> *mut c_void {
#[cfg(target_os = "macos")]
{
self.inner.as_raw()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
pub fn queue(&self) -> *mut c_void {
#[cfg(target_os = "macos")]
{
self.inner.queue()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
pub fn generation(&self) -> u64 {
#[cfg(target_os = "macos")]
{
self.inner.generation()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
}
impl fmt::Debug for MetalDevice {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("MetalDevice")
.field("raw", &self.as_raw())
.field("generation", &self.generation())
.finish()
}
}
pub struct MetalEvent {
#[cfg(target_os = "macos")]
inner: metal::Event,
#[cfg(not(target_os = "macos"))]
never: std::convert::Infallible,
}
impl MetalEvent {
pub fn as_raw(&self) -> *mut c_void {
#[cfg(target_os = "macos")]
{
self.inner.as_raw()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
pub fn signaled_value(&self) -> u64 {
#[cfg(target_os = "macos")]
{
self.inner.signaled()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
pub fn wait(&self, value: u64, timeout: Duration) -> bool {
#[cfg(target_os = "macos")]
{
self.inner.wait(value, timeout)
}
#[cfg(not(target_os = "macos"))]
{
let _ = (value, timeout);
match self.never {}
}
}
pub fn generation(&self) -> u64 {
#[cfg(target_os = "macos")]
{
self.inner.generation()
}
#[cfg(not(target_os = "macos"))]
{
match self.never {}
}
}
}
impl fmt::Debug for MetalEvent {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("MetalEvent")
.field("raw", &self.as_raw())
.field("signaled", &self.signaled_value())
.finish()
}
}
pub struct SharedTexture {
#[cfg(windows)]
inner: shared::Opened,
#[cfg(windows)]
keys: Option<(u64, u64)>,
#[cfg(windows)]
timeout_ms: u32,
#[cfg(target_os = "macos")]
inner: metal::Opened,
#[cfg(target_os = "macos")]
keyed: bool,
#[cfg(not(any(windows, target_os = "macos")))]
never: std::convert::Infallible,
}
#[cfg(target_os = "macos")]
const NT_HANDLES: &str = "NT handles are Windows-only; on macOS open an IOSurface \
(SharedTexture::from_iosurface, SharedTexture::from_mach_port)";
impl SharedTexture {
#[cfg(windows)]
fn new(inner: shared::Opened) -> Self {
Self {
inner,
keys: None,
timeout_ms: 100,
}
}
#[cfg(target_os = "macos")]
fn new(inner: metal::Opened) -> Self {
Self {
inner,
keyed: false,
}
}
pub fn open(handle: u64) -> Result<Self, SurfaceError> {
#[cfg(windows)]
{
shared::open(handle).map(Self::new)
}
#[cfg(target_os = "macos")]
{
let _ = handle;
Err(SurfaceError::NotSupported(NT_HANDLES))
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = handle;
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub fn open_from_process(pid: u32, handle: u64) -> Result<Self, SurfaceError> {
#[cfg(windows)]
{
shared::open_from_process(pid, handle).map(Self::new)
}
#[cfg(target_os = "macos")]
{
let _ = (pid, handle);
Err(SurfaceError::NotSupported(NT_HANDLES))
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = (pid, handle);
Err(SurfaceError::NotSupported(NO_D3D))
}
}
pub unsafe fn from_iosurface(surface: *mut c_void) -> Result<Self, SurfaceError> {
#[cfg(target_os = "macos")]
{
unsafe { metal::open_raw(surface) }.map(Self::new)
}
#[cfg(not(target_os = "macos"))]
{
let _ = surface;
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub fn from_mach_port(port: u32) -> Result<Self, SurfaceError> {
#[cfg(target_os = "macos")]
{
metal::open_mach_port(port).map(Self::new)
}
#[cfg(not(target_os = "macos"))]
{
let _ = port;
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub fn with_keyed_mutex(self, acquire: u64, release: u64) -> Self {
#[cfg(windows)]
{
let mut this = self;
this.inner.need_d3d11();
this.keys = Some((acquire, release));
this
}
#[cfg(target_os = "macos")]
{
let _ = (acquire, release);
Self {
keyed: true,
..self
}
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = (acquire, release);
match self.never {}
}
}
pub fn with_fence(self, fence: u64) -> Result<Self, SurfaceError> {
#[cfg(windows)]
{
let mut this = self;
this.inner.open_fence(fence)?;
Ok(this)
}
#[cfg(target_os = "macos")]
{
let _ = (self, fence);
Err(SurfaceError::NotSupported(NT_HANDLES))
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = fence;
match self.never {}
}
}
pub fn with_fence_from_process(self, pid: u32, fence: u64) -> Result<Self, SurfaceError> {
#[cfg(windows)]
{
let mut this = self;
this.inner.open_fence_from_process(pid, fence)?;
Ok(this)
}
#[cfg(target_os = "macos")]
{
let _ = (self, pid, fence);
Err(SurfaceError::NotSupported(NT_HANDLES))
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = (pid, fence);
match self.never {}
}
}
pub unsafe fn with_shared_event(self, event: *mut c_void) -> Result<Self, SurfaceError> {
#[cfg(target_os = "macos")]
{
let mut this = self;
unsafe { this.inner.set_event(event) }?;
Ok(this)
}
#[cfg(not(target_os = "macos"))]
{
let _ = (self, event);
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub unsafe fn with_shared_event_handle(
self,
handle: *mut c_void,
) -> Result<Self, SurfaceError> {
#[cfg(target_os = "macos")]
{
let mut this = self;
unsafe { this.inner.set_event_handle(handle) }?;
Ok(this)
}
#[cfg(not(target_os = "macos"))]
{
let _ = (self, handle);
Err(SurfaceError::NotSupported(NO_METAL))
}
}
pub fn with_timeout(self, timeout: Duration) -> Self {
#[cfg(windows)]
{
let mut this = self;
this.timeout_ms = timeout.as_millis().min(u128::from(u32::MAX - 1)) as u32;
this
}
#[cfg(target_os = "macos")]
{
let _ = timeout;
self
}
#[cfg(not(any(windows, target_os = "macos")))]
{
let _ = timeout;
match self.never {}
}
}
pub fn size(&self) -> (u32, u32) {
#[cfg(any(windows, target_os = "macos"))]
{
self.inner.size
}
#[cfg(not(any(windows, target_os = "macos")))]
{
match self.never {}
}
}
pub fn format(&self) -> SurfaceFormat {
#[cfg(any(windows, target_os = "macos"))]
{
self.inner.format
}
#[cfg(not(any(windows, target_os = "macos")))]
{
match self.never {}
}
}
}
impl fmt::Debug for SharedTexture {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("SharedTexture")
.field("size", &self.size())
.finish()
}
}
pub(crate) fn device_changed() {
#[cfg(windows)]
{
d3d11::forget_device();
d3d12::forget_device();
}
#[cfg(target_os = "macos")]
metal::forget_device();
feedback::with(|t| t.device_lost());
for surface in all() {
surface.device_lost();
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn one_name_is_one_surface() {
let a = surface("tests:one-name");
let b = surface("tests:one-name");
a.present_bgra(&[1, 2, 3, 4], 1, 1, 4).unwrap();
assert_eq!(b.stats().presented, 1);
assert_eq!(surface("tests:other-name").stats().presented, 0);
}
#[test]
fn a_padded_frame_is_packed_and_a_short_one_refused() {
let s = surface("tests:stride");
let mut pixels = vec![0u8; 12 * 2];
pixels[..8].copy_from_slice(&[1, 1, 1, 1, 2, 2, 2, 2]);
pixels[12..20].copy_from_slice(&[3, 3, 3, 3, 4, 4, 4, 4]);
s.present_bgra(&pixels, 2, 2, 12).unwrap();
match s.state().frame.clone() {
Some(Frame::Cpu { bgra, .. }) => {
assert_eq!(&*bgra, &[1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4])
}
_ => panic!("a CPU frame"),
}
assert!(matches!(
s.present_bgra(&pixels[..19], 2, 2, 12),
Err(SurfaceError::Size(_))
));
assert!(matches!(
s.present_bgra(&pixels, 4, 2, 12),
Err(SurfaceError::Size(_))
));
assert!(matches!(
s.present_bgra(&[], 0, 0, 0),
Err(SurfaceError::Size(_))
));
assert_eq!(s.stats().presented, 1);
s.present_bgrx(&pixels, 2, 2, 12).unwrap();
let frame = s.state().frame.clone();
match frame {
Some(Frame::Cpu { bgra, .. }) => {
assert_eq!(
&*bgra,
&[1, 1, 1, 255, 2, 2, 2, 255, 3, 3, 3, 255, 4, 4, 4, 255]
)
}
_ => panic!("a CPU frame"),
}
}
#[test]
fn watchers_hear_changes_once_and_stop_when_dropped() {
let s = surface("tests:watch");
let heard = Arc::new(Mutex::new(Vec::new()));
let sink = heard.clone();
let watch = s.on_change(move |_, e| lock(&sink).push(e));
let info = SurfaceInfo {
width: 640,
height: 360,
scale: 1.5,
visible: true,
..Default::default()
};
s.set_info(info);
s.set_info(info);
s.device_lost();
drop(watch);
s.set_info(SurfaceInfo::default());
assert_eq!(
*lock(&heard),
vec![SurfaceEvent::Changed(info), SurfaceEvent::DeviceLost]
);
assert_eq!(s.info(), SurfaceInfo::default());
}
#[test]
fn a_display_is_reported_when_it_moves_past_the_margin_and_kept_when_unknown() {
let s = surface("tests:display");
let heard = Arc::new(Mutex::new(Vec::new()));
let sink = heard.clone();
let _watch = s.on_change(move |_, e| lock(&sink).push(e));
let hdr = SurfaceDisplay {
known: true,
hdr: true,
headroom: 4.0,
potential_headroom: 4.0,
refresh_hz: Some(60.0),
..Default::default()
};
let with = |display| SurfaceInfo {
display,
..Default::default()
};
s.set_info(with(hdr));
s.set_info(with(SurfaceDisplay {
headroom: 4.02,
refresh_hz: Some(59.94),
..hdr
}));
s.set_info(with(SurfaceDisplay::default()));
let faster = SurfaceDisplay {
refresh_hz: Some(120.0),
..hdr
};
s.set_info(with(faster));
let unclocked = |d: SurfaceDisplay| {
assert!(d.refresh_period.is_some());
SurfaceDisplay {
refresh_period: None,
last_vblank: None,
..d
}
};
let heard: Vec<SurfaceEvent> = lock(&heard)
.iter()
.map(|e| match *e {
SurfaceEvent::DisplayChanged(d) => SurfaceEvent::DisplayChanged(unclocked(d)),
other => other,
})
.collect();
assert_eq!(
heard,
vec![
SurfaceEvent::DisplayChanged(hdr),
SurfaceEvent::DisplayChanged(faster)
]
);
assert_eq!(unclocked(s.info().display), faster);
}
#[test]
fn a_frame_of_the_other_format_is_refused_and_half_floats_are_mapped() {
let s = surface("tests:format");
assert_eq!(s.format(), SurfaceFormat::Bgra8);
assert_eq!(
s.present_rgba16f(&[0; 4], 1, 1, 4),
Err(SurfaceError::FormatMismatch {
surface: SurfaceFormat::Bgra8,
frame: SurfaceFormat::Rgba16Float
})
);
s.set_format(SurfaceFormat::Rgba16Float);
assert!(matches!(
s.present_bgra(&[0; 4], 1, 1, 4),
Err(SurfaceError::FormatMismatch { .. })
));
assert_eq!(s.stats().presented, 0);
let h = color::tests::f32_to_half;
s.present_rgba16f(&[h(2.0), h(0.5), h(0.0), h(1.0)], 1, 1, 4)
.unwrap();
let frame = s.state().frame.clone();
match frame {
Some(Frame::Cpu { bgra, .. }) => assert_eq!(&*bgra, &[0, 188, 255, 255]),
_ => panic!("a CPU frame"),
}
}
#[test]
fn each_present_returns_its_id_and_a_hidden_surface_drops_it_at_once() {
let s = surface("tests:frame-ids");
let heard = Arc::new(Mutex::new(Vec::new()));
let sink = heard.clone();
let watch = s.on_frame(move |e| lock(&sink).push(e));
let first = s.present_bgra(&[0; 4], 1, 1, 4).unwrap();
let second = s.present_bgrx(&[0; 4], 1, 1, 4).unwrap();
assert!(second > first);
feedback::deliver();
let hidden = |frame| FrameEvent::Dropped {
frame,
reason: FrameDropReason::Hidden,
};
assert_eq!(*lock(&heard), [hidden(first), hidden(second)]);
drop(watch);
s.present_bgra(&[0; 4], 1, 1, 4).unwrap();
feedback::deliver();
assert_eq!(lock(&heard).len(), 2, "nobody listens any more");
}
#[test]
fn clearing_withdraws_the_frame_once() {
let s = surface("tests:clear");
s.present_bgra(&[0; 4], 1, 1, 4).unwrap();
let seq = s.state().seq;
s.clear();
s.clear();
let st = s.state();
assert!(st.frame.is_none());
assert_eq!(st.lost, "cleared");
assert_eq!(st.seq, seq + 1);
}
}