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

- Specifying an extension prior to coding it.
- 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.
- If no suitable extension already exists, determine if you can agree on a multivendor or Khronos extension, or if the extension must be specific to a single vendor.
- Develop and write an extension specification, following the naming conventions.
- 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

- `"api"` identifies the API (`"GL"` for OpenGL and OpenGL ES; `"EGL"`, `"GLX"`, and `"WGL"` for the corresponding window-system abstraction APIs EGL, GLX, and WGL; `"GLU"` for the OpenGL Utility Library; and `"OVG"` for OpenVG. (Note: OpenMAX, OpenSL, OpenML TBD).
- `"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.

### Extension Registry

Khronos keeps a registry of extension specifications, enumerated type values, GLX codes (vendor private opcodes, vendor private with reply opcodes, new visual attribute type values, GLX error codes and GLX event codes), OpenGL rendering codes for GLX, and OpenGL rendering codes for GLS and extension numbers. Vendors shipping extensions using any of these values must obtain them from Khronos.

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.

There are detailed enumerant allocation policies for OpenGL, GLX, and WGL enumerants.

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:

>         static GLboolean CheckExtension(char *extName, const char *extString)
>         {
>     	/*
>     	 ** Search for extName in the extensions string.  Use of strstr()
>     	 ** is not sufficient because extension names can be prefixes of
>     	 ** other extension names.  Could use strtok() but the constant
>     	 ** string returned by glGetString can be in read-only memory.
>     	 */
>     	char *p = (char *)extString;
>     	char *end;
>     	int extNameLen;

>     	extNameLen = strlen(extName);
>     	end = p + strlen(p);

>     	while (p < end) {
>     	    int n = strcspn(p, " ");
>     	    if ((extNameLen == n) && (strncmp(extName, p, n) == 0)) {
>     		return GL_TRUE;
>     	    }
>     	    p += (n + 1);
>     	}
>     	return GL_FALSE;
>         }

>         const GLubyte *ext_string;
>         int new_ext_supported = GL_FALSE;

>         if (CheckExtension("GL_EXT_new_extension", glGetString(GL_EXTENSIONS)))
>     	new_ext_supported = GL_TRUE;

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:

>         #ifdef GL_EXT_new_extension
>     	if (new_ext_supported)
>     	    glNewExtensionEXT()
>         #endif

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:

>         typedef void (WINAPI *PFNGLNEWEXTENSIONEXTPROC)();
>         PFNGLNEWEXTENSIONEXTPROC *glNewExtensionEXT = NULL;

>         /* Do this once, after context creation */
>         #ifdef GL_EXT_new_extension
>     	if (new_ext_supported)
>     	    glNewExtensionEXT = (PFNGLNEWEXTENSIONEXTPROC)
>     		wglGetProcAddress("glNewExtensionEXT");
>         #endif

>         /* Do this when calling the extension */
>         #ifdef GL_EXT_new_extension
>     	if (new_ext_supported)
>     	    (*glNewExtensionEXT)();
>         #endif

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

>     	EGLDisplay dpy; // Initialized elsewhere
>     	int new_ext_supported = FALSE;

>     	if (CheckExtension("EGL_OES_new_extension",
>     			       eglGetString(display, EGL_EXTENSIONS));
>     		new_ext_supported = TRUE;
>         #endif

If the extension is supported, then it is safe to use it at runtime. However, compile time checks must be made to ensure that you can call the extension. For example:

>         #ifdef EGL_OES_new_extension
>     	if (new_ext_supported)
>     	    eglNewExtensionEXT(...);
>         #endif

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

>     	Display *dpy;
>     	int new_ext_supported = GL_FALSE;
>     	int major, minor, screen;

>     	if (!glXQueryVersion(dpy, &major, &minor))
>     	    exit(1);
>     	screen = DefaultScreen(dpy);

>         #ifdef GLX_VERSION_1_1
>     	if (minor > 0 || major > 1)
>     	    if (CheckExtension("GLX_EXT_new_extension",
>     			       glXQueryExtensionsString(dpy, screen)))
>     		new_ext_supported = GL_TRUE;
>         #endif

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:

>         #ifdef GLX_EXT_new_extension
>     	if (new_ext_supported)
>     	    glXNewExtensionEXT(...);
>         #endif

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

Code snippet should go here

Last modified August 13, 2006 by Jon Leech