Introduction

The Rust programming language aims to provide a safe environment, where you can't get any undefined behavior or crash. Glium is a Rust library that aims to push these goals for OpenGL as well.

Its objectives:

Be 100 % safe to use.
Avoid all OpenGL errors either with compile-time checks or runtime checks. If an OpenGL error is triggered, then it's a bug.
Provide all the features that core OpenGL provides.
Be compatible with the lowest OpenGL version possible, but still use 4.5 features if they are available.
Be compatible with both OpenGL and OpenGL ES.

Examples

Initialization

use glium::DisplayBuild;
let display = glutin::WindowBuilder::new().build_glium().unwrap();

Glium is based on the Glutin library, which is a pure Rust alternative to traditional libraries like GLFW, SDL or GLUT. When you call build_glium(), Glium will build the window and query various informations about the backend. While Glutin is a partially unsafe library due to the unsafe nature of OpenGL contexts, Glium on the other hand is totally safe.

The minimal requirements for Glium to start is an OpenGL 2.1 or an OpenGL ES 2 backend. If these are not met, build_glium returns an Err.

Loading an image into a texture

let image_data = File::open(&Path::new("image.png")).unwrap().read_to_end().unwrap();
let image = image::load(image_data, image::PNG).unwrap();
let texture = glium::texture::CompressedTexture2d::new(&display, image);

Glium interacts well with the image library, allowing one to easily load images.

You don't need to worry about client formats, data alignment, immutable storage, etc. Everything is handled automatically.

Render to texture

use glium::texture::UncompressedFloatFormat::U8U8U8U8;

let mut texture = glium::Texture2d::new_empty(display, U8U8U8U8, 1024, 1024);

texture.as_surface().draw(&vertex_buffer, &index_buffer, &program,
                      &uniforms, &params).unwrap();

Drawing on a texture is as easy as calling texture.as_surface(). Glium provides easy ways to execute the most common tasks.

If you need some more elaborate features (like a depth or stencil buffer, or multiple render targets), Glium provides some structs in the framebuffer module.

Persistent mapping

struct UniformBlockData {
    matrix: [[f32; 4]; 4],
    light: [f32; 3]
}

let mut buffer = glium::UniformBuffer::new_persistent(&display, UniformBlockData {
    matrix: build_identity_matrix(),
    light: [12.4, -0.4, 3.8]
});

loop {
    buffer.map().light[0] += 0.1;   // `map()` returns the existing mapping

    // the mapping must be released before using the buffer
    texture.as_surface().draw(&vertex_buffer, &index_buffer, &program,
                              uniforms! { MyBlock: &buffer }, &params).unwrap();

    // at the next cycle, the call to `buffer.map()` will block until the GPU has finished
    // its draw call
}

High-performance OpenGL applications need to reduce driver overhead by using techniques such as persistent mapping, indirect calls or bindless textures.

With raw OpenGL you need to take care not to write to a buffer while is is being used by the GPU, or it may result in a data race. Glium automatically handles this for you thanks to Rust's borrow checker and OpenGL's sync fences.

Getting started

Link to the documentation.

Need help?

Open an issue or contact @tomaka on #rust-gamedev