Trait PaintScene 

pub trait PaintScene {
    // Required methods
    fn fill_rect(&mut self, origin: Point, size: Size, color: AlphaColor<Srgb>);
    fn draw_text(&mut self, origin: Point, text: &str);

    // Provided methods
    fn fill_rounded_rect(
        &mut self,
        _origin: Point,
        _size: Size,
        _radius: f64,
        _color: AlphaColor<Srgb>,
    ) { ... }
    fn fill_rounded_rect_radii(
        &mut self,
        origin: Point,
        size: Size,
        radii: CornerRadii,
        color: AlphaColor<Srgb>,
    ) { ... }
    fn stroke_line(
        &mut self,
        _p0: Point,
        _p1: Point,
        _width: f64,
        _color: AlphaColor<Srgb>,
    ) { ... }
    fn push_clip(&mut self, _origin: Point, _size: Size) { ... }
    fn push_clip_rounded(&mut self, _origin: Point, _size: Size, _radius: f64) { ... }
    fn push_clip_rounded_radii(
        &mut self,
        origin: Point,
        size: Size,
        radii: CornerRadii,
    ) { ... }
    fn pop_clip(&mut self) { ... }
    fn draw_glyph_run(&mut self, _run: GlyphRun) { ... }
    fn draw_image(&mut self, _data: &ImageData, _dest: Rect) { ... }
    fn draw_shader(&mut self, _program: &ShaderProgram, _dest: Rect, _time: f32) { ... }
    fn draw_scene_texture(&mut self, _id: u64, _dest: Rect) { ... }
    fn draw_shadow(
        &mut self,
        _origin: Point,
        _size: Size,
        _radius: f64,
        _std_dev: f64,
        _color: AlphaColor<Srgb>,
    ) { ... }
    fn fill_rect_brush(&mut self, origin: Point, size: Size, brush: &Brush) { ... }
    fn fill_rounded_rect_brush(
        &mut self,
        _origin: Point,
        _size: Size,
        _radius: f64,
        _brush: &Brush,
    ) { ... }
    fn push_layer(&mut self, _origin: Point, _size: Size, _alpha: f32) { ... }
    fn pop_layer(&mut self) { ... }
    fn clear_rect(&mut self, _origin: Point, _size: Size) { ... }
    fn fill_path(&mut self, _origin: Point, _path: &BezPath, _brush: &Brush) { ... }
    fn stroke_path(
        &mut self,
        _origin: Point,
        _path: &BezPath,
        _width: f64,
        _brush: &Brush,
    ) { ... }
    fn stroke_path_dashed(
        &mut self,
        origin: Point,
        path: &BezPath,
        width: f64,
        _dash: DashPattern,
        brush: &Brush,
    ) { ... }
    fn push_transform(&mut self, _transform: Affine) { ... }
    fn pop_transform(&mut self) { ... }
    fn push_snapshot(
        &mut self,
        _key: u64,
        origin: Point,
        size: Size,
        alpha: f32,
        scale: f64,
    ) { ... }
    fn pop_snapshot(&mut self) { ... }
}

The renderer-agnostic paint target a widget draws into.

This trait was introduced as a local stand-in for frust_scene::SceneBuilder while the scene crate was still a stub, and the two were later reconciled additively: rather than churn the Widget::paint signature (and every widget/test written against it), SceneBuilder now implements this trait, so widgets keep painting through &mut dyn PaintScene while the shell hands them a real SceneBuilder whose commands reach the GPU backend.

The original fill_rect/draw_text shape is retained for source compatibility with existing recorder-style test scenes; real text rendering goes through PaintScene::draw_glyph_run, which carries shaped glyphs from frust-text.

Required Methods

fn fill_rect(&mut self, origin: Point, size: Size, color: AlphaColor<Srgb>)

Emit a filled axis-aligned rectangle at origin with size, filled with the solid color.

