opengl-registry/xml/readme.tex

\documentclass{article}

% Various packages of possible use. {index} creates problems for some reason.
% \usepackage{index}
\def\specpdftitle{The Khronos XML API Registry}
\usepackage[pdftex,bookmarksnumbered=true,linktocpage,plainpages=false,pdftitle={\specpdftitle},colorlinks=true]{hyperref}
\usepackage{amsmath,enumerate,epsfig,framed,mdframed,multicol,longtable,times,url}
\usepackage[normalem]{ulem}
% underscore allows use of _ instead of \_ in text. [strings] allows _ in file names
\usepackage[strings]{underscore}
\usepackage[breakwords,fit]{truncate}

\makeatletter
\makeatother
\makeindex

% Some commonly used abbreviations

\def\code#1{{\tt #1}}
\def\tag#1{{\tt <#1>\index{<#1>}}}
\def\attr#1{{\tt #1\index{#1}}}

\begin{document}

\title{The Khronos XML API Registry}
\author{Jon Leech}
\date{Last updated 2017-01-20}
\maketitle

\begin{abstract}

This document describes the Khronos XML API Registry schema, and provides
some additional information about using the registry and scripts to generate
C header files. The underlying XML files and scripts, as well as headers
generated from the current authoritative copy of the XML files, can be
obtained from the OpenGL-Registry github repository at

