How to Create Khronos API Extensions (original) (raw)

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.

Specification

When initially creating an extension, take the following steps:

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:

One complete, shipping example to refer to is theFog 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

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

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 theglext.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 byglGetString(GL_EXTENSIONS).

GLX #defines a preprocessor token corresponding to the extension name in <GL/glx.h> (or an include file thatglx.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 byglXQueryExtensionsString, glXGetClientString, and/orglXQueryServerString (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 bywglGetExtensionsStringEXT.

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 andGLX_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 aGL_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 aglXClientInfo 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 aglXClientInfo 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 theglext.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 byglXQueryServerString.

glXQueryExtensionsString returns the list of extensions that can be supported on the connection. The client then issues aglXQueryServerString 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 theglxext.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 byglGetString. 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 thewglGetExtensionsStringEXT interface defined byWGL_EXT_extensions_string, as well as viaglGetString, for compatibility with older programs.

Extension names for all known WGL extensions are #defined in thewglext.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 calledGL_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 fromwglGetProcAddress 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 byeglGetString(EGL_EXTENSIONS). For example, this code could be used to check whether an extension calledEGL_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 byglXQueryExtensionsString.

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