mew/

winitutils.rs

//! Utilities for working with windows & surfaces.
//!
//! To bundle a
//! [`winit::window::Window`](https://docs.rs/winit/latest/winit/window/struct.Window.html)
//! with its
//! [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html),
//! you're looking for [`SurfaceWindow`].
//!
//! For an abstraction over WebGL's retardedness having to provide a surface
//! before you can get a _wgpu_ adapter, see [`DeferredContext`].


use std::{
    cell::{
        BorrowMutError,
        Cell,
        RefCell,
        RefMut,
        UnsafeCell,
    },
    sync::{
        Arc,
        mpsc::{
            Receiver,
        },
    },
};
use thiserror::Error;
use winit::{
    dpi::PhysicalSize,
    error::OsError,
    window::{ Window, WindowAttributes, },
    event_loop::ActiveEventLoop,
};
use crate::{ RenderContext, RenderContextBuilder, BuildContextError, };


/// Error returned when waiting for a [`RenderContext`] to be built.
#[derive(Clone, Debug, Error)]
pub enum BuildDeferredContextError {
    /// Something went wrong with the actual building of the [`RenderContext`].
    #[error(transparent)]
    BuildContext(#[from] BuildContextError),
    /// The thread or async task dropped (only on web).
    #[error("Context builder thread dropped before finishing")]
    BuilderThreadDied,
}

/// Error returned trying to get the [`RenderContext`] from a [`DeferredContext`].
#[derive(Clone, Debug, Error)]
pub enum GetDeferredContextError {
    /// Something went wrong actually building the [`RenderContext`].
    /// This is a fatal error, if it fails you should probably just `panic!`.
    #[error(transparent)]
    Build(#[from] BuildDeferredContextError),
    /// On web, you need to provide a canvas surface to create a
    /// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html)
    /// before you can even get to the [`RenderContext`]. This is done automatically
    /// when you create a new window through [`DeferredContext::create_window`].
    #[error("No compatible surface has been provided yet to construct an Adapter")]
    RequiresSurface,
    /// On web, the async builder task hasn't returned a result yet. Building a
    /// [`RenderContext`] should be quick though, so if you see this something might be
    /// wrong.
    #[error("No context available yet, waiting on builder thread to finish")]
    StillBuilding,
}


/// Error returned when configuring a surface or making a texture view for the
/// surface.
#[derive(Clone, Debug, Error)]
pub enum ConfigSurfaceError {
    /// _wgpu_ could not create a surface, see
    /// [`wgpu::Instance::create_surface`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html#method.create_surface).
    #[error(transparent)]
    CreateSurface(#[from] wgpu::CreateSurfaceError),
    /// The surface already has an active view - a new one can't be created, nor can
    /// the current one be reconfigured.
    #[error("Surface is already active")]
    InUse,
    /// Can't reconfigure the surface because it hasn't been created or configured
    /// yet. Non-fatal, but run [`SurfaceWindow::init_with_context`] first.
    #[error("Surface hasn't been created or configured yet")]
    NotInitialized,
    /// Trying to use the surface failed. Non-fatal, but call
    /// [`SurfaceWindow::drop_surface`] to re-initialize it. Also see
    /// [`wgpu::SurfaceError`](https://docs.rs/wgpu/latest/wgpu/enum.SurfaceError.html).
    #[error(transparent)]
    SurfaceError(#[from] wgpu::SurfaceError),
    /// The surface that tried to be configure wasn't supported by this adapter. Don't
    /// mix & match resources between [`RenderContext`]s!
    #[error("Surface not supported by adapter - don't mix & match between contexts!")]
    Unsupported,
}

impl From<BorrowMutError> for ConfigSurfaceError {
    fn from(_e: BorrowMutError) -> Self {
        Self::InUse
    }
}


/// Error returned when trying to create a window.
#[derive(Debug, Error)]
pub enum CreateWindowError {
    /// The _winit_ event loop couldn't create a window for whatever reason, see
    /// [`winit::ActiveEventLoop::create_window`](https://docs.rs/winit/latest/x86_64-unknown-linux-gnu/winit/event_loop/struct.ActiveEventLoop.html#method.create_window).
    #[error(transparent)]
    Window(#[from] OsError),
    /// The window was created but _wgpu_ couldn't configure its surface.
    #[error(transparent)]
    ConfigSurface(#[from] ConfigSurfaceError),
}

impl From<wgpu::CreateSurfaceError> for CreateWindowError {
    fn from(e: wgpu::CreateSurfaceError) -> Self {
        Self::ConfigSurface(e.into())
    }
}


fn clamp_config_size(config: &mut wgpu::SurfaceConfiguration, device: &wgpu::Device, mut size: PhysicalSize<u32>) {
    let max_allowed_size = device.limits().max_texture_dimension_2d;
    let max_config_size = size.width.max(size.height);
    if max_config_size > max_allowed_size {
        let ratio = max_allowed_size as f32 / max_config_size.max(1) as f32;
        size.width = (size.width as f32 * ratio) as u32;
        size.height = (size.height as f32 * ratio) as u32;
    }

    config.width = size.width.max(1);
    config.height = size.height.max(1);
}


/// Persistent configuration for surfaces, which may be destroyed & re-created.
/// Overrides defaults of [`wgpu::SurfaceConfiguration`](https://docs.rs/wgpu/latest/wgpu/type.SurfaceConfiguration.html).
#[derive(Debug, Default)]
pub struct SurfaceConfigOptions {
    /// The surface's [`wgpu::PresentMode`](https://docs.rs/wgpu/latest/wgpu/enum.PresentMode.html).
    pub present_mode: Option<wgpu::PresentMode>,
    /// The surface's max frame latency.
    pub frame_latency: Option<u32>,
    /// The surface's [`wgpu::CompositeAlphaMode`](https://docs.rs/wgpu/latest/wgpu/enum.CompositeAlphaMode.html).
    pub alpha_mode: Option<wgpu::CompositeAlphaMode>,
}


/// A combined
/// [`winit::window::Window`](https://docs.rs/winit/latest/winit/window/struct.Window.html)
/// &
/// [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html).
#[derive(Debug)]
pub struct SurfaceWindow {
    config_opts: SurfaceConfigOptions,
    surface: RefCell<Option<Arc<wgpu::Surface<'static>>>>,
    window: Arc<Window>,
    target_size: Cell<Option<PhysicalSize<u32>>>,
    reconfigure: Cell<bool>,
}

impl SurfaceWindow {
    /// Create a new window under an
    /// [`winit::ActiveEventLoop`](https://docs.rs/winit/latest/winit/event_loop/struct.ActiveEventLoop.html).
    ///
    /// Also requires a
    /// [`winit::window::WindowAttributes`](https://docs.rs/winit/latest/winit/window/struct.WindowAttributes.html)
    /// (though [`Default`] should work fine for most cases) and a [`SurfaceConfigOptions`]
    /// ([`Default`] should be fine here too).
    pub fn new(event_loop: &ActiveEventLoop, attributes: WindowAttributes, config_opts: SurfaceConfigOptions) -> Result<Self, OsError> {
        let window = Arc::new(event_loop.create_window(attributes)?);
        Ok(Self {
            config_opts,
            //config: OnceCell::new(),
            surface: RefCell::new(None),
            window,
            target_size: Cell::new(None),
            reconfigure: Cell::new(false),
            //_config_lock: RefCell::new(()),
        })
    }

    /*
    /// Try to get the [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html),
    /// if it's been built.
    ///
    /// This is marked `unsafe` because reconfiguring this surface while it has an
    /// active view will cause _wgpu_ to panic. _wgpu_ doesn't enforce this so I
    /// gotta.
    pub unsafe fn try_get_surface(&self) -> Option<&wgpu::Surface<'static>> {
        self.surface.get().map(|s| &**s)
    }
    */

    /// Try to get the [`wgpu::SurfaceConfiguration`](https://docs.rs/wgpu/latest/wgpu/type.SurfaceConfiguration.html),
    /// if the surface has been created.
    pub fn try_get_config(&self) -> Option<wgpu::SurfaceConfiguration> {
        unsafe { &*self.surface.as_ptr() }
            .as_ref().and_then(|s| s.get_configuration())
    }

    /// Get a reference to the window.
    pub fn window(&self) -> &Window {
        &self.window
    }

    /*
    /// Get an [`Arc`] to the window.
    pub fn window_arc(&self) -> Arc<Window> {
        self.window.clone()
    }
    */

    /*
    fn get_surface(&self, instance: &wgpu::Instance) -> Result<(&Arc<wgpu::Surface<'static>>, bool), wgpu::CreateSurfaceError> {
        match self.surface.get() {
            Some(s) => Ok((s, false)),
            None => {
                let surface = instance.create_surface(self.window.clone())
                    .map(|s| s.into())?;
                Ok((self.surface.get_or_init(|| surface), true))
            },
        }
    }

    fn get_config(&self, surface: &wgpu::Surface<'static>, adapter: &wgpu::Adapter, device: &wgpu::Device) -> Option<(&wgpu::SurfaceConfiguration, bool)> {
        match self.config.get() {
            Some(c) => Some((c, false)),
            None => {
                let size = self.get_size();

                let mut config = surface.get_default_config(adapter, 0, 0)?;
                clamp_config_size(&mut config, device, size);

                self.config_opts.present_mode.map(|pm| config.present_mode = pm);
                self.config_opts.frame_latency.map(|fl| config.desired_maximum_frame_latency = fl);
                self.config_opts.alpha_mode.map(|am| config.alpha_mode = am);

                Some((self.config.get_or_init(|| config), true))
            },
        }
    }
    */

    /*
    fn get_surface(&self, instance: &wgpu::Instance) -> Result<&Arc<wgpu::Surface<'static>>, ConfigSurfaceError> {
        let mut lock = self.surface.try_borrow_mut()?;
        match &*lock {
            Some(s) => Ok(s),
            None => {
                let surface = self.make_surface(instance)?;
                Ok(lock.insert(Arc::new(surface)))
            },
        }
    }
    */

    fn make_surface(&self, instance: &wgpu::Instance) -> Result<wgpu::Surface<'static>, wgpu::CreateSurfaceError> {
        instance.create_surface(self.window.clone())
    }

    fn make_config(&self, surface: &wgpu::Surface<'static>, adapter: &wgpu::Adapter, device: &wgpu::Device) -> Option<wgpu::SurfaceConfiguration> {
        let mut config = surface.get_default_config(adapter, 0, 0)?;

        self.config_opts.present_mode.map(|pm| config.present_mode = pm);
        self.config_opts.frame_latency.map(|fl| config.desired_maximum_frame_latency = fl);
        self.config_opts.alpha_mode.map(|am| config.alpha_mode = am);

        let size = self.target_size.get()
            .unwrap_or_else(|| self.get_size());
        clamp_config_size(&mut config, device, size);

        Some(config)
    }

    /// Opaquely create, configure, and get the
    /// [`wgpu::SurfaceTexture`](https://docs.rs/wgpu/latest/wgpu/struct.SurfaceTexture.html)
    /// &
    /// [`wgpu::TextureView`](https://docs.rs/wgpu/latest/wgpu/struct.TextureView.html)
    /// of the underlying
    /// [`winit::window::Window`](https://docs.rs/winit/latest/winit/window/struct.Window.html).
    ///
    /// If the window's
    /// [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html)
    /// hasn't been created yet, it will do so now. If needed it'll make a new
    /// [`wgpu::SurfaceConfiguration`](https://docs.rs/wgpu/latest/wgpu/type.SurfaceConfiguration.html)
    /// using either the window's inner size or a manually provided one from
    /// the last [`Self::resize`].
    ///
    /// Next, it'll try getting its
    /// [`wgpu::SurfaceTexture`](https://docs.rs/wgpu/latest/wgpu/struct.SurfaceTexture.html)
    /// with
    /// [`wgpu::Surface::get_current_texture`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html#method.get_current_texture).
    /// This may fail if the surface was old and needed to be refreshed, in which
    /// case it'll need to fully recreate the surface. If getting the surface
    /// texture fails a 2nd time, the error will be raised to the caller.
    ///
    /// Only one [`ActiveSurfaceWindow`] is allowed at any one time, this is
    /// enforced during runtime.
    pub fn init_surface(&self, instance: &wgpu::Instance, adapter: &wgpu::Adapter, device: &wgpu::Device) -> Result<ActiveSurfaceWindow<'_>, ConfigSurfaceError> {
        let mut surface_lock = self.surface.try_borrow_mut()?;

        /*
        // See if surface is already created, configured, & doesn't need a reconfig,
        // then just try to get its texture
        let maybe_texture = surface_lock.as_ref()
            .filter(|_| !self.reconfigure.get())
            .filter(|s| s.get_configuration().is_some())
            .and_then(|s| s.get_current_texture().ok());

        // Surface may be borked, re-create it and then try to get its texture again
        let (surface, texture) = match maybe_texture {
            Some(t) => (RefMut::map(surface_lock, |sl| sl.as_mut().unwrap()), t),
            None => {
                let surface = match &*surface_lock {
                    // Exists but needs configuration. If also borked will be fixed in next call
                    Some(s) if s.get_configuration().is_none() || self.reconfigure.replace(false) => {
                        RefMut::map(surface_lock, |sl| sl.as_mut().unwrap())
                    },
                    // Exists & is configured but borked & needs to be recreated, or doesn't exist
                    _ => {
                        let new_surface = self.make_surface(instance)?;
                        RefMut::map(surface_lock, |sl| sl.insert(Arc::new(new_surface)))
                    },
                };
                let config = self.make_config(&surface, adapter, device)
                    .ok_or(ConfigSurfaceError::Unsupported)?;
                surface.configure(device, &config);

                let texture = surface.get_current_texture()?;

                (surface, texture)
            },
        };
        */

        let reconfigure = self.reconfigure.replace(false);
        let old_size = surface_lock.as_ref().and_then(|s| s.get_configuration()).map(|c| (c.width, c.height));
        let mut resized = false;

        // (Re)configure if surface exists & configuration is needed
        if let Some(surface) = &*surface_lock && (surface.get_configuration().is_none() || reconfigure) {
            let config = self.make_config(&surface, adapter, device)
                .ok_or(ConfigSurfaceError::Unsupported)?;
            surface.configure(device, &config);
            resized = old_size != Some((config.width, config.height));
        }

        let texture = match surface_lock.as_ref().and_then(|s| s.get_current_texture().ok()) {
            Some(t) => t,
            None => {
                // Surface borked, recreate everything
                let new_surface = Arc::new(self.make_surface(instance)?);
                let surface = surface_lock.insert(new_surface);

                let config = self.make_config(&surface, adapter, device)
                    .ok_or(ConfigSurfaceError::Unsupported)?;
                surface.configure(device, &config);

                resized = old_size != Some((config.width, config.height));

                // Get texture of new surface, if this errors something is really borked
                surface.get_current_texture()?
            },
        };

        let view = texture.texture.create_view(&wgpu::TextureViewDescriptor {
            format: Some(texture.texture.format()),
            ..Default::default()
        });

        Ok(ActiveSurfaceWindow {
            surface: RefMut::map(surface_lock, |sl| sl.as_mut().expect("Surface should have been created")),
            window: &self.window,
            texture,
            view,
            resized,
        })
    }

    /// Get a usable [`ActiveSurfaceWindow`], which guarantees that the window
    /// surface exists & is configured.
    ///
    /// See [`Self::init_surface`] for more details.
    pub fn init_with_context(&self, context: &RenderContext) -> Result<ActiveSurfaceWindow<'_>, ConfigSurfaceError> {
        self.init_surface(&context.instance, &context.adapter, &context.device)
    }

    /// Try to drop the surface.
    pub fn try_drop_surface(&self) -> Result<(), BorrowMutError> {
        let _ = self.surface.try_borrow_mut()?.take();
        Ok(())
    }

    /// Drop the surface now.
    pub fn drop_surface(&mut self) {
        let _ = self.surface.get_mut().take();
    }

    /*
    /// Try to reconfigure the surface, optionally specifying the surface's new size
    /// or `None` to query the window's inner size. Call this on _winit_ window
    /// resize events, after the surface has been created & initialized.
    ///
    /// Will return an error if no surface exists yet or if it hasn't already been
    /// configured, though this isn't fatal - just run [`Self::init_with_context`]
    /// first.  
    /// [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html)s
    /// also can't be reconfigured while they have an active view (while an
    /// [`ActiveSurfaceWindow`] exists), so it'll return another error. It isn't
    /// fatal either.
    pub fn try_reconfigure(&self, device: &wgpu::Device, target_size: Option<PhysicalSize<u32>>) -> Result<(), ConfigSurfaceError> {
        // Cannot reconfigure if an ActiveSurfaceWindow exists
        let surface_lock = self.surface.try_borrow_mut()?;
        let surface = surface_lock.as_ref().ok_or(ConfigSurfaceError::NotInitialized)?;
        /*
        let mut config = self.get_config.get_mut().ok_or(())?;
        clamp_config_size(config, device, size);
        */

        let size = target_size
            //.filter(|s| s.width != 0 && s.height != 0)
            .unwrap_or_else(|| self.get_size());

        let config = surface.get_configuration()
            .map(|mut c| { clamp_config_size(&mut c, device, size); c })
            .ok_or(ConfigSurfaceError::NotInitialized)?;

        surface.configure(device, &config);
        Ok(())
    }
    */

