blob: f02fa59a7e2a321d994a81497790e252886d5d16 [file] [log] [blame]
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