Crate glitter [] [src]

A type-safe, zero-cost OpenGL abstraction.

Introduction

OpenGL is an API designed for 2D and 3D rendering in a high-level, platform-agnostic way. In many situations, it is the only viable choice, considering platform, time, and performance requirements.

glitter is designed to provide a thin, zero-cost, type-safe wrapper for OpenGL. The API is designed to look and feel familiar to the plain C OpenGL API, so that translating code between glitter and OpenGL can be as painless as possible. Most OpenGL functions have a direct parallel in glitter, such as glClearColor, provided as gl.clear_color. Others provide several different wrapper functions to provide better type safety, such as glDrawElements, which is wrapped by gl.draw_elements, gl.draw_n_elements, and gl.draw_n_elements_buffered.

Additionally, some higher-level abstractions are included, usually to reduce boilerplate or to provide a common interface to work across multiple OpenGL versions. A simple example is the gl.build_program interface, which makes it quick and easy to create and link a program object, while also correctly checking and reporting any errors.

A good starting starting point to dive into glitter is the context module. This module is the home of the ContextOf type, which is the main entry point to making OpenGL calls.

OpenGL Version Support

Currently, glitter only supports OpenGL ES 2, although the goal is to enable support for targeting any OpenGL version. An example of what this entails is the VertexBuffer type. The current implementation of VertexBuffer uses OpenGL "vertex buffer objects" under the hood. However, OpenGL also has a complimentary feature, called "vertex array objects", that could replace the current implementation and reduce the number of draw calls. Unfortunately, this API is not available in OpenGL ES 2 (without an extension, that is). In a future version of glitter, the goal is to update VertexBuffer to use vertex array objects, and to fall back to vertex buffer objects when vertex array objects are unavailable.

Thread Safety

Eventually, glitter should support proper thread safety using the Send and Sync marker traits. For now, most types have been marked as !Send and !Sync, meaning that they cannot be sent or shared across threads.

The Future

In its current form, glitter should be considered work-in-progress, and the API will likely undergo radical changes before a 1.0 version is established.

Reexports

pub use context::*;
pub use buffer::*;
pub use shader::*;
pub use program::*;
pub use framebuffer::*;
pub use renderbuffer::*;
pub use texture::*;
pub use image_data::*;
pub use vertex_data::*;
pub use vertex_buffer::*;
pub use index_data::*;
pub use uniform_data::*;
pub use types::*;

Modules

buffer

Exposes the OpenGL Buffer object, and related types.

context

Home of ContextOf, which is the type that represents "the OpenGL state machine", and the type you use to make OpenGL calls.

framebuffer

Exposes the OpenGL Framebuffer object, and related types.

image_data

Contains types related to 2D image data.

index_data

Contains types related to index data, which are used for IndexBuffers.

prelude

Re-exports essential extension traits. Everything exported in this module should be used anywhere that glitter is used.

program

Exposes the OpenGL Program object and related types.

renderbuffer

Exposes the OpenGL Renderbuffer object, and related types.

shader

Exposes the OpenGL Shader object and related types.

texture

Exposes the OpenGL Texture family of objects and related types.

types

Contains miscellaneous general-purpose OpenGL types.

uniform_data

Contains types that represent uniform data, which is used for methods such as gl.set_uniform.

vertex_buffer

Contains a higher-level abstraction for creating vertex and index buffer.

vertex_data

Contains types related to vertex data, which are used for VertexBuffers.

Macros

attrib_pointers

Create an AttribBinder from a set of associations from vertex attribute names to ProgramAttribs.

impl_vertex_data

Implement the VertexData trait for a struct. Each field of the struct must that is part of the VertexData implementation must be a type that implements VertexDatum.

offset_of

Compute the offset of a field within a struct type.