molgfx_gpu/
surface.rs

1//! The presentation surface trait.
2//!
3//! A lost or outdated surface is a value, never a panic: acquisition
4//! returns a typed error, the caller reconfigures and reports the frame as
5//! skipped, and the next frame recovers.
6
7use crate::descriptors::TextureFormat;
8use crate::device::Device;
9use thiserror::Error;
10
11/// Why a frame could not be acquired.
12#[derive(Clone, Copy, PartialEq, Eq, Debug, Error)]
13#[non_exhaustive]
14pub enum SurfaceError {
15    /// The surface is lost; reconfigure before the next acquire.
16    #[error("surface lost")]
17    Lost,
18    /// The surface no longer matches the window; reconfigure.
19    #[error("surface outdated")]
20    Outdated,
21    /// Acquisition timed out this frame.
22    #[error("surface acquire timed out")]
23    Timeout,
24    /// The system is out of memory for surface buffers.
25    #[error("surface out of memory")]
26    OutOfMemory,
27}
28
29/// Surface configuration, refreshed on resize.
30#[derive(Clone, Copy, PartialEq, Eq, Debug)]
31pub struct SurfaceConfig {
32    /// Width in pixels.
33    pub width: u32,
34    /// Height in pixels.
35    pub height: u32,
36    /// The swapchain format the surface chose at open.
37    pub format: TextureFormat,
38}
39
40/// One acquired swapchain frame.
41pub trait SurfaceFrame<D: Device> {
42    /// The frame's render-target view.
43    fn view(&self) -> &D::TextureView;
44
45    /// Presents the frame.
46    fn present(self);
47}
48
49/// A presentation surface bound to a window.
50pub trait Surface<D: Device>: Sized {
51    /// The acquired-frame type.
52    type Frame: SurfaceFrame<D>;
53
54    /// (Re)configures for the given size; called on open and on resize.
55    fn configure(&mut self, device: &D, config: &SurfaceConfig);
56
57    /// The current configuration.
58    fn config(&self) -> &SurfaceConfig;
59
60    /// Acquires the next frame.
61    ///
62    /// # Errors
63    ///
64    /// Lost, outdated, timed out, or out of memory — all recoverable by
65    /// reconfiguring and skipping the frame.
66    fn acquire(&mut self) -> Result<Self::Frame, SurfaceError>;
67}
molgfx_gpu/surface.rs

molgfx_gpu/
surface.rs
