blob: 279d7197421aa5b9b5457bfefe2e85c79db18507 [file] [log] [blame]
Syntax Rules for OpenGL Extensions
Based on a version edited by Kurt Akeley on September 10, 2003.
Updates proposed by Eskil Steenberg, May 2006.
Revised by Benj Lipchak under the direction of the Ecosystem TSG, December 2006.
Reserved terms
--------------
** NOTE **
Whereas some of the other rules in subsequent sections of this document
are intended to be strictly adhered to, this section is intended as a
set of guidelines to assist in name decisions. The guidelines should
be considered, and then accepted or rejected, on a case by case basis.
** NOTE **
The terms used in OpenGL should have a consistent meaning. Any time
new functionality is introduced it is desired to use terms that are
previously established in GL. If no term exists that fits with the
new functionality, a new term may be used. Whenever a new term is used,
the precise meaning of that term should be specified and added to this
text so that future functionality has the option of reusing the term
with a consistent meaning.
A term in GL should encompass more then the meaning of the word found
in a dictionary. It should encompass limitations and usages and give the
reader a broader sense of the usage of the word in the context of OpenGL.
When choosing new words one should always name it for what it does and
never name it for its intended usage. In a general programmable
environment the naming should not suggest usage.
It is desired to keep data and the usage of data separated in the name
space. "image" data can be used for "texturing." The two should not be
named the same. This maintains consistency if in some future version
something other than an image can be used for texturing, or if an image
can be used for something other then texturing. This is why it is
strongly encouraged to name any storage class for what it stores, not the
usage of the data.
Whenever a procedure sets the state that is directly associated with
something that can be found in the language grammar, it is preferred to
use terms from the language like "attribute," "uniform" or "texture."
1: Asking for information
"Get" is used as a prefix whenever the procedure returns state from the GL.
2: Storage
"Create" is used for any procedure that creates an object. No other
creations should be named "create."
"Delete" is used for any procedure that marks an object for
destruction. No other destructions should be named "delete."
4: Object content
TBD: Names must be chosen.
5: Types of state setting
"Pname" is used to define what a subsequent parameter refers to. Pname
is always followed by a "param."
"Param" is only used when a generic parameter or array of parameters is
being passed in.
"Count" always refers to the length of an array.
"Size" always refers to size measured in units or number of bytes.
"Render" refers to the later parts of the pipeline that apply the
resulting data of a computation to a storage container. (Examples of
operations that can be refered to as rendering are sampling, depth test,
blending, and resolve.)
"Draw" refers to the earlier part of the pipeline when results are
being computed.
6: References
Any time an object is referenced by the context or another object the
following words should be used:
TBD: Names must be chosen.
Accepted terms
--------------
Notes:
1. Abbreviations are required for all usage unless otherwise noted.
2. Compound words (e.g. Doublebuffer) must always be used as
compounds. Embedded words are not capitalized in function
names, and are not separated by underscores in token names.
(e.g. Doublebuffer, not DoubleBuffer. DOUBLEBUFFER, not
DOUBLE_BUFFER.)
Exceptions:
(1) Abbreviation is used in function names, but not in token names.
(2) Abbreviation is used in token names, but not in function names.
(3) Abbreviation is used for GL and GL extensions, but not for
WGL abbreviations.
(4) Abbreviation is used only as the last characters of token names
that identify packed data types.
(E.g. GL_UNSIGNED_BYTE_2_3_3_REV)
(5) Abbreviation is used only in interleaved vertex array token names.
(e.g. GL_T4F_C4F_N3F_V4F)
(6) Abbreviation is used only for specific operations, such as
logical operations (Logic Op) or stencil operations (Stencil Op).
Abbreviation is not used for generic operations (e.g. Invalid
Operation).
Abbrev. Term or phrase Specification(s) used in
------- -------------- ------------------------
Access 28
Accum Accumulation Buffer GL, 9
Active GL, 15
Add GL, 6, 17
Address 2, 26
Aliased GL
Alignment GL
All GL
Alpha GL, 5, 9, 12, 17
Always GL
Ambient GL
ASCII American Standard ... 26, 27
And GL
Are GL
ALU Arithmetic Logic Unit 27
Array GL, 15, 16, 26, 28
Attenuation GL, 14
Attrib Attribute GL, 9, 20, 26, 27, 28
Auto Automatic GL
Aux Auxiliary GL, 9, 20
Back GL, 20
Base GL
Begin GL
Bias GL
Bind GL, 20, 26, 27, 28
Binding GL, 7, 26, 27, 28
Bit GL, 9
Bitfield GL
Bitmap GL, 9
Blend GL, 15
Blue GL, 9
BGR Blue Green Red GL
BGRA Blue Green Red Alpha GL
Boolean GL
Border GL, 13
Box GL
Buffer GL, 4, 5, 9, 11, 28
Byte GL
Call GL
Care GL
Choose 9
Clamp GL, 13
Clear GL
Client GL
Clip Clipping GL
CW Clockwise GL
Coeff Coefficient GL
C (5) Color GL, 3, 9, 17, 26, 28
Index Color Index GL, 9, 28
Combine GL, 17
Compare GL, 23, 24
Compile GL
Component GL, 22
Compressed GL, 12
Compression GL, 12
Constant GL, 17
Control GL
Convolution GL
Context 10
Coord Coordinate GL, 27
Copy GL, 9, 28
Correction GL
CCW Counter Clockwise GL
Coverage GL, 5
Cube GL, 7, 20
Cube Map 7, 20
Cull GL
Current GL, 10, 15, 16, 26, 27
Cutoff GL
Data 28
Decal GL
Decr Decrement GL
Delete GL, 4, 26, 27, 28
Density GL
Depth GL, 9, 16, 22, 26, 27
Dst Destination GL
Destroy 11
Diffuse GL
Dim Dimension GL
Direction GL
Disable GL, 26
List Display List
Distance GL, 14
Dither GL
Dont Do Not GL
Domain GL
Dot 19
Dot3 GL, 19
Double GL
Doublebuffer GL
Draw GL, 9, 11, 28
Dynamic 28
Edge GL, 28
Element GL, 28
Emission GL
Enable GL, 26
Enabled GL
End GL
Enum Enumerant GL
Env Environment GL, 26, 27
Equal GL
Equation GL
Equiv Equivalent GL
Error GL, 10, 26, 27
Eval Evaluate GL
XOR Exclusive OR GL
Execute GL
Exponent GL
Exp Exponential GL
Exp2 Exponential Squared GL
Extension GL, 5
Eye GL
Face GL, 20
Factor GL
Fade GL, 14
Fail GL, 24
False GL
Fan GL
Fastest GL
Feedback GL
Fill GL
Filter GL
Finish GL
First GL
Flag GL
Flat GL
Float GL
Flush GL
Fog GL, 28
Format GL, 9, 12, 20, 26, 27
Fragment GL, 27
Framebuffer (documentation only)
Front GL, 20
Frustum GL
Func Function GL, 23
Gen Generate GL, 26, 27, 28
Get GL, 2, 5, 9, 10, 11, 26, 27, 28
Granularity GL
GL Graphics Library GL
Greater GL
Gequal Greater than or equal to GL
Green GL, 9
Grid GL
Half GL
Height GL, 11
Hint GL, 12
Histogram GL
Identity GL
Ignore GL
Image GL, 12, 20, 27
Incr Increment GL
Index 16
Indices GL
Indirection 27
Init Initial GL
Init Initialize GL
Instruction 26, 27
Int (2) Integer GL
Intensity GL, 12
Interleaved GL
Internal GL
Interpolate GL, 17
Invalid GL, 10
Invert GL, 5
Inverted GL
Is GL, 26, 27, 28
Keep GL
LSB Least significant bit GL
Left GL, 20
Length GL, 26, 27
Less GL
Lequal Less than or equal to GL
Level GL, 20
LOD Level of Detail GL
Light GL
Light Model Lighting Model
Line GL
Linear GL
List GL
Limit 26, 27
Load GL, 3
Local GL, 26, 27
Logic Op Logical Operation GL
Loop GL
Luminance GL, 12
Mag Magnify GL
Make 10
Map GL, 7, 20, 28
Mapped 3, 28
Mask GL
Material GL
Matrix, Matrices GL, 16, 26, 27
Max Maximum GL, 7, 11, 14, 15, 16, 26, 27
Memory GL
Mesh GL
Win Microsoft Windows OS GL
Min Minimum GL, 14
Minmax Minimum Maximum GL
Min Minify GL, 14
Minus GL, 17
Mirrored GL, 21
Mode GL, 22, 23
Model GL
Modelview GL, 3, 15
Modulate GL, 17
Mipmap Multim in parvo map GL, 20
Multi Multiple GL
Mult Multiply GL, 3
Multisample GL, 5
Name GL
Native 26, 27
Nearest GL
NAND Negated AND GL
NOR Negated OR GL
Negative GL, 7, 20
Nesting GL
Never GL
New GL
Nicest GL
No GL, 9, 28
Noop No Operation GL
None GL
N (5) Normal GL, 7, 28
Normalize, Normalized GL, 26
Notequal GL
Num (3) Number Of GL
Object GL
Of GL
Offset GL
One GL, 17
Only 28
Operand GL, 17
Op (6) Operation GL
Or GL
Order GL
Ortho Orthographic GL
Out GL
Overflow GL
Pack GL
Palette 9, 16
Param Parameter GL, 14, 26, 27, 28
Pname Parameter Name GL
Pass GL
Pattern GL
Perspective GL
Phong GL
Pixel GL, 9, 10, 11
Pbuffer Pixel Buffer 11, 20
Plane GL
Point GL, 14, 26
Pointer GL, 15, 16, 26, 28
Polygon GL
Pop GL
Position GL
Pos (1) Position GL, 25, 26, 27
Positive GL, 7, 20
Post GL
Previous GL, 17
Primary GL, 17
Prioritize, Priority GL
Proc Procedure 2
Program 26, 27
Projection GL, 3
Proxy GL, 7
Push GL
Quad Quadrilateral GL
Quadratic GL
Query 11
Range GL
Raster GL
Read GL, 10, 28
Rect Rectangle GL
Red GL, 9
RGB Red Green Blue GL, 12, 17, 19, 20
RGBA Red Green Blue Alpha GL, 9, 12, 19, 20
Reduce GL
Ref Reference GL
Reflection GL, 7
Region GL, 4
Register 26
Render GL
Renderer GL
Repeat GL, 21
Replace GL, 17
Replicate GL
Rescale GL
Reset GL
Resident GL
Return GL
Rev (4) Reverse GL
Right GL, 20
Rotate, Rotated GL
Row GL
Sample GL, 5
Saturate GL
Scale, Scaled GL, 17
Scissor GL
Secondary GL, 28
Segment GL
Select GL
Selection GL
Separable GL
Separate GL
Set (noun only!) GL
Shade GL
Shade Model Shading Model
Shift GL, 9
Shininess GL
Short GL
Side GL, 26
Signed GL, 17
Single GL
Sink GL
Size GL, 7, 12, 14, 15, 16, 22, 26, 28
Skip GL
Smooth GL
Src Source GL, 17
Specular GL
Sphere GL
Spot GL
Stack GL, 16, 26, 27
Start GL
State GL
Static 28
Stencil GL, 9
Stereo GL, 9
Stipple GL
Store GL
Stream 28
Stride GL, 15, 16, 26
String GL, 5, 26, 27
Strip GL
Sub GL, 12
Subtract 17
Sub Image 12
Subpixel GL
Sub Table GL
Sum GL, 15, 26
Swap GL, 9
Table GL
Target 20
Temporary 26, 27
Test GL
Tex (1), Texture GL, 3, 7, 12, 17, 18, 20, 22, 23,
T(5) 24, 27, 28
Threshold GL, 14
Through GL
To GL, 9, 11, 13, 20, 23
Token GL
Transfer GL
Transform GL
Translate, Translated GL
Transpose GL, 3, 26, 27
Triangle GL
True GL
Two GL, 26
Type GL, 9, 10, 15, 16, 26
Under 26, 27
Underflow GL
Unit GL, 15, 27
Unity 15
Unmap 28
Unpack GL
Unsigned GL
Ubyte Unsigned Byte GL
Uint Unsigned Int GL
Ushort Unsigned Short GL
Usage 28
Valid GL
Value GL, 5, 9, 24
Vendor GL
Version GL
V (5) Vertex GL, 15, 26, 28
Vertices GL
Viewer GL
Viewport GL
Weight 15, 28
Width GL, 11
Window GL, 25
Wrap GL
Write 28
Writemask GL
Zero GL
Zoom GL
Abbreviations specifically not allowed
--------------------------------------
Bgn Begin
Mat Matrix
Pnt Point
Poly Polygon
Tri Triangle
Used in WGL specs only (or differently)
---------------------------------------
Abbrev. Term or phrase Specification(s) used in
------- -------------- ------------------------
Acceleration 9
Create 4, 11
DC ??? 10
Declare 11
Device 10
Exchange 9
Full 9
Generic 9
GDI ??? 9
Handle 11
HP ??? 11
Incompatible 10
Largest 11
Layer 9
Lost 11
Method 9
Need 9
Number Number Of 9
OpenGL 9
Overlay 9
Release 20
Restore 4
Save 4
Share 9
Support 9
System 9
Transparent 9
Undefined 9
Underlay 9
Name rules (for all names)
--------------------------
Always use the specified abbreviations. Never abbreviate terms
that are already in the OpenGL API and are not abbreviated. If you
add terms to your extensions, abbreviate consistently, maintaining
a local version of additions to the list of abbreviations.
Use Depth, never Z.
The word "object" should not be used in a function name unless it
operates on all object types.
Longer descriptive names are desired if they are believed to help
developers identify the purpose of a name.
The opposite of "create" is "destroy." "delete" marks an object for
later destruction.
All names should describe what functionality does, never its expected
usage.
Begin each word with a capital letter, except the second word of
compound words.
Procedure name rules
--------------------
Never use set, as in SetFeedbackBuffer. Set is implicit, unless
otherwise specified.
Use Verb-noun (DeleteList) and adjective-noun (EdgeFlag) formats.
Append a corporate-specific suffix to all procedures. For example:
glNewCommandSGI. All upper case is preferred for this suffix, but
is not required. The suffix is always last, following OpenGL type
and count suffixes. (e.g. glNewVertex3iSGI, not glNewVertexSGI3i.)
Definition name rules
---------------------
Use all capital letters.
Separate words with underscores, except words within compound words.
Append simple numeric suffixes directly to the end of definition
tokens (LIGHT0). Begin these sequences with 0.
Use an underscore to separate complex suffixes from the token body
(MAP_3V).
Append a corporate-specific suffix to the token, after any other
suffixes. For example: GL_NEW_TOKEN0_SGI. All upper case is
required.
All tokens that are used only for a single use should be grouped
together using enum types.
Parameter name rules
--------------------
<target> is reserved for the notion of "which is affected", and for
the corresponding "which is returned" get commands.
<params> is reserved for an array of parameters whose contents are
defined by a second enumerated argument, called <pname>.
Begin number sequences with 1, not 0. (e.g. u1,u2, not u0,u1)
Any parameters that contain more then one word should have the
second and subsequent words capitalized.
Long descriptive parameters are encouraged.
Parameter order
---------------
<X> precedes <Y> precedes <Z> precedes <W>.
<R> precedes <G> precedes <B> precedes <A>.
<S> precedes <T> precedes <R> precedes <Q>.
<U> precedes <V>.
The array being passed is always the last argument.
If a passed array has a type, the type specification argument immediately
precedes the array.
<pname> always precedes <params>.
<x> and <y> precede <width> and <height>.
<format> precedes <type>.
<target> is first.
<face> is first.
<object> is first.
<count> always precedes the thing that it counts.
Any time the function parameters contain an address of what they
operate on, the address is last.
Arrays are never terminated by NULL or any other termination but are
always specified by length.
For variable length arrays passed into the GL, the parameter list should
end with: "sizei count, const void* data"
For variable length arrays passed back from the GL, the parameter list
should end with: "sizei maxCount, sizei* count, void* data"
Parameter types
---------------
All integer quantity parameters (widths, heights, array lengths, etc.)
should be typed GLsizei, not GLint or GLuint. Note that GLsizei
generates an error only for negative values, so all integer quantity
parameters should accept the value zero.
Handles to specific object types are typed as pointers to the corresponding
abstract structs. Generic objects are passed around as void pointers.
Generic masks that do not have explicitly defined bit values (e.g.
color index write masks and stencil write masks) should be typed
GLuint. GLuint is also used for unsigned integer components, such as
color components and depth components.
Masks that do have explicitly defined bit values (e.g. attribute mask,
clear mask) should be typed GLbitfield, not GLuint.
All floating point parameters that are clamped to the range [0,1] when
received should be typed GLclampf or GLclampd, not GLfloat or GLdouble.
Extension name rules
--------------------
An extension name is prefixed with the same string that suffixes its
procedures and definitions. The prefix and the individual words are
separated with underscores, the prefix is all upper case, and the other
text is all lower case. For example, extension ARB_cool_feature, which
specifies glCoolProcedureARB() and defines GL_COOL_DEFINITION_ARB.
Suffix codes
------------
i signed 32-bit integer
ui unsigned 32-bit integer
s signed 16-bit integer
us unsigned 16-bit integer
b signed 8-bit integer
ub unsigned 8-bit integer
l signed 64-bit integer
ul unsigned 64-bit integer
f 32-bit float
d 64-bit float
t token enum
v vector format
N normalize values
# number of components (e.g. 3)
#x# matrix dimensions (e.g. 2x4)
Shared extensions
-----------------
An OpenGL extension may be deemed a shared extension if either:
1. Two or more OpenGL licensees agree in good faith to implement
and ship the extension, or
2. The OpenGL ARB determines that it is in the best interest of
the licensees that the extension be shared.
The procedures and definitions that are defined by a shared extension
are suffixed with EXT, rather than by a company-specific suffix.
Likewise, the extension name is prefixed by EXT. To avoid name
conflicts Silicon Graphics will maintain a registry of EXT extensions,
including all their procedures and definitions, in a location that is
accessible to all licensees.