# [`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`.

 ```
 
 ## 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