| 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. |