Skip to main content

FramePipeline

gpui

Trait FramePipeline 

Source 
pub trait FramePipeline: 'static {
    // Provided methods
    fn should_render(
        &mut self,
        is_dirty: bool,
        _metrics: &WindowMetrics,
    ) -> bool { ... }
    fn begin_frame(&mut self, window: &mut Window<'_>, cx: &mut App) { ... }
    fn evaluate_roots(
        &mut self,
        window: &mut Window<'_>,
        cx: &mut App,
    ) -> PreparedRoots { ... }
    fn layout_roots(
        &mut self,
        window: &mut Window<'_>,
        roots: &mut PreparedRoots,
        cx: &mut App,
    ) { ... }
    fn paint_roots(
        &mut self,
        window: &mut Window<'_>,
        roots: PreparedRoots,
        cx: &mut App,
    ) { ... }
    fn draw_roots(&mut self, window: &mut Window<'_>, cx: &mut App) { ... }
    fn finish_frame(&mut self, window: &mut Window<'_>, cx: &mut App) { ... }
    fn complete_frame(
        &mut self,
        window: &mut Window<'_>,
        cx: &mut App,
    ) -> Option<FocusId> { ... }
    fn end_frame(
        &mut self,
        window: &mut Window<'_>,
        cx: &mut App,
        focus_before_listeners: Option<FocusId>,
    ) { ... }
    fn draw(
        &mut self,
        window: &mut Window<'_>,
        cx: &mut App,
    ) -> ArenaClearNeeded { ... }
}
Expand description

The phases of drawing one frame, in the order FramePipeline::draw runs them.

A frame starts with should_render, which decides whether the frame’s work happens at all. The rest are the passes it is made of, and each one falls back to the Window method implementing it, so a pipeline overrides only what it wants to change and a pass that is not overridden behaves exactly as StandardImmediatePipeline does.

See the frame pipeline guide for what each pass is for, how far a pipeline outside this crate can go, and how to install one.

Provided Methods§

Source

fn should_render(&mut self, is_dirty: bool, _metrics: &WindowMetrics) -> bool

Whether the frame the application is about to draw should be drawn.

Defaults to drawing it. Answering false leaves the window exactly as it was — no roots gathered, nothing laid out, nothing painted — and leaves the work the frame would have done pending, so the next frame draws it. This is where a pipeline paces frames: dropping the ones the display cannot keep up with, or coalescing several invalidations into one frame.

A window that stays dirty keeps asking, so answer false to defer a frame rather than to drop it forever, and pace using the metrics handed in rather than ignoring them.

is_dirty says whether something changed since the last frame, as opposed to the platform asking for one on its own. Two frames are drawn whatever this returns: a window’s first frame, and one forced after the GPU device was lost, whose cached content may not be replayable.

Source

fn begin_frame(&mut self, window: &mut Window<'_>, cx: &mut App)

Opens the frame: samples the platform window, resets the scratch state the frame rebuilds, and takes ownership of the invalidations this frame owes.

Source

fn evaluate_roots( &mut self, window: &mut Window<'_>, cx: &mut App, ) -> PreparedRoots

Gathers the roots this frame will draw.

The roots are not laid out yet, so this is where a pipeline can decide what the frame is made of before any of it is measured.

Source

fn layout_roots( &mut self, window: &mut Window<'_>, roots: &mut PreparedRoots, cx: &mut App, )

Lays out and prepaints roots, then hit tests the pointer against what they registered.

Returning from here means the frame’s geometry is settled and its hitboxes are registered, so a pipeline can inspect or replace the roots before they paint.

Source

fn paint_roots( &mut self, window: &mut Window<'_>, roots: PreparedRoots, cx: &mut App, )

Paints roots, in the order they stack.

Source

fn draw_roots(&mut self, window: &mut Window<'_>, cx: &mut App)

Lays out and paints the window’s roots: the window’s own view tree, plus a prompt, drag image or tooltip if the frame has one.

Runs this pipeline’s evaluate, layout and paint passes in sequence, so overriding one of those is enough to intervene between them. Window::draw_roots is the same three passes with no pipeline in the way.

Source

fn finish_frame(&mut self, window: &mut Window<'_>, cx: &mut App)

Closes the painted frame: records the views it touched and hands the platform the input handler the frame asked for.

Source

fn complete_frame( &mut self, window: &mut Window<'_>, cx: &mut App, ) -> Option<FocusId>

Retires the painted frame, swaps it in, and dispatches the focus changes the swap produced.

Returns the focus that was current before the listeners ran: they may move it, and the caller has to tell those moves apart from its own.

Source

fn end_frame( &mut self, window: &mut Window<'_>, cx: &mut App, focus_before_listeners: Option<FocusId>, )

Closes the frame out and marks it ready to present.

Source

fn draw(&mut self, window: &mut Window<'_>, cx: &mut App) -> ArenaClearNeeded

Draws one frame by running the phases above in order.

Override this to drive the phases differently, or override a single phase to change what happens inside it.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§