OpenGL-Registry: the machine-readable core behind every OpenGL extension

The backing store behind the registry site on khronos.org

The README describes this repository as the API and Extension registries for the OpenGL family of APIs, namely OpenGL, OpenGL ES and OpenGL SC. What sits inside is broader than the name suggests: API specifications, specifications of Khronos-approved and vendor-approved extensions, header files corresponding to those specifications, the XML API Registry that defines each API, and the tools and scripts used to maintain them.

The stated primary purpose is to be the backing store for the web registry on khronos.org. That framing explains the shape of the tree, which is organised as web content and data rather than as a consumable library.

The repository contents section lists the directories and their roles. The ABI directory holds the OpenGL ABI for Linux. The api directory holds header files for all APIs, split into api/ES, api/GL and api/SC. The extensions directory holds extension specifications for all APIs and contains registry.py, the combined extension registry for all APIs, and makeindex.py, which creates HTML extension indices from registry.py. The specs directory holds API and Shading Language specifications, split into specs/es, specs/gl and specs/sc. The xml directory holds the XML API Registry and related tools, and the index_es.php, index_gl.php and index_sc.php files at the top level link to specifications, headers and extensions relevant to each API.

One boundary is worth noting early. The registry does not contain the OpenGL and OpenGL ES Reference Pages; those live in the KhronosGroup/OpenGL-Refpages repository.

Enumerant values are allocated by appending to gl.xml, glx.xml and wgl.xml

The XML directory is the mechanism behind the API. When an extension needs new values, the process starts by requesting one or more blocks of unused enumerants for GL, GLX or WGL, and the reservation is added to the end of gl.xml, glx.xml and/or wgl.xml. Once the pull request modifying the XML files is accepted into main, the requester has control of those enumerant blocks.

That last point carries a rule that surprises newcomers. The README states that any changes proposed to reserved values in the registry are not official until the pull request is accepted into the main branch. Until then, the value is a placeholder in a public file, and nothing in the file itself marks it as reserved by you.

Extension interfaces and enumerant assignments are added to the same XML files following existing examples, and the README instructs you to verify that the relevant extension headers are generated with the correct interfaces by running make in xml/, which requires the lxml Python module. That is the point where the XML registry turns into shipped headers.

For tool authors this is the interesting part of the repository. The XML API Registry is the machine-readable definition of the API, so anything that can parse it can derive bindings, validation and documentation without parsing the prose specifications.

Defining an extension is a nine step procedure, not a pull request

The README sets out the full sequence for creating a new extension specification, and the order matters because each step depends on the previous one being merged.

First, reserve enumerant blocks at the end of gl.xml, glx.xml or wgl.xml and get that pull request accepted, which is what gives you control of the values. Second, write the extension specification following the model of existing vendor specifications under extensions/vendor/. Third, obtain whatever degree of review, implementation and signoff you need from affected parties before declaring the extension complete.

Fourth, add the specification under extensions/vendor/extension. Fifth, modify extensions/registry.py to include the extension, using the next free ARB, GL and/or ES extension numbers depending on which API the extension covers, and execute the python script nextfree.py in the extensions directory to find those numbers. Sixth, once registry.py is updated, run make in extensions to update the PHP include files used to show the index of extensions on the registry website, which requires GNU make and Python 3. Seventh, add the extension numbers to the specification in the Number block. Eighth, add the extension interfaces and enumerant assignments to xml/gl.xml, xml/glx.xml and/or xml/wgl.xml following existing examples, and run make in xml to check the headers generate correctly, which needs lxml. Ninth, once the pull request adding the specification and modifying registry.py is accepted, the extension is registered.

The specification process is documented in more depth under docs, including a how to create extensions page, enumerant allocation policies, an extension specification template, extension promotion guidelines, a GLX opcode registry, OpenGL syntax rules and shading language extension conventions. The README is direct about their condition: these documents are largely out of date and may be updated or removed over time. Two of them carry update stamps from December 2006, so treat the current process text as the one to follow.

Registry bugs and API bugs go to different issue trackers

The README has a section titled Please Don't File API And GLSL Bugs Here, and the warning is specific enough to be useful.

