Crate golem

golem is an opinionated mostly-safe graphics API

When possible, golem should make simple things safe (bind objects before acting on them, or check if they’re bound for objects that are expensive to bind.) However, when not possible or convenient (bounds checking the indices in an element buffer, for example), golem provides unsafe APIs with well-defined safety conditions.

A minimal example to display a triangle:

let vertices = [
    // Position         Color
    -0.5, -0.5,         1.0, 0.0, 0.0, 1.0,
    0.5, -0.5,          0.0, 1.0, 0.0, 1.0,
    0.0, 0.5,           0.0, 0.0, 1.0, 1.0
];
let indices = [0, 1, 2];

let mut shader = ShaderProgram::new(
    ctx,
    ShaderDescription {
        vertex_input: &[
            Attribute::new("vert_position", AttributeType::Vector(D2)),
            Attribute::new("vert_color", AttributeType::Vector(D4)),
        ],
        fragment_input: &[Attribute::new("frag_color", AttributeType::Vector(D4))],
        uniforms: &[],
        vertex_shader: r#" void main() {
        gl_Position = vec4(vert_position, 0, 1);
        frag_color = vert_color;
    }"#,
        fragment_shader: r#" void main() {
        gl_FragColor = frag_color;
    }"#,
    },
)?;

let mut vb = VertexBuffer::new(ctx)?;
let mut eb = ElementBuffer::new(ctx)?;
vb.set_data(&vertices);
eb.set_data(&indices);
shader.bind();

ctx.clear();
unsafe {
    shader.draw(&vb, &eb, 0..indices.len(), GeometryMode::Triangles)?;
}

The core type of golem is the Context, which is constructed from the glow Context. From the Context, ShaderPrograms are created, which take in data from Buffers. Once the data is uploaded to the GPU via Buffer::set_data, it can be drawn via ShaderProgram::draw.

Initializing

The user is responsible for windowing and providing a valid glow Context to create a Context. You can try out the blinds crate, which works well with golem, but using winit directly or other windowing solutions like sdl2 are also options.

OpenGL Versions

It currently is implemented via glow, and it targets OpenGL 3.2 on desktop and WebGL 1 (so it should run on a wide range of hardware.) GL 3.2 is selected for maximum desktop availability, and WebGL 1 is available on 97% of clients to WebGL’s 75% (taken from caniuse.com at time of writing.)

Re-exports

• pub use glow;

Modules

• blend
  Various options to specify how to combine pixels with what they draw over
• depth
  Various options to specify the depth of view volume and how pixels are determined to occlude each other

Structs

• Attribute
  An input to a shader program stage
• Buffer
  A collection of values stored contiguously on the GPU, as either a VertexBuffer or an ElementBuffer
• Context
  The context required to interact with the GPU
• ShaderDescription
  The parameters to create a ShaderProgram
• ShaderProgram
  A GPU program that draws data to the screen
• Surface
  A framebuffer that allows render-to-texture
• Texture
  An image stored on the GPU
• Uniform
  A uniform value to pass in to the ShaderDescription

Enums

• AttributeType
  The data type of a given attribute
• ColorFormat
  How a pixel’s color is laid out in memory
• Dimension
  The dimensionality of a vector or matrix shader input
• GeometryMode
  The GeometryMode determines how the data is drawn during ShaderProgram::draw
• GolemError
  The library’s error conditions
• NumberType
  Used to determine whether shader uniforms are ints or floats
• TextureFilter
  How textures should scale when being drawn at non-native sizes
• TextureWrap
  How the texture should wrap if a sample is outside the edge
• UniformType
  The type of the uniform in GLSL
• UniformValue
  A value to provide to a uniform

Type Aliases

• ElementBuffer
  A buffer to store the indices that make up the geometry elements
• VertexBuffer
  A buffer to store the vertices on the GPU