iced_core/
renderer.rs

1//! Write your own renderer.
2#[cfg(debug_assertions)]
3mod null;
4
5use crate::{
6    Background, Border, Color, Font, Pixels, Rectangle, Shadow, Size,
7    Transformation, Vector,
8};
9
10/// A component that can be used by widgets to draw themselves on a screen.
11pub trait Renderer {
12    /// Starts recording a new layer.
13    fn start_layer(&mut self, bounds: Rectangle);
14
15    /// Ends recording a new layer.
16    ///
17    /// The new layer will clip its contents to the provided `bounds`.
18    fn end_layer(&mut self);
19
20    /// Draws the primitives recorded in the given closure in a new layer.
21    ///
22    /// The layer will clip its contents to the provided `bounds`.
23    fn with_layer(&mut self, bounds: Rectangle, f: impl FnOnce(&mut Self)) {
24        self.start_layer(bounds);
25        f(self);
26        self.end_layer();
27    }
28
29    /// Starts recording with a new [`Transformation`].
30    fn start_transformation(&mut self, transformation: Transformation);
31
32    /// Ends recording a new layer.
33    ///
34    /// The new layer will clip its contents to the provided `bounds`.
35    fn end_transformation(&mut self);
36
37    /// Applies a [`Transformation`] to the primitives recorded in the given closure.
38    fn with_transformation(
39        &mut self,
40        transformation: Transformation,
41        f: impl FnOnce(&mut Self),
42    ) {
43        self.start_transformation(transformation);
44        f(self);
45        self.end_transformation();
46    }
47
48    /// Applies a translation to the primitives recorded in the given closure.
49    fn with_translation(
50        &mut self,
51        translation: Vector,
52        f: impl FnOnce(&mut Self),
53    ) {
54        self.with_transformation(
55            Transformation::translate(translation.x, translation.y),
56            f,
57        );
58    }
59
60    /// Fills a [`Quad`] with the provided [`Background`].
61    fn fill_quad(&mut self, quad: Quad, background: impl Into<Background>);
62
63    /// Clears all of the recorded primitives in the [`Renderer`].
64    fn clear(&mut self);
65}
66
67/// A polygon with four sides.
68#[derive(Debug, Clone, Copy, PartialEq)]
69pub struct Quad {
70    /// The bounds of the [`Quad`].
71    pub bounds: Rectangle,
72
73    /// The [`Border`] of the [`Quad`]. The border is drawn on the inside of the [`Quad`].
74    pub border: Border,
75
76    /// The [`Shadow`] of the [`Quad`].
77    pub shadow: Shadow,
78}
79
80impl Default for Quad {
81    fn default() -> Self {
82        Self {
83            bounds: Rectangle::with_size(Size::ZERO),
84            border: Border::default(),
85            shadow: Shadow::default(),
86        }
87    }
88}
89
90/// The styling attributes of a [`Renderer`].
91#[derive(Debug, Clone, Copy, PartialEq)]
92pub struct Style {
93    /// The text color
94    pub text_color: Color,
95}
96
97impl Default for Style {
98    fn default() -> Self {
99        Style {
100            text_color: Color::BLACK,
101        }
102    }
103}
104
105/// A headless renderer is a renderer that can render offscreen without
106/// a window nor a compositor.
107pub trait Headless {
108    /// Creates a new [`Headless`] renderer;
109    fn new(default_font: Font, default_text_size: Pixels) -> Self;
110
111    /// Draws offscreen into a screenshot, returning a collection of
112    /// bytes representing the rendered pixels in RGBA order.
113    fn screenshot(
114        &mut self,
115        size: Size<u32>,
116        scale_factor: f32,
117        background_color: Color,
118    ) -> Vec<u8>;
119}