surfman/x11/surface.rs
1// surfman/src/platform/unix/x11/surface.rs
2//
3//! A surface implementation using X11 surfaces backed by TextureImage.
4
5use crate::base::egl::surface::{EGLBackedSurface, EGLSurfaceTexture};
6use std::marker::PhantomData;
7use x11_dl::xlib::Window;
8
9/// Represents a hardware buffer of pixels that can be rendered to via the CPU or GPU and either
10/// displayed in a native widget or bound to a texture for reading.
11///
12/// Surfaces come in two varieties: generic and widget surfaces. Generic surfaces can be bound to a
13/// texture but cannot be displayed in a widget (without using other APIs such as Core Animation,
14/// DirectComposition, or XPRESENT). Widget surfaces are the opposite: they can be displayed in a
15/// widget but not bound to a texture.
16///
17/// Surfaces are specific to a given context and cannot be rendered to from any context other than
18/// the one they were created with. However, they can be *read* from any context on any thread (as
19/// long as that context shares the same adapter and connection), by wrapping them in a
20/// `SurfaceTexture`.
21///
22/// Depending on the platform, each surface may be internally double-buffered.
23///
24/// Surfaces must be destroyed with the `destroy_surface()` method, or a panic will occur.
25#[derive(Debug)]
26pub struct Surface(pub(crate) EGLBackedSurface);
27
28/// Represents an OpenGL texture that wraps a surface.
29///
30/// Reading from the associated OpenGL texture reads from the surface. It is undefined behavior to
31/// write to such a texture (e.g. by binding it to a framebuffer and rendering to that
32/// framebuffer).
33///
34/// Surface textures are local to a context, but that context does not have to be the same context
35/// as that associated with the underlying surface. The texture must be destroyed with the
36/// `destroy_surface_texture()` method, or a panic will occur.
37#[derive(Debug)]
38pub struct SurfaceTexture(pub(crate) EGLSurfaceTexture);
39
40/// A wrapper for a Wayland surface, with associated size.
41#[derive(Clone)]
42pub struct NativeWidget {
43 pub(crate) window: Window,
44}
45
46unsafe impl Send for Surface {}
47
48/// Represents the CPU view of the pixel data of this surface.
49pub struct SurfaceDataGuard<'a> {
50 phantom: PhantomData<&'a ()>,
51}