gl

gl is the OpenGL bindings crate from the gl-rs workspace. Rather than shipping hand-written bindings, its build.rs invokes the sibling gl_generator crate at compile time to parse the Khronos XML API registry (vendored in khronos_api) and emit a bindings.rs file containing every OpenGL 4.6 Core function, constant, and type alias for the target platform. The generated src/lib.rs simply includes that file, so the published crate always exposes a complete, spec-accurate surface for the OpenGL version it was generated against.

At runtime, consumers call gl::load_with(|symbol| ...) and supply a loader closure from their windowing/context library (GLFW, glutin, SDL2, etc.) to resolve each function’s platform-specific address. Each generated function pointer tracks whether it has been successfully loaded; calling one that failed to load panics with a descriptive message instead of segfaulting, and is_loaded() lets callers probe extension support before use. All GL calls are unsafe, reflecting the underlying C API’s lack of safety guarantees.

Because the bindings are generated fresh per build rather than committed, gl stays trivially in sync with the Khronos registry and lets consumers restrict codegen to specific GL versions, profiles (Core/Compatibility), or extension sets via gl_generator’s Registry API — at the cost of needing gl_generator and khronos_api as build dependencies for anyone building from source.

What You Get

• Complete OpenGL 4.6 Core bindings generated from the official Khronos XML registry, not hand-maintained
• A load_with runtime loader that accepts any &str -> *const c_void closure, compatible with GLFW, glutin, SDL2, and other context libraries
• Per-function is_loaded() checks so callers can probe for extension/version support before calling
• Typed constants and type aliases (gl::types::*) matching the C API’s GLenum, GLuint, etc.
• A panic-on-unloaded-call safety net instead of silent segfaults when a function wasn’t resolved

Common Use Cases

• Raw OpenGL rendering in a custom game engine or graphics application built on a windowing crate like glutin or SDL2
• Low-level graphics prototyping where higher-level engine abstractions would get in the way
• Building higher-level safe wrapper crates on top of raw GL calls
• Cross-platform native rendering where an application needs OpenGL Core profile functions without vendoring its own bindings

Under The Hood

Architecture The crate itself is deliberately thin: src/lib.rs is little more than include!(concat!(env!("OUT_DIR"), "/bindings.rs")), with the real work happening in build.rs, which constructs a gl_generator::Registry for Api::Gl version 4.6 Core with all fallbacks enabled and writes the generated bindings into the build output directory. The actual code-generation logic lives one directory over in the sibling gl_generator crate, whose registry/parse.rs (roughly 1,400 lines) parses the Khronos XML API registry vendored by the khronos_api crate, and whose generators/ module (global_gen.rs, struct_gen.rs, static_gen.rs, etc.) renders that parsed registry into different binding styles depending on the chosen generator. gl always uses GlobalGenerator, producing free functions and global loaded-state flags rather than a struct-based API. Changing the target GL version or profile only requires editing the tuple passed to Registry::new in build.rs — the crate boundary between codegen (gl_generator) and generated-output consumer (gl) is the core abstraction, and it would break if the registry-parsing format in khronos_api changed shape.

Tech Stack This is a pure Rust Cargo workspace with no runtime dependencies for the gl crate itself beyond the C standard library types it re-exports (std::os::raw). Its only dependency is a build-dependencies edge on gl_generator (path-pinned to the same workspace version, 0.14.0), which in turn depends on khronos_api (vendored XML registry data), log for generator diagnostics, and xml-rs for registry parsing. dev-dependencies pull in glutin 0.24 solely for the examples/ (a windowed triangle demo), which are not part of the published crate’s dependency graph. There’s no async runtime, no ORM, no web framework — it’s a build-time codegen tool paired with a minimal generated-output shim, targeting native compilation (no wasm-specific handling observed).

Code Quality The workspace enforces cargo fmt --check and cargo clippy --all --all-targets -Dwarnings in CI (.github/workflows/ci.yml), and clippy lints are set at deny for uninlined_format_args workspace-wide. Testing is structural rather than unit-test-driven: six separate crates under tests/ (test_symbols, test_gen_symbols, test_no_warnings, test_with_extensions, test_add_registries, test_unstable_api) each exercise gl_generator’s codegen paths end-to-end by generating bindings for different registry configurations and asserting they compile and expose the expected symbols — effectively integration/compile tests for the generator rather than conventional #[test] unit tests of gl itself, and gl’s own src/lib.rs has its one embedded test commented out. Naming is consistent with the upstream C API (PascalCase functions, SCREAMING_CASE constants) by design, since the bindings mirror the Khronos spec. No unsafe audit tooling is visible beyond what clippy catches, which is expected given the crate’s inherent FFI nature.

API Design The public surface is intentionally minimal and mirrors the C OpenGL API directly: gl::load_with, per-function is_loaded(), and gl::types::* for type aliases, with no attempt to make the API safe or idiomatic Rust beyond load-checking. This keeps the learning curve low for anyone already familiar with OpenGL’s C API, but pushes all safety and ergonomics work onto downstream wrapper crates or application code — every call site is unsafe and the crate’s own docs are limited to a single README/lib.rs doc comment walkthrough rather than per-function documentation (each of the ~700+ generated functions relies on upstream Khronos reference docs).