docs/GLSLExtensionRules.txt

OpenGL(R) Shading Language Extension Conventions

Last Modified Date: 2006/12/18
Author Revision: 11

Document Source: the OpenGL Extension Registry at

    http://www.opengl.org/registry/

Contributors:

    Pat Brown, NVIDIA
    John Kessenich, 3Dlabs
    Jon Leech
    Barthold Lichtenbelt, 3Dlabs
    Bill Licea-Kane, ATI
    Kent Lin, Intel
    Jeremy Sandmel, ATI
    Folker Schamel, Spinor

The ARB OpenGL Shading Language working group has defined the following
conventions for writing OpenGL extension specifications that extend the
Shading Language syntax or semantics.

=======================================================================

Section #1:  Conventions to avoid name-space collision

  We expect the Shading Language to continue to evolve through the
  use of vendor, EXT, and ARB extensions, as well as through
  revisions to the core language specification itself. As a result,
  we'd like to establish some name conventions to avoid name-space
  collisions between vendors and between the extensions and the core
  language.

  We have the same kinds of concerns that resulted in the need for
  naming and syntax rules document for the non-shader parts of
  OpenGL:

    http://www.opengl.org/registry/doc/rules.html#spec_naming

  We expect that we will need to affix new names with vendor tags
  where appropriate, and  change and/or remove these tags as
  extensions are promoted, in the same fashion as for core GL
  function and token names.

  The fact that the Shading Language is modeled after C/C++ means
  that we have some additional requirements for what the language
  should "look" like.

  Consequently, vendors must use the following naming conventions
  when creating new OpenGL extensions that affect the syntax of the
  Shading Language.

  General principles:

   - New syntax defined by an extension should be suffixed with a
     vendor specific extension (EXT, ARB, SGI, etc),
     except as noted below where the constraints of
     being "C-like" make it unpalatble.
   - Vendors should make a good faith effort to ensure that new
     shading language extensions do not conflict in syntax or
     semantics with the extensions of other vendors
     or the ARB.

  Rules for adding or modifying specific Shading Language
  constructs defined by extensions follow.

  Note: VEN stands for any vendor tag, e.g. ARB, EXT, SGI, etc.

  Summary:
  --------
  1a) variables:	       gl_<Name>VEN
  1b) keywords:		       __<name>VEN
  1c) data types:
      1c1) keywords:	   __<name>VEN
      1c2) derived types:  gl_<Name>VEN
  1d) operators:	       use new data types as operands or ask ARB
  1e) functions:	       <name>VEN

  Details:
  --------
  1a) Variables
      STATUS:  RESOLVED

      New variables defined by an extension should use:
	    prefix:   "gl_"  (lower case, single underscore)
	    suffix:   "VEN"  (no underscore)

      Form:
	gl_<Name>VEN

	<Name> is subject to these constraints:
	  - Each word in <Name> must start with a capital letter.
	  - Words should be concatenated, not separated with
	    underscores.
	  - Don't use an underscore to separate the
	    final VEN suffix.

      Notes:
	All of the variables defined in the core
	shading language specification already follow this
	convention.

	New variables added by shading language extensions should
	match the naming style of the core specification
	where possible.

      Examples:
	uniform   float  gl_SomeNewBuiltinScalarARB;
	varying   vec4	 gl_YetAnotherVaryingEXT;
	attribute vec4	 gl_OneMoreAttributeATI

  1b) keywords:
      STATUS:  RESOLVED

      New keywords defined by an extension should use:
	prefix:  "__"  (double underscore)
	suffix:  VEN   (no underscore)

      Form:
	__<name>VEN

      Notes:
	New keywords should be prefixed with "__" because this is
	how C/C++ handle keyword extensions.  The core language
	specification reserves the use of "__" anywhere within a
	keyword so that future language revisions from the ARB will
	not conflict with user level names.

	To avoid name collisions between OpenGL implementations from
	different IHV's, extended keywords should also use a vendor
	suffix.

	The working group considered requiring a "gl_" for the
	prefix instead of "__", but felt this diverged too far from
	the conventions of C/C++

      Examples:
	__float4EXT
	__sampler4DSGI
	__elifARB
	__some_new_kind_of_while_loopARB

  1c) New data types:
      STATUS:  RESOLVED

      Naming conventions for new data types defined by an extension
      differ depending on whether the data type is a new fundamental
      type defined as a keyword (case 1c1), or a new derived type
      defined by Shading Language constructs (case 1c2). Currently the
      only derived types are "struct"s.

      1c1) For new data type keywords defined by an extension:

	  prefix:  "__" (double underscore)
	  suffix: VEN

	Form:
	   __<name>VEN

	Examples:
	  __float4SGI
	  __half2NV
	  __triplefloatARB
	  __mat5EXT

      1c2) For new derived types defined by an extension:

	  prefix:  "gl_" (gl and single underscore)
	  suffix: VEN

	Form:
	  gl_<name>VEN

	Examples:
	  gl_skinningParametersEXT
	  gl_newDerivedStateStructARB

	Notes:
	  If new data types are defined as keywords, then they
	  should follow the rules for keywords. If new data types
	  are derived types, then they should follow a different
	  naming convention, like the one for variables.

	  New data types should not be added as keywords unless
	  absolutely necessary.

  1d) New operators:
      STATUS:  RESOLVED

      To avoid name space collisions for new operators
      defined by an extension, or existing operators whose
      behavior is re-defined by an extensions, extensions should
      either:

    1d1) Add a new data type along with the operator and use at
	 least one of these new data types for the operands of the
	 (re)defined operator. The new data type name should follow
	 the rules given in (1c) above for new data types.

    or

    1d2) For IHVs who want to define a new operator to work on
	 existing data types or to redefine an existing operator to
	 work on existing data types, the IHV should come to the ARB
	 and request the new operator to avoid colliding with any
	 upcoming uses for the operator by the ARB.

    Examples:
      An extension which overloads the "+" operator to add an int
      and a "triple" should define a new gl_tripleEXT type, then
      define the behavior of the + operator when one operand is an
      int and the other is a gl_tripleEXT.

      An extension needing to overload the "+" operator to add an
      int and a float must obtain permission from the ARB. If it
      approves, the ARB would revise the shading language grammar
      to define the behavior of the + operator when one operand is
      an int and the other is a float.

      An extension needing to define an entirely new operator for
      exponentiation must obtain permission from the ARB. If it
      approves, the ARB would agree to reserve an appropriate new
      operator, such as "**", and the extension would define the
      behavior of that operator with respect to some data types.

    Notes:
      On the surface, operators by themselves need no additional
      name-space syntax. No one wants "+" redefined as gl_+ARB, for
      instance.

      However, the ARB still wants to avoid name space and semantic
      collisions as extensions are promoted. The ARB reserves the
      use of operators with existing types.

      Therefore we've adopted the two-pronged approach listed above.
      (A) is borrowed from C++ operator overloading conventions.
      (B) is a fall-back position in the event that (A) is
      inconvenient.

  1e) functions:
      STATUS:  RESOLVED

      New functions defined by an extension should use:
	prefix:  none  (note, no "gl_" or "__")
	suffix:  VEN

      Form:
       <name>VEN

      Examples:
	newfunctionEXT()
	SomeOtherFuncARB()
	Yet_Another_FunctionSGI()

      Notes:
	Since none of the standard core Shading Language functions
	start with the "gl_" prefix, new functions do not need this
	prefix either.	There is no need to avoid collisions between
	implementation-defined and user-defined functions, because
	the Shading Language specifically allows user overloading of
	built-in functions.  In other words, name collisions are
	expected and intentional.  Further, when a name collision
	occurs between a user function and an implementation-defined
	function, the user function takes precedence.

	However, we still must avoid name collisions between IHV's
	and to allow for promotion of new functions into EXT, ARB
	and core status.  So, new functions should use a VENDOR
	suffix.