    /// Set the target window size and trigger a reconfiguration.
    ///
    /// If you pass `None`, the size will be queried from the window, or you can
    /// specify it from a _winit_ resize event. The surface will be reconfigured
    /// when it's next initialized.
    pub fn resize(&self, size: Option<PhysicalSize<u32>>) {
        self.target_size.set(size);
        self.reconfigure();
    }

    /// Mark the surface to be reconfigured when it's next initialized.
    pub fn reconfigure(&self) {
        self.reconfigure.set(true);
    }

    /// Convenience function to get the window's inner size.
    pub fn get_size(&self) -> PhysicalSize<u32> {
        self.window.inner_size()
    }
}


/// A borrowed form of [`SurfaceWindow`] which guarantees that its surface
/// exists & is configured, ready to be rendered to.
///
/// Only one instance is allowed at any time (per [`SurfaceWindow`]). _wgpu_
/// panics if multiple
/// [`wgpu::SurfaceTexture`](https://docs.rs/wgpu/latest/wgpu/struct.SurfaceTexture.html)s
/// exist in specific conditions, so the safest thing to do is make sure only
/// one can exist.
#[must_use]
pub struct ActiveSurfaceWindow<'w> {
    //surface: &'w wgpu::Surface<'static>,
    //config: &'w wgpu::SurfaceConfiguration,
    surface: RefMut<'w, Arc<wgpu::Surface<'static>>>,
    window: &'w Window,
    texture: wgpu::SurfaceTexture,
    view: wgpu::TextureView,
    resized: bool,
}

impl ActiveSurfaceWindow<'_> {
    /// Get the window's [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html).
    ///
    /// This is `unsafe` because reconfiguring this surface while it has an
    /// active view will cause _wgpu_ to panic. _wgpu_ doesn't enforce this so I
    /// gotta. In other words:  
    /// ***ABSOLUTELY DO NOT CALL
    /// [`wgpu::Surface::configure`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html#method.configure)
    /// ON THIS SURFACE***
    pub unsafe fn surface(&self) -> &wgpu::Surface<'static> {
        &*self.surface
    }

    /// Get the surface's [`wgpu::SurfaceConfiguration`](https://docs.rs/wgpu/latest/wgpu/type.SurfaceConfiguration.html).
    ///
    /// Under the hood, `self.surface().get_configuration().unwrap()` - the surface
    /// is guaranteed to be configured if it made it into this struct.
    pub fn config(&self) -> wgpu::SurfaceConfiguration {
        self.surface.get_configuration()
            .expect("Surface should have been configured before constructing ActiveSurfaceWindow")
    }

    /// Get the [`winit::window::Window`](https://docs.rs/winit/latest/winit/window/struct.Window.html).
    pub fn window(&self) -> &Window {
        self.window
    }

    /// Convenience function to get the window's inner size.
    pub fn get_size(&self) -> PhysicalSize<u32> {
        self.window.inner_size()
    }

    /// Convenience function to get the configured size of the surface.
    ///
    /// Resize events may not be sent in time before a frame runs, leading to
    /// desyncs. This may cause a panic on _wgpu_'s side if you have a depth, which
    /// needs to always be kept the same size as the configured surface.  
    /// See also [`Self::resized`].
    pub fn get_config_size(&self) -> PhysicalSize<u32> {
        let config = self.config();
        PhysicalSize {
            width: config.width,
            height: config.height,
        }
    }

    /// Get the surface's
    /// [`wgpu::SurfaceTexture`](https://docs.rs/wgpu/latest/wgpu/struct.SurfaceTexture.html).
    pub fn texture(&self) -> &wgpu::SurfaceTexture {
        &self.texture
    }

    /// Get the surface texture's
    /// [`wgpu::TextureView`](https://docs.rs/wgpu/latest/wgpu/struct.TextureView.html)
    /// with default settings.
    pub fn view(&self) -> &wgpu::TextureView {
        &self.view
    }

    /// Returns `true` if the surface has just been resized (reconfigured or rebuilt
    /// with a new size since last frame).
    ///
    /// Useful to keep a depth stencil buffer in-sync.
    pub fn resized(&self) -> bool {
        self.resized
    }

    /// Get a [`wgpu::RenderPassColorAttachment`](https://docs.rs/wgpu/latest/wgpu/struct.RenderPassColorAttachment.html)
    /// to attach this surface's texture to a render pass, to draw to it using a
    /// specified clear colour.
    pub fn as_colour_attachment<'a>(&'a self, clear: Option<wgpu::Color>) -> wgpu::RenderPassColorAttachment<'a> {
        wgpu::RenderPassColorAttachment {
            view: &self.view,
            depth_slice: None,
            resolve_target: None,  // ???
            ops: wgpu::Operations {
                load: clear.map(|colour| wgpu::LoadOp::Clear(colour)).unwrap_or(wgpu::LoadOp::Load),
                store: wgpu::StoreOp::Store,
            },
        }
    }

    /// Present the graphics operations to the surface. Consumes this struct, init a
    /// new one for next frame.
    pub fn present_texture(self) {
        self.window.pre_present_notify();
        self.texture.present();
    }
}