fn draw_text(&mut self, origin: Point, text: &str)

Emit a run of unshaped text anchored at origin.

This records intent only — glyph shaping lives in frust-text. Real rendering uses PaintScene::draw_glyph_run; the SceneBuilder implementation treats this as a no-op.

Provided Methods

fn fill_rounded_rect( &mut self, _origin: Point, _size: Size, _radius: f64, _color: AlphaColor<Srgb>, )

Emit a filled axis-aligned rectangle with uniformly rounded corners.

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real rounded-rect command.

fn fill_rounded_rect_radii( &mut self, origin: Point, size: Size, radii: CornerRadii, color: AlphaColor<Srgb>, )

Emit a filled axis-aligned rectangle with per-corner radii — the shape a uniform PaintScene::fill_rounded_rect cannot express (a bottom-anchored sheet with only its top corners rounded, a segmented control’s end caps).

Defaulted to the uniform call with the largest corner rather than to a no-op: a recorder scene that only implements fill_rounded_rect still sees a rect painted here, in the spirit of PaintScene::fill_rect_brush’s “see something rather than nothing” fallback. The SceneBuilder implementation overrides it and records every corner faithfully.

fn stroke_line( &mut self, _p0: Point, _p1: Point, _width: f64, _color: AlphaColor<Srgb>, )

Stroke a straight line from p0 to p1 with the given width and solid color.

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real stroked-line command.

fn push_clip(&mut self, _origin: Point, _size: Size)

Push a rectangular clip (at origin/size) onto the backend clip stack; subsequent draws are clipped to it until the matching PaintScene::pop_clip.

Defaulted to a no-op so recorder scenes stay valid; the SceneBuilder implementation honors the clip by recording a push/pop command pair.

fn push_clip_rounded(&mut self, _origin: Point, _size: Size, _radius: f64)

Push a clip with uniformly rounded corners (at origin/size, corner radius) onto the backend clip stack; subsequent draws are clipped to the rounded shape until the matching PaintScene::pop_clip — the same pop PaintScene::push_clip uses, since there is one clip stack.

Lets paint code express a radiused mask over content a rectangular clip cannot shape — a rounded bitmap (avatar/thumbnail) being the motivating case. Defaulted to a no-op so recorder scenes stay valid; the SceneBuilder implementation honors it by recording a real frust_scene::Command::PushClipRounded/frust_scene::Command::PopClip pair.

fn push_clip_rounded_radii( &mut self, origin: Point, size: Size, radii: CornerRadii, )

Push a clip with per-corner radii onto the backend clip stack, popped by the same PaintScene::pop_clip as every other push.

Defaulted to the uniform PaintScene::push_clip_rounded with the largest corner rather than to a no-op — a defaulted push against an implemented pop would unbalance a recorder scene’s clip stack, so this one delegates for correctness, not just for visibility (see PaintScene::fill_rounded_rect_radii).

fn pop_clip(&mut self)

Pop the most recently pushed clip, rectangular or rounded. Defaulted to a no-op; see PaintScene::push_clip.

fn draw_glyph_run(&mut self, _run: GlyphRun)

Emit a run of already-shaped glyphs into the scene.

Defaulted to a no-op so pre-existing recorder scenes (which predate the text pipeline) stay valid without modification; the SceneBuilder implementation overrides it to record a real glyph-run command.

fn draw_image(&mut self, _data: &ImageData, _dest: Rect)

Draw an already-decoded image, scaled from its natural (data.widthxdata.height) size to fill the absolute dest rect.

A single additive method (added for frust-widgets::Image) on this otherwise layer-2 trait — authorized because Command::Image’s peniko::ImageData payload has to reach the scene through the same &mut dyn PaintScene seam every other paint call uses. Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real image command.

fn draw_shader(&mut self, _program: &ShaderProgram, _dest: Rect, _time: f32)

Draw a fragment-shader-filled rectangle, scaled to fill dest.