=============================================================

Section #2:  Protocol for accessing extension features in the
       shading language

  2a) Extension #defines?

    STATUS:  RESOLVED

    Every extension which affects shading language semantics or
    syntax must create a Shading Language preprocessor #define that
    matches the GL extension name string.  This #define would be
    available in the shading language if and only if the extension
    were supported on a given Shading Language implementation.

    Further, extensions which do not affect shading language
    semantics or syntax *must not* create this Shading Language
    preprocessor #define.

    The extension-writing template in the OpenGL Extension Registry
    will be updated to include a placeholder for shading language
    extensions showing the corresponding #define.

    Example:
      An extension which adds the extension string
	"GL_ARB_shading_extension_1"
      should also add a Shading Language preprocessor #define called
	GL_ARB_shading_extension_1

      Doing so means that a shader can do something like:

      #ifdef GL_ARB_shading_extension_1
	// do something using the extension
      #else
	// do something else or #error!
      #endif

    Notes:
      If an application wishes to emulate this behavior for any
      other extensions which do not directly affect the shading
      language syntax or behavior, they can simply query the
      extension string for the presence of these extensions and
      create their own #defines to be prepended to their shader
      strings.

    Pseudo-code example:
      char* prefixStr;
      if (glIsExtensionSupported("GL_ARB_texture_mirrored_repeat"))
      {
	ConcatString(prefixStr, "#define GL_ARB_texture_mirrored_repeat 1\n");
      }
      // use prefixStr as the first string given to glShaderSource()

  2b) Should we allow and/or require a shader author to declare
      their intended use of a given extension prior to use?

    STATUS:  RESOLVED - YES

    The ARB has received developer feedback requesting we strive
    towards portability in the shading language. The concern is
    shaders written on one implementation with an extension will not
    run on an implementation without the extension and that without
    an explicit "enable", the shader author may not realize that
    he/she was using any extended features.

    After much discussion, the resolution is as follows:

    For any extension which can affect shaders written without
    knowledge of the extension (i.e. no change in syntax to the
    shading language), the extension must introduce an API which
    explicitly "enables" the extended behavior. New extensions
    should not be allowed to change the behavior of old shaders
    without an explicit request to do so from the application.

    Further, for any extension which affects the syntax or semantics
    of the shading language, the shader author must explicitly make
    a request allow the use of the extension, by inserting this
    request within the shader text itself.

    This request is made using the following syntax:
      #extension <name> : <behavior>
    where
      <name> = the GL extension name string (as defined in section 2a,
	       starting with "GL_").
    and
      <behavior> can be one of the following:
      require, enable, warn, or disable

    Example:
      To use an extension which adds the extension string
      "GL_ARB_shading_extension_1", a shader should include a line like:

      #extension GL_ARB_shading_extension_1: enable

    See section 3.3 of the OpenGL Shading Language specification
    (Language Version 1.20) for details about using this mechanism.

-----------------------------------

Revision history:

 #11 - 12/18/2006 - Jon Leech
    - Clarify that #extension name must be the extension name string
      starting with "GL_", give an example, fix an old URL.

 #10 - 10/09/2006 - Jon Leech
    - Move registry URL to www.opengl.org.

  #9 - 05/12/2004 - js
    - no changes from rev #8, whitespace cleanup only

  #8 - 05/11/2004 - js
    - minor typos fixed
    - cleaned up language about when to use 1c1 or 1c2

  #7 - 05/07/2004 - Jon Leech
    - language cleanups including removing use of "built in"

  #6 - 04/29/04 - js
    - cleaned up psuedo code example in section 2a
    - change language about "decorate"ing names to "affix"

  #5 - 04/29/04 - js
    - added to contributors list

  #4 - 04/29/04 - js
    - cleaned up section 2 to reflect #extension resolution

  #3 - 03/15/04 - js
    - summarized section 1 conventions on name decorations

  #2 - 03/24/04 - js
    - reorganized doc to reflect recent working group discussions

  #1 - 03/19/04 - js
    - initial revision