opengl

Creates an OpenGL 3.3 Core context attached to a Win32 window handle (HWND). Accepts either a raw integer HWND or the table returned by win.native_handle(). Returns a GlState handle used by all other functions. Windows only; non-Windows returns an error.

use plugin opengl::{create_context}

let gl = create_context(hwnd)

Marks the context as current on the calling thread. With CS_OWNDC the context stays current from creation, so this is effectively a no-op but is provided for API completeness.

use plugin opengl::{make_current}

make_current()

Presents the back buffer to the screen by calling SwapBuffers on the device context. Call once per frame after all draw calls.

use plugin opengl::{swap_buffers}

swap_buffers()

Sets the GL viewport rectangle. Call after create_context and whenever the window is resized.

use plugin opengl::{create_context, viewport}

let gl = create_context(hwnd)
viewport(gl, 0, 0, 800, 600)

Sets the color used by clear for the color buffer. Values are floats in the range [0, 1].

use plugin opengl::{clear_color, clear}

clear_color(gl, 0.1, 0.1, 0.15, 1.0)
clear(gl, "color+depth")

Clears framebuffer attachments. mask is one of "color", "depth", "stencil", "color+depth", "color+stencil", "depth+stencil", or "all".

use plugin opengl::{clear}

clear(gl, "color+depth")

Enables a named GL capability. Supported names: "blend", "depth_test", "cull_face", "scissor_test", "stencil_test", "multisample", "polygon_offset_fill".

use plugin opengl::{enable}

enable(gl, "depth_test")
enable(gl, "blend")

Disables a named GL capability.

use plugin opengl::{disable}

disable(gl, "cull_face")

Sets the blend equation source and destination factors. Factor names include "src_alpha", "one_minus_src_alpha", "one", "zero", and others.

use plugin opengl::{enable, blend_func}

enable(gl, "blend")
blend_func(gl, "src_alpha", "one_minus_src_alpha")

Sets the depth comparison function. Values: "less", "lequal", "greater", "gequal", "equal", "notequal", "always", "never".

use plugin opengl::{depth_func}

depth_func(gl, "lequal")

Sets the scissor test rectangle. Fragments outside this rectangle are discarded when scissor_test is enabled.

use plugin opengl::{enable, scissor}

enable(gl, "scissor_test")
scissor(gl, 100, 100, 400, 300)

Sets the width of rasterized lines in pixels.

use plugin opengl::{line_width}

line_width(gl, 2.0)

Controls which color channels are written to the framebuffer. Pass true to enable writing, false to mask out a channel.

use plugin opengl::{color_mask}

color_mask(gl, true, true, true, false)

Enables (true) or disables (false) writes to the depth buffer.

use plugin opengl::{depth_mask}

depth_mask(gl, false)

Sets the polygon offset scale and bias for polygon_offset_fill. Used to prevent z-fighting when rendering decals over geometry.

use plugin opengl::{enable, polygon_offset}

enable(gl, "polygon_offset_fill")
polygon_offset(gl, 1.0, 1.0)

Compiles a GLSL shader from source. type is "vertex", "fragment", "geometry", or "compute". Returns a shader handle on success; raises an error with the compile log on failure.

use plugin opengl::{create_shader}

