Struct theo::DisplayBuilder

pub struct DisplayBuilder { /* private fields */ }

A builder containing system-specific information to create a Display.

The DisplayBuilder is used to create a Display. It allows the user to submit some parameters to the Display to customize its behavior. It is also used to provide essential parameters on some platforms; for instance, on X11, an XlibErrorHook is required to use the GLX backend.

Examples

use theo::Display;

let mut builder = Display::builder();

// Provide a window handle to bootstrap the context.
builder = builder.window(&window);

// Provide an error hook for GLX.
builder = builder.glx_error_hook(register_x11_error_hook);

// Force using software rendering.
builder = builder.force_swrast(true);

// Disable use of transparency.
builder = builder.transparent(false);

// Create the display.
let display = unsafe { builder.build(&my_display) };

Implementations

impl DisplayBuilder

pub fn new() -> Self

Create a new DisplayBuilder with default parameters.

Examples

use theo::DisplayBuilder;

let builder = DisplayBuilder::new();

pub fn window(self, window: impl HasRawWindowHandle) -> Self

Set the raw window handle to use to bootstrap the context.

This is only necessary for WGL bootstrapping. A window is necessary for querying for the WGL extensions. If you don’t provide a window, the context will be created with fewer available extensions. This is not necessary for any other platforms or backends.

Examples

use theo::DisplayBuilder;
use winit::window::Window;

let window: Window = create_window();

let mut builder = DisplayBuilder::new();

// Only needed on Windows.
#[cfg(target_os = "windows")]
{
    builder = builder.window(&window);
}

pub fn glx_error_hook(self, hook: impl Fn(XlibErrorHook) + 'static) -> Self

Set the error handler for GLX.

For the GLX platform, an error handler is required in order to properly handle errors. Error handling in Xlib is part of the global state, so there needs to be a single “source of truth” for error handling. This “source of truth” should support taking a closure that handles the error. This closure is then called whenever an error occurs.

For theo, this method allows passing in a closure that allows adding an error handler to the global state. This closure is then called whenever an error occurs.

For winit, you should pass in register_xlib_error_hook.

Examples

use std::os::raw::c_int;
use std::ptr;
use std::sync::Mutex;

use theo::{DisplayBuilder, XlibErrorHook};
use x11_dl::xlib::{Display, Xlib, XErrorEvent};

// A list of error handlers.
static ERROR_HANDLERS: Mutex<Vec<XlibErrorHook>> = Mutex::new(Vec::new());

// Register an error handler function.
// Note: This is a not a production-ready error handler. A real error handler should
// handle panics and interop with the rest of the application.
unsafe {
    unsafe extern "C" fn error_handler(
        display: *mut Display,
        event: *mut XErrorEvent
    ) -> c_int {
        let mut handlers = ERROR_HANDLERS.lock().unwrap();
        for handler in &*handlers {
            if (handler)(display.cast(), event.cast()) {
                break;
            }
        }
        0
    }

    let xlib = Xlib::open().unwrap();
    let display = (xlib.XOpenDisplay)(ptr::null());
    (xlib.XSetErrorHandler)(Some(error_handler));
}

let mut builder = DisplayBuilder::new();

// Provide an error hook for GLX.
builder = builder.glx_error_hook(|hook| {
    // Add the error hook to the list of error handlers.
    ERROR_HANDLERS.lock().unwrap().push(hook);
});

pub fn transparent(self, transparent: bool) -> Self

Set whether or not we should support transparent backgrounds.

Some backends, such as the software rasterizer, do not support transparency. On the other hand, others, such as EGL, do. This method allows you to set whether or not we should support transparent backgrounds.

Examples

use theo::DisplayBuilder;

let mut builder = DisplayBuilder::new();
builder = builder.transparent(false);

pub fn force_swrast(self, force_swrast: bool) -> Self

Force software rendering.

theo contains a software rasterization backend which is used as a fallback when no other backend is available. This method allows you to force the software rasterizer to be used even when other backends are available. This can be used, for example, to test the software rasterizer or to avoid using hardware acceleration.

Examples

use theo::DisplayBuilder;

let mut builder = DisplayBuilder::new();
builder = builder.force_swrast(true);

pub unsafe fn build( self, display: impl HasRawDisplayHandle ) -> Result<Display, Error>

Build a new Display.

Using the provided parameters, this method will attempt to build a new Display. If successful, it will return a new Display. Otherwise, it will return an error.

Safety

• The display handle must be a valid display that isn’t currently suspended.
• The window handle, if any, must also be valid.

Examples

use theo::DisplayBuilder;

let event_loop = winit::event_loop::EventLoop::new();
let mut builder = DisplayBuilder::new();
let display = unsafe { builder.build(&event_loop) }.unwrap();

impl DisplayBuilder

pub unsafe fn build_from_raw( self, raw: RawDisplayHandle ) -> Result<Display, Error>

Build the Display from a raw display handle.

This is equivalent to DisplayBuilder::build, but takes a raw display handle instead of a type that implements HasRawDisplayHandle. This is useful for implementing HasRawDisplayHandle for types that don’t own their display.

Safety

The raw handle must be a valid display that isn’t currently suspended. The raw handle must be valid for the duration of the Display.

Trait Implementations

impl Default for DisplayBuilder

fn default() -> Self

Returns the “default value” for a type.