# [`glregistry`][]
Cache and query the [OpenGL][] [registry][] locally.
`glregistry` is a Python program that glues together [HTTPS][] downloading,
[XPath][] querying, data accumulation/sorting, [`grep`][]ing, [color][] output,
and launching external [editor][]/[pager][] programs.
It tries to be a good Unix citizen by obeying relevant environment variables
and being [pipe][]-friendly, outputting newline-separated entries. Where
appropriate each line is in a widely supported format, usable with e.g.
[Vim][]'s [QuickFix][] ([`:cexpr`][]` system('glregistry audit')` or [`vim
-q`][]` <(glregistry audit)`) and [GNU Emacs][]' [Compilation Mode][] ([`M-x
compile`][]` glregistry audit`).
The vendors `KHR` (Khronos), `ARB` (Architecture Review Board), and `EXT`
(Extension) are treated specially and are sorted before other vendors. When
querying for enums, either directly or indirectly, enums with the same name,
except for one of these vendors added as a suffix, and the same value is
matched as well.
Note that only the OpenGL (not OpenGL ES) API, and only the core (not
compatibility) [profile][] is considered.
[`glregistry`]: https://git.rcrnstn.net/rcrnstn/glregistry
[OpenGL]: https://en.wikipedia.org/wiki/OpenGL
[registry]: https://registry.khronos.org/OpenGL/
[HTTPS]: https://en.wikipedia.org/wiki/HTTPS
[XPath]: https://en.wikipedia.org/wiki/XPath
[`grep`]: https://en.wikipedia.org/wiki/Grep
[color]: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
[editor]: https://en.wikipedia.org/wiki/Text_editor
[pager]: https://en.wikipedia.org/wiki/Terminal_pager
[pipe]: https://en.wikipedia.org/wiki/Pipeline_(Unix)
[Vim]: https://en.wikipedia.org/wiki/Vim_(text_editor)
[QuickFix]: https://vimhelp.org/quickfix.txt.html
[`:cexpr`]: https://vimhelp.org/quickfix.txt.html#%3Acexpr
[`vim -q`]: https://vimhelp.org/starting.txt.html#-q
[GNU Emacs]: https://en.wikipedia.org/wiki/GNU_Emacs
[Compilation Mode]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation-Mode.html
[`M-x compile`]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Compilation.html#index-compile-2624
[profile]: https://www.khronos.org/opengl/wiki/OpenGL_Context#OpenGL_3.2_and_Profiles
## Usage
`glregistry --help`:
```
glregistry 1.0
Cache and query the OpenGL registry locally.
Usage:
glregistry xml
glregistry xml-path
glregistry ext <extension>
glregistry ext-path <extension>
glregistry exts
glregistry exts-download
glregistry exts-all <name>
glregistry vendors
glregistry type <type>
glregistry aliases <enum>
glregistry value <enum>
glregistry enum <value>
glregistry supports <name>
glregistry names [<support>]
glregistry groups [<enum>]
glregistry enums [<group>]
glregistry enums-tree [<group>]
glregistry params [<group>]
glregistry params-tree [<group>]
glregistry audit [<path>]
glregistry audit-tree [<path>]
glregistry refs <name>
glregistry refs-all <name>
glregistry -h|--help
Commands:
xml
Download the registry XML and open it with an editor.
xml-path
Download the registry XML and print its local path.
ext <extension>
Download the <extension> spec and open it with an editor.
ext-path <extension>
Download the <extension> spec and print its local path.
exts
Print the names of all extension specs.
exts-download
Download all extension specs.
exts-all <name>
Print all downloaded extensions that mention <name>.
vendors
Print all vendor abbreviations.
type <type>
Print the definition of <type>.
aliases <enum>
Print the KHR, ARB, and EXT aliases of <enum>.
value <enum>
Print the value of <enum>.
enum <value>
Print the enum(s) that has the given <value>.
supports <name>
Print the OpenGL version or extension required to use <name>.
names [<support>]
Print the names introduced by the OpenGL version or extension <support> if
given, or all names if omitted. The special values VERSION and EXTENSION
print the names introduced by all versions or all extensions respectively.
groups [<enum>]
Print the groups of <enum> if given, or all groups if omitted.
enums [<group>]
Print the enums in <group> if given, or all enums if omitted.
enums-tree [<group>]
Print the enums in <group> if given, or all enums if omitted, sorted on
support, in a tree.
params [<group>]
Print the parameter names of <group> if given, or all parameter names if
omitted.
params-tree [<group>]
Print the parameter names of <group> if given, or all parameter names if
omitted, sorted on count, together with the commands sorted on support, in
a tree.
audit [<path>]
Search files in <path> if given, or the current directory if omitted,
recursively for OpenGL API names and print them sorted on location,
support, and name, in a list.
audit-tree [<path>]
Search files in <path> if given, or the current directory if omitted,
recursively for OpenGL API names and print them sorted on support, name,
and location, in a tree.
refs <name>
Print the URLs of all reference pages with name <name>.
refs-all <name>
Print the URLs of all reference pages that mention <name>, sorted on
support, in a tree.
Environment variables:
GLREGISTRY_CACHE
The directory to cache files in. Defaults to `$XDG_CACHE_HOME/glregistry`
or, if `$XDG_CACHE_HOME` is not defined, `$HOME/.cache/glregistry`.
GLREGISTRY_EDITOR
The editor to use when opening files. Defaults to `$EDITOR` or, if
`$EDITOR` is not defined, `editor` if it exists in `$PATH`, else `vi`. The
value is interpreted by the shell.
GLREGISTRY_PAGER
The pager to use when viewing output. Defaults to `$PAGER` or, if `$PAGER`
is not defined, `pager` if it exists in `$PATH`, else `less` . The value is
interpreted by the shell. If the `$LESS` environment variable is unset, it
is set to `FR`.
GLREGISTRY_COLORS
If standard out is a terminal, the colors used in output of the `enums`,
`enums-tree`, `params`, `params-tree`, `audit,` and `audit-tree` commands.
It uses the same format (and defaults) as GREP_COLORS, i.e. a
colon-separated list of capabilties: `ms` (matching selected), `fn` (file
name), `ln` (line and column number), `se` (separators). Added custom
capabilities are: `ve` (version), `ex` (extension), `un` (unsupported).
Defaults to `ms=01;31:fn=35:ln=32:se=36:ve=01;34:ex=34:un=01;33`.
```
## Examples
The following example demonstrates exploring the OpenGL API starting from code
in a repository.
## References
Note that some of these might be out of date.
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/readme.pdf>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/registry.rnc>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/reg.py>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/xml/genheaders.py>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/extensions/registry.py>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/syntaxrules.txt>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/promoting.html>
- <https://github.com/KhronosGroup/OpenGL-Registry/blob/main/docs/enums.html>
- <https://github.com/KhronosGroup/OpenGL-Registry/issues/481>
See also:
- The community-driven [OpenGL Hardware Database][].
[OpenGL Hardware Database]: https://opengl.gpuinfo.org
## Install
Make sure [Python is installed][Python download], [`pip`][] is available and
the [`pip`][], [`setuptools`][] and [`wheel`][] packages are up to date:
```sh
python3 -m pip install --user --upgrade pip setuptools wheel
```
Reference: [Python Packaging User Guide: Requirements for Installing
Packages][].
[Python download]: https://python.org/download
[`pip`]: https://pip.readthedocs.io
[`setuptools`]: https://setuptools.readthedocs.io
[`wheel`]: https://wheel.readthedocs.io
[Python Packaging User Guide: Requirements for Installing Packages]: https://packaging.python.org/tutorials/installing-packages/#requirements-for-installing-packages
### With [`pipx`][], for users
Make sure [`pipx`][] is installed:
```sh
python3 -m pip install --user pipx
```
Install `glregistry`:
```sh
pipx install "git+https://git.rcrnstn.net/rcrnstn/glregistry"
```
`glregistry` should now be in your [`PATH`][] (if not, run `python3 -m pipx
ensurepath`).
Reference: [Python Packaging User Guide: Installing stand alone command line
tools][].
[`pipx`]: https://pipxproject.github.io/pipx/
[`PATH`]: https://en.wikipedia.org/wiki/PATH_(variable)
[Python Packaging User Guide: Installing stand alone command line tools]: https://packaging.python.org/guides/installing-stand-alone-command-line-tools/
### Into [`venv`][], for developers
Clone and install into a repository [`venv`][] virtual environment:
```sh
git clone "https://git.rcrnstn.net/rcrnstn/glregistry"
cd "glregistry"
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --editable .
```
`glregistry` should now be in your (virtual environment) [`PATH`][].
Reference: [Python Packaging User Guide: Installing packages using pip and
virtual environments][].
[`venv`]: https://docs.python.org/3/library/venv.html
[Python Packaging User Guide: Installing packages using pip and virtual environments]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/
## License
Licensed under the [ISC License][] unless otherwise noted, see the
[`LICENSE`][] file.
[ISC License]: https://choosealicense.com/licenses/isc/
[`LICENSE`]: LICENSE
git.rcrnstn.net