#[derive(Debug)]
#[allow(dead_code)]
enum ContextState {
    WaitingForSurface {
        builder: RenderContextBuilder,
    },
    Building {
        receiver: Receiver<Result<RenderContext, BuildContextError>>,
    },
    Resolved {
        context: Result<RenderContext, BuildDeferredContextError>,
    },
}

impl ContextState {
    fn provide_surface(&mut self, surface: Arc<wgpu::Surface<'static>>) {
        match self {
            Self::WaitingForSurface { builder, } => {
                builder.with_compatible_surface(Some(surface));
                let builder =  // IF UNUSED, add feature `poll` or `webgl`
                    builder.clone();
                // If you're going to be using DeferredContext, you need to provide
                // a polling method - either by adding feature `poll` (for native)
                // or `webgl` (for web).

                #[cfg(all(feature = "webgl", not(feature = "poll")))]
                {
                    use std::sync::mpsc::sync_channel;
                    let (send, recv) = sync_channel::<Result<RenderContext, BuildContextError>>(1);
                    wasm_bindgen_futures::spawn_local(async move {
                        let context = builder.build().await;
                        let _ = send.send(context);
                    });

                    *self = Self::Building { receiver: recv, };
                }

                #[cfg(all(not(feature = "webgl"), feature = "poll"))]
                {
                    let context = pollster::block_on(builder.build())
                        .map(|c| c.into()).map_err(|e| e.into());
                    *self = Self::Resolved { context, };
                }

                #[cfg(all(feature = "webgl", feature = "poll"))]
                unreachable!("Ambiguous whether to start JS thread or poll, only one feature of `webgl` or `poll` should be enabled");

                #[cfg(not(any(feature = "webgl", feature = "poll")))]
                unreachable!("No way to poll for context, one feature of `webgl` or `poll` should be enabled");
            },
            _ => {},
        }
    }