An additive method (added for the shader-showcase feature) on this otherwise layer-2 trait — authorized because the shader program and destination have to reach the scene through the same &mut dyn PaintScene seam every other paint call uses. program carries the WGSL source and process-unique id; time is seconds, app-supplied. Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real shader-quad command.

Renders on the engine renderer via the external-texture path (see crates/frust-engine/src/effects/shader_quad.rs); there is no CPU-oracle golden for a user-supplied fragment shader, so engine-side correctness is proven on a real device instead — see docs/LIMITATIONS.md’s engine-shader-quad-goldens-uncomparable.

Cache-once contract

program must be a retained, already-created ShaderProgram handle (see ShaderProgram::new’s own doc for the full contract) — never a fresh one minted inline in the call that invokes this method. This method is reached from Widget::paint, which re-runs every frame, so a ShaderProgram::new call written directly at a draw_shader call site there mints a new process-unique id (and therefore a new GPU pipeline cache miss) every frame; the same applies to a crate::component::Component’s build, which re-runs every rebuild. Build the ShaderProgram once — in a Component’s init, or other retained widget state — and clone the handle in; a View::build call, by contrast, runs exactly once per widget instance and is a correct place to construct one.

fn draw_scene_texture(&mut self, _id: u64, _dest: Rect)

Composite a bound scene texture (pre-rendered via ExternalPass) into the scene.

An additive method on this otherwise layer-2 trait — authorized because the texture id and destination have to reach the scene through the same &mut dyn PaintScene seam every other paint call uses. id is a SceneTextureId::get(); dest is in the scene’s coordinate space. Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real scene-texture command.

The engine renders nothing if the id is unbound and warns once per process. Output is always blended (never replaces). The binding is established outside this paint call by ExternalPass::record; a texture whose pass has not bound anything yet simply draws nothing that frame, never an error.

fn draw_shadow( &mut self, _origin: Point, _size: Size, _radius: f64, _std_dev: f64, _color: AlphaColor<Srgb>, )

Draw a gaussian-blurred rounded-rectangle elevation shadow (an approximation of a CSS box-shadow) at origin/size.

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real frust_scene::Command::BlurredRoundedRect.

fn fill_rect_brush(&mut self, origin: Point, size: Size, brush: &Brush)

Emit a filled axis-aligned rectangle at origin with size, filled with an arbitrary brush (solid color or gradient).

Default implementation delegates to PaintScene::fill_rect using the brush’s solid color where possible (a Brush::Solid unwraps directly; a gradient brush falls back to transparent black, since a pre-existing recorder scene has no gradient concept to approximate it with) — so callers that only override fill_rect still see something painted rather than nothing. The SceneBuilder implementation records the brush faithfully via frust_scene::Command::RoundedRect’s zero-radius sibling (FillRect).

fn fill_rounded_rect_brush( &mut self, _origin: Point, _size: Size, _radius: f64, _brush: &Brush, )

Emit a filled axis-aligned rectangle with uniformly rounded corners, filled with an arbitrary brush (solid color or gradient).

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real frust_scene::Command::RoundedRect carrying the brush.

fn push_layer(&mut self, _origin: Point, _size: Size, _alpha: f32)

Push a translucent layer (at origin/size) onto the backend layer stack; subsequent draws are composited at alpha until the matching PaintScene::pop_layer.

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real frust_scene::Command::PushLayer/frust_scene::Command::PopLayer pair, nesting correctly with PaintScene::push_clip/PaintScene::pop_clip.

fn pop_layer(&mut self)

Pop the most recently pushed layer. Defaulted to a no-op; see PaintScene::push_layer.

fn clear_rect(&mut self, _origin: Point, _size: Size)

Clear an axis-aligned rectangle (at origin/size) to full transparency (alpha 0), erasing everything already painted below it in this scene — a real destination-clearing composite, not merely skipping paint over the region.

