Struct theo::Display

pub struct Display { /* private fields */ }

The display used to manage all surfaces.

This type contains all common types that can be shared among surfaces. It also contains methods for creating new surfaces. Most interactions with theo will be done through this type.

The backend used by this type is determined by the DisplayBuilder used to create it. By default, it will try to use the following backends in order. If one fails, it will try the next one.

• wgpu
• OpenGL
• Software rasterizer

This type also has properties that are useful for creating new surfaces. For example, you can use Display::supports_transparency to check if the display supports transparent backgrounds.

Examples

use theo::Display;

// Create a new display.
let mut display = unsafe { Display::new(&my_display) }.unwrap();

// Use the display to create a new window.
let mut window_builder = WindowBuilder::new()
    .with_transparency(display.supports_transparency());

if cfg!(using_x11) {
    if let Some(visual) = display.x11_visual() {
        unsafe {
            window_builder = window_builder.with_x11_visual(visual.as_ptr());
        }
    }
}

// Create the window.
let window = window_builder.build();

// Use the window to create a new theo surface.
let surface = unsafe {
    display.make_surface(
        &window,
        window.width(),
        window.height(),
    ).await.unwrap()
};

Implementations

impl Display

pub fn builder() -> DisplayBuilder

Create a new DisplayBuilder.

This is a shorthand that allows the user to avoid having to import the DisplayBuilder type.

pub unsafe fn new(display: impl HasRawDisplayHandle) -> Result<Self, Error>

Create a new, default Display.

This is a shorthand for DisplayBuilder::new().build().

Safety

The display handle must be a valid display that isn’t currently suspended. See the safety requirements of DisplayBuilder::build for more information.

Example

use theo::Display;

let event_loop = winit::event_loop::EventLoop::new();
let display = unsafe { Display::new(&event_loop) }.unwrap();

pub async unsafe fn make_surface( &mut self, window: impl HasRawWindowHandle, width: u32, height: u32 ) -> Result<Surface, Error>

Create a new Surface from a window.

This function creates the state that theo associates with a window with the provided width and height. The Surface can be used with the Display to draw to the window.

Asynchronous

This function is asynchronous, as it may be necessary to wait for data to become available. This is only used for the wgpu backend, as it requires the adapter to be created asynchronously. For remaining backends, this future will not return Pending.

Safety

The window handle must be a valid window that isn’t currently suspended. The width and height parameters aren’t necessarily required to be correct, but it’s recommended that they are in order to avoid visual bugs.

Examples

use theo::Display;
use winit::event_loop::EventLoop;
use winit::window::Window;

let event_loop = EventLoop::new();
let mut display = unsafe { Display::new(&event_loop) }.unwrap();

// In a real-world use case, parameters from the `display` would be used to create the window.
let window = Window::new(&event_loop).unwrap();
let size = window.inner_size();

// Create a new surface from the window.
let surface = unsafe {
    display.make_surface(
        &window,
        size.width,
        size.height,
    ).await.unwrap()
};

impl Display

pub fn supports_transparency(&self) -> bool

Whether or not this display supports transparent backgrounds.

If this is true, then the Surfaces created from this display will support transparency if the underlying windowing system supports it. You should use this to decide whether or not to use a transparent background.

Example

use theo::Display;

let event_loop = winit::event_loop::EventLoop::new();
let display = unsafe { Display::new(&event_loop) }.unwrap();

if display.supports_transparency() {
    create_transparent_window();
} else {
    create_opaque_window();
}

pub fn x11_visual(&self) -> Option<NonNull<()>>

The X11 visual used by this display, if any.

This is useful for creating Surfaces with a specific visual. On X11, you can use this to create a surface.

Example

use theo::Display;

let event_loop = winit::event_loop::EventLoop::new();
let display = unsafe { Display::new(&event_loop) }.unwrap();

let visual = display.x11_visual().unwrap();

pub async unsafe fn make_surface_from_raw( &mut self, window: RawWindowHandle, width: u32, height: u32 ) -> Result<Surface, Error>

Create a new Surface from a raw window handle.

This is equivalent to Display::make_surface, except that it takes a raw window handle instead of a window. This is useful if you want to create a surface from a window that doesn’t implement RawWindowHandle.

Asynchronous

This function is asynchronous, as it may be necessary to wait for data to become available. This is only used for the wgpu backend, as it requires the adapter to be created asynchronously. For remaining backends, this future will not return Pending.

Safety

The window handle must be a valid window that isn’t currently suspended. The width and height parameters aren’t necessarily required to be correct, but it’s recommended that they are in order to avoid visual bugs.

pub async fn present(&mut self)

Push the queue and present to all known surfaces.

This is necessary to call after all windows have been drawn to. It should be called once all windows that need to be drawn to have already been drawn to.

Asynchronous

For most backends, this is a no-op. For wgpu, it submits the queue and then waits for all of the queues to finish submitting.

Trait Implementations

impl Debug for Display

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.