Struct Painter

pub struct Painter { /* private fields */ }

Helper to paint shapes and text to a specific region on a specific layer.

All coordinates are screen coordinates in the unit points (one point can consist of many physical pixels).

A Painter never outlive a single frame/pass.

Implementations

impl Painter

pub fn new(ctx: Context, layer_id: LayerId, clip_rect: Rect) -> Self

Create a painter to a specific layer within a certain clip rectangle.

pub fn with_layer_id(self, layer_id: LayerId) -> Self

Redirect where you are painting.

pub fn with_clip_rect(&self, rect: Rect) -> Self

Create a painter for a sub-region of this Painter.

The clip-rect of the returned Painter will be the intersection of the given rectangle and the clip_rect() of the parent Painter.

pub fn set_layer_id(&mut self, layer_id: LayerId)

Redirect where you are painting.

It is undefined behavior to change the LayerId of crate::Ui::painter.

pub fn set_fade_to_color(&mut self, fade_to_color: Option<Color32>)

If set, colors will be modified to look like this

pub fn set_opacity(&mut self, opacity: f32)

Set the opacity (alpha multiplier) of everything painted by this painter from this point forward.

opacity must be between 0.0 and 1.0, where 0.0 means fully transparent (i.e., invisible) and 1.0 means fully opaque.

See also: Self::opacity and Self::multiply_opacity.

pub fn multiply_opacity(&mut self, opacity: f32)

Like Self::set_opacity, but multiplies the given value with the current opacity.

See also: Self::set_opacity and Self::opacity.

pub fn opacity(&self) -> f32

Read the current opacity of the underlying painter.

See also: Self::set_opacity and Self::multiply_opacity.

pub fn is_visible(&self) -> bool

If false, nothing you paint will show up.

Also checks Context::will_discard.

pub fn set_invisible(&mut self)

If false, nothing added to the painter will be visible

pub fn ctx(&self) -> &Context

Get a reference to the parent Context.

pub fn pixels_per_point(&self) -> f32

Number of physical pixels for each logical UI point.

pub fn fonts<R>(&self, reader: impl FnOnce(&Fonts) -> R) -> R

Read-only access to the shared Fonts.

See Context documentation for how locks work.

pub fn layer_id(&self) -> LayerId

Where we paint

pub fn clip_rect(&self) -> Rect

Everything painted in this Painter will be clipped against this. This means nothing outside of this rectangle will be visible on screen.

pub fn shrink_clip_rect(&mut self, new_clip_rect: Rect)

Constrain the rectangle in which we can paint.

Short for painter.set_clip_rect(painter.clip_rect().intersect(new_clip_rect)).

See also: Self::clip_rect and Self::set_clip_rect.

pub fn set_clip_rect(&mut self, clip_rect: Rect)

Everything painted in this Painter will be clipped against this. This means nothing outside of this rectangle will be visible on screen.

Warning: growing the clip rect might cause unexpected results! When in doubt, use Self::shrink_clip_rect instead.

pub fn round_to_pixel_center(&self, point: f32) -> f32

Useful for pixel-perfect rendering of lines that are one pixel wide (or any odd number of pixels).

pub fn round_pos_to_pixel_center(&self, pos: Pos2) -> Pos2

👎Deprecated: Use emath::GuiRounding with painter.pixels_per_point() instead

Useful for pixel-perfect rendering of lines that are one pixel wide (or any odd number of pixels).

pub fn round_to_pixel(&self, point: f32) -> f32

👎Deprecated: Use emath::GuiRounding with painter.pixels_per_point() instead

Useful for pixel-perfect rendering of filled shapes.

pub fn round_vec_to_pixels(&self, vec: Vec2) -> Vec2

👎Deprecated: Use emath::GuiRounding with painter.pixels_per_point() instead

Useful for pixel-perfect rendering.

pub fn round_pos_to_pixels(&self, pos: Pos2) -> Pos2

👎Deprecated: Use emath::GuiRounding with painter.pixels_per_point() instead

Useful for pixel-perfect rendering.

pub fn round_rect_to_pixels(&self, rect: Rect) -> Rect

👎Deprecated: Use emath::GuiRounding with painter.pixels_per_point() instead

Useful for pixel-perfect rendering.

impl Painter

Low level

pub fn add(&self, shape: impl Into<Shape>) -> ShapeIdx

It is up to the caller to make sure there is room for this. Can be used for free painting. NOTE: all coordinates are screen coordinates!

pub fn extend<I: IntoIterator<Item = Shape>>(&self, shapes: I)

Add many shapes at once.

Calling this once is generally faster than calling Self::add multiple times.

pub fn set(&self, idx: ShapeIdx, shape: impl Into<Shape>)

Modify an existing Shape.

pub fn for_each_shape(&self, reader: impl FnMut(&ClippedShape))

Access all shapes added this frame.

