DOCSEARCHbyAlgolia
Submit Docs

glutin

repository·master·Indexed 24 days ago

https://github.com/rust-windowing/glutin

A low-level Rust library for cross-platform OpenGL context creation. It serves as a foundational component in rendering pipelines and is often used with windowing libraries like winit. Glutin provides the mechanism for context creation but does not provide OpenGL bindings directly; users must use separate tools like gl_generator for bindings.

Tokens
7.7K
Snippets
14
Records
52
Agent score
84%

What's inside glutin

  2. Use glutin-winit for cross-platform glutin bootstrapping

    master
    The glutin-winit crate provides a way to bootstrap a glutin Display using winit as the windowing library. It is designed for cross-platform compatibility and serves as a reference implementation for integrating glutin with cross-platform windowing libraries.

  3. Understand the role of glutin in your stack

    master

    Glutin is a low-level library specifically for OpenGL context creation.

    It does not provide OpenGL bindings directly. You will need to use a separate tool or crate (such as gl_generator) to generate or provide the OpenGL bindings for your application. Glutin is designed to be a low-level building block, and it is recommended to implement your own abstraction layer between glutin and your high-level application logic.

  4. Handle Android lifecycle with glutin and winit

    master

    When targeting Android using winit, you must synchronize GL surface creation with the Android lifecycle events to avoid crashes or undefined behavior:

    1. Create the GL surface only after winit emits Event::Resumed.
    2. Destroy the GL surface when winit emits Event::Suspended.

    For a complete implementation, refer to the android.rs example in the glutin_examples directory.

  5. Run the Android example using cargo-apk

    master

    To compile and run the Android example on a physical device or emulator, you must have cargo-apk installed. Use the following command to run the android example from the glutin_examples package:

    $ cargo apk r -p glutin_examples --example android

  6. Run glutin examples locally

    master

    To try out the library using the provided examples, clone the repository and use cargo run with the window example. Note that these examples are written for the master branch and use gl_generator to provide OpenGL bindings.

    git clone https://github.com/rust-windowing/glutin
cd glutin
cargo run --example window

  7. Understand the Glutin initialization lifecycle

    master

    Glutin provides an OpenGL context across multiple platforms by abstracting underlying differences. The initialization process follows this flow:

    1. Load and connect to the platform's graphics API by creating a display.
    2. Use the display object to create all subsequent OpenGL objects, including:
      • config (Pixel formats/configurations)
      • context (The OpenGL state machine)
      • surface (The actual rendering area/buffer)

  8. Manage OpenGL context state with NotCurrentContext and PossiblyCurrentContext

    master

    Glutin uses a type-state pattern to manage the lifecycle and thread-safety of OpenGL contexts. This ensures that you cannot use a context on a thread unless it is explicitly made 'not current' (allowing it to be moved) or 'current' (allowing it to be used for rendering).

    1. NotCurrentContext

    Representing a context that is not current on any thread. This type is Send, meaning you can move it to a different thread. To use it, you must make it current.

    • make_current(surface): Makes the context current on the calling thread and returns a PossiblyCurrentContext.
    • make_current_surfaceless(): Makes the context current without a default framebuffer.
    • treat_as_possibly_current(): Upgrades the context to PossiblyCurrentContext without changing its current status.

    2. PossiblyCurrentContext

    Representing a context that might be current on the calling thread. This type is neither Send nor Sync because it is tied to the thread's local state. To move it to another thread, you must first make it not current.

    • make_not_current(): Makes the context not current and returns a NotCurrentContext (which is Send).
    • make_not_current_in_place(): Makes the context not current without changing the type.
    • is_current(): Returns true if the context is currently active on this thread.
    • make_current(surface): Re-affirms the context as current on this thread.

  9. Configure OpenGL API preference

    master

    The ApiPreference enum allows you to specify how glutin should prioritize different OpenGL backend providers (like EGL, GLX, or WGL) during bootstrapping.

    • FallbackEgl (Default): Attempts to use the system provider first, falling back to EGL if the system provider fails.
    • PreferEgl: Explicitly prefers EGL over system providers like GLX or WGL.

  10. Manage OpenGL rendering with the Surface type

    master

    The Surface<T> type represents a cross-platform OpenGL surface used for rendering. It is Send but not Sync, meaning you can move it to a different thread, but you cannot access it from multiple threads simultaneously. The type is generic over T, which defines the surface type (e.g., WindowSurface, PbufferSurface, or PixmapSurface).

    Common operations available via the GlSurface trait include:

    • swap_buffers(&self, context: &Self::Context): Swaps the back and front buffers.
    • set_swap_interval(&self, context: &Self::Context, interval: SwapInterval): Sets the swap interval (e.g., for VSync).
    • buffer_age(&self): Returns the age of the back buffer. A value of 0 indicates a new buffer or a failure to retrieve age, requiring a full redraw.
    • resize(&self, context: &Self::Context, width: NonZeroU32, height: NonZeroU32): Resizes the surface (primarily used on Wayland; often a no-op on other platforms).
    • width(&self) and height(&self): Returns the physical dimensions of the surface.

  11. Configure OpenGL settings with ConfigTemplateBuilder

    master

    Use ConfigTemplateBuilder to define the requirements for an OpenGL configuration (e.g., buffer sizes, multisampling, API type). This template is then used to match and select suitable configurations from the display.

    Commonly used methods include:

    • with_alpha_size(u8): Sets alpha bits (default 8).
    • with_depth_size(u8): Sets depth buffer bits (default 24).
    • with_stencil_size(u8): Sets stencil buffer bits (default 8).
    • with_multisampling(u8): Requests multisampling. The value must be a power of two.
    • with_api(Api): Filters by supported API (e.g., Api::OPENGL, Api::GLES2).
    • with_transparency(bool): Requests a configuration that supports transparency.
    • compatible_with_native_window(RawWindowHandle): Ensures the configuration is suitable for rendering into a specific native window.
    • with_surface_type(ConfigSurfaceTypes): Specifies required surface types like WINDOW, PIXMAP, or PBUFFER.

  12. Configure Glutin API backends

    master

    Glutin requires at least one API backend to be selected during compilation. If no backend is enabled, the crate will fail to compile with the error: Please select at least one api backend.

    Supported backends include:

    • egl_backend
    • glx_backend
    • wgl_backend
    • cgl_backend