    fn poll_resolve_context(&mut self) -> Result<&RenderContext, GetDeferredContextError> {
        match self {
            Self::WaitingForSurface { .. } => Err(GetDeferredContextError::RequiresSurface),
            Self::Building { receiver, } => {
                use std::sync::mpsc::TryRecvError;

                match receiver.try_recv() {
                    Ok(context) => {
                        let context = context.map_err(|e| e.into());
                        *self = Self::Resolved { context, };
                        let Self::Resolved { context, } = self else { unreachable!() };
                        Ok(context.as_ref().map_err(|e| e.clone())?)
                    },
                    Err(TryRecvError::Disconnected) => {
                        *self = Self::Resolved { context: Err(BuildDeferredContextError::BuilderThreadDied), };
                        Err(BuildDeferredContextError::BuilderThreadDied.into())
                    },
                    Err(TryRecvError::Empty) => Err(GetDeferredContextError::StillBuilding),
                }
            },
            Self::Resolved { context, } => Ok(context.as_ref().map_err(|e| e.clone())?),
        }
    }

    /*
    fn try_get_context(&self) -> Option<Rc<RenderContext>> {
        match self {
            Self::Resolved { context, } => context.as_ref().map(|c| c.ok()).flatten().clone(),
            _ => None,
        }
    }
    */
}


