Lines Matching defs:the
32 This document describes the Khronos OpenGL API Registry XML schema, and provides
33 some additional information about using the registry and scripts to generate
35 generated from the current authoritative copy of the XML files, can be
36 obtained from the OpenGL-Registry github repository at
49 The registry uses an XML representation of the API and a set of Python 3
50 scripts to manipulate the XML, based on the lxml Python bindings. It comes
52 requests on github, although the XML schema itself is mature and unlikely to
56 schema originally based on the OpenGL schema to describe those APIs.
61 translators between the schema.
66 Once the repository has been downloaded, if you're running
67 in a Linux command-line environment and have Python 3, the lxml Python
69 \code{make} and generate C/C++ header files for all the following
88 Starting with the Makefile rules and inspecting the files \code{gl.xml},
90 repurpose the registry for reasons other than header file generation, or
96 Windows 10, you should probably try to build in the Ubuntu Linux subsystem
102 When generating header files using the \code{genheaders.py} script, an
103 API name and profile name are required, as shown in the Makefile
105 or excluded. Based on this information, the generator script extracts
106 the relevant interfaces and creates a C-language header file for them.
112 the C types and definitions in the XML to something appropriate to their
120 internal documentation in the form of comments although nothing more
121 extensive exists yet, and it's possible the Python scripts will evolve
130 \tag{extension} tags describing the different elements of an API, as
132 schema file, \code{registry.rnc}, against which the XML registry files
147 Types and enumerants can have different definitions depending on the API
149 in the OpenGL and OpenGL ES APIs, for example. Features and extensions
150 can include some elements conditionally depending on the API profile
159 name. As used in \code{genheaders.py} and \code{gl.xml}, the API names
167 A \tag{registry} contains the entire definition of one or more related
176 Zero or more of each of the following tags, normally in this order
208 of the derived types used in the API.
211 tags denoting the type name.
218 \item \attr{name} - name of this type (if not defined in the tag body).
220 specializes this definition of the named type, so that the same
233 \item \tag{name} - contains the name of this type (if not defined in the
246 If the {\tt GLint64} type is required by a command, this will result in
247 the following declarations:
258 some metadata not captured by the \tag{types} tag (see section~\ref{tag:types})
264 \item \attr{name} - the name of the kind.
265 \item \attr{desc} - a description of what the kind indicates.
278 <kind name="Clamped[0; 1]" desc="This parameter will get clamped to the 0 to 1 range." />
304 \attr{kind} attribute defined, and and the comma separated elemenst
305 if the attribute matches a \tag{kind} name,
306 then the return type or parameter type is considered to be
307 further defined by the description provided by the \tag{kind} tags
308 with the matching names. C language bindings do not attempt to
316 some of the group annotations used for return and parameter types.
367 name, then the return type or parameter type is considered to be
368 constrained to values defined by the corresponding \tag{group}. C
376 The \tag{enums} tags contain individual \tag{enum} tags describing each of the
377 token (enumerant) names used in the API.
384 for all enums in the OpenGL / OpenGL ES shared namespace. Multiple
385 \tag{enums} tags can share the same namespace.
386 \item \attr{type} - a string describing the data type of the values of
388 present in the is \code{bitmask}.
389 \item \attr{start}, \attr{end} - integers defining the start and end of
392 enumerant allocations within a namespace, and are made by the
393 Khronos Registrar on request from implementers following the enum
395 \item \attr{vendor} - string describing the vendor or purposes to whom a
440 \item \attr{api} - an API name which specializes this definition of the
442 the same token (used to address a few accidental incompatibilities
444 \item \attr{type} - legal C suffix for the value to force it to a
447 Separated from the \attr{value} field since this eases parsing and
451 \par {\bf Note:} the \tag{group} tag (see section~\ref{tag:group})
452 serves the same purpose, but is deprecated in favor of this attribute.
453 Eventually all \tag{group} tags will be removed from the XML
458 different \attr{name} for the exact same \attr{value}. At present,
461 the {\em Changed Tokens} sections of appendices to the OpenGL
462 Specification. This might change in the future.
468 in the attributes.
475 but not yet assigned to specific enums. This just tracks the unused
481 \item \attr{start}, \attr{end} - integers defining the start and end of
483 \attr{end}. This range should not exceed the range reserved by the
485 \item \attr{vendor} - string describing the vendor or purposes to whom a
487 the \attr{vendor} attribute of the surrounding \attr{enums} block.
499 The \tag{commands} tag contains definitions of each of the functions
500 (commands) used in the API.
505 \item \attr{namespace} - a string defining the namespace in which
513 arbitrary order (although they are typically ordered by sorting on the
532 \item \tag{proto} must be the first element, and is a tag defining the C
533 function prototype of a command as described below, up to the
540 Following these elements, the remaining elements in a \tag{command}
544 \item \tag{alias} has one attribute, \attr{name}, containing a string which is the
547 command alias describes the case where there are two function
548 names which resolve to the {\bf same} client library code, so (for
549 example) the case where a command is promoted but is also given
552 the name of another command which is the {\em vector equivalent}
553 of this command. For example, the vector equivalent of
564 The \tag{proto} tag defines the return type and name of a command.
574 If the group name is defined, it may be interpreted as described in
580 legal C code describing the return type and name of a command. In addition
586 type must be previously defined for the definition of the command
590 \item The \tag{name} tag is required, and contains the command name
597 The \tag{param} tag defines the type and name of a parameter.
605 \item \attr{len} - parameter length, either an integer specifying the
606 number of elements of the parameter \tag{ptype}, or a complex
610 \item \attr{class} - an arbitrary string defining the type of object handles
617 If the group name is defined, it may be interpreted as described in
623 legal C code describing the type and name of a function parameter. In
629 type must be previously defined for the definition of the command
633 \item The \tag{name} tag is required, and contains the command name
662 is the set of interfaces (enumerants and commands) defined by a
671 \item \attr{name} - version name, used as the C preprocessor token under
672 which the version's interfaces are protected against multiple
676 \attr{name}. Rarely used, for odd circumstances where the
706 When processed into a C header for the \code{compatibility} profile of
707 OpenGL, this results in (assuming the usual definitions of these GL
723 If processed into a header for the \code{core} profile, the definition of
730 The \tag{extensions} tag contains definitions of each of the extenions
731 which are defined for the API.
741 typically ordered by sorting on the extension name, to improve human
749 extension is the set of interfaces defined by a particular API extension
753 which describes the set of API names which the extension can potentially
760 \code{\^{}} and \code{\$} bracketing it, which should match the
764 \attr{name}. Rarely used, for odd circumstances where the
792 The \attr{supported} attribute says that the extension can be supported for
793 either the GL compatibility (\code{gl}) or GL core (\code{glcore}) API
794 profiles, but not for other APIs. When processed into a C header for the
795 \code{core} profile of OpenGL, this results in (assuming the usual
816 \tag{feature} (this is primarily useful for the OpenGL core profile,
818 interfaces, although this usage is allowed by the schema). Except for
819 the tag name and behavior, the contents of \tag{require} and
825 \item \attr{profile} - string name of an API profile. Interfaces in the
826 tag are only required (or removed) if the specified profile is
831 in the tag are only required (or removed) if the specified API is
842 Zero or more of the following tags, in any order:
850 \item \attr{name} - name of the command (required).
858 \item \attr{name} - name of the enumerant (required).
863 the \tag{ptype} tags of commands, but in a few cases, additional
865 would ever be removed, although this usage is allowed by the
869 \item \attr{name} - name of the type (required).
879 \subsection{Stability of the XML Database and Schema}
883 to feedback and to Khronos' own wishlist. This means the XML schema is
888 canonicalization of the XML or sorting of \tag{command} and
889 \tag{extension} tags by name. Changes to the schema will be described in
890 the change log of this document (see section~\ref{changelog}). Changes
891 to the \code{.xml} files will be described in Github revision history.
894 \subsection{Feature Enhancements to the Registry}
897 There are lots of tools and additional tags that would make the XML format
898 more expressive and the tools more capable. Khronos is open to hosting
899 additional processing scripts for other purposes related to the definition
900 of the API and bindings to it.
908 a {\em client-side alias} or something of the sort).
914 The initial releases of the XML Registry did not include type annotation
915 and array length information from the old \code{.spec} files, which
918 been added to the XML, in the form of \tag{group} tags (see
921 that the corresponding return type belongs to a group, and \attr{len}
922 attributes on \tag{param} tags specifying the array length of the
925 There are many caveats regarding these annotations. For the most part
928 parameters which {\bf could} be given a group, and in many cases, the
932 the corresponding features have been promoted).
934 The \tag{group}s added to \code{gl.xml} are the enumerant groups defined
936 names were used in the annotations in \code{gl.spec}, and they
948 offers no information about the parameter not already present in its
959 no definition exists. This is because the existing \tag{group} mechanism
962 This is not a regression relative to the \code{.spec} files, which also
963 did not describe the meaning of these groups.
974 exists. This is because the existing \tag{group} mechanism can only
977 This is not a regression relative to the \code{.spec} files, which also
978 did not describe the meaning of these groups.
992 This is not a regression relative to the \code{.spec} files, which also
993 did not describe the meaning of these groups.
1008 groups during header generation. Invoking it with the
1024 reflect this not being the only Khronos XML API schema in use, and
1028 \item 2017-01-20 - Update for the move to the new github repository.
1037 annotations. Still need to add examples of the annotation