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