pub struct SurfaceHandle { /* private fields */ }Expand description
A named surface. Cheap to clone, Send + Sync; present from any thread.
Implementations§
Source§impl SurfaceHandle
impl SurfaceHandle
pub fn name(&self) -> &str
pub fn info(&self) -> SurfaceInfo
Sourcepub fn on_frame(&self, f: impl FnMut(FrameEvent) + Send + 'static) -> FrameWatch
pub fn on_frame(&self, f: impl FnMut(FrameEvent) + Send + 'static) -> FrameWatch
Calls f with what became of each frame presented from now on: exactly one
FrameEvent per frame id, in frame order, until the returned guard drops. f runs on
Skathi’s vsync thread (on macOS a thread of its own), not the UI thread; keep it short.
pub fn stats(&self) -> SurfaceStats
Sourcepub fn on_change(
&self,
f: impl Fn(&SurfaceHandle, SurfaceEvent) + Send + Sync + 'static,
) -> SurfaceWatch
pub fn on_change( &self, f: impl Fn(&SurfaceHandle, SurfaceEvent) + Send + Sync + 'static, ) -> SurfaceWatch
Calls f on the UI thread when SurfaceInfo changes or the device is lost, until the
returned guard drops. Keep it short; it may present.
Sourcepub fn set_format(&self, format: SurfaceFormat)
pub fn set_format(&self, format: SurfaceFormat)
Sets the pixel format presents must have; SurfaceFormat::Bgra8 until set. The frame
already shown stays until the next present.
pub fn format(&self) -> SurfaceFormat
Sourcepub fn present_bgra(
&self,
pixels: &[u8],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError>
pub fn present_bgra( &self, pixels: &[u8], width: u32, height: u32, stride: usize, ) -> Result<u64, SurfaceError>
Presents a CPU frame: BGRA with straight alpha, stride bytes per row. Works on every
platform. Every present returns the frame’s id (Self::on_frame).
Sourcepub fn present_rgba16f(
&self,
pixels: &[u16],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError>
pub fn present_rgba16f( &self, pixels: &[u16], width: u32, height: u32, stride: usize, ) -> Result<u64, SurfaceError>
Presents a CPU frame to a SurfaceFormat::Rgba16Float surface: RGBA half floats (IEEE
binary16 bits), straight alpha, stride values per row. It is mapped to 8-bit sRGB here,
and kept as it is too while a window can draw HDR.
Sourcepub fn present_bgrx(
&self,
pixels: &[u8],
width: u32,
height: u32,
stride: usize,
) -> Result<u64, SurfaceError>
pub fn present_bgrx( &self, pixels: &[u8], width: u32, height: u32, stride: usize, ) -> Result<u64, SurfaceError>
Self::present_bgra for BGRX: the fourth byte is ignored and the frame is opaque.
Sourcepub fn clear(&self)
pub fn clear(&self)
Withdraws the frame: elements paint nothing and fire surfacelost with reason "cleared".
Sourcepub fn d3d11_device(&self) -> Result<D3D11Device, SurfaceError>
pub fn d3d11_device(&self) -> Result<D3D11Device, SurfaceError>
The renderer’s D3D11 device. Textures for Self::present_d3d11_texture are made on it.
Sourcepub unsafe fn present_d3d11_texture(
&self,
texture: *mut c_void,
) -> Result<u64, SurfaceError>
pub unsafe fn present_d3d11_texture( &self, texture: *mut c_void, ) -> Result<u64, SurfaceError>
Presents an ID3D11Texture2D made on Self::d3d11_device: B8G8R8A8_UNORM, _UNORM_SRGB
or _TYPELESS (R16G16B16A16_FLOAT on a SurfaceFormat::Rgba16Float surface), straight
alpha, mip 0, any sample count. The texture is copied on the GPU before this returns, so the
producer may render its next frame into it at once.
§Safety
texture is a live ID3D11Texture2D COM pointer, or null.
Sourcepub fn d3d12_device(&self) -> Result<D3D12Device, SurfaceError>
pub fn d3d12_device(&self) -> Result<D3D12Device, SurfaceError>
The renderer’s D3D12 device and direct queue, under the D3D12 renderer.
Sourcepub fn release_fence(&self) -> Result<D3D12Fence, SurfaceError>
pub fn release_fence(&self) -> Result<D3D12Fence, SurfaceError>
This surface’s fence, which Self::present_d3d12 signals once it has copied a frame out
of the producer’s resource.
Sourcepub unsafe fn present_d3d12(
&self,
resource: *mut c_void,
resource_state: i32,
ready: Option<(*mut c_void, u64)>,
) -> Result<FramePresent, SurfaceError>
pub unsafe fn present_d3d12( &self, resource: *mut c_void, resource_state: i32, ready: Option<(*mut c_void, u64)>, ) -> Result<FramePresent, SurfaceError>
Presents an ID3D12Resource made on Self::d3d12_device: a 2D B8G8R8A8_UNORM (or
_UNORM_SRGB, _TYPELESS; R16G16B16A16_FLOAT on a SurfaceFormat::Rgba16Float surface)
texture, single-sampled, straight alpha, in resource_state (a
D3D12_RESOURCE_STATES, left as it is). The copy runs on a queue of the surface’s own after
a GPU wait for ready (fence, value); without ready the resource must already be written.
Nothing blocks. Returns the frame’s id and the value Self::release_fence reaches once the
resource is free to reuse.
§Safety
resource is null or a live ID3D12Resource; ready’s fence is a live ID3D12Fence.
Presents a shared texture from another device or process (see SharedTexture); one
opened with a fence takes Self::present_shared_fenced instead.
Presents a shared texture opened SharedTexture::with_fence (Windows) or
SharedTexture::with_shared_event (macOS): the copy waits until the fence or event
reaches wait, then it is signalled to release (the producer may write the texture again
once it gets there).
Sourcepub fn metal_device(&self) -> Result<MetalDevice, SurfaceError>
pub fn metal_device(&self) -> Result<MetalDevice, SurfaceError>
The renderer’s MTLDevice, on macOS. Textures for Self::present_metal_texture are made
on it.
Sourcepub fn release_event(&self) -> Result<MetalEvent, SurfaceError>
pub fn release_event(&self) -> Result<MetalEvent, SurfaceError>
This surface’s MTLSharedEvent, which Self::present_metal_texture signals once it has
copied a frame out of the producer’s texture.
Sourcepub unsafe fn present_metal_texture(
&self,
texture: *mut c_void,
ready: Option<(*mut c_void, u64)>,
) -> Result<FramePresent, SurfaceError>
pub unsafe fn present_metal_texture( &self, texture: *mut c_void, ready: Option<(*mut c_void, u64)>, ) -> Result<FramePresent, SurfaceError>
Presents an id<MTLTexture> made on Self::metal_device: 2D, BGRA8Unorm (or
BGRA8Unorm_sRGB; RGBA16Float on a SurfaceFormat::Rgba16Float surface),
single-sampled, straight alpha. The copy runs on a queue of the
surface’s own after a GPU wait for ready (an id<MTLSharedEvent> and the value the
producer signals after its last write); without ready the texture must already be
written. Nothing blocks. Returns the frame’s id and the value Self::release_event
reaches once the texture is free to reuse.
§Safety
texture is null or a live id<MTLTexture>; ready’s event is a live
id<MTLSharedEvent>.
Sourcepub unsafe fn present_cv_pixel_buffer(
&self,
buffer: *mut c_void,
) -> Result<u64, SurfaceError>
pub unsafe fn present_cv_pixel_buffer( &self, buffer: *mut c_void, ) -> Result<u64, SurfaceError>
Presents a CVPixelBufferRef (VideoToolbox, AVFoundation, ScreenCaptureKit): BGRA
(kCVPixelFormatType_32BGRA) or 4:2:0 bi-planar (420v, 420f, converted with the
buffer’s YCbCr matrix, BT.709 when it names none); RGhA (kCVPixelFormatType_64RGBAHalf)
on a SurfaceFormat::Rgba16Float surface. The buffer is retained until the GPU copied it;
a BGRA or RGhA one with no IOSurface is copied on the CPU. It must be fully written.
§Safety
buffer is null or a live CVPixelBufferRef.
Trait Implementations§
Source§impl Clone for SurfaceHandle
impl Clone for SurfaceHandle
Source§fn clone(&self) -> SurfaceHandle
fn clone(&self) -> SurfaceHandle
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read moreAuto Trait Implementations§
impl Forget for SurfaceHandle
impl Freeze for SurfaceHandle
impl Move for SurfaceHandle
impl RefUnwindSafe for SurfaceHandle
impl Send for SurfaceHandle
impl Sync for SurfaceHandle
impl Unpin for SurfaceHandle
impl UnsafeUnpin for SurfaceHandle
impl UnwindSafe for SurfaceHandle
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can
then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.Source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be
further downcast into Rc<ConcreteType> where ConcreteType implements Trait.Source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.Source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.Source§impl<T> DowncastSync for T
impl<T> DowncastSync for T
impl<S, T> Duplex<S> for Twhere
T: FromSample<S> + ToSample<S>,
impl<T> ErasedDestructor for Twhere
T: 'static,
Source§impl<S> FromSample<S> for S
impl<S> FromSample<S> for S
fn from_sample_(s: S) -> S
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more