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 -------------------- is reserved for the notion of "which is affected", and for the corresponding "which is returned" get commands. is reserved for an array of parameters whose contents are defined by a second enumerated argument, called . 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 --------------- precedes precedes precedes . precedes precedes precedes . precedes precedes precedes . precedes . The array being passed is always the last argument. If a passed array has a type, the type specification argument immediately precedes the array. always precedes . and precede and . precedes . is first. is first. is first. 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.