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_VEN 1b) keywords: __VEN 1c) data types: 1c1) keywords: __VEN 1c2) derived types: gl_VEN 1d) operators: use new data types as operands or ask ARB 1e) functions: 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_VEN is subject to these constraints: - Each word in 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: __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: __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_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: 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 : where = the GL extension name string (as defined in section 2a, starting with "GL_"). and 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