pub struct OverlaySurface { /* private fields */ }Expand description
A translucent swapchain above a hosted native view, drawing one command range of the frame — see the module docs for the host contract.
Implementations§
Source§impl OverlaySurface
impl OverlaySurface
Sourcepub unsafe fn new(
ctx: &mut RenderContext,
main: Option<&SurfaceRenderer>,
target: OverlayTarget,
width: u32,
height: u32,
) -> Result<Self, OverlayError>
pub unsafe fn new( ctx: &mut RenderContext, main: Option<&SurfaceRenderer>, target: OverlayTarget, width: u32, height: u32, ) -> Result<Self, OverlayError>
Creates the overlay’s swapchain on target, configured translucent at
width x height physical pixels, sharing ctx’s device and queue.
main is the main surface’s renderer when there is one; the overlay
then compiles its pipelines through the same persisted driver cache.
§Safety
The one unsafe crossing of this module (a sanctioned zone, like
frust_gpu::lifecycle::create_android_surface): target must name a
valid, live platform object — an acquired ANativeWindow* behind an
Android NDK handle, a valid display/window pair, or a live
CAMetalLayer* — that outlives the returned OverlaySurface and
every frame it acquires. Drop the OverlaySurface before releasing
the window or tearing down the layer.
§Errors
OverlayError::NoDevice before the main surface created the device;
OverlayError::Surface when the platform object yields no surface or
the swapchain cannot be configured; OverlayError::UnsupportedSurface
when the shared adapter cannot present to it;
OverlayError::NoTranslucentMode/OverlayError::StraightAlpha for
an alpha mode the overlay cannot use; OverlayError::Engine when the
overlay’s renderer cannot be built.
Sourcepub fn resize(&mut self, width: u32, height: u32)
pub fn resize(&mut self, width: u32, height: u32)
Resizes the swapchain (physical pixels); a zero extent is ignored, and an un-presented frame of the old size is dropped.
Sourcepub fn record(
&mut self,
encoder: &mut CommandEncoder,
scene: &Scene,
range: Range<usize>,
) -> Result<OverlayFrame, OverlayError>
pub fn record( &mut self, encoder: &mut CommandEncoder, scene: &Scene, range: Range<usize>, ) -> Result<OverlayFrame, OverlayError>
Acquires the overlay’s next frame and records the commands of scene
in range into it over a transparent clear — into the caller’s
encoder, so the overlay’s passes land in the same command buffer as
the main frame’s and one queue submit carries both (the segmented
frame, SurfaceRenderer::submit_segmented).
Nothing is submitted and nothing is presentable yet: the acquired
frame waits, recorded, until Self::end_frame is told whether the
encoder was submitted — then (and only then) it becomes the frame
Self::present/Self::take_deferred_present hand out. A frame
still waiting from an earlier call (presentable or merely recorded) is
dropped un-presented first (latest wins).
OverlayFrame::Reconfigured/OverlayFrame::Skipped recorded
nothing and leave nothing for Self::end_frame to close.
§Errors
OverlayError::Engine when the engine refuses the frame: the
acquired frame is dropped and the renderer’s frame already closed, so
there is nothing for Self::end_frame to do (the previous overlay
frame stays on screen). Shader-quad pre-passes the overlay recorded
ahead of the refusal stay in encoder, harmlessly — their targets are
the overlay’s own.
Sourcepub fn end_frame(&mut self, submitted: bool) -> bool
pub fn end_frame(&mut self, submitted: bool) -> bool
Closes the frame Self::record recorded, once the encoder it was
recorded into has been submitted (submitted) or dropped: the
renderer’s end-of-frame maintenance, and — when submitted — the
recorded frame becomes the one Self::present presents. Answers
whether a frame is now waiting to be presented; a no-op answering
false when nothing was recorded.
Sourcepub fn render(
&mut self,
scene: &Scene,
range: Range<usize>,
) -> Result<OverlayFrame, OverlayError>
pub fn render( &mut self, scene: &Scene, range: Range<usize>, ) -> Result<OverlayFrame, OverlayError>
The spike’s path only — Self::record into an encoder of the
overlay’s own, submitted on its own: a second queue submit per frame,
which the segmented frame exists to remove
(SurfaceRenderer::submit_segmented records every overlay into the
main frame’s encoder and submits once). Kept for the single-cut spike
host (FRUST_OVERLAY_SPIKE), which renders its overlay ahead of the
main frame.
Leaves the frame un-presented until Self::present (or
Self::take_deferred_present), so the host can land it right beside
the main frame’s present. A frame still waiting from the last call is
dropped un-presented first (latest wins).
§Errors
OverlayError::Engine when the engine refuses the frame (nothing is
presented; the previous overlay frame stays on screen).
Sourcepub fn present(&mut self) -> bool
pub fn present(&mut self) -> bool
Presents the frame Self::render (or a submitted Self::record)
left waiting, on the calling thread; false when there was none.
Sourcepub fn take_deferred_present(&mut self) -> Option<DeferredPresent>
pub fn take_deferred_present(&mut self) -> Option<DeferredPresent>
Hands the waiting frame out as a DeferredPresent, for a host that
presents the main frame and the overlay inside one platform
transaction (iOS presentsWithTransaction); None when there was
none.
Sourcepub fn renderer(&self) -> &OverlayRenderer
pub fn renderer(&self) -> &OverlayRenderer
The overlay’s renderer — its cut report, refusal count and GPU time.