glitter 0.1.0

A safe, low-level, zero-cost OpenGL wrapper library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

#![deny(missing_docs)]

//! 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`]
//! (context/trait.ContextExt.html#method.clear_color). Others provide several
//! different wrapper functions to provide better type safety, such as
//! `glDrawElements`, which is wrapped by [`gl.draw_elements`]
//! (context/buffer_context/trait.ContextBufferExt.html#method.draw_elements),
//! [`gl.draw_n_elements`]
//! (context/buffer_context/trait.ContextBufferExt.html#method.draw_n_elements),
//! and [`gl.draw_n_elements_buffered`]
//! (context/buffer_context/trait.ContextBufferExt.html#method.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`]
//! (context/program_context/trait.ContextProgramBuilderExt.html#method.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`]
//! (context/index.html) module. This module is the home of the [`ContextOf`]
//! (context/struct.ContextOf.html) 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 targetting any OpenGL version. An example of what this
//! entails is the [`VertexBuffer`](struct.VertexBuffer.html) type. The current
//! implementation of [`VertexBuffer`](struct.VertexBuffer.html) 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`]
//! (struct.VertexBuffer.html) 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`]
//! (https://doc.rust-lang.org/std/marker/trait.Send.html) and [`Sync`]
//! (https://doc.rust-lang.org/std/marker/trait.Sync.html) 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
//! establised.

#[macro_use] extern crate bitflags;
extern crate gl as gl_lib;
#[cfg(feature = "cgmath")] extern crate cgmath;
#[cfg(feature = "image")] extern crate image;

mod to_ref;

#[macro_use] mod macros;
pub mod context;
pub mod buffer;
pub mod shader;
pub mod program;
pub mod framebuffer;
pub mod renderbuffer;
pub mod texture;
pub mod image_data;
pub mod vertex_data;
pub mod vertex_buffer;
pub mod index_data;
pub mod uniform_data;
pub mod types;

#[cfg(feature = "cgmath")] mod cgmath_features;
#[cfg(feature = "image")] mod image_features;



pub use gl_lib as gl;

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::*;

/// Re-exports essential extension traits. Everything exported in this module
/// should be used anywhere that glitter is used.
///
/// Generally, this means that most modules that use glitter will start
/// with the following:
///
/// ```no_run
/// use glitter;
/// use glitter::prelude::*;
/// ```
pub mod prelude {
    pub use context::{AContext, BufferContext,
                      ArrayBufferContext, ElementArrayBufferContext,
                      FramebufferContext, ContextFramebufferBuilderExt,
                      ProgramContext, ContextProgramBuilderExt,
                      RenderbufferContext, ContextRenderbufferBuilderExt,
                      TextureBinding, ContextTextureBuilderExt,
                      TextureUnit, TextureUnitBinding, ATextureUnitBinding,
                      TextureUnitBinding2d, TextureUnitBindingCubeMap,
                      TextureUnit0Context, TextureUnit1Context,
                      TextureUnit2Context, TextureUnit3Context,
                      TextureUnit4Context, TextureUnit5Context,
                      TextureUnit6Context, TextureUnit7Context};
    pub use context::ext::*;
    pub use shader::ContextShaderBuilderExt;
    pub use vertex_buffer::{VertexBufferContext, IndexBufferContext,
                            ContextVertexBufferExt};
    pub use types::GLObject;
}