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)
- 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.
- 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
- 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