Struct Scene 

pub struct Scene { /* private fields */ }

A 2D scene: the declarative description of what to draw.

Implementations

impl Scene

pub fn new() -> Scene

Creates an empty scene, with a neutral clip.

pub fn clear(&mut self)

Empties the scene so it can be reused on the next frame.

pub fn set_clip(&mut self, clip: Rect)

Sets the clip rectangle applied to subsequent primitives.

pub fn current_clip(&self) -> Rect

The current clip rectangle, for intersecting with local bounds.

pub fn set_owner(&mut self, owner: u64)

Sets the emitting widget’s identity for subsequent primitives.

pub fn current_owner(&self) -> u64

The emitting widget’s identity, as the next primitive will carry it.

pub fn set_bounds(&mut self, bounds: Rect)

Declares the box the widget about to paint was laid out in. Text primitives record it, which is how the renderer knows what a line of text covers — a Primitive::Text otherwise says only where it begins. Set by the widget walk before every paint; a scene built by hand leaves it UNBOUNDED, and the renderer then keeps that text above everything, as it always did.

pub fn current_bounds(&self) -> Rect

The box currently being painted into.

pub fn push_primitive(&mut self, primitive: Primitive)

Appends an already-formed primitive, with its clip and owner already baked in. This replays a cached subtree (a repaint boundary) as-is, without repainting it.

pub fn split_off(&mut self, start: usize) -> Vec<Primitive>

Removes and returns the primitives from index start onwards, preserving order. This wraps an already-painted subtree in a layer (Primitive::Layer): paint the subtree, then move its range of primitives into a layer, giving it group opacity.

pub fn push_faded(&mut self, primitive: &Primitive, opacity: f32)

Replays an existing primitive at reduced opacity — an exit fade.

pub fn fill_rect(&mut self, rect: Rect, color: Color)

Adds a solid rectangle, with square corners and no border.

pub fn draw_shape(&mut self, rect: Rect, shape: ShapeBorder, fill: Color)

Adds a rectangle with rounded corners (uniform through f32, or per corner through BorderRadius) and/or a border. Fills a shape, and draws its edge if it has one.

Three of the four shapes are rounded rectangles once the box is known, so they go down the same path as Scene::draw_rect and cost nothing extra; a bevel becomes a filled path plus a stroked one. A caller who does this by hand at each site gets the fast path wrong somewhere, which is the whole reason this is one function.

pub fn draw_rect( &mut self, rect: Rect, color: Color, radius: impl Into<BorderRadius>, border_width: f32, border_color: Color, )

Adds a flat-coloured rectangle, with an optional border.

pub fn shaded_rect( &mut self, rect: Rect, gradient: Gradient, opacity: f32, radius: impl Into<BorderRadius>, border_width: f32, border_color: Color, )

A rectangle filled with a gradient (milestone 644): any of the reference’s three, relative to rect, with corners and a border as Scene::draw_rect has them.

pub fn gradient_rect( &mut self, rect: Rect, color: Color, color2: Color, dir: [f32; 2], radius: impl Into<BorderRadius>, border_width: f32, border_color: Color, )

Adds a linear-gradient rectangle (color → color2 along dir).

pub fn shadow( &mut self, rect: Rect, color: Color, radius: impl Into<BorderRadius>, blur: f32, )

Adds a soft shadow — a rounded rectangle with a blurred edge, no border.

pub fn styled_shadow( &mut self, rect: Rect, color: Color, radius: impl Into<BorderRadius>, blur: f32, blur_style: BlurStyle, )

Adds a soft shadow whose blur keeps one side of the shape’s edge, or both (BlurStyle). As Self::shadow, rect already reaches blur beyond the shape, which runs blur inside it.

pub fn fill_path(&mut self, path: &Path, color: Color)

Fills a vector path with a flat colour, using the non-zero rule.

pub fn fill_path_gradient( &mut self, path: &Path, from_color: Color, to_color: Color, from: Point, to: Point, )

Fills a path with a linear gradient: from_color at from, to_color at to, clamped outside that span.

The two points are in the path’s own space rather than relative to its box, so the fade can be aimed at the thing it is about — the edge a glow springs from, the depth of a band — which is what an ellipse cap needs, its bounding box being mostly off screen.

pub fn fill_path_radial( &mut self, path: &Path, from_color: Color, to_color: Color, center: Point, radii: Size, inner: f32, )

Fills a path with a radial gradient: from_color on the ellipse of radii inner × radii about center, to_color on the ellipse of radii radii.

This is what a shape with a curved boundary needs in order to fade to nothing all the way round: a straight fade reaches zero on a line, so it still leaves an edge wherever the shape turns away from that line.

pub fn fill_path_ramp(&mut self, path: &Path, ramp: GradientRamp, opacity: f32)

Fills a path with a GradientRamp — any number of stops, along a line or between two circles, turned or skewed by its own transform.

pub fn stroke_path(&mut self, path: &Path, color: Color, width: f32)

Strokes a path’s outline (colour plus width), with no fill.

pub fn paint_path( &mut self, path: &Path, fill: Option<Color>, stroke: Option<Stroke>, )

Adds a path filled and/or stroked — both passes in one primitive.

pub fn draw_image( &mut self, image: &Arc<ImageData>, rect: Rect, uv: Rect, tint: Color, )

Draws an image into rect, sampling the uv sub-region (in 0..1) and tinting it by tint (white = unchanged). Low level: see Scene::image for automatic fitting through crate::BoxFit.

