windows-xp/Source/XPSP1/NT/multimedia/opengl/exts/rules/exthowto.txt

					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