Bindings to Gl 4.6
Generated by phosphorus and then slightly post-edited by hand.
Included Extensions (activate via cargo feature):
debug_trace_calls: if cfg!(debug_assertions), any call to a GL function will
trace!what was called and with what args.
debug_automatic_glGetError: If cfg!(debug_assertions), this will automatically call
glGetErrorafter every call to any other GL function. If an error code occurs it’s shown via
error!along with the name of the function that had the error.
error!macros from the
logcrate. Otherwise they just call
chlorine: gets all C types from the
chlorinecrate (which is
no_stdfriendly). Otherwise they will be imported from
bytemuck: Adds support for the
bytemuckcrate, mostly in the form of
inline: Tags all GL calls as
inline_always: Tags all GL calls as
#[inline(always)]. This will effectively override the
The crate is
no_std friendly by default, but features above can end up
std to be available.
The docs for this crate hosted on docs.rs generate both the
struct_loader documentation for sake of completeness.
However, you are generally expected to use only one loader style in any particular project.
Each loader style has its own small advantages:
global_loaderstores the GL function pointers in static
- Call [
load_global_gl_with] to initialize the pointers.
- Each GL function is available as a global function under its standard
- This lets you call GL functions from anywhere at all, and it’s how you might expect to use GL if you have a C background.
- Being able to call GL from anywhere makes it easy to write Drop impls, among other things.
- Call [
struct_loaderstores all the function pointers in the fields of a
GlFns::load_withto make a
- Each GL function is available as a method on the struct with the
glprefix removed. It’s presumed that you’ll call the struct itself
gl, so calls will look something like
- This is closer to how WebGL works on WASM targets, and so this is how
glowcrate works to maintain consistency across desktop and web.
- Also, if you want to do any sort of “live code reloading” you’ll have to
use the struct loader. DLLs don’t share their static values with the
main program, so if the DLL uses the global loader functions the
pointers won’t be loaded and calling any GL function from the DLL will
panic. Instead, if you just pass a
&GlFnsto your DLL it can call the GL methods just fine.
In both styles, if you call a function that isn’t loaded you will get a
panic. This generally only happens if the context doesn’t fully support
the GL version. You can check if a GL command is loaded or not before
actually calling it by adding
_is_loaded to the name of the command. In
glGetError_is_loaded to check if
glGetError is globally
gl.GetError_is_loaded to check if it’s loaded in a
All of the “
_is_loaded” functions are hidden in the generated docs just
to keep things tidy, but they’re there.
In general, there’s many ways that GL can go wrong.
For the purposes of this library, it’s important to focus on the fact that:
- Initially all functions are null pointers. If a function is called when it’s in a null state then you’ll get a panic (reminder: a panic is safe).
- You can load pointers from the current GL context (described above).
- These pointers are technically context specific, though in practice different contexts for the same graphics driver often all share the same function pointers.
- The loader has no way to verify that pointers it gets are actually pointers to the correct functions, it just trusts what you tell it.
- Since loading a function pointer transitions the world from “it will definitely (safely) panic to call that GL command” to “it might be UB to call that GL command (even with the correct arguments)”, the act of simply loading a function pointer is itself considered to be
- Individual GL commands are generally safe to use once they’ve been properly loaded for the current context, but this crate doesn’t attempt to sort out what is safe and what’s not. All GL commands are blanket marked as being
unsafe. It’s up to you to try and manage this unsafety! Sorry, but this crate just does what you tell it to.
- Contains all the GL enumerated values.
- Contains the
GlFnstype for using the struct GL loader.
- Contains all the GL types.
- RELAX 🔒
- This is called to panic when a not-loaded function is attempted.
- Loads a function pointer. Rejects suggested pointer addresses which are likely to be lies. This function is used by both the global loader and struct loader. We mark it as
inline(never)to favor a small binary over initialization speed. Returns if there’s now a non-null value in the atomic pointer.
- APcv 🔒