pub fn draw_image_strict( &mut self, image: &Arc<ImageData>, rect: Rect, uv: Rect, tint: Color, )

Scene::draw_image, sampled strictly inside uv: no filtered sample reaches the texels around it. For one part of a picture stretched apart from the rest, as a centre slice’s are.

pub fn draw_image_mapped( &mut self, image: &Arc<ImageData>, to_screen: Affine, tint: Color, )

Draws a whole image through an affine map from its pixels — (0, 0) to (width, height) — to the screen, tinted by tint: a bitmap inside vector artwork, which may be turned, slanted or mirrored with it (milestone 694).

A map that only scales and moves is one image primitive. Any other draws the image upright at its size on screen, at the origin, in a transformed layer that turns it into place, so it is sampled once at the resolution it is shown at. Like any transformed layer, an image larger than the window once on screen loses what lies past the window’s size.

pub fn image(&mut self, image: &Arc<ImageData>, rect: Rect, fit: BoxFit)

Draws an image fitted into rect per fit (aspect preserved, letterboxed or cropped), untinted.

pub fn layer(&mut self, opacity: f32, build: impl FnOnce(&mut Scene))

Composes a layer: build fills a subgroup of primitives, which is then composited as one at opacity (0..1). Unlike an opacity applied primitive by primitive, the group alpha stays correct where the inner primitives overlap. The layer inherits the current clip and owner.

pub fn transformed( &mut self, transform: LayerTransform, build: impl FnOnce(&mut Scene), )

Composes a transformed layer: build fills a subgroup of primitives, which is rendered flat and then composited through transform.

The transform belongs to the group and not to the primitives inside it, which is the whole point: a rotation applies to a rectangle, a line of text and an image at once, and none of them has to know how to rotate itself.

Paint the group where it fits, not where it lands. The renderer draws the group flat into a window-sized texture and composites that through the transform, so anything laid out flat beyond the window is gone before the transform could have brought it back inside. A group that ends up near an edge should be built at the origin and carried there by the transform.

pub fn masked(&mut self, mask: ShaderMask, build: impl FnOnce(&mut Scene))

Adds a masked group: everything build emits is composited as one, with mask multiplied into it, so the shader’s alpha becomes the group’s transparency.

A fade has to be a group. Applied primitive by primitive it would fade each of them against the background separately, and where two of them overlap the result is neither one nor the other.

pub fn blended(&mut self, mode: BlendMode, build: impl FnOnce(&mut Scene))

Adds a blended group (milestone 646): everything build emits is composited as one, meeting what is already painted underneath by mode rather than being painted over it. The group’s clip is where it applies; outside it, what was there stays.

pub fn blended_in( &mut self, mode: BlendMode, shape: ClipShape, build: impl FnOnce(&mut Scene), )

Scene::blended in a shape inscribed in the current clip: rounded corners or an ellipse, or a path in absolute coordinates.

pub fn rich_text(&mut self, position: Point, runs: Vec<TextRun>)

Adds rich text: resolved runs, mixing styles and colours, laid out as one piece, anchored by its top-left corner.

pub fn rich_text_wrapped( &mut self, position: Point, runs: Vec<TextRun>, max_width: f32, )

Adds a rich paragraph: the runs wrap beyond max_width, and the render’s wrapping matches the layout’s.

pub fn text( &mut self, position: Point, text: impl Into<String>, style: &ResolvedTextStyle, color: Color, )

Adds a line of text, anchored by its top-left corner — size, weight and italics from the ResolvedTextStyle.

It takes a resolved style and not a TextStyle because this is the bottom of the chain: a shaper needs a number and there is nobody left below to ask one of. color is settled the same way, by the caller, usually against the theme — which is the one answer this crate cannot work out for itself.

There is deliberately no form of this that takes a bare f32 size. A number arriving here has been through TextStyle::resolved, which is the single place the reader’s font size is applied; a second door taking a raw constant is a door onto text that ignores the reader, and forty-seven call sites walked through it (milestone 406).

pub fn text_wrapped( &mut self, position: Point, text: impl Into<String>, style: &ResolvedTextStyle, color: Color, max_width: f32, )

Adds a paragraph: styled text that wraps beyond max_width, the render’s wrapping matching the layout’s.

pub fn text_block( &mut self, position: Point, text: impl Into<String>, style: &ResolvedTextStyle, color: Color, block: TextBlock, )

Adds a block of styled text: a box of a known width, which the text may be wrapped in and is aligned inside.

The three settings travel together because they are one decision. A width with no wrapping is a line that knows where its box ends and runs past it anyway — which is what a clipped or ellipsised line is — and an alignment with no width has nothing to align against.

pub fn rich_text_block( &mut self, position: Point, runs: Vec<TextRun>, block: TextBlock, )

Adds a block of rich text: resolved runs in a box of a known width, which they may be wrapped in and are aligned inside. The rich counterpart of Scene::text_block.

pub fn len(&self) -> usize

The number of primitives in the scene.

pub fn is_empty(&self) -> bool

true when the scene holds no primitives at all.

pub fn primitives(&self) -> &[Primitive]

The primitives, in insertion order, which is drawing order.

pub fn scaled(&self, factor: f32) -> Scene

A copy of the scene with all geometry scaled by factor — the logical → physical conversion for HiDPI rendering.

Trait Implementations

impl Clone for Scene

fn clone(&self) -> Scene

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scene

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

Formats the value using the given formatter.

impl Default for Scene

fn default() -> Scene

Returns the “default value” for a type.