Struct PaintingContext 

pub struct PaintingContext {
    pub estimated_bounds: Rect,
    /* private fields */
}

A place to paint.

Rather than holding a canvas directly, crate::RenderObjects paint using a painting context. The painting context has a Canvas, which receives the individual draw operations, and also has functions for painting child render objects.

When painting a child render object, the canvas held by the painting context can change because the draw operations issued before and after painting the child might be recorded in separate compositing layers. For this reason, do not hold a reference to the canvas across operations that might paint child render objects.

New PaintingContext objects are created automatically when using PaintingContext::repaint_composited_child and push_layer.

Fields

estimated_bounds: Rect

An estimate of the bounds within which the painting context’s canvas will record painting commands. This can be useful for debugging.

The canvas will allow painting outside these bounds.

The estimated_bounds rectangle is in the canvas coordinate system.

Implementations

impl PaintingContext

pub fn new( container_layer: AnyContainerLayer, estimated_bounds: Rect, ) -> PaintingContext

Creates a painting context.

Typically only called by repaint_composited_child and push_layer.

pub fn repaint_composited_child(app: &mut App, child: AnyRenderObject)

Repaint the given render object.

The render object must be attached to a crate::PipelineOwner, must have a composited layer, and must be in need of painting. The render object’s layer, if any, is re-used, along with any layers in the subtree that don’t need to be repainted.

pub fn update_layer_properties(app: &mut App, child: AnyRenderObject)

Update the composited layer of child without repainting its children.

The render object must be attached to a crate::PipelineOwner, must have a composited layer, and must be in need of a composited layer update but not in need of painting. The render object’s layer is re-used, and none of its children are repaint or their layers updated.

pub fn paint_child( &mut self, app: &mut App, child: AnyRenderObject, offset: Offset, )

Paint a child crate::RenderObject.

If the child has its own composited layer, the child will be composited into the layer subtree associated with this painting context. Otherwise, the child will be painted into the current PictureLayer for this context.

pub fn add_composition_callback( &self, app: &mut App, callback: CompositionCallback, ) -> Box<dyn FnOnce(&mut App)>

Adds a CompositionCallback for the current AnyContainerLayer used by this context.

pub fn stop_recording_if_needed(&mut self, app: &mut App)

Stop recording to a canvas if recording has started.

Do not call this function directly: functions in this class will call this method as needed. This function is called internally to ensure that recording is stopped before adding layers or finalizing the results of a paint.

Creates and appends the PictureLayer here rather than in start_recording: ClipContext::canvas has no App. See PORTING.md.

pub fn set_is_complex_hint(&mut self)

Hints that the painting in the current layer is complex and would benefit from caching.

pub fn set_will_change_hint(&mut self)

Hints that the painting in the current layer is likely to change next frame.

pub fn add_layer(&mut self, app: &mut App, layer: AnyLayer)

Adds a composited leaf layer to the recording.

After calling this function, the canvas property will change to refer to a new Canvas that draws on top of the given layer.

pub fn push_layer( &mut self, app: &mut App, child_layer: AnyContainerLayer, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), offset: Offset, child_paint_bounds: Option<Rect>, )

Appends the given layer to the recording, and calls the painter callback with that layer, providing the child_paint_bounds as the estimated paint bounds of the child. The child_paint_bounds can be used for debugging but have no effect on painting.

The given layer must be an unattached orphan. (Providing a newly created object, rather than reusing an existing layer, satisfies that requirement.)

The offset is the offset to pass to the painter. In particular, it is not an offset applied to the layer itself. Layers conceptually by default have no position or size, though they can transform their contents. For example, an crate::OffsetLayer applies an offset to its children.

If the child_paint_bounds are not specified then the current layer’s paint bounds are used. This is appropriate if the child layer does not apply any transformation or clipping to its contents. The child_paint_bounds, if specified, must be in the coordinate system of the new layer (i.e. as seen by its children after it applies whatever transform to its contents), and should not go outside the current layer’s paint bounds.