\begin{center}
{\bf \href{https://github.com/KhronosGroup/OpenGL-Registry}
          {https://github.com/KhronosGroup/OpenGL-Registry}}
\end{center}

\end{abstract}

\tableofcontents

\section{Introduction}

The registry uses an XML representation of the API and a set of Python 3
scripts to manipulate the XML, based on the lxml Python bindings. It comes
with an XML schema and validator. Outside users are welcome to submit pull
requests on github, although the XML schema itself is mature and unlikely to
change at this point.

Some groups outside Khronos have their own XML based API descriptions,
often used for additional purposes such as library code generators or
extension loaders, and it may be desirable to construct XSLT or other
translators between the schema.


\section{Getting Started}

Once the repository has been downloaded, if you're running
in a Linux command-line environment and have Python 3, the lxml Python
bindings, and libxml installed, you should just be able to invoke
\code{make} and generate C/C++ header files for all the following
targets:

\begin{itemize}
\item \code{GL/glext.h} - OpenGL 1.2 (and later) compatibility profile
      API + extensions
\item \code{GL/glcorearb.h} - OpenGL core profile API + extensions
\item \code{GLES/gl.h} - OpenGL compatibility profile API
\item \code{GLES/glext.h} - OpenGL ES 1.x extensions
\item \code{GLES2/gl2.h} - OpenGL ES 2.x API
\item \code{GLES2/gl2ext.h} - OpenGL ES 2.x extensions
\item \code{GLES3/gl3.h} - OpenGL ES 3.x API
\item \code{GL/glx.h} - GLX API
\item \code{GL/glxext.h} - GLX 1.3 (and later) API + extensions
\item \code{GL/wgl.h} - WGL API
\item \code{GL/wglext.h} - WGL extensions
\item \code{EGL/egl.h} - EGL (still being worked on)
\end{itemize}

Starting with the Makefile rules and inspecting the files \code{gl.xml},
\code{genheaders.py}, and \code{reg.py} will be necessary if you want to
repurpose the registry for reasons other than header file generation, or
to generate headers for languages other than C.

If you're running in a Microsoft Windows, MaxOS X, or other non-Linux
environment, there are equivalent versions of Python and GNU Make, although
we haven't tested this ourselves. Feedback would be helpful. If you're using
Windows 10, you should probably try to build in the Ubuntu Linux subsystem
rather than older Unix emulation environments such as Cygwin.


\subsection{Header Generation Script - \code{genheaders.py}}

When generating header files using the \code{genheaders.py} script, an
API name and profile name are required, as shown in the Makefile
examples. Additionally, specific versions and extensions can be required
or excluded. Based on this information, the generator script extracts
the relevant interfaces and creates a C-language header file for them.
\code{genheaders.py} contains predefined generator options for OpenGL compatibility
and core profiles, OpenGL ES 1 / 2 / 3, GLX, and WGL headers.

The generator script is intended to be generalizable to other languages
by writing new generator classes. Such generators would have to rewrite
the C types and definitions in the XML to something appropriate to their
language.

\subsection{Registry Processing Script - \code{reg.py}}

Actual XML registry processing is done in \code{reg.py}, which contains
several objects and methods for loading registries and extracting
interfaces and extensions for use in header generation. There is some
internal documentation in the form of comments although nothing more
extensive exists yet, and it's possible the Python scripts will evolve
significantly based on public feedback.


\section{XML Registry Schema}
\label{schema}

The format of an XML registry is a top level \tag{registry} tag
containing \tag{types}, \tag{enums}, \tag{commands}, \tag{feature}, and
\tag{extension} tags describing the different elements of an API, as
explained below. This description corresponds to a formal Relax NG
schema file, \code{registry.rnc}, against which the XML registry files
can be validated.

At present there are separate registries for:

\begin{itemize}
\item OpenGL and OpenGL ES - \code{gl.xml}
\item GLX - \code{glx.xml}
\item WGL - \code{wgl.xml}
\item EGL - \code{egl.xml} (still in development)
\end{itemize}

\subsection{Profiles}
\label{schema:profile}

Types and enumerants can have different definitions depending on the API
profile requested, which allows us to accomodate minor incompatibilities
in the OpenGL and OpenGL ES APIs, for example. Features and extensions
can include some elements conditionally depending on the API profile
requested.

\subsection{API Names}
\label{schema:apiname}

Several tags use a \attr{api} attribute. This is an arbitrary string,
specified at header generation time, for labelling properties of a
specific API. The string can be, but is not necessarily, an actual API
name. As used in \code{genheaders.py} and \code{gl.xml}, the API names
are \code{gl}, \code{gles1}, and \code{gles2}, corresponding to OpenGL,
OpenGL ES 1, and OpenGL ES 2/3, respectively.


\section{Registry Root (\tag{registry} tag)}
\label{schema:root}

A \tag{registry} contains the entire definition of one or more related
APIs.

\subsection{Attributes of \tag{registry} tags}

None.

\subsection{Contents of \tag{registry} tags}

Zero or more of each of the following tags, normally in this order
(although order shouldn't be important):

\begin{itemize}
\item \tag{comment} - Contains arbitrary text, such as a copyright
      statement. Unused.
\item \tag{types} (see section~\ref{tag:types}) - defines API types.
      Usually only one tag is used.
\item \tag{groups} (see section~\ref{tag:groups}) - defines named groups
      of tokens for possible parameter validation in API bindings for
      languages other than C. Usually only one tag is used.
\item \tag{enums} (see section~\ref{tag:enums}) - defines API enumerants
      (tokens). Usually multiple tags are used.
\item \tag{commands} (see section~\ref{tag:commands}) - defines API
      commands (functions). Usually only one tag is used.
\item \tag{feature} (see section~\ref{tag:feature}) - defines API
      feature interfaces (API versions, more or less). One tag per
      feature set.
\item \tag{extensions} (see section~\ref{tag:extensions}) - defines API
      extension interfaces. Usually only one tag is used, wrapping many
      extensions.
\end{itemize}


\section{API types (\tag{types} tag)}
\label{tag:types}

The \tag{types} tag contains individual \tag{type} tags describing each
of the derived types used in the API.

Each \tag{type} tag contains legal C code, with attributes or embedded
tags denoting the type name.

\subsection{Attributes of \tag{type} tags}

\begin{itemize}
\item \attr{requires} - another type name this type requires to complete
      its definition.
\item \attr{name} - name of this type (if not defined in the tag body).
\item \attr{api} - an API name (see \tag{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.
\item \attr{comment} - arbitrary string (unused).
\end{itemize}

\subsection{Contents of \tag{type} tags}

\tag{type} contains text which is legal C code for a type declaration.
It may also contain embedded tags:

\begin{itemize}
\item \tag{apientry/} - insert a platform calling convention macro here
      during header generation, used mostly for function pointer types.
\item \tag{name} - contains the name of this type (if not defined in the
      tag attributes).
\end{itemize}

\subsection{Example of a \tag{types} tag}

\begin{verbatim}
<types>
    <type name="stddef"><![CDATA[#include <stddef.h>]]></type>
    <type requires="stddef">typedef ptrdiff_t <name>GLintptr</name>;</type>
</types>
\end{verbatim}

If the {\tt GLint64} type is required by a command, this will result in
the following declarations:

\begin{verbatim}
#include <stddef.h>
typedef ptrdiff_t GLintptr;
\end{verbatim}


\section{Enumerant Groups (\tag{groups} tag)}
\label{tag:groups}

The \tag{groups} tags contain individual \tag{group} tags describing
some of the group annotations used for return and parameter types.

\subsection{Attributes of \tag{groups} tags}

None.

\subsection{Contents of \tag{groups} tags}

Each \tag{groups} block contains zero or more \tag{group} tags, in
arbitrary order (although they are typically ordered by group name, to
improve human readability).

\subsection{Example of \tag{groups} tags}

\begin{verbatim}
<groups>
    <group name="AccumOp">
        <enum name="GL_ACCUM"/>
    </group>

    <group name="AttribMask">
        <enum name="GL_ACCUM_BUFFER_BIT"/>
        <enum name="GL_ALL_ATTRIB_BITS"/>
    </group>
</groups>
\end{verbatim}


\section{Enumerant Group (\tag{group} tag)}
\label{tag:group}

Each \tag{group} tag defines a single group annotation.

\subsection{Attributes of \tag{group} tags}

\begin{itemize}
\item \attr{name} - group name, an arbitrary string for grouping a set
      of enums together within a broader namespace.
\end{itemize}

\subsection{Contents of \tag{group} tags}

\tag{group} tags may contain zero or more \tag{enum} tags. Each
\tag{enum} tag may contain only a \attr{name} attribute, which should
correspond to a \tag{enum} definition in an \tag{enums} block.

\subsection{Meaning of \tag{group} tags}
\label{tag:group:meaning}

If a \tag{proto} or \tag{param} tag of a \tag{command} has a
\attr{group} attribute defined, and that attribute matches a \tag{group}
name, then the return type or parameter type is considered to be
constrained to values defined by the corresponding \tag{group}. C
language bindings do not attempt to enforce this constraint in any way,
but other language bindings may try to do so.


\section{Enumerant Blocks (\tag{enums} tag)}
\label{tag:enums}

The \tag{enums} tags contain individual \tag{enum} tags describing each of the
token (enumerant) names used in the API.

\subsection{Attributes of \tag{enums} tags}

\begin{itemize}
\item \attr{namespace} - a string for grouping many different enums
      together, currently unused but typically something like \code{GL}
      for all enums in the OpenGL / OpenGL ES shared namespace. Multiple
      \tag{enums} tags can share the same namespace.
\item \attr{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 \code{bitmask}.
\item \attr{start}, \attr{end} - integers defining the start and end of
      a reserved range of enumerants for a particular vendor or purpose.
      \attr{start} must be $\leq$ \attr{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.
\item \attr{vendor} - string describing the vendor or purposes to whom a
      reserved range of enumerants is allocated.
\item \attr{comment} - arbitrary string (unused)
\end{itemize}

\subsection{Contents of \tag{enums} tags}

Each \tag{enums} block contains zero or more \tag{enum} and \tag{unused}
tags, in arbitrary order (although they are typically ordered by sorting
on enumerant values, to improve human readability).

\subsection{Example of \tag{enums} tags}

\begin{verbatim}
<enums namespace="AttribMask" type="bitmask">
    <enum value="0x00000001"  name="GL_CURRENT_BIT" />
    <enum value="0x00000002"  name="GL_POINT_BIT" />
</enums>
<enums namespace="GL" start="0x80E0" end="0x810F" vendor="MS">
    <enum value="0x80E0"      name="GL_BGR" />
        <unused start="0x80E1" end="0x810F" />
</enums>
\end{verbatim}

When processed into a C header, and assuming all these tokens were
required, this results in

\begin{verbatim}
#define GL_CURRENT_BIT 0x00000001
#define GL_POINT_BIT   0x00000001
#define GL_BGR         0x80E0
\end{verbatim}


\section{Enumerants (\tag{enum} tag)}
\label{tag:enum}

Each \tag{enum} tag defines a single GL (or other API) token.

\subsection{Attributes of \tag{enum} tags}

\begin{itemize}
\item \attr{value} - enumerant value, a legal C constant (usually a
      hexadecimal integer).
\item \attr{name} - enumerant name, a legal C preprocessor token name.
\item \attr{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).
\item \attr{type} - legal C suffix for the value to force it to a
      specific type. Currently only \code{u} and \code{ull} are used,
      for \code{unsigned} 32- and 64-bit integer values, respectively.
      Separated from the \attr{value} field since this eases parsing and
      sorting of values, and is rarely used.
\item \attr{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 \attr{name} for the exact same \attr{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 {\em Changed Tokens} sections of appendices to the OpenGL
      Specification. This might change in the future.
\end{itemize}

\subsection{Contents of \tag{enum} tags}

\tag{enum} tags have no allowed contents. All information is contained
in the attributes.


\section{Unused Enumerants (\tag{unused} tag)}
\label{tag:unused}

Each \tag{unused} tag defines a range of enumerants which is allocated,
but not yet assigned to specific enums. This just tracks the unused
values and is not needed for header generation.

\subsection{Attributes of \tag{unused} tags}

\begin{itemize}
\item \attr{start}, \attr{end} - integers defining the start and end of
      an unused range of enumerants. \attr{start} must be $\leq$
      \attr{end}. This range should not exceed the range reserved by the
      surrounding \tag{enums} tag.
\item \attr{vendor} - string describing the vendor or purposes to whom a
      reserved range of enumerants is allocated. Usually identical to
      the \attr{vendor} attribute of the surrounding \attr{enums} block.
\item \attr{comment} - arbitrary string (unused)
\end{itemize}

\subsection{Contents of \tag{unused} tags}

None.


\section{Command Blocks (\tag{commands} tag)}
\label{tag:commands}

The \tag{commands} tag contains definitions of each of the functions
(commands) used in the API.

\subsection{Attributes of \tag{commands} tags}

\begin{itemize}
\item \attr{namespace} - a string defining the namespace in which
      commands live, currently unused but typically something like
      \code{GL}.
\end{itemize}

\subsection{Contents of \tag{commands} tags}

Each \tag{commands} block contains zero or more \tag{command} tags, in
arbitrary order (although they are typically ordered by sorting on the
command name, to improve human readability).


\section{Commands (\tag{command} tag)}
\label{tag:command}

The \tag{command} tag contains a structured definition of a single API
command (function).

\subsection{Attributes of \tag{command} tags}

\begin{itemize}
\item \attr{comment} - arbitrary string (unused).
\end{itemize}

\subsection{Contents of \tag{command} tags}

\begin{itemize}
\item \tag{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.
\item \tag{param} elements for each command parameter follow, defining
      its name and type, as described below. If a command takes no
      arguments, it has no \tag{param} tags.
\end{itemize}

Following these elements, the remaining elements in a \tag{command}
tag are optional and may be in any order:

\begin{itemize}
\item \tag{alias} has one attribute, \attr{name}, containing 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 {\bf same} client library code, so (for
      example) the case where a command is promoted but is also given
      different GLX protocol would {\bf not} be an alias in this sense.
\item \tag{vecequiv} has one attribute, \attr{name}, containing a string which is
      the name of another command which is the {\em vector equivalent}
      of this command. For example, the vector equivalent of
      \code{glVertex3f} is \code{glVertex3fv}.
\item \tag{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.
\end{itemize}


\subsection{Command prototype (\tag{proto} tags)}
\label{tag:command:proto}

The \tag{proto} tag defines the return type and name of a command.

\subsubsection{Attributes of \tag{proto} tags}

\begin{itemize}
\item \attr{group} - group name, an arbitrary string.
\end{itemize}

If the group name is defined, it may be interpreted as described in
section~\ref{tag:group:meaning}.

\subsubsection{Contents of \tag{proto} tags}

The text elements of a \tag{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:

\begin{itemize}
\item The \tag{ptype} tag is optional, and contains text which is a
      valid type name found in \tag{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 \tag{ptype} tags.
\item The \tag{name} tag is required, and contains the command name
      being described.
\end{itemize}

\subsection{Command parameter (\tag{param} tags)}
\label{tag:command:param}

The \tag{param} tag defines the type and name of a parameter.

\subsubsection{Attributes of \tag{param} tags}

\begin{itemize}
\item \attr{group} - group name, an arbitrary string.
\item \attr{len} - parameter length, either an integer specifying the
      number of elements of the parameter \tag{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.
\end{itemize}

If the group name is defined, it may be interpreted as described in
section~\ref{tag:group:meaning}.

\subsubsection{Contents of \tag{param} tags}

The text elements of a \tag{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:

\begin{itemize}
\item The \tag{ptype} tag is optional, and contains text which is a
      valid type name found in \tag{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 \tag{ptype} tags.
\item The \tag{name} tag is required, and contains the command name
      being described.
\end{itemize}

\subsection{Example of a \tag{commands} tag}

\begin{verbatim}
<commands>
    <command>
        <proto>void <name>glBeginConditionalRenderNV</name></proto>
        <param><ptype>GLuint</ptype> <name>id</name></param>
        <param><ptype>GLenum</ptype> <name>mode</name></param>
        <alias name="glBeginConditionalRender" />
        <glx type="render" opcode="348" />
    </command>
</commands>
\end{verbatim}

When processed into a C header, this results in

\begin{verbatim}
void glBeginConditionalRenderNV(GLuint id, GLenum mode);
\end{verbatim}


\section{API Features / Versions (\tag{feature} tag)}
\label{tag:feature}

API features are described in individual \tag{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.

\subsection{Attributes of \tag{feature} tags}

\begin{itemize}
\item \attr{api} - API name this feature is for (see
      section~\ref{schema:apiname}), such as \code{gl} or \code{gles2}.
\item \attr{name} - version name, used as the C preprocessor token under
      which the version's interfaces are protected against multiple
      inclusion. Example: \code{GL\_VERSION\_4\_2}.
\item \attr{protect} - an additional preprocessor token used to protect
      a feature definition. Usually another feature or extension
      \attr{name}. Rarely used, for odd circumstances where the
      definition of a feature or extension requires another to be
      defined first.
\item \attr{number} - feature version number, usually a string
      interpreted as $majorNumber.minorNumber$. Example: \code{4.2}.
\item \attr{comment} - arbitrary string (unused)
\end{itemize}

\subsection{Contents of \tag{feature} tags}

Zero or more \tag{require} and \tag{remove} tags (see
section~\ref{tag:required}), in arbitrary order. Each tag describes a
set of interfaces that is respectively required for, or removed from,
this feature, as described below.

\subsection{Example of a \tag{feature} tag}

\begin{verbatim}
<feature api="gl" name="GL_VERSION_3_0" number="3.0">
    <require>
        <enum name="GL_COMPARE_REF_TO_TEXTURE" />
        <enum name="GL_CLIP_DISTANCE0" />
        <command name="glEndTransformFeedback" />
    </require>
    <require profile="compatibility">
        <enum name="GL_INDEX" />
    </require>
</feature>
\end{verbatim}

When processed into a C header for the \code{compatibility} profile of
OpenGL, this results in (assuming the usual definitions of these GL
interfaces):

\begin{verbatim}
#ifndef GL_VERSION_3_0
#define GL_VERSION_3_0 1
#define GL_COMPARE_REF_TO_TEXTURE         0x884E
#define GL_CLIP_DISTANCE0                 0x3000
#define GL_INDEX                          0x8222
typedef void (APIENTRYP PFNGLENDTRANSFORMFEEDBACKPROC) (void);
#ifdef GL_GLEXT_PROTOTYPES
GLAPI void APIENTRY glEndTransformFeedback (void);
#endif
#endif /* GL_VERSION_3_0 */
\end{verbatim}

If processed into a header for the \code{core} profile, the definition of
\code{GL\_INDEX} would not appear.


\section{Extension Blocks (\tag{extensions} tag)}
\label{tag:extensions}

The \tag{extensions} tag contains definitions of each of the extenions
which are defined for the API.

\subsection{Attributes of \tag{extensions} tags}

None.

\subsection{Contents of \tag{extensions} tags}

Each \tag{extensions} block contains zero or more \tag{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).


\section{API Extensions (\tag{extension} tag)}
\label{tag:extension}

API extensions are described in individual \tag{extension} tags. An
extension is the set of interfaces defined by a particular API extension
specification, such as \code{ARB\_multitexture}. \tag{extension} is
similar to \tag{feature}, but instead of having \attr{version} and
\attr{profile} attributes, instead has a \attr{supported} attribute,
which describes the set of API names which the extension can potentially
be implemented against.

\subsection{Attributes of \tag{extension} tags}

\begin{itemize}
\item \attr{supported} - a regular expression, with an implicit
      \code{\^{}} and \code{\$} bracketing it, which should match the
      \attr{api} tag of a set of \tag{feature} tags.
\item \attr{protect} - an additional preprocessor token used to protect
      an extension definition. Usually another feature or extension
      \attr{name}. Rarely used, for odd circumstances where the
      definition of an extension requires another to be defined first.
\item \attr{comment} - arbitrary string (unused)
\end{itemize}

\subsection{Contents of \tag{extension} tags}

Zero or more \tag{require} and \tag{remove} tags (see
section~\ref{tag:required}), in arbitrary order. Each tag describes a
set of interfaces that is respectively required for, or removed from,
this extension, as described below.

\subsection{Example of an \tag{extensions} tag}

\begin{verbatim}
<extensions>
    <extension name="GL_ARB_robustness" supported="gl|glcore" >
        <require>
            <enum name="GL_NO_ERROR" />
            <command name="glGetGraphicsResetStatusARB" />
        </require>
        <require api="gl" profile="compatibility">
            <command name="glGetnMapdvARB" />
        </require>
    </extension>
</extensions>
\end{verbatim}

The \attr{supported} attribute says that the extension can be supported for
either the GL compatibility (\code{gl}) or GL core (\code{glcore}) API
profiles, but not for other APIs. When processed into a C header for the
\code{core} profile of OpenGL, this results in (assuming the usual
definitions of these GL interfaces):

\begin{verbatim}
#ifndef GL_ARB_robustness
#define GL_ARB_robustness 1
#define GL_NO_ERROR                       0
typedef GLenum (APIENTRYP PFNGLGETGRAPHICSRESETSTATUSARBPROC) (void);
#ifdef GL_GLEXT_PROTOTYPES
GLAPI GLenum APIENTRY glGetGraphicsResetStatusARB (void);
#endif
#endif /* GL_ARB_robustness */
\end{verbatim}


\section{Required and Removed Interfaces (\tag{require} and \tag{remove} tags)}
\label{tag:required}

A \tag{require} block defines a set of interfaces (types, enumerants and
commands) {\em required} by a \tag{feature} or \tag{extension}. A
\tag{remove} block defines a set of interfaces {\em removed} by a
\tag{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 \tag{require} and
\tag{remove} tags are identical.

\subsection{Attributes of \tag{require} and \tag{remove} tags}

\begin{itemize}
\item \attr{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.
\item \attr{comment} - arbitrary string (unused)
\item \attr{api} - an API name (see section~\ref{schema:apiname}). 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.

      {\bf The \attr{api} attribute is only supported inside
      \tag{extension} tags,} since \tag{feature} tags already define a
      specific API.
\end{itemize}

\subsection{Contents of \tag{require} and \tag{remove} tags}

Zero or more of the following tags, in any order:

\begin{itemize}
\item \tag{command} specifies an required (or removed) command defined
      in a \tag{commands} block. The tag has no content, but contains
      elements:

      \begin{itemize}
      \item \attr{name} - name of the command (required).
      \item \attr{comment} - arbitrary string (optional and unused).
      \end{itemize}
\item \tag{enum} specifies an required (or removed) enumerant defined in
      a \tag{enums} block. The tag has no content, but contains
      elements:

      \begin{itemize}
      \item \attr{name} - name of the enumerant (required).
      \item \attr{comment} - arbitrary string (optional and unused).
      \end{itemize}
\item \tag{type} specifies a required (or removed) type defined in a
      \tag{types} block. Most types are picked up implicitly by using
      the \tag{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:

      \begin{itemize}
      \item \attr{name} - name of the type (required).
      \item \attr{comment} - arbitrary string (optional and unused).
      \end{itemize}
\end{itemize}


\section{General Discussion}
\label{general}


\subsection{Stability of the XML Database and Schema}
\label{general:stability}

The new registry schema, scripts, and databases are evolving in response
to feedback and to Khronos' own wishlist. This means the XML schema is
subject to change, although most such change will probably be confined
to adding attributes to existing tags. The XML databases such as
\code{gl.xml} will evolve in response to schema changes, to new
extensions and API versions, and to general cleanup, such as
canonicalization of the XML or sorting of \tag{command} and
\tag{extension} tags by name. Changes to the schema will be described in
the change log of this document (see section~\ref{changelog}). Changes
to the \code{.xml} files will be described in Subversion revision
history.


\subsection{Feature Enhancements to the Registry}
\label{general:enhancements}

There are lots of tools and additional tags that would make the XML
format more expressive and the tools more capable. Khronos is open to
hosting additional processing scripts for other purposes. We're hoping
to be much more responsive to bugs filed in the Khronos public bugzilla
now that there's a more modern and maintainable framework to build on.

A partial wishlist follows:

\begin{itemize}
\item Enhance \tag{command} \tag{alias} tags to describe more relaxed
      sorts of aliases, such as commands equivalent in behavior and
      interface, but using different GLX protocol (this might be called
      a {\em client-side alias} or something of the sort).
\end{itemize}

\subsection{Type Annotations and Relationship to \code{.spec} Files}
\label{general:annotations}

The initial releases of the XML Registry did not include type annotation
and array length information from the old \code{.spec} files, which
generated a number of complaints from people writing bindings of OpenGL
to languages other than C. The majority of these annotations have now
been added to the XML, in the form of \tag{group} tags (see
section~\ref{tag:group}) defining groups of related enumerants,
\attr{group} attributes on \tag{proto} and \tag{param} tags specifying
that the corresponding return type belongs to a group, and \attr{len}
attributes on \tag{param} tags specifying the array length of the
corresponding parameter.

There are many caveats regarding these annotations. For the most part
they date from SGI's OpenGL 1.1 implementation, and have not been
updated. The defined \tag{group}s therefore do not cover many API
parameters which {\bf could} be given a group, and in many cases, the
defined \tag{group}s have not been updated to add new enumerants from
later versions of OpenGL and OpenGL extensions. The group names are
often somewhat misleading (with imbedded vendor extension tags, while
the corresponding features have been promoted).

The \tag{group}s added to \code{gl.xml} are the enumerant groups defined
in \code{enum.spec}, and \code{enumext.spec}. Many additional group
names were used in the annotations in \code{gl.spec}, and they
fall in several categories discussed below.


\subsubsection{Simple API Type Aliases}

Group names that were simply an alias for a GL type have been left
entirely out of \code{gl.xml}, since they offer no useful additional
information.

For example, a parameter described as \code{UInt32} in \code{gl.spec} is
not annotated with \code{group="UInt32"} in \code{gl.xml}, because this
offers no information about the parameter not already present in its
declaration as \code{<ptype>GLuint</ptype>}.

A few examples of such groups are \code{cl\_context},
\code{handleARB}, \code{Int32}, and \code{sync}.


\subsubsection{Numeric Constraints}

Group names representing some type of numerical constraint on a value
are retained in \tag{proto} and \tag{param} \attr{group} attributes, but
no definition exists. This is because the existing \tag{group} mechanism
can only describe constraints to specific enumerant names.

This is not a regression relative to the \code{.spec} files, which also
did not describe the meaning of these groups.

A few examples of such groups are \code{CheckedFloat32},
\code{ClampedFixed}, and \code{CoordD}.


\subsubsection{GL Object Names}

Group names representing an object name obtained from e.g. a
\code{glGen*} command, such as a display list name, are retained in in
\tag{proto} and \tag{param} \attr{group} attributes, but no definition
exists. This is because the existing \tag{group} mechanism can only
describe constraints to specific enumerant names.

This is not a regression relative to the \code{.spec} files, which also
did not describe the meaning of these groups.

A few examples of such groups are \code{List} and \code{Path}.


\subsubsection{Groups Not Defined Yet}

Group names representing enumerant groups which were not defined in
\code{enum.spec} and \code{enumext.spec} are retained in \tag{proto} and
\tag{param} \attr{group} attributes, but no definition exists. Such
groups usually are a result of vendors contributing \code{gl.spec}
entries for an extension without contributing corresponding
\code{enum.spec} entries.

This is not a regression relative to the \code{.spec} files, which also
did not describe the meaning of these groups.

A few examples of such groups are \code{ArrayObjectPNameATI},
\code{BinormalPointerTypeEXT}, and \code{SpriteParameterNameSGIX}.


\subsubsection{Other Groups}

There are probably a few groups which are present in \code{gl.xml} but
should not be. These can be gradually cleaned up over time.


\subsubsection{Validating Groups}

The \code{genheaders.py} script has been enhanced to allow validating
groups during header generation. Invoking it with the
\code{-validate} option, for example via:

\code{\$ genheaders.py -validate -registry gl.xml}

\noindent will generate a text dump on standard output showing all
parameter type \attr{group} attributes which do {\bf not} have
corresponding \tag{group} tags.


\section{Change Log}
\label{changelog}

\begin{itemize}
\item 2017-01-20 - Update for the move to the new github repository.
\item 2014-06-16 - Add \tag{vendor} attribute to \tag{unused} tags.
\item 2013-09-17 - Add \tag{comment} attribute to \tag{command} tags
      within \tag{commands}.
\item 2013-06-24 - Add \tag{groups} and \tag{group} tags, renamed
      \tag{enums} attribute \attr{class} to \attr{group}, and add
      parameter type annotation attributes \attr{group} and \attr{len}
      to both \tag{proto} and \tag{param}. Add
      section~\ref{general:annotations} discussing limitations of these
      annotations. Still need to add examples of the annotation
      attributes.
\item 2013-06-19 - Added \tag{extensions} tag block as a wrapper around
      groups of \tag{extension} tags, to ease XML transformations such
      as sorting extensions by name.
\item 2013-06-14 - Expanded description of tags, better formatting
\item 2013-06-12 - First release, text file format
\end{itemize}

\input{readme.ind}

% \printindex

\end{document}