surfman/platform/unix/
default.rs

1// surfman/src/platform/unix/default.rs
2//
3//! The default backend for Unix, which dynamically switches between Wayland, X11 and surfaceless.
4
5/// Wayland or X11 display server connections.
6pub mod connection {
7    use crate::platform::generic::multi::connection::Connection as MultiConnection;
8    use crate::platform::generic::multi::connection::NativeConnection as MultiNativeConnection;
9    use crate::platform::generic::multi::device::Device as MultiDevice;
10    use crate::platform::unix::generic::device::Device as SWDevice;
11    use crate::platform::unix::wayland::device::Device as WaylandDevice;
12    use crate::platform::unix::x11::device::Device as X11Device;
13    type HWDevice = MultiDevice<WaylandDevice, X11Device>;
14
15    /// Either a Wayland or an X11 display server connection.
16    pub type Connection = MultiConnection<HWDevice, SWDevice>;
17
18    /// Either a Wayland or an X11 native connection
19    pub type NativeConnection = MultiNativeConnection<HWDevice, SWDevice>;
20}
21
22/// OpenGL rendering contexts.
23pub mod context {
24    use crate::platform::generic::multi::context::Context as MultiContext;
25    use crate::platform::generic::multi::context::ContextDescriptor as MultiContextDescriptor;
26    use crate::platform::generic::multi::context::NativeContext as MultiNativeContext;
27    use crate::platform::generic::multi::device::Device as MultiDevice;
28    use crate::platform::unix::generic::device::Device as SWDevice;
29    use crate::platform::unix::wayland::device::Device as WaylandDevice;
30    use crate::platform::unix::x11::device::Device as X11Device;
31    type HWDevice = MultiDevice<WaylandDevice, X11Device>;
32
33    /// Represents an OpenGL rendering context.
34    ///
35    /// A context allows you to issue rendering commands to a surface. When initially created, a
36    /// context has no attached surface, so rendering commands will fail or be ignored. Typically,
37    /// you attach a surface to the context before rendering.
38    ///
39    /// Contexts take ownership of the surfaces attached to them. In order to mutate a surface in
40    /// any way other than rendering to it (e.g. presenting it to a window, which causes a buffer
41    /// swap), it must first be detached from its context. Each surface is associated with a single
42    /// context upon creation and may not be rendered to from any other context. However, you can
43    /// wrap a surface in a surface texture, which allows the surface to be read from another
44    /// context.
45    ///
46    /// OpenGL objects may not be shared across contexts directly, but surface textures effectively
47    /// allow for sharing of texture data. Contexts are local to a single thread and device.
48    ///
49    /// A context must be explicitly destroyed with `destroy_context()`, or a panic will occur.
50    pub type Context = MultiContext<HWDevice, SWDevice>;
51
52    /// Information needed to create a context. Some APIs call this a "config" or a "pixel format".
53    ///
54    /// These are local to a device.
55    pub type ContextDescriptor = MultiContextDescriptor<HWDevice, SWDevice>;
56
57    /// Either a Wayland or an X11 native context
58    pub type NativeContext = MultiNativeContext<HWDevice, SWDevice>;
59}
60
61/// Thread-local handles to devices.
62pub mod device {
63    use crate::platform::generic::multi::device::Adapter as MultiAdapter;
64    use crate::platform::generic::multi::device::NativeDevice as MultiNativeDevice;
65    use crate::platform::unix::generic::device::Device as SWDevice;
66    use crate::platform::unix::wayland::device::Device as WaylandDevice;
67    use crate::platform::unix::x11::device::Device as X11Device;
68
69    use crate::platform::generic::multi::device::Device as MultiDevice;
70    type HWDevice = MultiDevice<WaylandDevice, X11Device>;
71
72    /// Represents a hardware display adapter that can be used for rendering (including the CPU).
73    ///
74    /// Adapters can be sent between threads. To render with an adapter, open a thread-local
75    /// `Device`.
76    pub type Adapter = MultiAdapter<HWDevice, SWDevice>;
77
78    /// A thread-local handle to a device.
79    ///
80    /// Devices contain most of the relevant surface management methods.
81    pub type Device = MultiDevice<HWDevice, SWDevice>;
82
83    /// Either a Wayland or an X11 native device
84    pub type NativeDevice = MultiNativeDevice<HWDevice, SWDevice>;
85}
86
87/// Hardware buffers of pixels.
88pub mod surface {
89    use crate::platform::generic::multi::device::Device as MultiDevice;
90    use crate::platform::generic::multi::surface::NativeWidget as MultiNativeWidget;
91    use crate::platform::generic::multi::surface::Surface as MultiSurface;
92    use crate::platform::generic::multi::surface::SurfaceTexture as MultiSurfaceTexture;
93    use crate::platform::unix::generic::device::Device as SWDevice;
94    use crate::platform::unix::wayland::device::Device as WaylandDevice;
95    use crate::platform::unix::x11::device::Device as X11Device;
96    type HWDevice = MultiDevice<WaylandDevice, X11Device>;
97
98    /// A wrapper for a Wayland surface or an X11 `Window`, as appropriate.
99    pub type NativeWidget = MultiNativeWidget<HWDevice, SWDevice>;
100
101    /// Represents a hardware buffer of pixels that can be rendered to via the CPU or GPU and
102    /// either displayed in a native widget or bound to a texture for reading.
103    ///
104    /// Surfaces come in two varieties: generic and widget surfaces. Generic surfaces can be bound
105    /// to a texture but cannot be displayed in a widget (without using other APIs such as Core
106    /// Animation, DirectComposition, or XPRESENT). Widget surfaces are the opposite: they can be
107    /// displayed in a widget but not bound to a texture.
108    ///
109    /// Surfaces are specific to a given context and cannot be rendered to from any context other
110    /// than the one they were created with. However, they can be *read* from any context on any
111    /// thread (as long as that context shares the same adapter and connection), by wrapping them
112    /// in a `SurfaceTexture`.
113    ///
114    /// Depending on the platform, each surface may be internally double-buffered.
115    ///
116    /// Surfaces must be destroyed with the `destroy_surface()` method, or a panic will occur.
117    pub type Surface = MultiSurface<HWDevice, SWDevice>;
118
119    /// Represents an OpenGL texture that wraps a surface.
120    ///
121    /// Reading from the associated OpenGL texture reads from the surface. It is undefined behavior
122    /// to write to such a texture (e.g. by binding it to a framebuffer and rendering to that
123    /// framebuffer).
124    ///
125    /// Surface textures are local to a context, but that context does not have to be the same
126    /// context as that associated with the underlying surface. The texture must be destroyed with
127    /// the `destroy_surface_texture()` method, or a panic will occur.
128    pub type SurfaceTexture = MultiSurfaceTexture<HWDevice, SWDevice>;
129
130    // FIXME(pcwalton): Revamp how this works.
131    #[doc(hidden)]
132    pub struct SurfaceDataGuard {}
133}
surfman/platform/unix/default.rs

surfman/platform/unix/
default.rs
