Struct Scene 

pub struct Scene {
    pub shadows: Vec<Shadow>,
    pub quads: Vec<Quad>,
    pub paths: Vec<Path<ScaledPixels>>,
    pub underlines: Vec<Underline>,
    pub monochrome_sprites: Vec<MonochromeSprite>,
    pub subpixel_sprites: Vec<SubpixelSprite>,
    pub polychrome_sprites: Vec<PolychromeSprite>,
    pub surfaces: Vec<PaintSurface>,
    pub backdrop_filters: Vec<BackdropFilter>,
    pub filter_boundaries: Vec<FilterBoundary>,
    /* private fields */
}

The primitives painted for one frame, ready for a renderer to consume.

crate::Window fills a scene while it paints. You rarely create one yourself, but it is public so tests and custom renderers can inspect the result. Add primitives with Scene::insert_primitive in paint order, then call Scene::finish before reading the renderer-facing vectors: finish sorts them by draw order and compiles the render plan.

Examples

let bounds = Bounds {
    origin: point(ScaledPixels(0.), ScaledPixels(0.)),
    size: size(ScaledPixels(100.), ScaledPixels(40.)),
};
let mut scene = Scene::default();
scene.insert_primitive(Quad {
    bounds,
    content_mask: ContentMask { bounds, ..Default::default() },
    background: rgb(0x2563eb).into(),
    ..Default::default()
});
scene.finish();
assert_eq!(scene.quads.len(), 1);

Fields

shadows: Vec<Shadow>

Shadow primitives. Sorted by draw order after Scene::finish.

quads: Vec<Quad>

Quad primitives. Sorted by draw order after Scene::finish.

paths: Vec<Path<ScaledPixels>>

Path primitives. A PathId is the index the path had when it was inserted, which Scene::finish can change by sorting this vector.

underlines: Vec<Underline>

Underline primitives. Sorted by draw order after Scene::finish.

monochrome_sprites: Vec<MonochromeSprite>

Single-color sprites, such as icons and glyph masks.

subpixel_sprites: Vec<SubpixelSprite>

Glyphs drawn with subpixel anti-aliasing.

polychrome_sprites: Vec<PolychromeSprite>

Full-color sprites, such as images and color emoji.

surfaces: Vec<PaintSurface>

crate::PaintSurface primitives, such as video frames.

backdrop_filters: Vec<BackdropFilter>

crate::BackdropFilter primitives.

filter_boundaries: Vec<FilterBoundary>

Start and end markers of content-filter groups. They always come in matched pairs.

Implementations

impl Scene

pub fn clear(&mut self)

Removes every primitive and resets the scene so that it can be painted again.

The vectors keep their capacity, so a scene that is cleared and refilled each frame reuses its allocations.

pub fn len(&self) -> usize

Returns the number of paint operations in this scene, including layer boundaries.

pub fn push_layer(&mut self, bounds: Bounds<ScaledPixels>)

Starts a layer. Every primitive inserted until the matching Scene::pop_layer receives the layer’s draw order, so the layer’s contents are not interleaved with surrounding primitives. Within a layer, the renderer still groups work by primitive type.

crate::Window::paint_layer calls this for you.

pub fn pop_layer(&mut self)

Ends the layer started by the most recent Scene::push_layer. The scene does not check that the calls are balanced, so callers must keep the nesting correct.

pub fn raise_order_floor(&mut self)

Makes every primitive inserted after this call draw above every primitive inserted before it.

Use this to put overlays, such as tooltips and drag images, above the rest of the scene. The renderer draws primitives in ascending draw order.

pub fn insert_primitive(&mut self, primitive: impl Into<Primitive>)

Adds a primitive in paint order and assigns it a draw order.

A primitive whose bounds are empty after clipping to its content mask is dropped. A transformed sprite is clipped by its transformed bounds. Filter boundaries are never dropped. Inside a layer started with Scene::push_layer, the primitive takes the layer’s draw order. Otherwise it takes one more than the highest draw order of any primitive that it overlaps, so it draws above them. In either case the order is at least the floor set by Scene::raise_order_floor.

Examples

let mut scene = Scene::default();
let bounds = Bounds {
    origin: point(ScaledPixels(0.), ScaledPixels(0.)),
    size: size(ScaledPixels(100.), ScaledPixels(40.)),
};
// The default content mask is empty, so this quad is clipped away.
scene.insert_primitive(Quad { bounds, ..Default::default() });
scene.finish();
assert!(scene.quads.is_empty());

pub fn replay(&mut self, range: Range<usize>, prev_scene: &Scene)

Inserts the paint operations in range from prev_scene into this scene, as if they had been painted again.

Use this to reuse the output of an earlier frame for a view that hasn’t changed. Draw orders are assigned again in this scene.

Panics

Panics if range extends past the end of prev_scene’s paint operations.

pub fn finish(&mut self)

Sorts the primitives by draw order and compiles the renderer’s plan.

Call this after painting and before rendering. Adding a primitive after finish marks the scene unfinished again; call finish again before reading Scene::batches or Scene::render_commands.

pub fn batches(&self) -> impl Iterator<Item = PrimitiveBatch> + '_

Returns the draw batches of a finished scene, in drawing order.

Each batch is a run of one primitive type that the renderer draws in one call. PrimitiveBatch::FilterBoundary entries mark the start and end of content-filter groups. Use Scene::render_commands when you also need the offscreen target for each group.

Panics

In debug builds, panics if the scene hasn’t been finished.

Examples

let bounds = Bounds {
    origin: point(ScaledPixels(0.), ScaledPixels(0.)),
    size: size(ScaledPixels(100.), ScaledPixels(40.)),
};
let mut scene = Scene::default();
scene.insert_primitive(Quad {
    bounds,
    content_mask: ContentMask { bounds, ..Default::default() },
    ..Default::default()
});
scene.finish();
assert_eq!(
    scene.batches().collect::<Vec<_>>(),
    vec![PrimitiveBatch::Quads { range: 0..1, smoothed: false }],
);

pub fn render_commands(&self) -> &[RenderCommand]

Returns the render commands of a finished scene, in drawing order.

Commands are primitive batches, plus begin and end markers for content-filter groups that say whether each group draws into an isolated target. Renderers use these instead of Scene::batches when they manage offscreen targets.

Panics

In debug builds, panics if the scene hasn’t been finished.

pub fn render_plan(&self) -> &ScenePlan

Returns the compiled ScenePlan of a finished scene.

Panics

In debug builds, panics if the scene hasn’t been finished, or if its primitive storage changed after Scene::finish.

pub fn surface_opacities(&self) -> &[f32]

Returns the opacity of each entry in Scene::surfaces, in the same order.

Surfaces are fully opaque here; group opacity is applied when compositing.

pub fn requires_offscreen_rendering(&self) -> bool

Returns true if rendering this scene needs an offscreen target. That is the case when it has backdrop filters, content filters, or grouped opacity.

Panics

In debug builds, panics if the scene hasn’t been finished.

Trait Implementations

impl Default for Scene

fn default() -> Self

Returns the “default value” for a type.