# [`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. ``` $ glregistry audit-tree example-repo 4.6,GL_ARB_texture_filter_anisotropic,GL_EXT_texture_filter_anisotropic GL_TEXTURE_MAX_ANISOTROPY src/gltexture.cpp:3:17 $ glregistry exts-all GL_TEXTURE_MAX_ANISOTROPY GL_ARB_sampler_objects GL_ARB_texture_filter_anisotropic GL_EXT_texture_filter_anisotropic $ glregistry groups GL_TEXTURE_MAX_ANISOTROPY SamplerParameterF TextureParameterName $ glregistry enums-tree SamplerParameterF 1.0 GL_TEXTURE_BORDER_COLOR 1.2 GL_TEXTURE_MAX_LOD GL_TEXTURE_MIN_LOD 1.4,GL_EXT_texture_lod_bias GL_TEXTURE_LOD_BIAS 4.6,GL_ARB_texture_filter_anisotropic,GL_EXT_texture_filter_anisotropic GL_TEXTURE_MAX_ANISOTROPY $ glregistry params-tree SamplerParameterF pname:3 3.3,GL_ARB_sampler_objects glGetSamplerParameterfv glSamplerParameterf glSamplerParameterfv $ glregistry refs glSamplerParameter https://registry.khronos.org/OpenGL-Refpages/gl4/html/glSamplerParameter.xhtml ``` ## 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