impl Painter

Debug painting

pub fn debug_rect(&self, rect: Rect, color: Color32, text: impl ToString)

pub fn error(&self, pos: Pos2, text: impl Display) -> Rect

pub fn debug_text( &self, pos: Pos2, anchor: Align2, color: Color32, text: impl ToString, ) -> Rect

Text with a background.

See also Context::debug_text.

impl Painter

Paint different primitives

pub fn line_segment( &self, points: [Pos2; 2], stroke: impl Into<Stroke>, ) -> ShapeIdx

Paints a line from the first point to the second.

pub fn line(&self, points: Vec<Pos2>, stroke: impl Into<PathStroke>) -> ShapeIdx

Paints a line connecting the points. NOTE: all coordinates are screen coordinates!

pub fn hline( &self, x: impl Into<Rangef>, y: f32, stroke: impl Into<Stroke>, ) -> ShapeIdx

Paints a horizontal line.

pub fn vline( &self, x: f32, y: impl Into<Rangef>, stroke: impl Into<Stroke>, ) -> ShapeIdx

Paints a vertical line.

pub fn circle( &self, center: Pos2, radius: f32, fill_color: impl Into<Color32>, stroke: impl Into<Stroke>, ) -> ShapeIdx

pub fn circle_filled( &self, center: Pos2, radius: f32, fill_color: impl Into<Color32>, ) -> ShapeIdx

pub fn circle_stroke( &self, center: Pos2, radius: f32, stroke: impl Into<Stroke>, ) -> ShapeIdx

pub fn rect( &self, rect: Rect, corner_radius: impl Into<CornerRadius>, fill_color: impl Into<Color32>, stroke: impl Into<Stroke>, stroke_kind: StrokeKind, ) -> ShapeIdx

See also Self::rect_filled and Self::rect_stroke.

pub fn rect_filled( &self, rect: Rect, corner_radius: impl Into<CornerRadius>, fill_color: impl Into<Color32>, ) -> ShapeIdx

pub fn rect_stroke( &self, rect: Rect, corner_radius: impl Into<CornerRadius>, stroke: impl Into<Stroke>, stroke_kind: StrokeKind, ) -> ShapeIdx

pub fn arrow(&self, origin: Pos2, vec: Vec2, stroke: impl Into<Stroke>)

Show an arrow starting at origin and going in the direction of vec, with the length vec.length().

pub fn image( &self, texture_id: TextureId, rect: Rect, uv: Rect, tint: Color32, ) -> ShapeIdx

An image at the given position.

uv should normally be Rect::from_min_max(pos2(0.0, 0.0), pos2(1.0, 1.0)) unless you want to crop or flip the image.

tint is a color multiplier. Use Color32::WHITE if you don’t want to tint the image.

Usually it is easier to use crate::Image::paint_at instead:

egui::Image::new(egui::include_image!("../assets/ferris.png"))
    .corner_radius(5)
    .tint(egui::Color32::LIGHT_BLUE)
    .paint_at(ui, rect);

impl Painter

Text

pub fn text( &self, pos: Pos2, anchor: Align2, text: impl ToString, font_id: FontId, text_color: Color32, ) -> Rect

Lay out and paint some text.

To center the text at the given position, use Align2::CENTER_CENTER.

To find out the size of text before painting it, use Self::layout or Self::layout_no_wrap.

Returns where the text ended up.

pub fn layout( &self, text: String, font_id: FontId, color: Color32, wrap_width: f32, ) -> Arc<Galley>

Will wrap text at the given width and line break at \n.

Paint the results with Self::galley.

pub fn layout_no_wrap( &self, text: String, font_id: FontId, color: Color32, ) -> Arc<Galley>

Will line break at \n.

Paint the results with Self::galley.

pub fn layout_job(&self, layout_job: LayoutJob) -> Arc<Galley>

Lay out this text layut job in a galley.

Paint the results with Self::galley.

pub fn galley(&self, pos: Pos2, galley: Arc<Galley>, fallback_color: Color32)

Paint text that has already been laid out in a Galley.

You can create the Galley with Self::layout or Self::layout_job.

Any uncolored parts of the Galley (using Color32::PLACEHOLDER) will be replaced with the given color.

Any non-placeholder color in the galley takes precedence over this fallback color.

pub fn galley_with_override_text_color( &self, pos: Pos2, galley: Arc<Galley>, text_color: Color32, )

Paint text that has already been laid out in a Galley.

You can create the Galley with Self::layout.

All text color in the Galley will be replaced with the given color.

pub fn galley_with_color( &self, pos: Pos2, galley: Arc<Galley>, text_color: Color32, )

👎Deprecated: Use Painter::galley or Painter::galley_with_override_text_color instead

Trait Implementations

impl Clone for Painter

fn clone(&self) -> Painter

Returns a copy of the value.

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

Performs copy-assignment from source.