# gloam   [![Build Status]][actions] [![Latest Version]][crates.io]
[Build Status]: https://img.shields.io/github/actions/workflow/status/tycho/gloam/ci.yml?branch=master
[actions]: https://github.com/tycho/gloam/actions?query=branch%3Amaster
[Latest Version]: https://img.shields.io/crates/v/gloam.svg
[crates.io]: https://crates.io/crates/gloam
A loader generator for Vulkan, OpenGL, OpenGL ES, EGL, GLX, and WGL.
Reads Khronos XML spec files and generates C dispatch code.
gloam is a clean-room rewrite of [GLAD](https://github.com/Dav1dde/glad) in Rust,
with first-class support for ANGLE extension supplementals, Vulkan command-scope
inference, and a hash-based extension detection strategy that avoids string
comparisons at load time.
---
## Quick start
```sh
# 1. Populate bundled XML specs and headers (one-time setup, or to refresh).
./scripts/fetch_bundled.sh
# 2. Build.
cargo build --release
# 3. Generate a C loader for OpenGL 3.3 core + all extensions.
./target/release/gloam --api gl:core=3.3 c --loader
# 5. Generate a combined GL 3.3 + GLES 2.0 + Vulkan + EGL loader.
./target/release/gloam --api gl:core,gles2,vulkan,egl --merge c --alias --loader
```
---
## Command reference
```
gloam [OPTIONS] <COMMAND>
Options:
--api <SPEC> API specifiers (required). Comma-separated list of
name[:profile][=major.minor] tokens. Profile is
required for GL (core|compat). Version is optional
(latest if omitted). Examples:
gl:core=3.3
gles2=3.0
gl:core=3.3,gles2=3.0
vk=1.3
egl=1.5
--extensions <FILTER> Restrict extensions. Either a path to a file (one
name per line) or a comma-separated inline list.
Omit to include all extensions supported by the
requested API.
--promoted Automatically include any extension whose commands
were promoted into the requested core version, even
if not listed in --extensions. Handles both
same-name promotion (e.g. ARB_copy_buffer) and
renamed promotion (e.g. ARB_multitexture →
glActiveTexture). Scoped per-API to prevent
cross-contamination in merged builds.
--predecessors Automatically include any extension that is a
predecessor of an already-selected extension — i.e.
its commands or enums are aliases of those in the
selected set. Follows chains to a fixed point, so
indirect predecessors are included too. Runs after
--promoted, so promoted extensions also seed the
predecessor search.
--merge Merge multiple APIs of the same spec into a single
output file. Required when combining gl and gles2.
--out-path <DIR> Output directory [default: .]
--quiet Suppress progress messages.
--fetch Fetch XML specs from upstream Khronos URLs instead
of the bundled copies. Any fetch failure is fatal.
Commands:
c Generate a C loader.
--alias Enable bijective function-pointer alias resolution at
load time. If the canonical slot is null but an alias
was loaded by the driver (or vice versa), the pointer
is propagated to both slots.
--loader Include a built-in dlopen/LoadLibrary convenience layer.
```
### Extension selection flags
The three extension-related flags are orthogonal and compose freely:
| `--alias` | *Runtime*: propagates loaded function pointers to alias slots at load time |
| `--promoted` | *Selection*: adds extensions whose commands were promoted into requested core |
| `--predecessors` | *Selection*: adds predecessor extensions of the already-selected set |
Typical use with an explicit `--extensions` list:
```sh
# Explicit list only — exactly what you asked for.
gloam --api gl:core=4.6,gles2=3.2 --extensions GL_KHR_debug,... --merge c
# Explicit list + promoted ARB predecessors of core functions.
gloam --api gl:core=4.6,gles2=3.2 --extensions GL_KHR_debug,... --promoted --merge c
# Explicit list + promoted + extension-to-extension predecessor chains.
gloam --api gl:core=4.6,gles2=3.2 --extensions GL_KHR_debug,... --promoted --predecessors --merge c
```
---
## Generated C output
For `--api gl:core=3.3 c --loader`, gloam emits into the output directory:
```
include/
gloam/
gl.h # public header — include this in your project
KHR/
khrplatform.h # auxiliary headers copied from bundled/
xxhash.h # single-file xxHash amalgamation used by the loader
src/
gl.c # loader implementation
```
When generating without `--merge`, each API gets its own stem:
`gles2` → `gles2.h` / `gles2.c`, `gl` → `gl.h` / `gl.c`, etc.
**`include/gloam/gl.h`**
- `GloamAPIProc` opaque function pointer type and `GloamLoadFunc` callback typedef
- `APIENTRY` / `APIENTRYP` / `GLOAM_API_PTR` / `GLAPIENTRY` calling convention macros
- `typedef` declarations in topological dependency order
- `#define` constants for all required enums
- PFN typedef for every selected command (e.g. `PFNGLACTIVETEXTUREPROC`)
- `GloamGLContext` struct with:
- `featArray[]` — one `unsigned char` flag per version feature
- `extArray[]` — one `unsigned char` flag per extension
- `pfnArray[]` / named union members — one function pointer slot per command
- Feature presence macros (`GLOAM_GL_VERSION_3_3`, …)
- Extension presence macros (`GLOAM_GL_ARB_SYNC`, …)
- `#define glFoo (gloam_gl_context.Foo)` dispatch macros (or prototypes under `__INTELLISENSE__`)
- `gloamLoadGLContext(ctx, getProcAddr)` / `gloamLoadGL(getProcAddr)` declarations
- With `--loader`: `gloamLoaderLoadGLContext` / `gloamLoaderUnloadGLContext` /
`gloamLoaderResetGLContext` (and non-Context variants) declarations
**`src/gl.c`**
- Static function-name string table (`kFnNames[]`)
- Feature PFN range table (contiguous-run compressed)
- Per-API extension hash table (pre-baked XXH3-64, sorted for binary search)
- Extension PFN range table and index subset per API
- `gloamLoadGLContext()`:
1. Bootstraps `glGetString` then calls `find_core` to parse `GL_VERSION` and
set `featArray` bits
2. Bulk-loads function pointers for each enabled feature via the range table
3. Hashes driver-reported extension names, Shellsorts them, binary-searches
against the pre-baked table, sets `extArray` bits for matches
4. Loads function pointers for each detected extension via the range table
5. With `--alias`: resolves bijective function-pointer alias pairs
- With `--loader`: `gloamLoaderLoad/Unload/ResetGLContext()` — opens the platform
GL library, wires up `wglGetProcAddress` / `glXGetProcAddressARB` with correct
calling conventions, delegates to `gloamLoadGLContext`, stores the library
handle in `context->glad_loader_handle`
### Extension detection strategy
At load time, the generated code:
1. Calls `glGetIntegerv(GL_NUM_EXTENSIONS, &n)` to get the count.
2. Calls `glGetStringi(GL_EXTENSIONS, i)` for each `i`, hashes each name
with XXH3-64 (the same algorithm used at generator time), and stores
the hashes in a heap-allocated `uint64_t[]`.
3. Shellsorts the array in-place (Ciura gap sequence — no extra memory,
~160 bytes of code).
4. Binary-searches the sorted driver hashes against the pre-baked known
extension hash table embedded in the generated source.
This gives O(n log n) total work to detect all extensions, with O(log n)
per lookup, and zero string comparisons at runtime.
---
## Vulkan loading
Vulkan function loading requires knowing which `vkGet*ProcAddr` entry point
to use for each command. gloam infers this from the first parameter type:
| (none / non-handle) | Global | `vkGetInstanceProcAddr(NULL, name)` |
| `VkInstance` / `VkPhysicalDevice` | Instance | `vkGetInstanceProcAddr(instance, name)` |
| `VkDevice` / `VkQueue` / `VkCommandBuffer` | Device | `vkGetDeviceProcAddr(device, name)` |
| `vkGetInstanceProcAddr` itself | Unknown | `dlsym` / `GetProcAddress` |
### Multi-call loading model
`gloamLoadVulkanContext` (and `gloamLoaderLoadVulkanContext`) may be called
multiple times on the same context as the application progresses through
Vulkan initialisation. Each call is **additive** — it fills in whatever
the current set of live handles allows, without wiping previous work:
```c
// Pass 1: all handles NULL — loads Global-scope functions,
// detects available instance extensions.
gloamLoaderLoadVulkanContext(ctx, NULL, NULL, NULL);
// ... create VkInstance based on detected extensions ...
// Pass 2: instance live — loads Instance-scope functions,
// detects available device extensions.
gloamLoaderLoadVulkanContext(ctx, instance, NULL, NULL);
// ... create VkPhysicalDevice / VkDevice ...
// Pass 3: device live — loads Device-scope functions.
gloamLoaderLoadVulkanContext(ctx, instance, physical_device, device);
```
### Caller-managed library handle
The library handle is stored in `context->glad_loader_handle` so you can
supply your own:
```c
// Pre-populate to skip dlopen:
ctx->glad_loader_handle = my_vk_handle;
gloamLoaderLoadVulkanContext(ctx, NULL, NULL, NULL);
// During cleanup, zero the field first to prevent gloam from closing
// a handle you still own:
ctx->glad_loader_handle = NULL;
gloamLoaderUnloadVulkanContext(ctx);
```
`glad_loader_handle` is present on **all** context types (GL, EGL, VK, …)
so this pattern is consistent across APIs.
---
## Bundled files
`bundled/` contains compile-time snapshots of upstream XML specs and
auxiliary headers. They are embedded into the binary via `include_str!`
so the binary is fully self-contained.
To refresh them:
```sh
./scripts/fetch_bundled.sh # fetch everything
./scripts/fetch_bundled.sh --xml # XML specs only
./scripts/fetch_bundled.sh --hdrs # headers only
```
The `--fetch` CLI flag bypasses the bundled copies and fetches directly
from upstream at generation time. Any failure is fatal.
---
## Alias resolution (`--alias`)
When `--alias` is passed, the generated loader emits a runtime resolver:
after loading all function pointers, if the canonical slot for an alias
pair is null but the alias slot was loaded by the driver (or vice versa),
the loaded pointer is propagated to both slots. This is useful for
extension functions that were later promoted to core under a new name,
where a driver may only expose one spelling.
Note: `--alias` is a *runtime* concern — it does not affect which extensions
are selected. For selection-time alias expansion see `--promoted` and
`--predecessors`.
---
## Building from source
```sh
cargo build # debug
cargo build --release # release
cargo test
```
Requires Rust 1.88 or later.