/// Defer the contstruction of the [`RenderContext`] until a surface is
/// constructed.
///
/// WebGL really screws up the normal workflow of "first create your _wgpu_
/// handles, then make windows and stuff", because creating the
/// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html)
/// requires a
/// [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html)
/// to be passed in after creating it with a
/// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html)
/// using the configuration of a
/// [`winit::window::Window`](https://docs.rs/winit/latest/winit/window/struct.Window.html).
/// To top it all off, this painful back-and-forth involves `async`.
///
/// On web, this struct caches a builder and constructs the [`RenderContext`]
/// in a JS thread oppurtunistically when it is used to construct a
/// [`SurfaceWindow`].  
/// Native platforms block the thread when constructing, it's not an operation
/// that should take very long. _pollster_ doesn't seem to get along with JS
/// however.
///
/// See example usage below. There's a bit of jumping through hoops, but most of
/// it is handled in the background.
/// ```rust
/// impl ApplicationHandler for YourApp {
///     fn resume(&mut self, event_loop: &ActiveEventLoop) {
///         // Create a window and provide the surface to the deferred context to start building.
///         // In the worst case (web), at this point it will have an unconfigured surface and no config.
///         let window = self.window.get_or_init(|| {
///             let mut attributes = WindowAttributes::default();
///             #[cfg(target_arch = "wasm32")]
///             attributes.with_canvas(get_webgl_canvas());
///             // On web, will provide the surface to the context builder so it can
///             // start building the context. The surface isn't configured until it's needed.
///             self.deferred_context.create_window(event_loop, attributes, Default::default())
///                 .expect("Couldn't create window");
///         });
///
///         // Can't do much else until we have a valid context, which may take until
///         // the next function call to finish building. Move on to main loop.
///         self.suspended = false;
///     }
///
///     fn window_event(&mut self, event_loop: &ActiveEventLoop, window_id: _, event: _) {
///         if self.suspended { return; }
///
///         let context = match self.defered_context.get_context() {
///             Ok(c) => c,
///             // Something went wrong building the context, abort.
///             Err(GetDeferredContextError::Build(e)) => panic!("Error building context: {e}"),
///             // resume() didn't run for some reason, RenderContext has no surface
///             // to use to initialize with (on web).
///             Err(GetDeferredContextError::RequiresSurface) => unreachable!("Surface should have been provided in resume()"),
///             // Still building, will try again next window_event().
///             Err(GetDeferredContextError::StillBuilding) => return,
///         };
///
///         // Now that the context is ready, we can finish configuring the window surface.
///         // init_surface() will create everything when needed and make sure it's configured.
///         let active_window = self.window.get().expect("Window should have created in resume()")
///             .init_with_context(&context).expect("Couldn't init window");
///
///         // Side-note: Vertex/shader buffers, pipelines, etc. are also dependent on the
///         // RenderContext being configured (with a surface on web).
///         // Put the buffers in an Option/OnceCell and generate them ASAP.
///         let buffers_and_shit = self.buffers_and_shit.get_or_insert_with(|| init_buffers_and_shit(&context, active_window));
///
///         Self::finally_render(context, active_window);
///     }
///
///     fn suspended(&mut self, event_loop: &ActiveEventLoop) {
///         // Android requires surfaces be dropped on suspend. init_surface() above
///         // will re-create and configure the window surface automatically when unsuspended.
///         self.window.get_mut().map(|w| w.drop_surface());
///         self.suspended = true;
///     }
/// }
/// ```
#[derive(Debug)]
pub struct DeferredContext {
    instance: wgpu::Instance,
    context: UnsafeCell<ContextState>,
}

