20.3 How to Read an OpenGL Extension Specification

When reading an OpenGL extension specification, it helps to be familiar with the original OpenGL specification. The operation of an OpenGL extension is described as additions and changes to the core OpenGL specification. Having a copy of the core OpenGL specification handy is a good idea when reviewing an OpenGL specification.

OpenGL extension specifications consist of multiple sections. There is a common form established by convention used by nearly all OpenGL extension specifications. Often within a specification, the gl and GL prefixes on routine names and tokens are assumed. The following describes the purpose of the most common sections in the order that they normally appear in extension specifications:

Name

Lists the official name of the extension. This name uses underscores instead of spaces between words. The name also begins with a prefix that indicates who developed the extension. This prefix helps to avoid naming conflicts if two independent groups implement a similar extension. It also helps identity who is promoting use of the extension. For example: SGIS_point_parameters was an extension proposed by Silicon Graphics. The SGIS prefix belongs to Silicon Graphics. SGI uses the SGIS prefix to indicate that the extension is specialized and may not be available on all SGI hardware. Other prefixes in use are:

ARB

- Extensions officially approved by the OpenGL Architectural Review Board

EXT

- Extensions agreed upon by multiple OpenGL vendors

ES

- Evans and Sutherland

HP

- Hewlett-Packard

IBM

- International Business Machines

INTEL

- Intel

KTX

- Kinetix (maker of 3D Studio Max)

MESA

- Brian Paul's freeware portable OpenGL implementation

NV

- NVIDIA Corporation

SGI

- Silicon Graphics

SGIS

- Silicon Graphics (limited set of machines)

SGIX

- Silicon Graphics (experimental)

SUN

- Sun Microsystems

WIN

- Microsoft

Note that the SGIS_point_parameters extension has since been standardized by other OpenGL vendors. So now there is also an EXT_point_parameters extension with the same basic functionality as the SGIS version. The EXT prefix indicates that multiple vendors have agreed to support the extension. Successful OpenGL extensions are often promoted to EXT or ARB extensions or made an official part of OpenGL in a future revision to the core OpenGL specification. Almost all of the new functionality in OpenGL 1.1 and 1.2 showed up first as OpenGL extensions.

Name Strings

The name string or strings is used to indicate that the extension is supported by a given OpenGL implementation. Applications can query the GL_ EXTENSIONS string with OpenGL's glGetString() to determine what extensions are available. OpenGL also supports the idea of window system dependent extensions. Core OpenGL extension name strings are generally prefixed with GL_ while window system dependent extensions are prefixed with GLX_ for the X Window System or WGL_ for Win32 based on what window system to which the extension applies. Note that there may be multiple strings if the extension provides both core OpenGL rendering functionality and window system dependent functionality.

In the case of the X Window System, support for GLX extensions is indicated by listing the GLX extension name in the string returned by glxQueryExtensionsString(). Querying the core OpenGL extension string that requires an OpenGL rendering context be created and made current (calling glGetString() assumes a current OpenGL context). However, using glxQueryExtensionString() only requires a connection to an X server. Because the X Window System is client/server based, the OpenGL client library may support different extensions than the OpenGL server. For this reason, it is also possible to query the extensions supported by the client or server individually using glxQueryClientString() and glxQueryServerString() respectively. To actually use most GLX extensions, a GLX extension must be supported by both the OpenGL client and server (it is possible for an extension to be a pure client-side extension though). For this reason, the strings returned by glxQueryClientString() and glxQueryServerString() are intended for informational use only. The string returned by glxQueryExtensionsString() is typically intersection of the extensions supported by both the client and server. This is the string you should check before you use a GLX extension.

WGL extensions are advertised through OpenGL's core extension string, the one returned by glGetString().

Version

A source code control revision string to keep track of what version of the specification the given text file represents. It is important to make sure that you have the latest version of the extension specification in case there are any important changes. Normally the version string has the date the extension was last updated.

Number

