API Reference¶

glreg provides functionality to parse and extract data from OpenGL XML API Registry files. Types, enums and functions (commands) in the registry can be enumerated. This module also provides functions to resolve dependencies and filter APIs in the registry. This makes it useful for generating OpenGL headers or loaders.

Classes¶

class glreg.Registry(name=None, types=None, enums=None, commands=None, features=None, extensions=None)¶

API Registry

name¶: Optional Registry name (or None)

types¶: collections.OrderedDict mapping of (type name, type API) to Type objects.

enums¶: collections.OrderedDict mapping of enum names to Enum objects.

commands¶: collections.OrderedDict mapping of command names to Command objects.

features¶: collections.OrderedDict mapping of feature names to Feature objects.

extensions¶: collections.OrderedDict mapping of extension names to Extension objects.

text¶: (readonly) Formatted API declarations. Equivalent to the concatenation of text attributes of all types, enums and commands in this registry.

get_apis()¶

Returns set of api names referenced in this Registry

Returns:	set of api name strings

get_extensions(support=None)¶

Returns filtered list of extensions in this registry

Parameters:	support – Return only extensions with this extension support string, or None to return all extensions.
Returns:	list of Extension objects

get_features(api=None)¶

Returns filtered list of features in this registry

Parameters:	api (str) – Return only features with this api name, or None to return all features.
Returns:	list of Feature objects

get_profiles()¶

Returns set of profile names referenced in this Registry

Returns:	set of profile name strings

get_removes(api=None, profile=None)¶

Returns filtered list of Remove objects in this registry

Parameters:	api (str) – Return Remove objects with this api name or None to return all Remove objects. profile (str) – Return Remove objects with this profile or None to return all Remove objects.
Returns:	list of Remove objects

get_requires(api=None, profile=None, support=None)¶

Returns filtered list of Require objects in this registry

Parameters:	api (str) – Return Require objects with this api name or None to return all Require objects. profile (str) – Return Require objects with this profile or None to return all Require objects. support (str) – Return Require objects with this extension support string or None to return all Require objects.
Returns:	list of Require objects

get_supports()¶

Returns set of extension support strings referenced in this Registry

Returns:	set of extension support strings

get_type(name, api=None)¶

Returns Type name, with preference for the Type of api.

Parameters:	name (str) – Type name api (str) – api name to prefer, of None to prefer types with no api name
Returns:	Type object

class glreg.Type(name, template, required_types=None, api=None, comment=None)¶

name¶: Type name

template¶

Type definition template with the following arguments:

name: name of the type (usually Type.name)
apientry: calling convention macro (usually the string APIENTRY, which is a C macro defined by the system platform headers)

required_types¶: set of str specifying the names of types this type depends on.

api¶: API name which this Type is valid for

comment¶: Optional comment, or None

text¶: (readonly) Formatted type definition. Equivalent to self.template.format(name=self.name, apientry='APIENTRY')

class glreg.Enum(name, value, comment=None)¶

name¶: Enum name

value¶: Enum string value

comment¶: Optional comment, or None

text¶: (readonly) Formatted enum C definition. Equivalent to '#define {0.name} {0.value}'.format(self)

class glreg.Command(name, type, proto_template, params, comment=None)¶

name¶: Command name

type¶: Command return type, or None

proto_template¶

Command identifier template string with the following arguments:

name: Command name (usually Command.name)
type: Command return type (usually Command.type). This argument is only used when this command has a return type.

params¶: list of command Params

comment¶: Optional comment, or None

required_types¶: (readonly) set of names of types which this Command depends on.

proto_text¶: (readonly) Formatted Command identifier. Equivalent to self.proto_template.format(type=self.type, name=self.name)

text¶: (readonly) Formatted Command C declaration.

class glreg.Param(name, type, template)¶

name¶: Param name

type¶: Optional name of Param type, or None

template¶

Param definition template with the following arguments:

name: Param name (usually Param.name)
type: Param type (usually Param.type). This argument is only used when this Param has a type.

text¶: Formatted Param definition. Equivalent to self.template.format(name=self.name, type=self.type)

class glreg.Feature(name, api, number, requires, removes, comment=None)¶

Feature

name¶: Feature name

api¶: API name which this Feature is valid for

number¶: Feature number as (major, minor) tuple.

requires¶: list of Feature Require objects.

removes¶: list of Feature Remove objects.

comment¶: Optional comment, or None.

get_apis()¶

Returns set of api names referenced in this Feature.

Returns:	set of api names

get_profiles()¶

Returns set of profile names referenced in this Feature

Returns:	set of profile names

get_removes(profile=None)¶

Get filtered list of Remove objects in this Feature

Parameters:	profile (str) – Return Remove objects with this profile or None to return all Remove objects.
Returns:	list of Remove objects

get_requires(profile=None)¶

Get filtered list of Require objects in this Feature

Parameters:	profile (str) – Return Require objects with this profile or None to return all Require objects.
Returns:	list of Require objects

class glreg.Extension(name, supported, requires, comment=None)¶

Extension

name¶: Extension name

supported¶: set of extension ‘supported’ strings