The platform-view hole-punch (frust-widgets’ PlatformViewWidget) is the sole v1 consumer: on a translucent (Mode B) surface a slot punches its rect so an opaque app backdrop painted below it (the catalog’s AppBackground) doesn’t seal the hole the hosted native view shows through. Gated on PaintCtx::is_translucent by the widget — clearing on an opaque surface would erase real app content, and the clear is disregarded there anyway (see frust_scene::Command::ClearRect).

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real frust_scene::Command::ClearRect.

fn fill_path(&mut self, _origin: Point, _path: &BezPath, _brush: &Brush)

Fill an arbitrary vector path (e.g. an arc — see frust_scene::arc_path) at origin, using the nonzero winding rule and brush.

path is in the widget’s local coordinate space; origin translates it into the parent’s space, mirroring every other PaintScene method’s origin convention. Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation records a real frust_scene::Command::Path.

fn stroke_path( &mut self, _origin: Point, _path: &BezPath, _width: f64, _brush: &Brush, )

Stroke an arbitrary vector path (e.g. an arc) at origin with width and round caps/joins, using brush.

Defaulted to a no-op so pre-existing recorder scenes stay valid; see PaintScene::fill_path.

fn stroke_path_dashed( &mut self, origin: Point, path: &BezPath, width: f64, _dash: DashPattern, brush: &Brush, )

Stroke an arbitrary vector path at origin as a dashed line: the same stroke PaintScene::stroke_path paints, broken into dash’s on/off runs by the render crate at encode time.

Defaulted to the solid PaintScene::stroke_path rather than to a no-op — dashing is a visual refinement, so a scene that cannot express it still draws the path.

fn push_transform(&mut self, _transform: Affine)

Push an affine transform, composed with the current one, onto the backend transform stack; subsequent draws are transformed until the matching PaintScene::pop_transform.

Defaulted to a no-op so pre-existing recorder scenes stay valid; the SceneBuilder implementation composes and records it. Unlike the origin-offset convention every other method uses (a pure translation), this is the one seam that also carries scale/rotation — the shared-element (“hero”) morph is the first consumer, repainting a tagged subtree under a rect→rect transform (position and scale) so it morphs between two pages during a navigation transition.

fn pop_transform(&mut self)

Pop the most recently pushed transform, restoring the previous one. Defaulted to a no-op; see PaintScene::push_transform.

fn push_snapshot( &mut self, _key: u64, origin: Point, size: Size, alpha: f32, scale: f64, )

Push a snapshot bracket: the body is rasterizable once and cached by key across frames. The alpha and scale are presentation parameters applied to the whole cached body (alpha blending, uniform scale).

The default implementation emulates the presentation for recorders that don’t have a snapshot concept: it pushes a transform (scale about the rect’s center), then a layer (at the rect with the given alpha). A renderer may cache and apply both as a whole; a recorder sees the component pieces. The matching PaintScene::pop_snapshot pops both in the reverse order.

SceneBuilder overrides this to call the snapshot-aware builder methods directly, which record Command::PushSnapshot/PopSnapshot and no extra transform/layer commands.

fn pop_snapshot(&mut self)

Pop the most recently pushed snapshot bracket. Defaulted to the reverse of PaintScene::push_snapshot’s default: pop layer, then transform. Recorders that don’t override both may see unbalanced stacks if only one is overridden; the default pair is provided for source compatibility.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors

impl PaintScene for DiscardScene

impl PaintScene for SceneBuilder<'_>

Bridges the provisional PaintScene boundary onto the real frust_scene::SceneBuilder.

Widgets paint through &mut dyn PaintScene; the desktop shell hands them a SceneBuilder, so filled rectangles and shaped glyph runs land in the display list under the builder’s current transform. Unshaped PaintScene::draw_text is intentionally dropped here — text must be shaped (by frust-text) into glyph runs before it can be drawn.