|
|
Paula Womack September 29, 1995
A. SPECIFICATION
Is there already an extension that does what I want?
The specifications for extensions that have already been proposed by licensees can be obtained from sgiblab.sgi.com. via ftp using the opengl_l account. (Get the tar file extension_info.tar.Z.) Check out the extensions here before creating your own. There may be another licensee working on a similar extension.
Some of the extension specifications are also available to the public on sgigate (using anonymous ftp). Look in pub/opengl/extensions.
What is the best way to create a new extension? The best way to create a new extension is to first write a specification. A template can be found in the extension_info.tar.Z file. It is important to think about all the different areas of the OpenGL (and maybe GLX) specification that are affected. (For example, if you are defining a new attribute, can it be pushed and popped? How do you read back the values?) The template can help you with this.
syntax.rules is also included in extension_info.tar.Z. Your extension should follow the OpenGL syntax guidelines.
All the new names introduced by the extension should have a vendor-specific suffix appended to them. (e.g., glNewCommandSGI or glXNewCommandSGI) If another licensee agrees to support the extension, or if the ARB approves the extension, then the EXT designation can be used.
How do I name my extension?
All extensions must be named and the name should be included in the extension specification. The extension name must have the vendor-specific acronym or EXT prepended to the front. (e.g., SGI_new_extension or EXT_new_extension)
If the extension modifies OpenGL then the token GL_<ext_name> (e.g., GL_SGI_new_extension or GL_EXT_new_extension) must be included in the extension string that is returned by glGetString and it also must be defined in gl.h (or an include file that gl.h includes).
If the extension modifies GLX then the token GLX_<ext_name> (e.g., GLX_SGI_new_extension or GLX_EXT_new_extension) must be included in the extension string that is returned by glXQueryExtensionsString, glXGetClientString, and glXQueryServerString (See below for a description of the different routines) and it also must be defined in glx.h (or an include file that glx.h includes).
Note that extensions can have both OpenGL components and windowing system components. For example, the SGI multisampling extension modifies both GLX and OpenGL. In this case there will be two tokens associated with the extension (e.g., GL_SGIS_multisample and GLX_SGIS_multisample) and the extension will be advertised by both OpenGL and GLX. What else do I need to do? SGI keeps a registry of 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, OpenGL rendering codes for gls and extension numbers.
If an extension defines new enumerated types then you need to register a block of values from SGI (they are allocated in blocks of 16). If an extension defines new OpenGL rendering commands then you need to register gls rendering codes for it. Also, if you want the extensions to work with the X windowing system (i.e., with GLX), then you need to request some GLX opcodes and define GLX protocol for it. All new extensions should 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 must also be registered with SGI.
It is a good idea to include the new enumerated values, GLX codes and extension number in the specification.
Once you have completed the extension, you should consider making it available to other licensees by mailing it to [email protected]. SGI will then include the new extension in the extension_info.tar file on sgiblab.sgi.com.
B. IMPLEMENTATION
Errors:
Whenever possible, extensions should use existing errors instead of defining new error returns. For GLX, if a new protocol error is introduced, then a error number must be registered with SGI. 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.
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 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 OpenGL extensions recognized by libGL.x must be defined in gl.h, or a header file that gl.h includes (e.g., #define GL_SGI_new_extension)
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. If the server supports GLX version 1.1 or greater then the client 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 OpenGL extensions recognized by libGL.x must be defined in glx.h, or a header file that glx.h includes (e.g., #define GLX_SGI_new_extension)
C. USING 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 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
Before using a GLX extension, programmers should check the compile time defines and the extension string returned by glXQueryExtensionsString. Since glXQueryExtensionsString, is only available in GLX versions 1.1 and later, programmers must also check the GLX version.
For example, 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 need to 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) glNewExtensionEXT(...) #endif
|
