iced_graphics/
compositor.rs

1//! A compositor is responsible for initializing a renderer and managing window
2//! surfaces.
3use crate::core::Color;
4use crate::futures::{MaybeSend, MaybeSync};
5use crate::{Error, Settings, Shell, Viewport};
6
7use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
8use thiserror::Error;
9
10use std::borrow::Cow;
11
12/// A graphics compositor that can draw to windows.
13pub trait Compositor: Sized {
14    /// The iced renderer of the backend.
15    type Renderer;
16
17    /// The surface of the backend.
18    type Surface;
19
20    /// Creates a new [`Compositor`].
21    fn new<W: Window + Clone>(
22        settings: Settings,
23        compatible_window: W,
24        shell: Shell,
25    ) -> impl Future<Output = Result<Self, Error>> {
26        Self::with_backend(settings, compatible_window, shell, None)
27    }
28
29    /// Creates a new [`Compositor`] with a backend preference.
30    ///
31    /// If the backend does not match the preference, it will return
32    /// [`Error::GraphicsAdapterNotFound`].
33    fn with_backend<W: Window + Clone>(
34        _settings: Settings,
35        _compatible_window: W,
36        _shell: Shell,
37        _backend: Option<&str>,
38    ) -> impl Future<Output = Result<Self, Error>>;
39
40    /// Creates a [`Self::Renderer`] for the [`Compositor`].
41    fn create_renderer(&self) -> Self::Renderer;
42
43    /// Crates a new [`Surface`] for the given window.
44    ///
45    /// [`Surface`]: Self::Surface
46    fn create_surface<W: Window + Clone>(
47        &mut self,
48        window: W,
49        width: u32,
50        height: u32,
51    ) -> Self::Surface;
52
53    /// Configures a new [`Surface`] with the given dimensions.
54    ///
55    /// [`Surface`]: Self::Surface
56    fn configure_surface(
57        &mut self,
58        surface: &mut Self::Surface,
59        width: u32,
60        height: u32,
61    );
62
63    /// Returns [`Information`] used by this [`Compositor`].
64    fn information(&self) -> Information;
65
66    /// Loads a font from its bytes.
67    fn load_font(&mut self, font: Cow<'static, [u8]>) {
68        crate::text::font_system()
69            .write()
70            .expect("Write to font system")
71            .load_font(font);
72    }
73
74    /// Presents the [`Renderer`] primitives to the next frame of the given [`Surface`].
75    ///
76    /// [`Renderer`]: Self::Renderer
77    /// [`Surface`]: Self::Surface
78    fn present(
79        &mut self,
80        renderer: &mut Self::Renderer,
81        surface: &mut Self::Surface,
82        viewport: &Viewport,
83        background_color: Color,
84        on_pre_present: impl FnOnce(),
85    ) -> Result<(), SurfaceError>;
86
87    /// Screenshots the current [`Renderer`] primitives to an offscreen texture, and returns the bytes of
88    /// the texture ordered as `RGBA` in the `sRGB` color space.
89    ///
90    /// [`Renderer`]: Self::Renderer
91    fn screenshot(
92        &mut self,
93        renderer: &mut Self::Renderer,
94        viewport: &Viewport,
95        background_color: Color,
96    ) -> Vec<u8>;
97}
98
99/// A window that can be used in a [`Compositor`].
100///
101/// This is just a convenient super trait of the `raw-window-handle`
102/// traits.
103pub trait Window:
104    HasWindowHandle + HasDisplayHandle + MaybeSend + MaybeSync + 'static
105{
106}
107
108impl<T> Window for T where
109    T: HasWindowHandle + HasDisplayHandle + MaybeSend + MaybeSync + 'static
110{
111}
112
113/// Defines the default compositor of a renderer.
114pub trait Default {
115    /// The compositor of the renderer.
116    type Compositor: Compositor<Renderer = Self>;
117}
118
119/// Result of an unsuccessful call to [`Compositor::present`].
120#[derive(Clone, PartialEq, Eq, Debug, Error)]
121pub enum SurfaceError {
122    /// A timeout was encountered while trying to acquire the next frame.
123    #[error("A timeout was encountered while trying to acquire the next frame")]
124    Timeout,
125    /// The underlying surface has changed, and therefore the surface must be updated.
126    #[error(
127        "The underlying surface has changed, and therefore the surface must be updated."
128    )]
129    Outdated,
130    /// The swap chain has been lost and needs to be recreated.
131    #[error("The surface has been lost and needs to be recreated")]
132    Lost,
133    /// There is no more memory left to allocate a new frame.
134    #[error("There is no more memory left to allocate a new frame")]
135    OutOfMemory,
136    /// Acquiring a texture failed with a generic error.
137    #[error("Acquiring a texture failed with a generic error")]
138    Other,
139}
140
141/// Contains information about the graphics (e.g. graphics adapter, graphics backend).
142#[derive(Debug)]
143pub struct Information {
144    /// Contains the graphics adapter.
145    pub adapter: String,
146    /// Contains the graphics backend.
147    pub backend: String,
148}
149
150#[cfg(debug_assertions)]
151impl Compositor for () {
152    type Renderer = ();
153    type Surface = ();
154
155    async fn with_backend<W: Window + Clone>(
156        _settings: Settings,
157        _compatible_window: W,
158        _shell: Shell,
159        _preferred_backend: Option<&str>,
160    ) -> Result<Self, Error> {
161        Ok(())
162    }
163
164    fn create_renderer(&self) -> Self::Renderer {}
165
166    fn create_surface<W: Window + Clone>(
167        &mut self,
168        _window: W,
169        _width: u32,
170        _height: u32,
171    ) -> Self::Surface {
172    }
173
174    fn configure_surface(
175        &mut self,
176        _surface: &mut Self::Surface,
177        _width: u32,
178        _height: u32,
179    ) {
180    }
181
182    fn load_font(&mut self, _font: Cow<'static, [u8]>) {}
183
184    fn information(&self) -> Information {
185        Information {
186            adapter: String::from("Null Renderer"),
187            backend: String::from("Null"),
188        }
189    }
190
191    fn present(
192        &mut self,
193        _renderer: &mut Self::Renderer,
194        _surface: &mut Self::Surface,
195        _viewport: &Viewport,
196        _background_color: Color,
197        _on_pre_present: impl FnOnce(),
198    ) -> Result<(), SurfaceError> {
199        Ok(())
200    }
201
202    fn screenshot(
203        &mut self,
204        _renderer: &mut Self::Renderer,
205        _viewport: &Viewport,
206        _background_color: Color,
207    ) -> Vec<u8> {
208        vec![]
209    }
210}
211
212#[cfg(debug_assertions)]
213impl Default for () {
214    type Compositor = ();
215}
iced_graphics/compositor.rs

iced_graphics/
compositor.rs
