Skip to main content

SurfaceHandle

Struct SurfaceHandle 

Source
pub struct SurfaceHandle { /* private fields */ }
Expand description

A named surface. Cheap to clone, Send + Sync; present from any thread.

Implementations§

Source§

impl SurfaceHandle

Source

pub fn name(&self) -> &str

Source

pub fn info(&self) -> SurfaceInfo

Source

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.

Source

pub fn stats(&self) -> SurfaceStats

Source

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.

Source

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.

Source

pub fn format(&self) -> SurfaceFormat

Source

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).

Source

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.

Source

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.

Source

pub fn clear(&self)

Withdraws the frame: elements paint nothing and fire surfacelost with reason "cleared".

Source

pub fn d3d11_device(&self) -> Result<D3D11Device, SurfaceError>

The renderer’s D3D11 device. Textures for Self::present_d3d11_texture are made on it.

Source

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.

Source

pub fn d3d12_device(&self) -> Result<D3D12Device, SurfaceError>

The renderer’s D3D12 device and direct queue, under the D3D12 renderer.

Source

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.

Source

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.

Source

pub fn present_shared( &self, texture: &SharedTexture, ) -> Result<u64, SurfaceError>

Presents a shared texture from another device or process (see SharedTexture); one opened with a fence takes Self::present_shared_fenced instead.

Source

pub fn present_shared_fenced( &self, texture: &SharedTexture, wait: u64, release: u64, ) -> Result<u64, SurfaceError>

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).

Source

pub fn metal_device(&self) -> Result<MetalDevice, SurfaceError>

The renderer’s MTLDevice, on macOS. Textures for Self::present_metal_texture are made on it.

Source

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.

Source

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>.

Source

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

Source§

fn clone(&self) -> SurfaceHandle

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for SurfaceHandle

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert 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>

Convert 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)

Convert &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)

Convert &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> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<S> FromSample<S> for S

Source§

fn from_sample_(s: S) -> S

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

Source§

fn into_sample(self) -> T

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, S> SimdFrom<T, S> for T
where S: Simd,

Source§

fn simd_from(_simd: S, value: T) -> T

Source§

impl<F, T, S> SimdInto<T, S> for F
where T: SimdFrom<F, S>, S: Simd,

Source§

fn simd_into(self, simd: S) -> T

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

Source§

fn to_sample_(self) -> U

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> Upcast<T> for T

Source§

fn upcast(&self) -> Option<&T>

Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more