impl DeferredContext {
    /// Create a new deferred builder from a regular builder, with the appropriate
    /// method for the platform.
    ///
    /// On web, this will call [`Self::new_requiring_surface`]; on native with the
    /// `poll` feature, [`Self::new_poll`].
    #[cfg(any(feature = "webgl", feature = "poll", docs))]
    pub fn new(builder: RenderContextBuilder) -> Self {
        #[cfg(feature = "webgl")]
        return Self::new_requiring_surface(builder);
        #[cfg(feature = "poll")]
        return Self::new_poll(builder);
    }

    /// Create a new deferred builder from a regular builder, in "waiting-for-surface"
    /// mode. On native you don't have to use this unless you really want to validate
    /// the surface format is compatible.
    #[cfg(any(feature = "webgl", feature = "poll", docs))]
    pub fn new_requiring_surface(mut builder: RenderContextBuilder) -> Self {
        let instance = builder.get_instance();
        Self {
            instance,
            context: ContextState::WaitingForSurface { builder, }.into(),
        }
    }

    /// Create a future that immediately tries to `await` the finalization of a
    /// [`RenderContextBuilder`].
    ///
    /// It's not really intended to use _mew_ in an async environment - the app as
    /// a whole can contain async logic, sure, but rendering stuff deserves its own
    /// system thread.
    #[cfg(any(not(feature = "webgl"), docs))]
    pub async fn new_async(mut builder: RenderContextBuilder) -> Self {
        let instance = builder.get_instance();
        let context = builder.build().await.map(|c| c.into()).map_err(|e| e.into());
        Self {
            instance,
            context: ContextState::Resolved { context, }.into(),
        }
    }

