Crate glin[][src]

Easy to use, light OpenGL 3+ wrapper

glin aims to be a mostly bindless, simple wrapper over opengl that simplifies and provides a safe api for opengl without aiming to cover every possible case but instead making it easy to use unsafe calls in combination with the safe api when one needs to use extensions or any opengl api that is not covered (yet).

That means for example that in certain cases functions will take GLenums directly as parameters when the particular parameter can change or have several options not originally on the standard through extensions, while parameters that have clearly defined options in the standard will have an enum representation.

Usage

The first thing needed to use glin is a Context. A context needs an instance implementing GLWindow to be able to load the Open GL or Open GL ES functions:

#![allow(unused_imports)]

extern crate glfw;
extern crate glin;
extern crate egli;
extern crate glutin;

use glfw::Context;

#[cfg(feature = "glfw")]
fn main(){
    let mut glfw_instance = glfw::init(glfw::FAIL_ON_ERRORS).unwrap();

    glfw_instance.window_hint(glfw::WindowHint::ContextVersion(4, 1));
    glfw_instance.window_hint(glfw::WindowHint::OpenGlProfile( glfw::OpenGlProfileHint::Core ));
    glfw_instance.window_hint(glfw::WindowHint::OpenGlForwardCompat(true));
    let (mut window, receiver) = glfw_instance
        .create_window(1280, 720, "triangle", glfw::WindowMode::Windowed).unwrap();
    window.set_key_polling(true);
    window.make_current();
    glfw_instance.set_swap_interval(glfw::SwapInterval::Sync(1));

    let _context = glin::Context::new(&mut window).unwrap();
}

use egli::Display;

#[cfg(feature = "egli")]
fn main(){
    use std::ptr;

    let mut display = Display::from_default_display()
        .expect("failed to get EGL display");

    display.initialize()
        .expect("failed to initialize");

    let configs = display.config_filter()
                         .choose_configs()
                         .expect("failed to get configurations");

    let config = *configs.first().unwrap();
    let surface = display.create_window_surface(config, ptr::null_mut()).unwrap();

    let context = display
        .create_context_with_client_version(config, egli::ContextClientVersion::OpenGlEs2)
        .unwrap();

    display.make_current(&surface, &surface, &context).unwrap();

    let _context = glin::Context::new(&mut display).unwrap();
}


use glutin::GlContext;

#[cfg(feature = "glutin")]
fn main(){
    let mut events_loop = glutin::EventsLoop::new();
    let window = glutin::WindowBuilder::new()
        .with_title("Hello, world!")
        .with_dimensions(1024, 768);
    let context = glutin::ContextBuilder::new()
        .with_vsync(true);
    let mut gl_window = glutin::GlWindow::new(window, context, &events_loop).unwrap();

    unsafe {
        gl_window.make_current().unwrap();
    }

    let _context = glin::Context::new(&mut gl_window).unwrap();
}

#[cfg(not(any(feature = "glfw", feature = "egli", feature = "glutin")))]
fn main(){

}

Once we have a context we can start creating glin objects and issuing draw calls through it.

Creating glin Objects

To create any glin object you need a context and the constructor calls are done through that context which generally returns a builder that can be customized with more parameters to finally create the desired object:

use std::mem;
use glin::gl;

struct Vertex{
    position: [f32;3],
}

fn main(){
    let gl: glin::Context = unsafe{ mem::uninitialized() };
    let buffer_object: glin::BufferObject<Vertex> = gl.new_buffer().empty().unwrap();
    let program = gl.new_program().from_src(&[
            (gl::VERTEX_SHADER, "// vertex shader source"),
            (gl::FRAGMENT_SHADER, "// fragment shader source"),
        ]).unwrap();
    let _texture = gl.new_texture().from_format(glin::texture::Format{
        target: gl::TEXTURE_2D,
        internal_format: gl::RGBA,
        width: 640,
        height: 480,
        levels: 1,
        #[cfg(all(not(feature = "gles"), not(feature="webgl")))]
        samples: 0,
    });
}

Drawing

Drawing geometry in glin is done through vaos. A VAO is just an OpenGL vertex array object but also contains a memory reference to the buffers it uses internally.

Apart from the geometry in order to draw something in glin you'll need a glsl program, it's uniforms and optionally some properties that customize the drawing.

To use a set of properties, just call with on an exisiting context to create a new context with the original properties + the new properties passed as parameter:

#[macro_use] extern crate glin;
use std::mem;
use glin::gl;

#[derive(VertexFormat)]
struct Vertex{
    position: [f32;3],
}

fn main(){
    let gl: glin::Context = unsafe{ mem::uninitialized() };
    let buffer_object: glin::BufferObject<Vertex> = gl.new_buffer().empty().unwrap();
    let program = gl.new_program().from_src(&[
            (gl::VERTEX_SHADER, "// vertex shader source"),
            (gl::FRAGMENT_SHADER, "// fragment shader source"),
        ]).unwrap();
    let vao: glin::SimpleVao<Vertex> = gl.new_simple_vao()
        .empty_from_bindings(&program, gl::TRIANGLES)
        .unwrap();
    let gl = gl.with(&[glin::Property::DepthTest(true)]);
    gl.draw(&vao, &program, &[]).is_ok();
}

Modules

attributes

glsl attributes and utilities to represent them in vaos

buffer_object

Buffer Objects are the main way of storing data to be used by the GPU

cubemap
fbo
gl
macros
program
query
simple_vao
texture
vao

Macros

attribute_format_by_name
impl_to_attribute_format
uniforms

easy way to set uniforms to pass a draw call

Structs

BufferObject

A mutable buffer object allocated with gl(Named)BufferData

BufferObjectImmutable

Inmmutable buffer object allocated with gl(Named)BufferStorage

Context

Used to issue draw calls

CreationProxy
CubeMap

Wrapper for a Texture allocated as a CubeMap

DebugInfo
Error
Fbo

Wrapper for an OpenGL frame buffer object

MapReadFlags
MapReadWriteFlags
MapWriteFlags
Program

A wrapper for a glsl program

Rect
Sampler

Wraps an OpenGL sampler

Screen
SharedBuffer

Wrapper around a BufferObject with internal reference counting

SharedBufferImmutable

Wrapper around a BufferObjectImmutable with internal reference counting

SimpleVao

Is a simplified version of VAO

State

Represents the state of a Context

Texture

Wraps an OpenGL texture + some metadata about it's format

TextureSampler
Vao

A wrapper for an OpenGL VAO

Enums

DebugSeverity
DebugSource
DebugType
ErrorKind
Property

Traits

Bindings

Attribute bindings in a program

BufferRange

A view into a portion of a buffer object

CreationContext
CubemapImage
GlWindow
Image
OffscreenBuffer
RenderSurface
SurfaceCreationContext
VaoDraw

VaoRange + a draw mode

VaoRange

range of a vao's vertices or elements

VertexFormat

Implemented by vertex types to convert attribute bindings into attribute formats

Functions

gl_format_from_internal
gl_type_from_internal

Type Definitions

IndexT
Result