Problems with the OpenGL and OpenGL ES API and Shading Language specifications should not be filed here. API issues, core or extension, belong in the issue tracker of the KhronosGroup/OpenGL-API repository, and Shading Language issues belong in the KhronosGroup/OpenGL-GLSL repository. Issues should be tagged with +[OpenGL]+ or +[OpenGL ES]+ in the title when they are specific to one of those APIs or to the shading language.

What does belong here is a problem with the registry itself: missing or badly formed extension documents, headers or XML files.

If something about working with extensions is unclear, the README invites an issue on this repository rather than leaving the contributor to guess. That invitation is aimed at the extension author and the tooling contributor, and it is the right channel for questions about the xml and extensions directories.

For a user who simply wants the constants, neither tracker is relevant, and the headers in api are the answer.

The 125 MB of PDFs is the clone cost, and it only hits once

The README addresses the repository size head on, under a heading that admits the problem. The specs directory contains over 125 MB of PDFs, including the latest specifications for each version of OpenGL and OpenGL ES. For someone who wants to add a single extension, the repository download time is called out as somewhat distressing.

The mitigation offered is that the primary purpose of the repository is to serve the web registry on khronos.org, and that git is very efficient, so once the initial clone is done, updates will be small and quick.

That is a workable model for a contributor or a tool author, and a poor one for a build script that clones on every CI run. A sparse checkout, a shallow clone, or vendoring the api directory at build time are the practical answers, though the README documents none of them.

It also tells you where the value density is. The api directory is what most consumers want, the xml directory is what tool authors want, and specs is what a reader wants and a build system does not.

ES and SC headers depend on a file kept outside this repository

The api directory is split into api/ES, api/GL and api/SC, and the note attached to it carries an important dependency detail. The OpenGL ES and OpenGL SC headers all depend on the shared khrplatform.h file, and that file is maintained in the EGL Registry on khronos.org rather than in this repository.

So the headers you copy out of this repository are not self-contained. An ES or SC consumer has to also obtain khrplatform.h from the EGL Registry and keep the two in step, which is a small thing to get wrong in exactly the way that produces a confusing compile error rather than an obvious one.

The GL headers do not carry that note, so a desktop-only consumer can treat api/GL as self-contained.

The tooling picture follows the same split. registry.py is the combined extension registry for all APIs, and makeindex.py turns it into HTML extension indices for the website. The PHP include files that serve the index are regenerated by make in the extensions directory, which needs GNU make and Python 3, and the headers are regenerated by make in the xml directory, which needs lxml. Two build systems, two toolchains, both Python based.

Maintenance state, licence and the gaps in the documentation

The repository is not archived and the last push was on 2026-10-06, so the registry continues to receive changes. There are no GitHub releases, so there is no version to cite and no tag to pin against; the practical approach is to record the commit your build used, especially since the XML files change as enumerants are reserved and released.

The licence is where this project is vaguer than it looks. The README file itself carries a copyright line for The Khronos Group Inc. and an SPDX identifier of CC-BY-4.0, and the licence information in the repository listing is not resolved to a named licence. The README text and the specification documents have their own terms, and anyone redistributing generated headers or specification PDFs should read the files in the repository rather than assume a single licence covers everything.

The documentation gaps are known and documented. The docs directory is described as mostly out of date, the repository listing carries a separate CODE_OF_CONDUCT.adoc and SECURITY.md alongside a CONTRIBUTING.adoc, and the API and GLSL specification issues are routed to two other repositories entirely. For a project whose entire purpose is being the authority on an API, the fragmentation of the process across four repositories is the main structural cost a new contributor pays.

Editorial conclusion

OpenGL-Registry is the right source for anyone generating OpenGL, ES or SC bindings, validating enum values against the authoritative XML, or walking through the extension process, and it is the wrong dependency for an application that only needs a handful of constants, where the generated headers alone would do. Before using it, check the api/GL, api/ES and api/SC directories for the headers you need rather than cloning the whole repository, read the licence file yourself since the README carries an SPDX identifier of CC-BY-4.0 for its own text, and remember that the last push was on 2026-10-06 with no tagged releases, so pin a commit rather than tracking main.

Frequently asked questions

Official sources

1. Issues
2. KhronosGroup/OpenGL-Registry on GitHub
3. README