Struct glutin::ContextWrapper

source · [−]

pub struct ContextWrapper<T: ContextCurrentState, W> { /* private fields */ }

Expand description

A context which has an underlying window, which may or may not be stored separately.

If the window is stored separately, it is a RawContext<T>. Otherwise, it is a WindowedContext<T>.

Implementations

source

impl<T: ContextCurrentState> ContextWrapper<T, Window>

source

pub fn window(&self) -> &Window

Borrow the inner W.

source

pub unsafe fn split(self) -> (RawContext<T>, Window)

Split the Window apart from the OpenGL Context. Should only be used when intending to transfer the RawContext<T> to another thread.

Unsaftey:

The OpenGL Context must be dropped before the Window.

source

impl<W> ContextWrapper<PossiblyCurrent, W>

source

pub fn swap_buffers(&self) -> Result<(), ContextError>

Swaps the buffers in case of double or triple buffering.

You should call this function every time you have finished rendering, or the image may not be displayed on the screen.

Warning: if you enabled vsync, this function will block until the next time the screen is refreshed. However drivers can choose to override your vsync settings, which means that you can’t know in advance whether swap_buffers() will block or not.

source

pub fn swap_buffers_with_damage(
&self,
rects: &[Rect]
) -> Result<(), ContextError>

Swaps the buffers in case of double or triple buffering using specified damage rects.

You should call this function every time you have finished rendering, or the image may not be displayed on the screen.

Warning: if you enabled vsync, this function will block until the next time the screen is refreshed. However drivers can choose to override your vsync settings, which means that you can’t know in advance whether swap_buffers_with_damage() will block or not.

source

pub fn swap_buffers_with_damage_supported(&self) -> bool

Returns whether or not swap_buffer_with_damage is available. If this function returns false, any call to swap_buffers_with_damage will return an error.

source

pub fn get_pixel_format(&self) -> PixelFormat

Returns the pixel format of the main framebuffer of the context.

source

pub fn resize(&self, size: PhysicalSize<u32>)

Resize the context.

Some platforms (macOS, Wayland) require being manually updated when their window or surface is resized.

The easiest way of doing this is to take every WindowEvent::Resized that is received and pass its dpi::PhysicalSize into this function.

source

pub fn buffer_age(&self) -> u32

Query the underlying surface back’s buffer age.

Return n is the number of frames elapsed since it was most recently drawn.

source

impl<T: ContextCurrentState, W> ContextWrapper<T, W>

source

pub fn context(&self) -> &Context<T>

Borrow the inner GL Context.

source

pub unsafe fn make_current(
self
) -> Result<ContextWrapper<PossiblyCurrent, W>, (Self, ContextError)>

Sets this context as the current context. The previously current context (if any) is no longer current.

A failed call to make_current might make this, or no context current. It could also keep the previous context current. What happens varies by platform and error.

To attempt to recover and get back into a know state, either:

attempt to use is_current() to find the new current context; or
call make_not_current() on both the previously current context and this context.

A higher level overview.

In OpenGl, only a single context can be current in a thread at a time. Making a new context current will make the old one not current. Contexts can only be sent to different threads if they are not current.

If you call make_current() on some context, you should call treat_as_not_current() as soon as possible on the previously current context.

If you wish to move a currently current context to a different thread, you should do one of two options:

Call make_current() on another context, then call treat_as_not_current() on this context.
Call make_not_current() on this context.

If you are aware of what context you intend to make current next, it is preferable for performance reasons to call make_current() on that context, then call treat_as_not_current() on this context.

If you are not aware of what context you intend to make current next, consider waiting until you do. If you need this context not current immediately (e.g. to transfer it to another thread), then call make_not_current() on this context.

Please avoid calling make_not_current() on one context only to call make_current() on another context before and/or after. This hurts performance by requiring glutin to:

Check if this context is current; then
If it is, change the current context from this context to none; then
Change the current context from none to the new context.

Instead prefer the method we mentioned above with make_current() and treat_as_not_current().

source

pub unsafe fn make_not_current(
self
) -> Result<ContextWrapper<NotCurrent, W>, (Self, ContextError)>

If this context is current, makes this context not current. If this context is not current however, this function does nothing.

Please see make_current().

source

pub unsafe fn treat_as_not_current(self) -> ContextWrapper<NotCurrent, W>

Treats this context as not current, even if it is current. We do no checks to confirm that this is actually case.

If unsure whether or not this context is current, please use make_not_current() which will do nothing if this context is not current.

Please see make_current().

source

pub unsafe fn treat_as_current(self) -> ContextWrapper<PossiblyCurrent, W>

Treats this context as current, even if it is not current. We do no checks to confirm that this is actually case.

This function should only be used if you intend to track context currency without the limited aid of glutin, and you wish to store all the Contexts as NotCurrent.

Please see make_current() for the preferred method of handling context currency.

source