let vert = create_shader(gl, "vertex", "
  #version 330 core
  layout(location=0) in vec3 pos;
  void main() { gl_Position = vec4(pos, 1.0); }
")

Links a table of shader handles into a shader program. Returns a program handle on success; raises an error with the link log on failure. Detaches shaders after linking.

use plugin opengl::{create_shader, create_program, use_program}

let vert = create_shader(gl, "vertex", vert_src)
let frag = create_shader(gl, "fragment", frag_src)
let prog = create_program(gl, #{1: vert, 2: frag})
use_program(prog)

Activates a linked shader program for subsequent draw calls.

use plugin opengl::{use_program}

use_program(prog)

Looks up a named uniform variable in a linked program. Returns a uniform location handle, or -1 if the name is not found (inactive/optimized-out uniforms).

use plugin opengl::{uniform_location, set_uniform_1f}

let loc = uniform_location(prog, "uTime")
set_uniform_1f(prog, loc, 1.5)

Sets a float uniform variable. Requires use_program to have been called with the same program.

use plugin opengl::{set_uniform_1f}

set_uniform_1f(prog, time_loc, 3.14)

Sets a vec2 uniform variable.

use plugin opengl::{set_uniform_2f}

set_uniform_2f(prog, res_loc, 800.0, 600.0)

Sets a vec3 uniform variable, typically used for colors or world-space positions.

use plugin opengl::{set_uniform_3f}

set_uniform_3f(prog, color_loc, 1.0, 0.5, 0.0)

Sets a vec4 uniform variable.

use plugin opengl::{set_uniform_4f}

set_uniform_4f(prog, clear_loc, 0.1, 0.1, 0.15, 1.0)

Sets an int or sampler2D uniform. Use for passing texture unit indices to samplers.

use plugin opengl::{set_uniform_1i}

set_uniform_1i(prog, tex_loc, 0)

Sets a mat4 uniform from exactly 64 bytes of little-endian float data (16 × f32).

use plugin opengl::{set_uniform_mat4}

set_uniform_mat4(prog, mvp_loc, matrix_bytes)

Allocates a new OpenGL buffer object. Use with buffer_bind and buffer_data or buffer_data_floats to upload vertex or index data.

use plugin opengl::{create_buffer, buffer_bind, buffer_data_floats}

let vbo = create_buffer(gl)
buffer_bind(vbo, "array")
buffer_data_floats(vbo, "array", #{1: 0.0, 2: 0.5, 3: 0.0}, "static_draw")

Binds a buffer object to the named target. Targets: "array" (vertex data), "element" / "element_array" (index data), "uniform".

use plugin opengl::{buffer_bind}

buffer_bind(vbo, "array")

Uploads raw bytes to a buffer. usage is "static_draw", "dynamic_draw", or "stream_draw". Also binds the buffer before uploading.

use plugin opengl::{buffer_data}

buffer_data(ibo, "element", index_bytes, "static_draw")

Uploads a table of float values to a buffer, converting each to little-endian f32 bytes internally. More convenient than buffer_data when data originates as Zolo numbers.

use plugin opengl::{buffer_data_floats}

let verts = #{1: -0.5, 2: -0.5, 3: 0.0, 4: 0.5, 5: -0.5, 6: 0.0, 7: 0.0, 8: 0.5, 9: 0.0}
buffer_data_floats(vbo, "array", verts, "static_draw")

Creates a new vertex array object (VAO) that records vao_attrib_pointer and vao_enable_attrib calls. Bind before configuring attributes.

use plugin opengl::{create_vertex_array, vao_bind}

let vao = create_vertex_array(gl)
vao_bind(vao)

Binds a vertex array object, making it the active VAO for subsequent attribute configuration and draw calls.

use plugin opengl::{vao_bind}

vao_bind(vao)

Unbinds the current VAO (binds 0). Call after finishing attribute setup.

use plugin opengl::{vao_unbind}

vao_unbind(vao)

Defines how a vertex attribute is read from the currently bound array buffer. type is "float", "int", etc. normalized is a bool.

use plugin opengl::{vao_attrib_pointer, vao_enable_attrib}

vao_attrib_pointer(vao, 0, 3, "float", false, 12, 0)
vao_enable_attrib(vao, 0)

Enables vertex attribute array access at the given index for the bound VAO.

use plugin opengl::{vao_enable_attrib}

vao_enable_attrib(vao, 0)

Deletes a compiled shader object and frees GPU resources.

use plugin opengl::{delete_shader}

delete_shader(vert_shader)
delete_shader(frag_shader)

Deletes a linked shader program.

use plugin opengl::{delete_program}

delete_program(prog)

Deletes a buffer object and frees GPU memory.

use plugin opengl::{delete_buffer}

delete_buffer(vbo)

Deletes a vertex array object.

use plugin opengl::{delete_vertex_array}

delete_vertex_array(vao)

Deletes a texture object and frees GPU memory.

use plugin opengl::{delete_texture}

delete_texture(tex)

Allocates a new 2D texture object. Use with texture_bind, texture_image_2d, and texture_parameter to upload and configure it.

use plugin opengl::{create_texture, texture_bind, texture_image_2d}

let tex = create_texture(gl)
texture_bind(tex, 0)
texture_image_2d(tex, 0, "rgba8", 256, 256, rgba_bytes)

Activates texture unit unit and binds the texture to GL_TEXTURE_2D.

use plugin opengl::{texture_bind}

texture_bind(tex, 0)

Uploads 2D image data to a texture. internal_format is "rgba", "rgb", "rgba8", "rgb8", or "red". Input bytes are interpreted as GL_RGBA / GL_UNSIGNED_BYTE.

use plugin opengl::{texture_image_2d}

texture_image_2d(tex, 0, "rgba8", 512, 512, image_bytes)

Sets a texture sampling parameter. name is "min_filter", "mag_filter", "wrap_s", or "wrap_t". value is "linear", "nearest", "clamp_to_edge", "repeat", etc.

use plugin opengl::{texture_parameter}

texture_parameter(tex, "min_filter", "linear")
texture_parameter(tex, "wrap_s", "clamp_to_edge")

Generates a full mipmap chain for the texture from the base level image. Call after texture_image_2d when using mipmap filter modes.

use plugin opengl::{texture_generate_mipmaps, texture_parameter}

texture_generate_mipmaps(tex)
texture_parameter(tex, "min_filter", "linear_mipmap_linear")

Draws count primitives starting at vertex first. mode is "triangles", "triangle_strip", "lines", "points", etc.

use plugin opengl::{draw_arrays}

draw_arrays(gl, "triangles", 0, 3)

Draws count primitives using indices from the currently bound element array buffer. index_type is "unsigned_short" or "unsigned_int".

use plugin opengl::{draw_elements}

draw_elements(gl, "triangles", 36, "unsigned_short", 0)

Returns the current GL error state as a string: "no_error", "invalid_enum", "invalid_value", "invalid_operation", "out_of_memory", or "unknown_error". Clears the error flag.

use plugin opengl::{get_error}

let err = get_error(gl)
if err != "no_error" {
  print("GL error: {err}")
}

Flushes all pending GL commands to the GPU command queue without blocking. Use when synchronization is needed without a full stall.

use plugin opengl::{flush}

flush(gl)

Blocks until all previously issued GL commands have completed on the GPU. Use for timing measurements or when reading back GPU data.

use plugin opengl::{finish}

finish(gl)