Each OpenGL extension is assigned a unique number. Silicon Graphics allocates these numbers to ensure that OpenGL extensions do not overlap in their usage of enumerants or protocol tokens. This number is only important to extension implementors.

Dependencies

Often an extension specification builds on the functionality of pre-existing extensions. This section documents other extensions upon which the specified extension depends. Dependencies indicate that another extension ``is required'' to support the specified extension or that the specified extension ``affects'' the specification of another extension. When an extension affects the specification of another extension, the affecting extension is responsible for fully documenting the interactions between the two extensions.

The dependencies section often also indicates which version of the OpenGL core standard that the extension specification is based on. Later sections specify the extension based on updates to the relevant section of the particular OpenGL specification that the extension is based on.

You can often tell how important a given extension is to the evolution of OpenGL based on how many other extensions are listed that depend on or are affected by the given extension.

Overview

The section provides a description, often terse and without justification, for the extension's specified functionality. If you are trying to figure out what the extension does, this is the most useful section of an OpenGL extension specification. Do not expect a tutorial though.

Issues

Often there are issues that need to be resolved in the specification of an extension. This section documents open issues and states the resolution to resolved issues. These issues are often things of interest to the extension implementor, but can also help a programmer understand how the extension really works.

New Procedures and Functions

This section lists the function prototypes for any new procedures and functions that the extension adds. Keep in mind that specifications often leave out the gl prefix when discussing routines. Also note that the extension's new functions will be suffixed with the same letters used as the prefix for the extension name.

New Tokens

This section lists the tokens (also called enumerants) that the extension adds. The routines that accept each set of new enumerants are documented. The integer value of the enumerants is documented here. These values should be added to <GL/gl.h>. Keep in mind that specifications often leave out the GL_ prefix when discussing enumerants. Also note that the extension's new enumerants will be suffixed with the same letters used as the prefix for the extension name.

Additions to Chapter XX of the 1.X Specification (XXX)

These sections document how the core OpenGL specification should be amended to add the extension's functionality to the core OpenGL functionality. Notice that the exact version of the core OpenGL specification (such as 1.0, 1.1, or 1.2) is documented. The chapters typically amended by an extension specification are:

• Chapter 2 - OpenGL Operations
• Chapter 3 - Rasterization
• Chapter 4 - Fragments and the Framebuffer
• Chapter 5 - Special Functions
• Chapter 6 - State and State Requests

These sections are quite legalistic. They indicate precisely how the OpenGL specification wording should be amended or changed. Often tables within the specification are amended as well.

Additions to the GLX Specification

If an extension has any window system dependent functionality affecting the GLX interface to the X Window System, these issues would be documented here.

GLX Protocol

When implementing the extension for the X Window System, if any special X11 extension protocol for the GLX extension is required to support the extension, the protocol would be documented in this section. This section is only interesting to GLX protocol implementors because the GLX protocol is hidden from application programmers beneath the OpenGL API.

Dependencies on XXX

These sections describe how the extension depends on some other extension that was listed in the Dependencies section. Usually the wording says that if the other extension is not supported, simply ignore the portion of this extension dealing with the dependent extension's state and functionality.

Errors

If the extension introduces any new error conditions particular to the extension, they are documented here.

New State

Extensions typically add new state variables to OpenGL's state machine. These new variables are documented in this section. The variable's get enumerant, type, get command, initial value, description, section of the specification describing the state variable's function, and the attribute group that the state belongs to are all documented in tables in this section.

New Implementation Dependent State

Extensions may add implementation dependent state. These are typically maximum and minimum supported ranges for the extension functionality. For example, what is the widest line size supported by the extension. These values can be queried through OpenGL's glGet() family of routines.

Backward Compatibility

If the extension supersedes an older extension, issues surrounding backward compatibility with the older extension are documented in this section.

Note that these sections are merely established by convention. While the conventions for OpenGL extension specifications are normally followed, extensions vary in how closely they stick to the conventions. Generally, the more preliminary an extension is, the more loosely specified it is. Hopefully after sufficient review and even implementation, the specification language and format is improved to provide an unambiguous final specification.