2 files changed, 45 insertions, 26 deletions

diff --git a/graphics/src/window/compositor.rs b/graphics/src/window/compositor.rs
index 7674f227..de2a6990 100644
--- a/graphics/src/window/compositor.rs
+++ b/graphics/src/window/compositor.rs
@@ -1,6 +1,9 @@
 use crate::{Color, Error, Viewport};
+
 use iced_native::mouse;
+
 use raw_window_handle::HasRawWindowHandle;
+use thiserror::Error;
 
 /// A graphics compositor that can draw to windows.
 pub trait Compositor: Sized {
@@ -16,14 +19,15 @@ pub trait Compositor: Sized {
     /// The swap chain of the backend.
     type SwapChain;
 
-    /// Creates a new [`Backend`].
-    ///
-    /// [`Backend`]: trait.Backend.html
-    fn new(settings: Self::Settings) -> Result<(Self, Self::Renderer), Error>;
+    /// Creates a new [`Compositor`].
+    fn new<W: HasRawWindowHandle>(
+        settings: Self::Settings,
+        compatible_window: Option<&W>,
+    ) -> Result<(Self, Self::Renderer), Error>;
 
     /// Crates a new [`Surface`] for the given window.
     ///
-    /// [`Surface`]: #associatedtype.Surface
+    /// [`Surface`]: Self::Surface
     fn create_surface<W: HasRawWindowHandle>(
         &mut self,
         window: &W,
@@ -31,8 +35,8 @@ pub trait Compositor: Sized {
 
     /// Crates a new [`SwapChain`] for the given [`Surface`].
     ///
-    /// [`SwapChain`]: #associatedtype.SwapChain
-    /// [`Surface`]: #associatedtype.Surface
+    /// [`SwapChain`]: Self::SwapChain
+    /// [`Surface`]: Self::Surface
     fn create_swap_chain(
         &mut self,
         surface: &Self::Surface,
@@ -42,8 +46,7 @@ pub trait Compositor: Sized {
 
     /// Draws the output primitives to the next frame of the given [`SwapChain`].
     ///
-    /// [`SwapChain`]: #associatedtype.SwapChain
-    /// [`Surface`]: #associatedtype.Surface
+    /// [`SwapChain`]: Self::SwapChain
     fn draw<T: AsRef<str>>(
         &mut self,
         renderer: &mut Self::Renderer,
@@ -52,5 +55,26 @@ pub trait Compositor: Sized {
         background_color: Color,
         output: &<Self::Renderer as iced_native::Renderer>::Output,
         overlay: &[T],
-    ) -> mouse::Interaction;
+    ) -> Result<mouse::Interaction, SwapChainError>;
+}
+
+/// Result of an unsuccessful call to [`Compositor::draw`].
+#[derive(Clone, PartialEq, Eq, Debug, Error)]
+pub enum SwapChainError {
+    /// A timeout was encountered while trying to acquire the next frame.
+    #[error(
+        "A timeout was encountered while trying to acquire the next frame"
+    )]
+    Timeout,
+    /// The underlying surface has changed, and therefore the swap chain must be updated.
+    #[error(
+        "The underlying surface has changed, and therefore the swap chain must be updated."
+    )]
+    Outdated,
+    /// The swap chain has been lost and needs to be recreated.
+    #[error("The swap chain has been lost and needs to be recreated")]
+    Lost,
+    /// There is no more memory left to allocate a new frame.
+    #[error("There is no more memory left to allocate a new frame")]
+    OutOfMemory,
 }
diff --git a/graphics/src/window/gl_compositor.rs b/graphics/src/window/gl_compositor.rs
index 1f37642e..34d70be3 100644
--- a/graphics/src/window/gl_compositor.rs
+++ b/graphics/src/window/gl_compositor.rs
@@ -15,28 +15,27 @@ use core::ffi::c_void;
 /// If you implement an OpenGL renderer, you can implement this trait to ease
 /// integration with existing windowing shells, like `iced_glutin`.
 pub trait GLCompositor: Sized {
-    /// The renderer of the [`Compositor`].
+    /// The renderer of the [`GLCompositor`].
     ///
     /// This should point to your renderer type, which could be a type alias
     /// of the [`Renderer`] provided in this crate with with a specific
     /// [`Backend`].
     ///
-    /// [`Compositor`]: trait.Compositor.html
-    /// [`Renderer`]: ../struct.Renderer.html
-    /// [`Backend`]: ../backend/trait.Backend.html
+    /// [`Renderer`]: crate::Renderer
+    /// [`Backend`]: crate::Backend
     type Renderer: iced_native::Renderer;
 
-    /// The settings of the [`Compositor`].
+    /// The settings of the [`GLCompositor`].
     ///
     /// It's up to you to decide the configuration supported by your renderer!
     type Settings: Default;
 
-    /// Creates a new [`Compositor`] and [`Renderer`] with the given
+    /// Creates a new [`GLCompositor`] and [`Renderer`] with the given
     /// [`Settings`] and an OpenGL address loader function.
     ///
-    /// [`Compositor`]: trait.Compositor.html
-    /// [`Renderer`]: #associatedtype.Renderer
-    /// [`Backend`]: ../backend/trait.Backend.html
+    /// [`Renderer`]: crate::Renderer
+    /// [`Backend`]: crate::Backend
+    /// [`Settings`]: Self::Settings
     #[allow(unsafe_code)]
     unsafe fn new(
         settings: Self::Settings,
@@ -44,19 +43,15 @@ pub trait GLCompositor: Sized {
     ) -> Result<(Self, Self::Renderer), Error>;
 
     /// Returns the amount of samples that should be used when configuring
-    /// an OpenGL context for this [`Compositor`].
-    ///
-    /// [`Compositor`]: trait.Compositor.html
+    /// an OpenGL context for this [`GLCompositor`].
     fn sample_count(settings: &Self::Settings) -> u32;
 
-    /// Resizes the viewport of the [`Compositor`].
-    ///
-    /// [`Compositor`]: trait.Compositor.html
+    /// Resizes the viewport of the [`GLCompositor`].
     fn resize_viewport(&mut self, physical_size: Size<u32>);
 
     /// Draws the provided output with the given [`Renderer`].
     ///
-    /// [`Compositor`]: trait.Compositor.html
+    /// [`Renderer`]: crate::Renderer
     fn draw<T: AsRef<str>>(
         &mut self,
         renderer: &mut Self::Renderer,