Struct theo::DisplayBuilder
source · pub struct DisplayBuilder { /* private fields */ }
Expand description
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§
source§impl DisplayBuilder
impl DisplayBuilder
sourcepub fn new() -> Self
pub fn new() -> Self
Create a new DisplayBuilder
with default parameters.
Examples
use theo::DisplayBuilder;
let builder = DisplayBuilder::new();
sourcepub fn window(self, window: impl HasRawWindowHandle) -> Self
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);
}
sourcepub fn glx_error_hook(self, hook: impl Fn(XlibErrorHook) + 'static) -> Self
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);
});
sourcepub fn transparent(self, transparent: bool) -> Self
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);
sourcepub fn force_swrast(self, force_swrast: bool) -> Self
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);
sourcepub unsafe fn build(
self,
display: impl HasRawDisplayHandle
) -> Result<Display, Error>
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 validdisplay
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();
source§impl DisplayBuilder
impl DisplayBuilder
sourcepub unsafe fn build_from_raw(
self,
raw: RawDisplayHandle
) -> Result<Display, Error>
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§
Auto Trait Implementations§
impl !RefUnwindSafe for DisplayBuilder
impl !Send for DisplayBuilder
impl !Sync for DisplayBuilder
impl Unpin for DisplayBuilder
impl !UnwindSafe for DisplayBuilder
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere T: Any,
§fn into_any(self: Box<T, Global>) -> Box<dyn Any, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any, Global>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.§fn into_any_rc(self: Rc<T, Global>) -> Rc<dyn Any, Global>
fn into_any_rc(self: Rc<T, Global>) -> Rc<dyn Any, Global>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.