requires¶: list of Require objects

comment¶: Optional comment, or None.

get_apis()¶

Returns set of api names referenced in this Extension

Returns:	set of api name strings

get_profiles()¶

Returns set of profile names referenced in this Extension

Returns:	set of profile name strings

get_requires(api=None, profile=None)¶

Return filtered list of Require objects in this Extension

Parameters:	api (str) – Return Require objects with this api name or None to return all Require objects. profile (str) – Return Require objects with this profile or None to return all Require objects.
Returns:	list of Require objects

get_supports()¶

Returns set of extension support strings referenced in Extension

Returns:	set of extension support strings

class glreg.Require(types, enums, commands, profile=None, api=None, comment=None)¶

A requirement

types¶: list of type names which this Require requires.

enums¶: list of enum names which this Require requires.

commands¶: list of command names which this Require requires.

profile¶: Profile name which this Require is valid for

api¶: API name which this Require is valid for

comment¶: Optional comment, or None.

as_symbols()¶

Set of symbols required by this Require

Returns:	set of `(symbol type, symbol name)` tuples

class glreg.Remove(types, enums, commands, profile=None, comment=None)¶

Removal requirement

types¶: List of type names of Types to remove.

enums¶: List of enum names of Enums to remove.

commands¶: List of command names of Commands to remove.

profile¶: Profile name which this Remove is valid for.

comment¶: Optional comment, or None.

as_symbols()¶

Set of symbols required to be removed by this Remove

Returns:	set of `(symbol type, symbol name)` tuples

Registry loading functions¶

glreg.load(f)¶

Loads Registry from file

Parameters:	f (File-like object) – File to load
Returns:	Registry

glreg.loads(s)¶

Load registry from string

Parameters:	s (str or bytes) – Registry XML contents
Returns:	Registry

Registry importing functions¶

glreg.import_type(dest, src, name, api=None, filter_symbol=None)¶

Import Type name and its dependencies from Registry src to Registry dest.

Parameters:	dest (Registry) – Destination Registry src (Registry) – Source Registry name (str) – Name of type to import api (str) – Prefer to import Types with api Name api, or None to import Types with no api name. filter_symbol (Callable with signature `(symbol_type:str, symbol_name:str) -> bool`) – Optional filter callable

glreg.import_enum(dest, src, name)¶

Import Enum name from Registry src to Registry dest.

Parameters:	dest (Registry) – Destination Registry src (Registry) – Source Registry name (str) – Name of Enum to import

glreg.import_command(dest, src, name, api=None, filter_symbol=None)¶

Import Command name and its dependencies from Registry src to Registry dest

Parameters:	dest (Registry) – Destination Registry src (Registry) – Source Registry name (str) – Name of Command to import api (str) – Prefer to import Types with api name api, or None to import Types with no api name filter_symbol (Callable with signature `(symbol_type:str, symbol_name:str) -> bool`) – Optional filter callable

glreg.import_feature(dest, src, name, api=None, profile=None, filter_symbol=None)¶

Imports Feature name, and all its dependencies, from Registry src to Registry dest.

Parameters:

dest (Registry) – Destination Registry
src (Registry) – Source Registry
name (str) – Name of Feature to import
api (str) – Prefer to import dependencies with api name api, or None to import dependencies with no API name.
profile (str) – Import dependencies with profile name profile, or None to import all dependencies.
filter_symbol (Callable with signature (symbol_type:str, symbol_name:str) -> bool) – Optional symbol filter callable

glreg.import_extension(dest, src, name, api=None, profile=None, filter_symbol=None)¶

Imports Extension name, and all its dependencies.

Parameters:	dest (Registry) – Destination Registry src (Registry) – Source Registry name (str) – Name of Extension to import api (str) – Prefer to import types with API name api, or None to prefer Types with no API name. filter_symbol (Callable with signature `(symbol_type:str, symbol_name:str) -> bool`) – Optional symbol filter callable

glreg.import_registry(dest, src, api=None, profile=None, support=None, filter_symbol=None)¶

Imports all features and extensions and all their dependencies.

Parameters:

dest (Registry) – Destination API
src (Registry) – Source Registry
api (str) – Only import Features with API name api, or None to import all features.
profile (str) – Only import Features with profile name profile, or None to import all features.
support (str) – Only import Extensions with this extension support string, or None to import all extensions.
filter_symbol (Callable with signature (symbol_type:str, symbol_name:str) -> bool) – Optional symbol filter callable

API grouping functions¶

glreg.group_apis(reg, features=None, extensions=None, api=None, profile=None, support=None)¶

Groups Types, Enums, Commands with their respective Features, Extensions

Similar to import_registry(), but generates a new Registry object for every feature or extension.

Parameters:

reg (Registry) – Input registry
features (Iterable of strs) – Feature names to import, or None to import all.
extensions (Iterable of strs) – Extension names to import, or None to import all.
profile (str) – Import features which belong in profile, or None to import all.
api (str) – Import features which belong in api, or None to import all.
support (str) – Import extensions which belong in this extension support string, or None to import all.

Returns:

list of Registry objects