pub fn push_clip_rect( &mut self, app: &mut App, needs_compositing: bool, offset: Offset, clip_rect: Rect, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), clip_behavior: Clip, old_layer: Option<Handle<ClipRectLayer>>, ) -> Option<Handle<ClipRectLayer>>

Clip further painting using a rectangle.

The needs_compositing argument specifies whether the child needs compositing. Typically this matches the value of AnyRenderObject::needs_compositing for the caller. If false, this method returns None, indicating that a layer is no longer necessary. If a render object calling this method stores the old_layer in its AnyRenderObject::layer field, it should set that field to None.

When needs_compositing is false, this method will use a more efficient way to apply the layer effect than actually creating a layer.

The offset argument is the offset from the origin of the canvas’ coordinate system to the origin of the caller’s coordinate system.

The clip_rect is the rectangle (in the caller’s coordinate system) to use to clip the painting done by painter. It should not include the offset.

pub fn push_clip_rrect( &mut self, app: &mut App, needs_compositing: bool, offset: Offset, bounds: Rect, clip_rrect: RRect, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), clip_behavior: Clip, old_layer: Option<Handle<ClipRRectLayer>>, ) -> Option<Handle<ClipRRectLayer>>

Clip further painting using a rounded rectangle.

pub fn push_clip_path( &mut self, app: &mut App, needs_compositing: bool, offset: Offset, bounds: Rect, clip_path: Arc<Path>, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), clip_behavior: Clip, old_layer: Option<Handle<ClipPathLayer>>, ) -> Option<Handle<ClipPathLayer>>

Clip further painting using a path.

pub fn push_transform( &mut self, app: &mut App, needs_compositing: bool, offset: Offset, transform: Matrix4, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), old_layer: Option<Handle<TransformLayer>>, ) -> Option<Handle<TransformLayer>>

Transform further painting using a matrix.

The offset argument is the offset to pass to painter and the offset to the origin used by transform.

The transform argument is the Matrix4 with which to transform the coordinate system while calling painter. It should not include offset. It is applied effectively after applying offset.

pub fn push_opacity( &mut self, app: &mut App, offset: Offset, alpha: i32, painter: impl FnOnce(&mut App, &mut PaintingContext, Offset), old_layer: Option<Handle<OpacityLayer>>, ) -> Handle<OpacityLayer>

Blend further painting with an alpha value.

The offset argument indicates an offset to apply to all the children (the rendering created by painter).

The alpha argument is the alpha value to use when blending the painting done by painter. An alpha value of 0 means the painting is fully transparent and an alpha value of 255 means the painting is fully opaque.

Trait Implementations

impl ClipContext for PaintingContext

fn canvas(&mut self) -> &mut Canvas

The canvas on which to paint.

The current canvas can change whenever you paint a child using this context, which means it’s fragile to hold a reference to the canvas returned by this getter.

fn clip_path_and_paint( &mut self, path: &Arc<Path>, clip_behavior: Clip, bounds: Rect, painter: impl FnOnce(&mut Self), )

Clip canvas with Path according to Clip and then paint. The canvas is restored to the pre-clip status afterwards.

fn clip_rrect_and_paint( &mut self, rrect: RRect, clip_behavior: Clip, bounds: Rect, painter: impl FnOnce(&mut Self), )

Clip canvas with a rounded rect and then paint. The canvas is restored to the pre-clip status afterwards.

fn clip_r_superellipse_and_paint( &mut self, rse: RSuperellipse, clip_behavior: Clip, bounds: Rect, painter: impl FnOnce(&mut Self), )

Clip canvas with a rounded superellipse and then paint. The canvas is restored to the pre-clip status afterwards.

fn clip_rect_and_paint( &mut self, rect: Rect, clip_behavior: Clip, bounds: Rect, painter: impl FnOnce(&mut Self), )

Clip canvas with a rect and then paint. The canvas is restored to the pre-clip status afterwards.