embedded_graphics/primitives/rounded_rectangle/
mod.rs

1//! The rounded rectangle primitive.
2
3use core::ops::Range;
4
5use crate::{
6    geometry::{Dimensions, Point, Size},
7    primitives::{rectangle::Rectangle, ContainsPoint, OffsetOutline, PointsIter, Primitive},
8    transform::Transform,
9};
10
11mod corner_radii;
12mod ellipse_quadrant;
13mod points;
14mod styled;
15
16pub use corner_radii::{CornerRadii, CornerRadiiBuilder};
17use ellipse_quadrant::{EllipseQuadrant, Quadrant};
18pub use points::Points;
19pub use styled::StyledPixelsIterator;
20
21/// Rounded rectangle primitive.
22///
23/// Creates a rectangle with rounded corners. Corners can be circular or elliptical in shape, and
24/// each corner may have a separate radius applied to it. To create a rounded rectangle with the same
25/// radius for each corner, use the [`with_equal_corners`](RoundedRectangle::with_equal_corners()) method.
26///
27/// Rounded rectangles with different radii for each corner can be created by passing a
28/// [`CornerRadii`](super::CornerRadii) configuration struct to the [`new`](RoundedRectangle::new())
29/// method.
30///
31/// # Overlapping corners
32///
33/// It is possible to create a `RoundedRectangle` with corner radii too large to be contained within
34/// its edges. When this happens, the corner radii will be confined to fit within the rounded
35/// rectangle before use by other parts of embedded-graphics.
36///
37/// This is similar but not identical to
38/// [how the CSS specification works](https://www.w3.org/TR/css-backgrounds-3/#corner-overlap) as it
39/// relies on floating point calculations.
40///
41/// # Examples
42///
43/// ## Create a uniform rounded rectangle
44///
45/// This example creates a rounded rectangle 50px wide by 60px tall. Using
46/// [`with_equal_corners`](RoundedRectangle::with_equal_corners()), all corners are given the same 10px circular
47/// radius. The rectangle is drawn using a solid green fill with a 5px red stroke.
48///
49/// ```rust
50/// use embedded_graphics::{
51///     pixelcolor::Rgb565,
52///     prelude::*,
53///     primitives::{Rectangle, RoundedRectangle, PrimitiveStyle, PrimitiveStyleBuilder},
54/// };
55/// # use embedded_graphics::mock_display::MockDisplay;
56/// # let mut display = MockDisplay::default();
57///
58/// let style = PrimitiveStyleBuilder::new()
59///     .stroke_width(5)
60///     .stroke_color(Rgb565::RED)
61///     .fill_color(Rgb565::GREEN)
62///     .build();
63///
64/// RoundedRectangle::with_equal_corners(
65///     Rectangle::new(Point::new(5, 5), Size::new(40, 50)),
66///     Size::new(10, 10),
67/// )
68/// .into_styled(style)
69/// .draw(&mut display)?;
70/// # Ok::<(), core::convert::Infallible>(())
71/// ```
72///
73/// ## Different corner radii
74///
75/// This example creates a rounded rectangle 50px wide by 60px tall. Each corner is given a distinct
76/// radius in the x and y direction by creating a [`CornerRadii`](super::CornerRadii)
77/// object and passing that to [`RoundedRectangle::new`](RoundedRectangle::new()).
78///
79/// ```rust
80/// use embedded_graphics::{
81///     pixelcolor::Rgb565,
82///     prelude::*,
83///     primitives::{CornerRadiiBuilder, Rectangle, RoundedRectangle, PrimitiveStyle, PrimitiveStyleBuilder},
84/// };
85/// # use embedded_graphics::mock_display::MockDisplay;
86/// # let mut display = MockDisplay::default();
87///
88/// let style = PrimitiveStyleBuilder::new()
89///     .stroke_width(5)
90///     .stroke_color(Rgb565::RED)
91///     .fill_color(Rgb565::GREEN)
92///     .build();
93///
94/// let radii = CornerRadiiBuilder::new()
95///     .top_left(Size::new(5, 6))
96///     .top_right(Size::new(7, 8))
97///     .bottom_right(Size::new(9, 10))
98///     .bottom_left(Size::new(11, 12))
99///     .build();
100///
101/// RoundedRectangle::new(Rectangle::new(Point::new(5, 5), Size::new(40, 50)), radii)
102///     .into_styled(style)
103///     .draw(&mut display)?;
104/// # Ok::<(), core::convert::Infallible>(())
105/// ```
106///
107/// ## Using `CornerRadiiBuilder`
108///
109/// This example creates a rounded rectangle 50px wide by 60px tall. Corner radii are set using the
110/// [`CornerRadiiBuilder`](super::CornerRadiiBuilder) builder.
111///
112/// ```rust
113/// use embedded_graphics::{
114///     pixelcolor::Rgb565,
115///     prelude::*,
116///     primitives::{CornerRadii, CornerRadiiBuilder, Rectangle, RoundedRectangle, PrimitiveStyle, PrimitiveStyleBuilder},
117/// };
118/// # use embedded_graphics::mock_display::MockDisplay;
119/// # let mut display = MockDisplay::default();
120///
121/// let style = PrimitiveStyleBuilder::new()
122///     .stroke_width(5)
123///     .stroke_color(Rgb565::RED)
124///     .fill_color(Rgb565::GREEN)
125///     .build();
126///
127/// let radii = CornerRadiiBuilder::new()
128///     // Set the top left and top right corner radii to 10 x 20px
129///     .top(Size::new(10, 20))
130///     // Set the bottom right corner radius to 5 x 8px
131///     .bottom_right(Size::new(5, 8))
132///     .build();
133///
134/// RoundedRectangle::new(Rectangle::new(Point::new(5, 5), Size::new(40, 50)), radii)
135///     .into_styled(style)
136///     .draw(&mut display)?;
137/// # Ok::<(), core::convert::Infallible>(())
138/// ```
139#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
140#[cfg_attr(feature = "defmt", derive(::defmt::Format))]
141pub struct RoundedRectangle {
142    /// The base rectangle
143    pub rectangle: Rectangle,
144
145    /// The radius of each corner
146    pub corners: CornerRadii,
147}
148
149impl RoundedRectangle {
150    /// Creates a new rounded rectangle with the given corner radii.
151    ///
152    /// The size and position of the rounded rectangle is determined by the given base
153    /// rectangle.
154    pub const fn new(rectangle: Rectangle, corners: CornerRadii) -> Self {
155        Self { rectangle, corners }
156    }
157
158    /// Creates a new rounded rectangle with equal corner radius for all corners.
159    ///
160    /// The size and position of the rounded rectangle is determined by the given base
161    /// rectangle.
162    pub const fn with_equal_corners(rectangle: Rectangle, corner_radius: Size) -> Self {
163        Self::new(rectangle, CornerRadii::new(corner_radius))
164    }
165
166    /// Return the rounded rectangle with confined corner radii.
167    ///
168    /// This method will return a rounded rectangle of the same width and height, but with all
169    /// corner radii confined to fit within its base rectangle.
170    ///
171    /// Calling this method is not necessary when using operations provided by embedded-graphics
172    /// (`.into_styled()`, `.contains()`, etc) as these confine the corner radii internally.
173    ///
174    /// # Examples
175    ///
176    /// ## Confine corner radii that are too large
177    ///
178    /// This example creates a rounded rectangle 50px x 60px in size. Each corner is set to an equal
179    /// radius of 40px x 40px. Each edge of the rectangle would thus need to be at least 80px long
180    /// to contain all corner radii completely. By using `confine_radii`, the corner radii are
181    /// reduced to 25px x 25px so that they fit within the 50px x 60px base rectangle.
182    ///
183    /// ```rust
184    /// use embedded_graphics::{
185    ///     geometry::{Point, Size},
186    ///     primitives::{CornerRadii, CornerRadiiBuilder, Rectangle, RoundedRectangle},
187    /// };
188    ///
189    /// let radii = CornerRadiiBuilder::new().all(Size::new(40, 40)).build();
190    ///
191    /// let base_rectangle = Rectangle::new(Point::zero(), Size::new(50, 60));
192    ///
193    /// let rounded_rectangle = RoundedRectangle::new(base_rectangle, radii);
194    ///
195    /// let confined = rounded_rectangle.confine_radii();
196    ///
197    /// assert_eq!(
198    ///     confined.corners,
199    ///     CornerRadii {
200    ///         top_left: Size::new(25, 25),
201    ///         top_right: Size::new(25, 25),
202    ///         bottom_right: Size::new(25, 25),
203    ///         bottom_left: Size::new(25, 25),
204    ///     }
205    /// );
206    /// ```
207    pub fn confine_radii(&self) -> Self {
208        Self::new(self.rectangle, self.corners.confine(self.rectangle.size))
209    }
210
211    fn get_confined_corner_quadrant(&self, quadrant: Quadrant) -> EllipseQuadrant {
212        let Self {
213            rectangle, corners, ..
214        } = self;
215
216        let Rectangle { top_left, size, .. } = *rectangle;
217
218        let corners = corners.confine(size);
219
220        match quadrant {
221            Quadrant::TopLeft => {
222                EllipseQuadrant::new(top_left, corners.top_left, Quadrant::TopLeft)
223            }
224            Quadrant::TopRight => EllipseQuadrant::new(
225                top_left + size.x_axis() - corners.top_right.x_axis(),
226                corners.top_right,
227                Quadrant::TopRight,
228            ),
229            Quadrant::BottomRight => EllipseQuadrant::new(
230                top_left + size - corners.bottom_right,
231                corners.bottom_right,
232                Quadrant::BottomRight,
233            ),
234            Quadrant::BottomLeft => EllipseQuadrant::new(
235                top_left + size.y_axis() - corners.bottom_left.y_axis(),
236                corners.bottom_left,
237                Quadrant::BottomLeft,
238            ),
239        }
240    }
241}
242
243impl OffsetOutline for RoundedRectangle {
244    fn offset(&self, offset: i32) -> Self {
245        let rectangle = self.rectangle.offset(offset);
246
247        let corners = if offset >= 0 {
248            let corner_offset = Size::new_equal(offset as u32);
249
250            CornerRadii {
251                top_left: self.corners.top_left.saturating_add(corner_offset),
252                top_right: self.corners.top_right.saturating_add(corner_offset),
253                bottom_right: self.corners.bottom_right.saturating_add(corner_offset),
254                bottom_left: self.corners.bottom_left.saturating_add(corner_offset),
255            }
256        } else {
257            let corner_offset = Size::new_equal((-offset) as u32);
258
259            CornerRadii {
260                top_left: self.corners.top_left.saturating_sub(corner_offset),
261                top_right: self.corners.top_right.saturating_sub(corner_offset),
262                bottom_right: self.corners.bottom_right.saturating_sub(corner_offset),
263                bottom_left: self.corners.bottom_left.saturating_sub(corner_offset),
264            }
265        };
266
267        Self::new(rectangle, corners)
268    }
269}
270
271impl Primitive for RoundedRectangle {}
272
273impl PointsIter for RoundedRectangle {
274    type Iter = Points;
275
276    fn points(&self) -> Self::Iter {
277        Points::new(self)
278    }
279}
280
281impl ContainsPoint for RoundedRectangle {
282    fn contains(&self, point: Point) -> bool {
283        let rounded_rectangle_contains = RoundedRectangleContains::new(self);
284        rounded_rectangle_contains.contains(point)
285    }
286}
287
288impl Dimensions for RoundedRectangle {
289    fn bounding_box(&self) -> Rectangle {
290        self.rectangle
291    }
292}
293
294impl Transform for RoundedRectangle {
295    /// Translate the rounded rectangle from its current position to a new position by (x, y)
296    /// pixels, returning a new `RoundedRectangle`. For a mutating transform, see `translate_mut`.
297    ///
298    /// ```
299    /// # use embedded_graphics::prelude::*;
300    /// use embedded_graphics::primitives::{Rectangle, RoundedRectangle};
301    ///
302    /// let original = RoundedRectangle::with_equal_corners(
303    ///     Rectangle::new(Point::new(5, 10), Size::new(20, 30)),
304    ///     Size::new(10, 15),
305    /// );
306    /// let moved = original.translate(Point::new(10, 12));
307    ///
308    /// assert_eq!(original.bounding_box().top_left, Point::new(5, 10));
309    /// assert_eq!(moved.bounding_box().top_left, Point::new(15, 22));
310    /// ```
311    fn translate(&self, by: Point) -> Self {
312        Self {
313            rectangle: self.rectangle.translate(by),
314            ..*self
315        }
316    }
317
318    /// Translate the rounded rectangle from its current position to a new position by (x, y) pixels.
319    ///
320    /// ```
321    /// # use embedded_graphics::prelude::*;
322    /// use embedded_graphics::primitives::{Rectangle, RoundedRectangle};
323    ///
324    /// let mut shape = RoundedRectangle::with_equal_corners(
325    ///     Rectangle::new(Point::new(5, 10), Size::new(20, 30)),
326    ///     Size::new(10, 15),
327    /// );
328    ///
329    /// shape.translate_mut(Point::new(10, 12));
330    ///
331    /// assert_eq!(shape.bounding_box().top_left, Point::new(15, 22));
332    /// ```
333    fn translate_mut(&mut self, by: Point) -> &mut Self {
334        self.rectangle.translate_mut(by);
335
336        self
337    }
338}
339
340#[derive(Clone, PartialEq, Eq, Hash, Debug)]
341#[cfg_attr(feature = "defmt", derive(::defmt::Format))]
342pub(in crate::primitives) struct RoundedRectangleContains {
343    /// Bounding box rows.
344    rows: Range<i32>,
345    /// Bounding box columns.
346    columns: Range<i32>,
347
348    /// Rows that don't belong to a corner radius on the left side.
349    straight_rows_left: Range<i32>,
350    /// Rows that don't belong to a corner radius on the right side.
351    straight_rows_right: Range<i32>,
352
353    /// Confined top left corner ellipse.
354    top_left: EllipseQuadrant,
355    /// Confined top right corner ellipse.
356    top_right: EllipseQuadrant,
357    /// Confined bottom left corner ellipse.
358    bottom_left: EllipseQuadrant,
359    /// Confined bottom right corner ellipse.
360    bottom_right: EllipseQuadrant,
361}
362
363impl RoundedRectangleContains {
364    pub fn new(rounded_rectangle: &RoundedRectangle) -> Self {
365        let top_left = rounded_rectangle.get_confined_corner_quadrant(Quadrant::TopLeft);
366        let top_right = rounded_rectangle.get_confined_corner_quadrant(Quadrant::TopRight);
367        let bottom_left = rounded_rectangle.get_confined_corner_quadrant(Quadrant::BottomLeft);
368        let bottom_right = rounded_rectangle.get_confined_corner_quadrant(Quadrant::BottomRight);
369
370        let rows = rounded_rectangle.rectangle.rows();
371        let columns = rounded_rectangle.rectangle.columns();
372
373        let straight_rows_left = (rows.start + top_left.bounding_box().size.height as i32)
374            ..(rows.end - bottom_left.bounding_box().size.height as i32);
375        let straight_rows_right = (rows.start + top_right.bounding_box().size.height as i32)
376            ..(rows.end - bottom_right.bounding_box().size.height as i32);
377
378        Self {
379            rows,
380            columns,
381
382            straight_rows_left,
383            straight_rows_right,
384
385            top_left,
386            top_right,
387            bottom_left,
388            bottom_right,
389        }
390    }
391
392    pub fn contains(&self, point: Point) -> bool {
393        if !(self.rows.contains(&point.y) && self.columns.contains(&point.x)) {
394            return false;
395        }
396
397        if point.y < self.straight_rows_left.start
398            && point.x < self.top_left.bounding_box().columns().end
399        {
400            return self.top_left.contains(point);
401        }
402
403        if point.y < self.straight_rows_right.start
404            && point.x >= self.top_right.bounding_box().columns().start
405        {
406            return self.top_right.contains(point);
407        }
408
409        if point.y >= self.straight_rows_left.end
410            && point.x < self.bottom_left.bounding_box().columns().end
411        {
412            return self.bottom_left.contains(point);
413        }
414
415        if point.y >= self.straight_rows_right.end
416            && point.x >= self.bottom_right.bounding_box().columns().start
417        {
418            return self.bottom_right.contains(point);
419        }
420
421        true
422    }
423}
424
425#[cfg(test)]
426mod tests {
427    use super::*;
428    use crate::{
429        geometry::{Point, Size},
430        mock_display::MockDisplay,
431        pixelcolor::BinaryColor,
432        primitives::CornerRadiiBuilder,
433    };
434
435    #[test]
436    fn clamp_radius_at_rect_size() {
437        let clamped = RoundedRectangle::with_equal_corners(
438            Rectangle::new(Point::zero(), Size::new(20, 30)),
439            Size::new_equal(50),
440        )
441        .points();
442
443        let expected = RoundedRectangle::with_equal_corners(
444            Rectangle::new(Point::zero(), Size::new(20, 30)),
445            Size::new_equal(10),
446        )
447        .points();
448
449        assert!(clamped.eq(expected));
450    }
451
452    #[test]
453    fn large_bottom_right_corner() {
454        let radii = CornerRadiiBuilder::new()
455            .all(Size::new_equal(20))
456            .bottom_right(Size::new(200, 200))
457            .build();
458
459        let base_rectangle = Rectangle::with_corners(Point::new_equal(20), Point::new_equal(100));
460
461        let rounded_rectangle = RoundedRectangle::new(base_rectangle, radii);
462
463        let confined = rounded_rectangle.confine_radii();
464
465        assert_eq!(
466            confined,
467            RoundedRectangle {
468                rectangle: base_rectangle,
469                corners: CornerRadii {
470                    top_left: Size::new_equal(7),
471                    top_right: Size::new_equal(7),
472                    bottom_right: Size::new_equal(73),
473                    bottom_left: Size::new_equal(7),
474                }
475            }
476        );
477    }
478
479    #[test]
480    fn offset() {
481        let center = Point::new(10, 20);
482        let rect = Rectangle::with_center(center, Size::new(3, 4));
483        let rounded = RoundedRectangle::with_equal_corners(rect, Size::new(2, 3));
484
485        assert_eq!(rounded.offset(0), rounded);
486
487        assert_eq!(
488            rounded.offset(1),
489            RoundedRectangle::with_equal_corners(
490                Rectangle::with_center(center, Size::new(5, 6)),
491                Size::new(3, 4)
492            ),
493        );
494        assert_eq!(
495            rounded.offset(2),
496            RoundedRectangle::with_equal_corners(
497                Rectangle::with_center(center, Size::new(7, 8)),
498                Size::new(4, 5)
499            ),
500        );
501
502        assert_eq!(
503            rounded.offset(-1),
504            RoundedRectangle::with_equal_corners(
505                Rectangle::with_center(center, Size::new(1, 2)),
506                Size::new(1, 2)
507            ),
508        );
509        assert_eq!(
510            rounded.offset(-2),
511            RoundedRectangle::with_equal_corners(
512                Rectangle::with_center(center, Size::new(0, 0)),
513                Size::new(0, 1)
514            ),
515        );
516        assert_eq!(
517            rounded.offset(-3),
518            RoundedRectangle::with_equal_corners(
519                Rectangle::with_center(center, Size::new(0, 0)),
520                Size::new(0, 0)
521            ),
522        );
523    }
524
525    #[test]
526    fn contains_equal_corners() {
527        let rounded_rectangle = RoundedRectangle::with_equal_corners(
528            Rectangle::new(Point::new(1, 2), Size::new(20, 10)),
529            Size::new(8, 4),
530        );
531
532        let expected = MockDisplay::from_points(rounded_rectangle.points(), BinaryColor::On);
533
534        let display = MockDisplay::from_points(
535            rounded_rectangle
536                .rectangle
537                .offset(10)
538                .points()
539                .filter(|p| rounded_rectangle.contains(*p)),
540            BinaryColor::On,
541        );
542        display.assert_eq(&expected);
543    }
544
545    #[test]
546    fn contains_different_corners() {
547        let rounded_rectangle = RoundedRectangle::new(
548            Rectangle::new(Point::new(1, 2), Size::new(25, 10)),
549            CornerRadiiBuilder::new()
550                .top_left(Size::new_equal(10))
551                .bottom_right(Size::new_equal(10))
552                .build(),
553        );
554
555        let expected = MockDisplay::from_points(rounded_rectangle.points(), BinaryColor::On);
556
557        let display = MockDisplay::from_points(
558            rounded_rectangle
559                .rectangle
560                .offset(10)
561                .points()
562                .filter(|p| rounded_rectangle.contains(*p)),
563            BinaryColor::On,
564        );
565        display.assert_eq(&expected);
566    }
567}
embedded_graphics/primitives/rounded_rectangle/mod.rs

embedded_graphics/primitives/rounded_rectangle/
mod.rs
