How to Create Khronos API Extensions

This document outlines the steps to create, define, and use
an extension for some of the APIs supported by Khronos. It
is currently focused on OpenGL, OpenGL ES, GLX, and EGL.
Some discussion of OpenVG and WGL is also included.

Implementing an extension (this
discusses only aspects of the implemention visible to users -
primarily determining if the extension is available and
defining its interface in header files.

Using an extension in an application (this
discusses the mechanics of using an extension if and only if
it's supported by an implementation).

Specification

When initially creating an extension, take the following steps:

Determine if an existing extension
can be used, instead of writing a new one. This may involve
reuse of an existing specification, or
promotion to multivendor or
Khronos-approved status. In either case, coordinate this use
with the vendor(s) defining and shipping the existing extension.

When you're ready to release the extension, freeze the
specification and add it to the
registry maintained by Khronos. At this time (but not
before), you can obtain permanent token (enumerant) assignments.

When shipping an extension, make sure that its interfaces are
defined in header files accessible to ISVs. If the extension is
Khronos-approved, use the Khronos-provided headers.

Is there already an extension that does what I want?

Specifications for extensions that have already been developed can
be obtained from the Extension
Registry maintained by Khronos. Since we are just getting started
with most of the Khronos APIs, the registry currently contains only
OpenGL, GLX, and WGL extension specifications.

It's possible that additional extensions may have been submitted to
the registry but not yet updated on the website, or that another
licensee may be working on a similar extension but not yet have released
the specification. So it's worth asking on the appropriate Working
Group mailing list if anyone has defined related functionality already.

Should the extension be Khronos-approved, multivendor, or specific
to a single vendor?

OpenGL's history has made clear that ISVs do not want to deal
with vendor-specific extensions if they can possibly avoid it. So if
the functionality being exposed is going to be available on multiple
platforms - as most will - it's a good idea to agree on a single
extension with other vendors providing that functionality. This
makes it easier for ISVs to justify using extensions.

If the functionality is well-understood, it may be appropriate to
define a Khronos-approved extension. This is the most
"blessed" category of extension; it goes through the
entire standards process, and is approved by the group, but remains
optional functionality. Many core features have been promoted
directly from existing Khronos-approved extensions.

If Khronos as a whole isn't ready to deal with the extension, but
other vendors are, then it should be defined as a multivendor
extension. The interested parties can develop the specification
entirely among themselves, outside the standards process; or they
may be able to use Khronos Working Groups as a forum to develop the
specification.

In some cases, vendors may share a common core of functionality,
with vendor-specific additional features. Here, it may make sense to
agree on a multivendor extension to access the core, with additional
vendor-specific extensions layered on the core exposing unique
features.

Finally, some extensions will probably have to remain proprietary.

How do I write a specification?

Start with the template for writing
extension specifications. There are different templates for
different APIs, but general comments apply:

It's important to think about all the different areas of the core
language specification(s) that are affected. How are queries for
state handled? What attribute group does new state belong in? How
are existing calls modified or expanded in scope? How are existing
objects affected by use of the extension? The template helps with
this by at least reminding you to consider each part of the core
language specification.

Extension specifications must be written against a specific version
of the core API specification. If possible, it's highly preferable
to write against the most recent public version. "Written
against" means that new language must be written as
well-defined modifications to the Specification being referenced. It
should be possible for someone not involved with the development of
an extension to sit down with a copy of the Specification and the
extension and produce a merged document identical to that you
intended.

Extension specifications may also be specified as Docbook XML
documents, although we're still using plain text for the most part.
Docbook is a very powerful structural representation of documents,
but we're still feeling our way into using it. Known Docbook tools and editors are described
elsewhere.

One complete, shipping example to refer to is the
Fog Coordinate OpenGL extension
specification.

Naming Conventions

API entry points and enumerants in an extension must be named
according to the syntax rules specific to
that API. In particular, follow the sections "Extension name
rules" and "Shared extensions".

All extensions must be named and the name included in the extension
specification. The extension name is of the form
"api_category_name" where

"category" identifies the extension category.
For a vendor-specific extension, the category is a 2-3 letter string
identifying the vendor: "NV" for NVIDIA,
"ATI" for ATI, etc. For a multivendor extensions,
the category is "EXT". For Khronos-approved
extensions, one of several API-specific categories is used
("ARB" for OpenGL extensions,
"OES" for OpenGL ES extensions,
"OML" for OpenML extensions, and so on).

"name" is one or more words separated by
underscores, providing a short label for the extension.
Conventionally the name is entirely lower-case.

For example, the extension name
"GL_EXT_framebuffer_object" is used for a
multivendor OpenGL extension adding support for framebuffer objects.

Choose names that are

Short.

Meaningful.

Not prefixes of any existing extension name (disregarding the
category). For example, "GL_ARB_fog" is a prefix
of "GL_EXT_fog_coord", so should not be chosen.

Not prefixed by any existing extension name (again, disregarding
the category).

The goal is for names to be clear, but not at the cost of confusion
or ambiguity.

Advertising Extension Names to Applications

Each Khronos API provides a way of describing the supported
extensions at compile- and run-time. This is done by a combination
of preprocessor tokens in header files, and queryable extension
strings.

OpenGL and OpenGL ES #define a preprocessor token
corresponding to the extension name in <GL/gl.h> (or
an include file that gl.h includes, such as the
glext.h header provided in the registry). When this token
is defined, it indicates that the function prototypes and enumerant
definitions required to use the extension are available at compile
time.

If an OpenGL or OpenGL ES extension is supported at runtime, the
extension name must also be included in the string returned by
glGetString(GL_EXTENSIONS).

GLX #defines a preprocessor token corresponding to the
extension name in <GL/glx.h> (or an include file that
glx.h includes, such as the glxext.h header
provided in the registry). When this token is defined, it indicates
that the function prototypes and enumerant definitions required to
use the extension are available at compile time.

If a GLX extension is supported at runtime, the extension name must
also be included in the strings returned by
glXQueryExtensionsString, glXGetClientString, and/or
glXQueryServerString (see below for a description of the
different routines).

WGL #defines a preprocessor token corresponding to the
extension name in the wglext.h header provided in the
registry (the wgl.h supplied with Microsoft Windows does not
#include wglext.h, or define any extensions itself). When
this token is defined, it indicates that the function prototypes and
enumerant definitions required to use the extension are available at
compile time.

If a WGL extension is supported at runtime, the extension name must
also be included in the string returned by
wglGetExtensionsStringEXT.

OpenVG extension conventions are To Be Determined.

Note that extensions can have both OpenGL components and windowing
system components. For example, the ARB multisampling extension
modifies both GLX and OpenGL. In this case there will be two tokens
associated with the extension (e.g., GL_ARB_multisample and
GLX_ARB_multisample) and the extension will be advertised
by both OpenGL and GLX.

If an extension defines new OpenGL enumerant names, values for those
names must be requested in one or more blocks of 16 values. If an
extension defines new OpenGL rendering commands then you need to
register GLS rendering codes for it. If you want the extensions to
work with the X windowing system (i.e., with GLX), then you must
request GLX opcodes and define GLX protocol for it.

All new extensions must have a number associated with them for
documentation purposes. If an extension depends on another
extension, the other extension must have a lower number. (Note that
when an extension is deprecated, the number associated with it is
not reassigned.) This number will also be assigned by Khronos when
you register the extension.

Include all new enumerated values, GLX codes, and the extension
number in the specification.

Once you have completed the extension, please make it available to
other Khronos members and application developers, by submitting the
extension specification to the Khronos Registrar for inclusion in
the public registry.

Implementing and Advertising Extensions

Errors

Whenever possible, extensions should use existing errors instead of
defining new error returns. For GLX, if a new protocol error is
introduced, then an error number must be obtained from and
registered with Khronos.

Vendors may ship a single OpenGL library, containing extensions, for
a variety of platforms. It is possible that some of the extension
routines defined in the library may not be supported on some of the
platforms. If this is the case and an application calls a routine
that is not supported by the current OpenGL renderer then a
GL_INVALID_OPERATION error should be returned.

OpenGL Extension Availability

OpenGL extensions must be advertised in the extension string
returned by glGetString. Note that in a client-server
environment, this call returns the set of extensions that can be
supported on the connection. GLX client libraries must send a
glXClientInfo request to the server at start up time (if the
client libarary is 1.1 or later) indicating the version of the
client library and the OpenGL extensions that it supports. Then,
when glGetString is called, the client issues a GetString
request. The server intersects the set of extensions that the client
supports with the set of extensions that it supports (if a
glXClientInfo request was never received then the server
assumes that the client supports no OpenGL extensions) and returns
the result to the client. The client library then appends any
client-side only extensions to the list and returns the result.

Extension names for all known OpenGL extensions are #defined in the
glext.h header included in the registry.

EGL Extension Availability

EGL extensions must be advertised in the extension string returned
by eglQueryString(EGL_EXTENSIONS). Extension names for all
known EGL extensions are #defined in the eglext.h header
included in the registry.

GLX Extension Availability

GLX client-side extensions must be advertised in the extension
string returned by glXGetClientString; server-side extensions
must be advertised in the extension string returned by
glXQueryServerString.

glXQueryExtensionsString returns the list of extensions that
can be supported on the connection. The client then issues a
glXQueryServerString request, intersects the returned string
with the set of extensions it can support and then appends any
client-side only extensions to the list.

Extension names for all known GLX extensions are #defined in the
glxext.h header included in the registry.

WGL Extension Availability

WGL initially had no mechanism for returning its own extensions
string. For this reason, WGL extension names were initially
advertised in the GL extensions string returned by
glGetString. With the creation of a more formal WGL extension
mechanism, all implementations offering WGL extensions should export
the WGL_EXT_extensions_string extension, and should
advertise WGL extensions in the extensions string returned by the
wglGetExtensionsStringEXT interface defined by
WGL_EXT_extensions_string, as well as via
glGetString, for compatibility with older programs.

Extension names for all known WGL extensions are #defined in the
wglext.h header included in the registry.

Use of Extensions

Using OpenGL Extensions

Programmers that wish to use a particular OpenGL extension should
check both compile-time defines (to ensure that the extension is
supported by the library they are compiling against) and the
extension string returned by glGetString (to ensure that the
renderer supports the extension). For Windows, extensions usually
are not defined at link time, and function pointers to extension
APIs should be obtained by calling wglGetProcAddress.

For example, the following code could be used to check whether the
renderer supports an OpenGL extension called
GL_EXT_new_extension. This code would need to be executed
after the context had been made current:

If the renderer supports the extension, then it is safe to use it at
runtime. (Note that in a client-server environment,
glGetString will only return the set of extensions that can
be supported by the client and server.) However, compile time checks
must be made to ensure that the library that you are linked against
supports the extension. For example:

For a Windows OpenGL implementation, extensions are usually
dynamically loaded from the device driver, rather than statically
linked. Function pointers to extension APIs are obtained from
wglGetProcAddress and use to invoke the extension. For
example:

Using EGL Extensions

Before using an EGL extension, check for the extension name in both
the compile-time #defines and the extension string returned by
eglGetString(EGL_EXTENSIONS). For example, this code could
be used to check whether an extension called
EGL_OES_new_extension can be used.

Using GLX Extensions

Before using a GLX extension, programmers should check the compile
time defines and the extension string returned by
glXQueryExtensionsString.

The following code could be used to check whether an extension
called GLX_EXT_new_extension can be used on the connection.
This code would be executed after the connection had been opened and
the existence of the GLX extension had been established.

If the extension is supported on the connection, then it is safe to
use it at runtime. However, compile time checks must be made to
ensure that the library that you are linked against supports the
extension. For example:

Using WGL Extensions

Before using a WGL extension, check for its presence in the WGL
extensions string. Note that the WGL extension string query is
itself an extension; if not supported, WGL extensions are also
advertised in the base GL extensions string.