epaint/lib.rs
1//! A simple 2D graphics library for turning simple 2D shapes and text into textured triangles.
2//!
3//! Made for [`egui`](https://github.com/emilk/egui/).
4//!
5//! Create some [`Shape`]:s and pass them to [`Tessellator::tessellate_shapes`] to generate [`Mesh`]:es
6//! that you can then paint using some graphics API of your choice (e.g. OpenGL).
7//!
8//! ## Coordinate system
9//! The left-top corner of the screen is `(0.0, 0.0)`,
10//! with X increasing to the right and Y increasing downwards.
11//!
12//! `epaint` uses logical _points_ as its coordinate system.
13//! Those related to physical _pixels_ by the `pixels_per_point` scale factor.
14//! For example, a high-dpi screen can have `pixels_per_point = 2.0`,
15//! meaning there are two physical screen pixels for each logical point.
16//!
17//! Angles are in radians, and are measured clockwise from the X-axis, which has angle=0.
18//!
19//! ## Feature flags
20#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
21//!
22
23#![allow(clippy::float_cmp)]
24#![allow(clippy::manual_range_contains)]
25
26mod brush;
27pub mod color;
28mod corner_radius;
29mod corner_radius_f32;
30pub mod image;
31mod margin;
32mod margin_f32;
33mod mesh;
34pub mod mutex;
35mod shadow;
36pub mod shape_transform;
37mod shapes;
38pub mod stats;
39mod stroke;
40pub mod tessellator;
41pub mod text;
42mod texture_atlas;
43mod texture_handle;
44pub mod textures;
45pub mod util;
46mod viewport;
47
48pub use self::{
49 brush::Brush,
50 color::ColorMode,
51 corner_radius::CornerRadius,
52 corner_radius_f32::CornerRadiusF32,
53 image::{AlphaFromCoverage, ColorImage, ImageData, ImageDelta},
54 margin::Margin,
55 margin_f32::*,
56 mesh::{Mesh, Mesh16, Vertex},
57 shadow::Shadow,
58 shapes::{
59 CircleShape, CubicBezierShape, EllipseShape, PaintCallback, PaintCallbackInfo, PathShape,
60 QuadraticBezierShape, RectShape, Shape, TextShape,
61 },
62 stats::PaintStats,
63 stroke::{PathStroke, Stroke, StrokeKind},
64 tessellator::{TessellationOptions, Tessellator},
65 text::{FontFamily, FontId, Fonts, FontsView, Galley},
66 texture_atlas::TextureAtlas,
67 texture_handle::TextureHandle,
68 textures::TextureManager,
69 viewport::ViewportInPixels,
70};
71
72#[deprecated = "Renamed to CornerRadius"]
73pub type Rounding = CornerRadius;
74
75pub use ecolor::{Color32, Hsva, HsvaGamma, Rgba};
76pub use emath::{Pos2, Rect, Vec2, pos2, vec2};
77
78#[deprecated = "Use the ahash crate directly."]
79pub use ahash;
80
81pub use ecolor;
82pub use emath;
83
84#[cfg(feature = "color-hex")]
85pub use ecolor::hex_color;
86
87/// The UV coordinate of a white region of the texture mesh.
88///
89/// The default egui texture has the top-left corner pixel fully white.
90/// You need need use a clamping texture sampler for this to work
91/// (so it doesn't do bilinear blending with bottom right corner).
92pub const WHITE_UV: emath::Pos2 = emath::pos2(0.0, 0.0);
93
94/// What texture to use in a [`Mesh`] mesh.
95///
96/// If you don't want to use a texture, use `TextureId::Managed(0)` and the [`WHITE_UV`] for uv-coord.
97#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
98#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
99pub enum TextureId {
100 /// Textures allocated using [`TextureManager`].
101 ///
102 /// The first texture (`TextureId::Managed(0)`) is used for the font data.
103 Managed(u64),
104
105 /// Your own texture, defined in any which way you want.
106 /// The backend renderer will presumably use this to look up what texture to use.
107 User(u64),
108}
109
110impl Default for TextureId {
111 /// The epaint font texture.
112 fn default() -> Self {
113 Self::Managed(0)
114 }
115}
116
117/// A [`Shape`] within a clip rectangle.
118///
119/// Everything is using logical points.
120#[derive(Clone, Debug, PartialEq)]
121pub struct ClippedShape {
122 /// Clip / scissor rectangle.
123 /// Only show the part of the [`Shape`] that falls within this.
124 pub clip_rect: emath::Rect,
125
126 /// The shape
127 pub shape: Shape,
128}
129
130impl ClippedShape {
131 /// Transform (move/scale) the shape in-place.
132 ///
133 /// If using a [`PaintCallback`], note that only the rect is scaled as opposed
134 /// to other shapes where the stroke is also scaled.
135 pub fn transform(&mut self, transform: emath::TSTransform) {
136 let Self { clip_rect, shape } = self;
137 *clip_rect = transform * *clip_rect;
138 shape.transform(transform);
139 }
140}
141
142/// A [`Mesh`] or [`PaintCallback`] within a clip rectangle.
143///
144/// Everything is using logical points.
145#[derive(Clone, Debug)]
146pub struct ClippedPrimitive {
147 /// Clip / scissor rectangle.
148 /// Only show the part of the [`Mesh`] that falls within this.
149 pub clip_rect: emath::Rect,
150
151 /// What to paint - either a [`Mesh`] or a [`PaintCallback`].
152 pub primitive: Primitive,
153}
154
155/// A rendering primitive - either a [`Mesh`] or a [`PaintCallback`].
156#[derive(Clone, Debug)]
157pub enum Primitive {
158 Mesh(Mesh),
159 Callback(PaintCallback),
160}
161
162// ---------------------------------------------------------------------------
163
164/// Was epaint compiled with the `rayon` feature?
165pub const HAS_RAYON: bool = cfg!(feature = "rayon");