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

#![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 targeting 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
//! established.

#[macro_use] extern crate bitflags;
extern crate gl;
#[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 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;
}