User Guide

Loading a Registry

Begin by importing the glreg module:

>>> import glreg

Use glreg.load() to load a OpenGL XML API Registry file. Assuming our file is named gl.xml in the current directory:

>>> registry = glreg.load(open('gl.xml'))

glreg.load() returns a glreg.Registry object.

Types

glreg.Type objects define the OpenGL types such as GLbyte, GLint etc.

Registry.types is a collections.OrderedDict object mapping (type name, type api) tuples to Type objects:

>>> registry.types
OrderedDict([(('stddef', None), Type(...)), ...

Use Registry.get_type() to look up Type objects by their name as it will take into account both Types with an API name specified and Types with no API name specified.

>>> registry.get_type('GLbyte')  # Get OpenGL's GLbyte typedef
Type('GLbyte', 'typedef signed char {name};')
>>> registry.get_type('GLbyte', 'gles2')  # Get OpenGLES2's GLbyte typedef
Type('GLbyte', 'typedef khronos_int8_t {name};', ...
>>> registry.get_type('GLbyte') is registry.get_type('GLbyte', 'gles2')
False
>>> registry.get_type('GLsync', 'gles2')
Type('GLsync', 'typedef struct __GLsync ...
>>> registry.get_type('GLsync')
Type('GLsync', 'typedef struct __GLsync ...
>>> registry.get_type('GLsync') is registry.get_type('GLsync', 'gles2')
True

Type.template is the template string of the type in Python’s Format String Syntax (PEP 3101). It has a name replacement field where the type’s identifier needs to be substituted in. It is usually Type.name or some similar variant.

>>> t = registry.get_type('GLbyte')
>>> t.template
'typedef signed char {name};'
>>> t.template.format(name=t.name)
'typedef signed char GLbyte;'

The Type.text convenience attribute does this common substitution.

>>> t.text
'typedef signed char GLbyte;'

Note that Type objects can depend on other types. Their names are listed in Type.required_types

>>> t = registry.get_type('GLbyte', 'gles2')
>>> t.required_types
{'khrplatform'}

Enums

glreg.Enum objects define the OpenGL constants such as GL_POINTS, GL_TRIANGLES etc.

Registry.enums is a collections.OrderedDict object mapping enum names to Enum objects:

>>> registry.enums
OrderedDict([('GL_CURRENT_BIT', Enum('GL_CURRENT_BIT', '0x00000001')), ...
>>> registry.enums['GL_POINTS']
Enum('GL_POINTS', '0x0000')

Commands

glreg.Command objects define OpenGL functions such as glClear and glDrawArrays.

Registry.commands is a collections.OrderedDict object mapping command names to Command objects:

>>> registry.commands
OrderedDict([('glAccum', Command(...)), ('glAccumxOES', Command(...
>>> registry.commands['glDrawArrays']
Command('glDrawArrays', 'void {name}', [Param('mode', 'GLenum', ...

Command objects contain their prototype template and a list of its parameters as Param objects:

>>> cmd = registry.commands['glDrawArrays']
>>> cmd.proto_template  # The command's prototype template
'void {name}'
>>> cmd.proto_text  # Convenience attribute for command's prototype
'void glDrawArrays'
>>> cmd.params  # The command's parameters
[Param('mode', 'GLenum', '{type} {name}'), Param('first', 'GLint', ...

Features

glreg.Feature objects are basically OpenGL version definitions.

Registry.features is a collections.OrderedDict object mapping feature names to Feature objects.

>>> registry.features
OrderedDict([('GL_VERSION_1_0', Feature(...)), ('GL_VERSION_1_1', Feature(...

Each Feature object lists the type, enum and command names that were introduced in that version in internal Require objects.

>>> registry.features['GL_VERSION_3_2']  # OpenGL version 3.2
Feature('GL_VERSION_3_2', 'gl', (3, 2), [Require([], ['GL_CONTEXT_CORE_PRO...
>>> feature = registry.features['GL_VERSION_3_2']
>>> feature.requires  # List of Require objects
[Require([], ['GL_CONTEXT_CORE_PROFILE_BIT', 'GL_CONTEXT_COMPATIBILITY...

On the other hand, Remove objects specify the types, enum and command names that were removed in that version.

>>> feature.removes  # List of Remove objects
[Remove([], [], ['glNewList', 'glEndList', 'glCallList', 'glCallLists', ...

Extensions

glreg.Extension objects are OpenGL extension definitions. Just like Feature objects, each Extension object list the type, enum and command names that were defined in that extension in internal Require objects.

>>> registry.extensions
OrderedDict([('GL_3DFX_multisample', Extension(...)), ('GL_3DFX_tbuffer', ...

Handling dependencies and removals

As seen above, Feature objects and Extension objects express dependency and removals of types, enums and commands in a registry through their Require and Remove objects. These dependencies and removals can be resolved using the Registry Importing functions.

glreg.import_type() imports a Type and its dependencies from one Registry object to another.

>>> dst_reg = glreg.Registry()
>>> glreg.import_type(dst_reg, registry, 'GLbyte')
>>> dst_reg.types
OrderedDict([(('GLbyte', None), Type('GLbyte', 'typedef signed char ...
>>> dst_reg = glreg.Registry()
>>> glreg.import_type(dst_reg, registry, 'GLbyte', api='gles2')
>>> dst_reg.types
OrderedDict([(('khrplatform', None), Type('khrplatform', ...

glreg.import_enum() imports a Enum from one Registry object to another. Note that Enum objects have no dependencies.

>>> dst_reg = glreg.Registry()
>>> glreg.import_enum(dst_reg, registry, 'GL_POINTS')
>>> dst_reg.enums
OrderedDict([('GL_POINTS', Enum('GL_POINTS', '0x0000'))])

glreg.import_command() imports a Command and its dependencies from one Registry to another.

>>> dst_reg = glreg.Registry()
>>> glreg.import_command(dst_reg, registry, 'glBufferData')
>>> dst_reg.commands
OrderedDict([('glBufferData', Command('glBufferData', 'vo...

glreg.import_feature() imports a Feature and its dependencies from one Registry to another. Removals which are active in the source Registry will be taken into account – all their specified types, enums and commands will not be imported.

>>> dst_reg = Registry()
>>> glreg.import_feature(dst, registry, 'GL_VERSION_3_2')
>>> dst_reg.features  # `dst_reg` now only contains GL_VERSION_3_2 and its deps
OrderedDict([('GL_VERSION_3_2', Feature('GL_VERSION_3_2', 'gl', (3, 2), ...

glreg.import_extension() imports a Extension and its dependencies from one Registry to another.

>>> dst_reg = Registry()
>>> glreg.import_extension(dst_reg, registry, 'GL_ARB_ES2_compatibility')
>>> dst_reg.extensions
OrderedDict([('GL_ARB_ES2_compatibility', Extension('GL_ARB_ES2_c...

Filtering Features and Extensions

When calling glreg.import_feature() without any of its filter arguments, close inspection of the destination registry will reveal that both OpenGL and OpenGL ES commands are mixed together, and that the OpenGL types have overridden the OpenGL ES types. This is undesirable for applications which only target OpenGL and OpenGL ES.

We can ensure that only OpenGL or OpenGL ES types, enums and commands are imported into the destination registry using filters.

Feature objects can be filtered by api name and profile name. Extension objects can be filtered by extension support strings.

>>> dst = Registry()  # Destination registry
>>> import_registry(dst, registry, api='gl', profile='core', support='glcore')
>>> list(dst.features.keys())  # dst now only contains OpenGL Core features
['GL_VERSION_1_0', 'GL_VERSION_1_1', 'GL_VERSION_1_2', ...
>>> list(dst.extensions.keys())  # dst now only contains OpenGL Core extensions
['GL_ARB_ES2_compatibility', 'GL_ARB_ES3_1_compatibility', 'GL_ARB_ES3_comp...

Registry.get_apis(), Registry.get_profiles() and Registry.get_supports() will return all the api names, profile names and extension support strings referenced in the registry respectively.

>>> sorted(registry.get_apis())
['gl', 'gles1', 'gles2']
>>> sorted(registry.get_profiles())
['common', 'compatibility', 'core']
>>> sorted(registry.get_supports())
['gl', 'glcore', 'gles1', 'gles2']

Grouping Types, Enums and Commands by their Feature or Extension

OpenGL C header files typically group types, enums and commands by the feature or extension where they were first introduced. This can be accomplished using glreg.group_apis().

glreg.group_apis() generates a new Registry object for every feature and extension in a registry while importing their types, enums and commands. This effectively groups types, enums and commands with the feature or extension where they were first defined.

>>> group_apis(registry, api='gles2', support='gles2')
[Registry('GL_ES_VERSION_2_0', OrderedDict([(('khrplatform', None), Type...

A simple OpenGL (ES) C header can thus be generated with the following loop:

>>> for api in group_apis(registry, api='gles2', support='gles2'):
...     print('#ifndef ' + api.name)
...     print('#define ' + api.name)
...     print(api.text)
...     print('#endif')
#ifndef GL_ES_VERSION_2_0
#define GL_ES_VERSION_2_0
#include <KHR/khrplatform.h>
typedef khronos_int8_t GLbyte;
...

Command-line interface

When run as a script from the command line, glreg provides a simple command line interface for generating C header files from a registry.

Example usage:

$ python -mglreg --list-apis gl.xml
gl
gles1
gles2
$ python -mglreg --list-profiles gl.xml
common
compatibility
core
$ python -mglreg --list-supports gl.xml
gl
glcore
gles1
gles2
$ python -mglreg --api gl --profile core --support glcore gl.xml
#ifndef GL_VERSION_1_0
#define GL_VERSION_1_0
typedef void GLvoid;
typedef unsigned int GLenum;
typedef int GLint;
typedef int GLsizei;
typedef double GLdouble;
typedef unsigned int GLbitfield;
typedef float GLfloat;
typedef unsigned char GLboolean;
typedef unsigned int GLuint;
extern void glBlendFunc(GLenum sfactor, GLenum dfactor);
extern void glClear(GLbitfield mask);...

The command-line arguments are as follows:

registry

Registry path. If this argument is not provided, glreg will read the registry from standard input.

-o PATH, --output PATH

Write output to PATH.

--api API

Output only features with API name API.

--profile PROFILE

Output only features with profile name PROFILE.

--support SUPPORT

Output only extensions with extension support string SUPPORT.

--list-apis

List api names in registry.

--list-profiles

List profile names in registry.

--list-supports

List extension support strings in registry

Limitations

  • <remove> tags in <extension> tags, despite being defined in the schema, is not supported because they do not make sense.
  • <group> tags are not supported yet.