This module implements an Oriented Object interface to the OpenGL XML API Registry which describe the OpenGL API and theses official extensions. The XML file and its relative documentation are stored in the Khronos OpenGL API CVS.
To generate the API of a particular OpenGL version uses for example this code snippet:
xml_file_path = default_api_path('gl') # path to gl.xml
gl_spec = GlSpecParser(xml_file_path)
api_enums, api_commands = gl_spec.generate_api('gles', ApiNumber('2.0'), 'core')
api_enums, api_commands = gl_spec.generate_api('gl', ApiNumber('4.4'), 'core')
Then you will get an instance of the class Enums and Commands corresponding to the requested API.
The query-opengl-api tool in the bin directory provides some functions to query the OpenGL API. You could look at its source code to learn how to use this module. See the tools section.
Bases: object
This class implements a cached GlSpecParser using Pickle files.
Pickle files are stored in the HOME directory.
Generate and pickle an API.
Unpickle an API.
Unpickle a :class:’GlSpecParser’.
Pickle the GlSpecParser instance.
Return the file path for the pickled API.
Return the file path for the pickled XML Registry (GlSpecParser).
Bases: object
This class defines an OpenGL command.
Public Attributes:
- input_parameter
- number of input parameters
- name
- command name
- output_parameter
- number of output parameters
- parameter_dict
- dictionnary of parameters
- parameters
- list of parameters
return_type
XML Registry Documentation:
The <command> tag contains a structured definition of a single API command (function).
Attributes of <command> tags:
- comment
- arbitrary string (unused).
Contents of <command> tags:
- <proto> must be the first element, and is a tag defining the C function prototype of a command as described below, up to the function name but not including function parameters.
- <param> elements for each command parameter follow, defining its name and type, as described below. If a command takes no arguments, it has no <param> tags.
Following these elements, the remaining elements in a <command> tag are optional and may be in any order:
- <alias> has no attributes and contains a string which is the name of another command this command is an alias of, used when promoting a function from extension to ARB or ARB to API status. A command alias describes the case where there are two function names which resolve to the same client library code, so (for example) the case where a command is promoted but is also given different GLX protocol would not be an alias in this sense.
- <vecequiv> has no attributes and contains a string which is the name of another command which is the vector equivalent of this command. For example, the vector equivalent of glVertex3f is glVertex3fv.
- <glx> defines GLX protocol information for this command, as described below. Many GL commands don’t have GLX protocol defined, and other APIs such as EGL and WGL don’t use GLX at all.
Command prototype (<proto> tags):
The <proto> tag defines the return type and name of a command.
Attributes of <proto> tags
- group
- group name, an arbitrary string.
If the group name is defined, it may be interpreted as described in <ref>.
Contents of <proto> tags:
The text elements of a <proto> tag, with all other tags removed, is legal C code describing the return type and name of a command. In addition it may contain two semantic tags:
- The <ptype> tag is optional, and contains text which is a valid type name found in <type> tag, and indicates that this type must be previously defined for the definition of the command to succeed. Builtin C types, and any derived types which are expected to be found in other header files, should not be wrapped in <ptype> tags.
- The <name> tag is required, and contains the command name being described.
Bases: PyOpenGLng.GlApi.NameDict
This class stores the OpenGL commands.
XML Registry Documentation:
The <commands> tag contains definitions of each of the functions (commands) used in the API.
Attributes of <commands> tags:
- namespace
- a string defining the namespace in which commands live, currently unused but typically something like GL.
Contents of <commands> tags:
Each <commands> block contains zero or more <command> tags, in arbitrary order (although they are typically ordered by sorting on the command name, to improve human readability).
Bases: object
This class defines an enumerant.
The name of an enumerant can be retrieved using str(enumerant) and its value using int(enumerant).
Public Attributes:
XML Registry Documentation:
Each <enum> tag defines a single GL (or other API) token.
Attributes of <enum> tags:
- value
- enumerant value, a legal C constant (usually a hexadecimal integer).
- name
- enumerant name, a legal C preprocessor token name.
- api
- an API name which specializes this definition of the named enum, so that different APIs may have different values for the same token (used to address a few accidental incompatibilities between GL and GL ES).
- type
- legal C suffix for the value to force it to a specific type. Currently only u and ull are used, for unsigned 32- and 64-bit integer values, respectively. Separated from the value field since this eases parsing and sorting of values, and is rarely used.
- alias
- name of another enumerant this is an alias of, used where token names have been changed as a result of profile changes or for consistency purposes. An enumerant alias is simply a different name for the exact same value. At present, enumerants which are promoted from extension to core API status are not tagged as aliases - just enumerants tagged as aliases in the Changed Tokens sections of appendices to the OpenGL Specification. This might change in the future.
- comment
- arbitrary string (unused).
Contents of <enum> tags:
<enum> tags have no allowed contents. All information is contained in the attributes.
Bases: object
This class defines a list of enumerants.
Public Attributes:
comment
end
group
namespace
start
type
vendor
XML Registry Documentation:
The <enums> tags contain individual <enum> tags describing each of the token (enumerant) names used in the API.
Attributes of <enums> tags:
- namespace
- a string for grouping many different enums together, currently unused but typically something like GL for all enums in the OpenGL / OpenGL ES shared namespace. Multiple <enums> tags can share the same namespace.
- type
- a string describing the data type of the values of this group of enums, currently unused. The only string used at present in the is bitmask.
- start, end
- integers defining the start and end of a reserved range of enumerants for a particular vendor or purpose. start must be <= end. These fields define formal enumerant allocations within a namespace, and are made by the Khronos Registrar on request from implementers following the enum allocation policy.
- vendor
- string describing the vendor or purposes to whom a reserved range of enumerants is allocated.
- comment
- arbitrary string (unused)
- group
- group name, an arbitrary string.
Contents of <enums> tags:
Each <enums> block contains zero or more <enum> and <unused> tags, in arbitrary order (although they are typically ordered by sorting on enumerant values, to improve human readability).
Bases: object
This class defines the features of an extension.
Features are provided as a list of required or removed interfaces (commands, enumerants and types).
Public Attributes:
comment
name
protect
supported
XML Registry Documentation:
The <extensions> tag contains definitions of each of the extenions which are defined for the API.
Attributes of <extensions> tags: None
Contents of <extensions> tags:
Each <extensions> block contains zero or more <extension> tags, each describing an API extension, in arbitrary order (although they are typically ordered by sorting on the extension name, to improve human readability).API Extensions (<extension> tag):
API extensions are described in individual <extension> tags. An extension is the set of interfaces defined by a particular API extension specification, such as ARB_multitexture. <extension> is similar to <feature>, but instead of having version and profile attributes, instead has a supported attribute, which describes the set of API names which the extension can potentially be implemented against.
Attributes of <extension> tags:
- supported
- a regular expression, with an implicit ^ and $ bracketing it, which should match the api tag of a set of <feature> tags.
- protect
- an additional preprocessor token used to protect an extension def- inition. Usually another feature or extension name. Rarely used, for odd cir- cumstances where the definition of an extension requires another to be defined first.
- comment
- arbitrary string (unused)
Contents of <extension> tags:
Zero or more <require> and <remove> tags (see <ref>), in arbitrary order. Each tag describes a set of interfaces that is respectively required for, or removed from, this extension, as described below.
Bases: object
This class defines the features of an API.
Features are provided as a list of required or removed interfaces (commands, enumerants and types).
Public Attributes:
api
api_number
comment
name
protect
XML Registry Documentation:
API features are described in individual <feature> tags. A feature is the set of interfaces (enumerants and commands) defined by a particular API and version, such as OpenGL 4.0 or OpenGL ES 3.0, and includes all API profiles of that version.
Attributes of <feature> tags:
- api
- API name this feature is for (see <ref>), such as gl or gles2.
- name
- version name, used as the C preprocessor token under which the version’s interfaces are protected against multiple inclusion. Example: GL_VERSION_4_2.
- protect
- an additional preprocessor token used to protect a feature definition. Usually another feature or extension name. Rarely used, for odd circumstances where the definition of a feature or extension requires another to be defined first.
- number
- feature version number, usually a string interpreted as majorNumber.minorNumber. Example: 4.2.
- comment
- arbitrary string (unused)
Contents of <feature> tags:
Zero or more <require> and <remove> tags (see <ref>), in arbitrary order. Each tag describes a set of interfaces that is respectively required for, or removed from, this feature, as described below.
Bases: object
This class implements the OpenGL Registry XML file parser and the Oriented Object interface.
Public Attributes:
Convert node attributes.
The parameter int_attributes specifies a list of attributes that must be converted to integers.
The parameter renaming can be specified to perform a key renaming during the copy. It must be a dictionary where the keys correspond to the source keys and the values to the destination keys.
Copy a dictionary.
The parameter renaming can be specified to perform a key renaming during the copy. It must be a dictionary where the keys correspond to the source keys and the values to the destination keys.
Iter on nodes and call the callback function if the tag match.
Parse a C type and look for const and pointer multiplicity.
Return the type without const and *.
Bases: object
This class defines an Enumerant Group, e.g. TextureMagFilter regroups the relevant enumerant for texture magnification filter
Public Attributes:
comment
name
XML Registry Documentation:
Each <group> tag defines a single group annotation.
Attributes of <group> tags:
- name
- group name, an arbitrary string for grouping a set of enums together within a broader namespace.
Contents of <group> tags:
<group> tags may contain zero or more <enum> tags. Each <enum> tag may contain only a name attribute, which should correspond to a <enum> definition in an <enums> block.Meaning of <group> tags:
If a <proto> or <param> tag of a <command> has a group attribute defined, and that attribute matches a <group> name, then the return type or parameter type is considered to be constrained to values defined by the corresponding <group>. C language bindings do not attempt to enforce this constraint in any way, but other language bindings may try to do so.
Bases: PyOpenGLng.GlApi.NameDict
This class registers Enumerant Groups.
XML Registry Documentation:
The <groups> tags contain individual <group> tags describing some of the group annotations used for return and parameter types.
Attributes of <groups> tags: None
Contents of <groups> tags:
Each <groups> block contains zero or more <group> tags, in arbitrary order (although they are typically ordered by group name, to improve human readability).
Bases: dict
This class extend the Python dictionnary class with two methods register() and unregister().
Bases: exceptions.Exception
Bases: object
This class defines a command parameter.
Public Attributes:
- array_size
- array size or None
- pointer_parameters
- array of pointer parameters where this parameter acts as a size parameter
- c_type
- corresponding Type instance or “void”
- computed_size
- Boolean
- const
- Boolean
- group
- group name
- location
- parameter position in the prototype
- name
- parameter name or None for return type
- pointer
- pointer level, i.e. 0 for a non-pointer parameter, 1 for *, 2 for **
- size_multiplier
- integer to be multiplied with the size parameter to get the size
- size_parameter
- name of the size parameter or None
- type
- parameter type without const and ``*
XML Registry Documentation:
The <param> tag defines the type and name of a parameter.
Attributes of <param> tags:
- group
- group name, an arbitrary string.
- len
- parameter length, either an integer specifying the number of elements of the parameter <ptype>, or a complex string expression with poorly defined syntax, usually representing a length that is computed as a combination of other command parameter values, and possibly current GL state as well.
If the group name is defined, it may be interpreted as described in <ref>.
Contents of <param> tags:
The text elements of a <param> tag, with all other tags removed, is legal C code describing the type and name of a function parameter. In addition it may contain two semantic tags:
- The <ptype> tag is optional, and contains text which is a valid type name found in <type> tag, and indicates that this type must be previously defined for the definition of the command to succeed. Builtin C types, and any derived types which are expected to be found in other header files, should not be wrapped in <ptype> tags.
- The <name> tag is required, and contains the command name being described.
Bases: PyOpenGLng.GlApi.RequiredInterface
This class defines a removed interface.
Create and append a RemovedItem.
Bases: PyOpenGLng.GlApi.RequiredItem
This class represents a removed command, enumerant or type from an interface.
Bases: object
This class defines a required interface.
Public Attributes:
api
comment
profile
XML Registry Documentation:
A <require> block defines a set of interfaces (types, enumerants and commands) required by a <feature> or <extension>. A <remove> block defines a set of interfaces removed by a <feature> (this is primarily useful for the OpenGL core profile, which removed many interfaces - extensions should never remove interfaces, although this usage is allowed by the schema). Except for the tag name and behavior, the contents of <require> and <remove> tags are identical.
Attributes of <require> and <remove> tags:
- profile
- string name of an API profile. Interfaces in the tag are only required (or removed) if the specified profile is being generated. If not specified, interfaces are required (or removed) for all API profiles.
- comment
- arbitrary string (unused)
- api
- an API name (see <ref>). Interfaces in the tag are only required (or removed) if the specified API is being generated. If not specified, interfaces are required (or removed) for all APIs. The api attribute is only supported inside <extension> tags, since <feature> tags already define a specific API.
Contents of <require> and <remove> tags:
Zero or more of the following tags, in any order:
<command> specifies an required (or removed) command defined in a <commands> block. The tag has no content, but contains elements:
- name
name of the command (required).
- comment
arbitrary string (optional and unused).
<enum> specifies an required (or removed) enumerant defined in a <enums> block. The tag has no content, but contains elements:
- name
name of the enumerant (required).
- comment
arbitrary string (optional and unused).
<type> specifies a required (or removed) type defined in a <types> block. Most types are picked up implicitly by using the <ptype> tags of commands, but in a few cases, additional types need to be specified explicitly (it is unlikely that a type would ever be removed, although this usage is allowed by the schema). The tag has no content, but contains elements:
- name
name of the type (required).
- comment
arbitrary string (optional and unused).
Create and append a RequiredItem.
Bases: object
This class represents a required command, enumerant or type for an interface.
Public Attributes:
comment
name
- type
- can be “command”, “enumerant” or “type”
Bases: object
This class defines an OpenGL type.
Public Attributes:
- api
- API name
- api_entry
- Boolean, cf. supra
- c_code
- correponding C type declaration (without name), e.g. typedef unsigned int
- c_type
- correponding C type, e.g. int
- comment
- cf. supra
- name
- e.g. GLenum
- pointer
- Boolean
- requires
- cf. supra
- unsigned
- Boolean
XML Registry Documentation:
Each <type> tag contains legal C code, with attributes or embedded tags denoting the type name.
Attributes of <type> tags:
- requires
- another type name this type requires to complete its definition.
- name
- name of this type (if not defined in the tag body).
- api
- an API name (see <feature> below) which specializes this definition of the named type, so that the same API types may have different definitions for e.g. GL ES and GL.
- comment
- arbitrary string (unused).
Contents of <group> tags:
<type> contains text which is legal C code for a type declaration. It may also contain embedded tags:
- <apientry/>
- insert a platform calling convention macro here during header generation, used mostly for function pointer types.
- <name>
- contains the name of this type (if not defined in the tag attributes).
List of C types
Bases: object
This class registers the API types.
Public Attributes:
- c_types
- dictionnary of types indexed by their names
- types
- list of types
XML Registry Documentation:
The <types> tag contains individual <type> tags describing each of the derived types used in the API.