    /// Immediately try to finalize a [`RenderContextBuilder`], by blocking on
    /// [`Self::new_async`].
    ///
    /// Realistically, it should not take long at all to build a [`RenderContext`].
    /// Even if it does, it should be fine to block the main render thread because,
    /// well, what are you going to render without a context?
    #[cfg(any(all(not(feature = "webgl"), feature = "poll"), docs))]
    pub fn new_poll(builder: RenderContextBuilder) -> Self {
        pollster::block_on(Self::new_async(builder))
    }

    /// Create a [`SurfaceWindow`], and at the same time, provide the builder with
    /// a WebGL surface so it can create a valid
    /// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html).
    ///
    /// In effect, you can almost ignore the whole initialization workflow - just
    /// make a window in the event loop, and then get the context to draw to it.
    /// If you can't get the context, try again until you can.
    pub fn create_window(&self, event_loop: &ActiveEventLoop, attributes: WindowAttributes, config_opts: SurfaceConfigOptions) -> Result<SurfaceWindow, CreateWindowError> {
        let mut window = SurfaceWindow::new(event_loop, attributes, config_opts)?;
        let surface = Arc::new(window.make_surface(&self.instance)?);
        let _ = window.surface.get_mut().insert(surface.clone());
        unsafe { &mut *self.context.get() }.provide_surface(surface);
        /*
        if let Ok(context) = self.get_context() {
            window.init_surface(&context.instance, &context.adapter, &context.device)?;
        }
        */
        Ok(window)
    }

    /// Get a clone of the
    /// [`wgpu::Instance`](https://docs.rs/wgpu/latest/wgpu/struct.Instance.html),
    /// which may have been created automatically.
    pub fn get_instance(&self) -> wgpu::Instance {
        self.instance.clone()
    }

    /// Try to get the [`RenderContext`].
    ///
    /// If it hasn't been built yet, or if it ran into an error while building,
    /// you'll get an `Err(_)` - try again next frame.
    ///
    /// On web, make sure to create a window with [`Self::create_window`], as you
    /// can't get a
    /// [`wgpu::Adapter`](https://docs.rs/wgpu/latest/wgpu/struct.Adapter.html)
    /// before providing a
    /// [`wgpu::Surface`](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html).  
    /// Makes sense, right? Totally not backwards? That's why I made this.
    pub fn get_context(&self) -> Result<&RenderContext, GetDeferredContextError> {
        let context_state = unsafe { &mut *self.context.get() };
        context_state.poll_resolve_context()
    }
}