1Syntax Rules for OpenGL Extensions 2 3Based on a version edited by Kurt Akeley on September 10, 2003. 4Updates proposed by Eskil Steenberg, May 2006. 5Revised by Benj Lipchak under the direction of the Ecosystem TSG, December 2006. 6 7 8Reserved terms 9-------------- 10 11 ** NOTE ** 12 Whereas some of the other rules in subsequent sections of this document 13 are intended to be strictly adhered to, this section is intended as a 14 set of guidelines to assist in name decisions. The guidelines should 15 be considered, and then accepted or rejected, on a case by case basis. 16 ** NOTE ** 17 18 The terms used in OpenGL should have a consistent meaning. Any time 19 new functionality is introduced it is desired to use terms that are 20 previously established in GL. If no term exists that fits with the 21 new functionality, a new term may be used. Whenever a new term is used, 22 the precise meaning of that term should be specified and added to this 23 text so that future functionality has the option of reusing the term 24 with a consistent meaning. 25 26 A term in GL should encompass more then the meaning of the word found 27 in a dictionary. It should encompass limitations and usages and give the 28 reader a broader sense of the usage of the word in the context of OpenGL. 29 30 When choosing new words one should always name it for what it does and 31 never name it for its intended usage. In a general programmable 32 environment the naming should not suggest usage. 33 34 It is desired to keep data and the usage of data separated in the name 35 space. "image" data can be used for "texturing." The two should not be 36 named the same. This maintains consistency if in some future version 37 something other than an image can be used for texturing, or if an image 38 can be used for something other then texturing. This is why it is 39 strongly encouraged to name any storage class for what it stores, not the 40 usage of the data. 41 42 Whenever a procedure sets the state that is directly associated with 43 something that can be found in the language grammar, it is preferred to 44 use terms from the language like "attribute," "uniform" or "texture." 45 46 47 1: Asking for information 48 49 "Get" is used as a prefix whenever the procedure returns state from the GL. 50 51 52 2: Storage 53 54 "Create" is used for any procedure that creates an object. No other 55 creations should be named "create." 56 57 "Delete" is used for any procedure that marks an object for 58 destruction. No other destructions should be named "delete." 59 60 61 4: Object content 62 63 TBD: Names must be chosen. 64 65 66 5: Types of state setting 67 68 "Pname" is used to define what a subsequent parameter refers to. Pname 69 is always followed by a "param." 70 71 "Param" is only used when a generic parameter or array of parameters is 72 being passed in. 73 74 "Count" always refers to the length of an array. 75 76 "Size" always refers to size measured in units or number of bytes. 77 78 "Render" refers to the later parts of the pipeline that apply the 79 resulting data of a computation to a storage container. (Examples of 80 operations that can be refered to as rendering are sampling, depth test, 81 blending, and resolve.) 82 83 "Draw" refers to the earlier part of the pipeline when results are 84 being computed. 85 86 87 6: References 88 89 Any time an object is referenced by the context or another object the 90 following words should be used: 91 92 TBD: Names must be chosen. 93 94 95Accepted terms 96-------------- 97 98 Notes: 99 100 1. Abbreviations are required for all usage unless otherwise noted. 101 102 2. Compound words (e.g. Doublebuffer) must always be used as 103 compounds. Embedded words are not capitalized in function 104 names, and are not separated by underscores in token names. 105 (e.g. Doublebuffer, not DoubleBuffer. DOUBLEBUFFER, not 106 DOUBLE_BUFFER.) 107 108 Exceptions: 109 110 (1) Abbreviation is used in function names, but not in token names. 111 112 (2) Abbreviation is used in token names, but not in function names. 113 114 (3) Abbreviation is used for GL and GL extensions, but not for 115 WGL abbreviations. 116 117 (4) Abbreviation is used only as the last characters of token names 118 that identify packed data types. 119 (E.g. GL_UNSIGNED_BYTE_2_3_3_REV) 120 121 (5) Abbreviation is used only in interleaved vertex array token names. 122 (e.g. GL_T4F_C4F_N3F_V4F) 123 124 (6) Abbreviation is used only for specific operations, such as 125 logical operations (Logic Op) or stencil operations (Stencil Op). 126 Abbreviation is not used for generic operations (e.g. Invalid 127 Operation). 128 129 130 131 Abbrev. Term or phrase Specification(s) used in 132 ------- -------------- ------------------------ 133 Access 28 134 Accum Accumulation Buffer GL, 9 135 Active GL, 15 136 Add GL, 6, 17 137 Address 2, 26 138 Aliased GL 139 Alignment GL 140 All GL 141 Alpha GL, 5, 9, 12, 17 142 Always GL 143 Ambient GL 144 ASCII American Standard ... 26, 27 145 And GL 146 Are GL 147 ALU Arithmetic Logic Unit 27 148 Array GL, 15, 16, 26, 28 149 Attenuation GL, 14 150 Attrib Attribute GL, 9, 20, 26, 27, 28 151 Auto Automatic GL 152 Aux Auxiliary GL, 9, 20 153 Back GL, 20 154 Base GL 155 Begin GL 156 Bias GL 157 Bind GL, 20, 26, 27, 28 158 Binding GL, 7, 26, 27, 28 159 Bit GL, 9 160 Bitfield GL 161 Bitmap GL, 9 162 Blend GL, 15 163 Blue GL, 9 164 BGR Blue Green Red GL 165 BGRA Blue Green Red Alpha GL 166 Boolean GL 167 Border GL, 13 168 Box GL 169 Buffer GL, 4, 5, 9, 11, 28 170 Byte GL 171 Call GL 172 Care GL 173 Choose 9 174 Clamp GL, 13 175 Clear GL 176 Client GL 177 Clip Clipping GL 178 CW Clockwise GL 179 Coeff Coefficient GL 180 C (5) Color GL, 3, 9, 17, 26, 28 181 Index Color Index GL, 9, 28 182 Combine GL, 17 183 Compare GL, 23, 24 184 Compile GL 185 Component GL, 22 186 Compressed GL, 12 187 Compression GL, 12 188 Constant GL, 17 189 Control GL 190 Convolution GL 191 Context 10 192 Coord Coordinate GL, 27 193 Copy GL, 9, 28 194 Correction GL 195 CCW Counter Clockwise GL 196 Coverage GL, 5 197 Cube GL, 7, 20 198 Cube Map 7, 20 199 Cull GL 200 Current GL, 10, 15, 16, 26, 27 201 Cutoff GL 202 Data 28 203 Decal GL 204 Decr Decrement GL 205 Delete GL, 4, 26, 27, 28 206 Density GL 207 Depth GL, 9, 16, 22, 26, 27 208 Dst Destination GL 209 Destroy 11 210 Diffuse GL 211 Dim Dimension GL 212 Direction GL 213 Disable GL, 26 214 List Display List 215 Distance GL, 14 216 Dither GL 217 Dont Do Not GL 218 Domain GL 219 Dot 19 220 Dot3 GL, 19 221 Double GL 222 Doublebuffer GL 223 Draw GL, 9, 11, 28 224 Dynamic 28 225 Edge GL, 28 226 Element GL, 28 227 Emission GL 228 Enable GL, 26 229 Enabled GL 230 End GL 231 Enum Enumerant GL 232 Env Environment GL, 26, 27 233 Equal GL 234 Equation GL 235 Equiv Equivalent GL 236 Error GL, 10, 26, 27 237 Eval Evaluate GL 238 XOR Exclusive OR GL 239 Execute GL 240 Exponent GL 241 Exp Exponential GL 242 Exp2 Exponential Squared GL 243 Extension GL, 5 244 Eye GL 245 Face GL, 20 246 Factor GL 247 Fade GL, 14 248 Fail GL, 24 249 False GL 250 Fan GL 251 Fastest GL 252 Feedback GL 253 Fill GL 254 Filter GL 255 Finish GL 256 First GL 257 Flag GL 258 Flat GL 259 Float GL 260 Flush GL 261 Fog GL, 28 262 Format GL, 9, 12, 20, 26, 27 263 Fragment GL, 27 264 Framebuffer (documentation only) 265 Front GL, 20 266 Frustum GL 267 Func Function GL, 23 268 Gen Generate GL, 26, 27, 28 269 Get GL, 2, 5, 9, 10, 11, 26, 27, 28 270 Granularity GL 271 GL Graphics Library GL 272 Greater GL 273 Gequal Greater than or equal to GL 274 Green GL, 9 275 Grid GL 276 Half GL 277 Height GL, 11 278 Hint GL, 12 279 Histogram GL 280 Identity GL 281 Ignore GL 282 Image GL, 12, 20, 27 283 Incr Increment GL 284 Index 16 285 Indices GL 286 Indirection 27 287 Init Initial GL 288 Init Initialize GL 289 Instruction 26, 27 290 Int (2) Integer GL 291 Intensity GL, 12 292 Interleaved GL 293 Internal GL 294 Interpolate GL, 17 295 Invalid GL, 10 296 Invert GL, 5 297 Inverted GL 298 Is GL, 26, 27, 28 299 Keep GL 300 LSB Least significant bit GL 301 Left GL, 20 302 Length GL, 26, 27 303 Less GL 304 Lequal Less than or equal to GL 305 Level GL, 20 306 LOD Level of Detail GL 307 Light GL 308 Light Model Lighting Model 309 Line GL 310 Linear GL 311 List GL 312 Limit 26, 27 313 Load GL, 3 314 Local GL, 26, 27 315 Logic Op Logical Operation GL 316 Loop GL 317 Luminance GL, 12 318 Mag Magnify GL 319 Make 10 320 Map GL, 7, 20, 28 321 Mapped 3, 28 322 Mask GL 323 Material GL 324 Matrix, Matrices GL, 16, 26, 27 325 Max Maximum GL, 7, 11, 14, 15, 16, 26, 27 326 Memory GL 327 Mesh GL 328 Win Microsoft Windows OS GL 329 Min Minimum GL, 14 330 Minmax Minimum Maximum GL 331 Min Minify GL, 14 332 Minus GL, 17 333 Mirrored GL, 21 334 Mode GL, 22, 23 335 Model GL 336 Modelview GL, 3, 15 337 Modulate GL, 17 338 Mipmap Multim in parvo map GL, 20 339 Multi Multiple GL 340 Mult Multiply GL, 3 341 Multisample GL, 5 342 Name GL 343 Native 26, 27 344 Nearest GL 345 NAND Negated AND GL 346 NOR Negated OR GL 347 Negative GL, 7, 20 348 Nesting GL 349 Never GL 350 New GL 351 Nicest GL 352 No GL, 9, 28 353 Noop No Operation GL 354 None GL 355 N (5) Normal GL, 7, 28 356 Normalize, Normalized GL, 26 357 Notequal GL 358 Num (3) Number Of GL 359 Object GL 360 Of GL 361 Offset GL 362 One GL, 17 363 Only 28 364 Operand GL, 17 365 Op (6) Operation GL 366 Or GL 367 Order GL 368 Ortho Orthographic GL 369 Out GL 370 Overflow GL 371 Pack GL 372 Palette 9, 16 373 Param Parameter GL, 14, 26, 27, 28 374 Pname Parameter Name GL 375 Pass GL 376 Pattern GL 377 Perspective GL 378 Phong GL 379 Pixel GL, 9, 10, 11 380 Pbuffer Pixel Buffer 11, 20 381 Plane GL 382 Point GL, 14, 26 383 Pointer GL, 15, 16, 26, 28 384 Polygon GL 385 Pop GL 386 Position GL 387 Pos (1) Position GL, 25, 26, 27 388 Positive GL, 7, 20 389 Post GL 390 Previous GL, 17 391 Primary GL, 17 392 Prioritize, Priority GL 393 Proc Procedure 2 394 Program 26, 27 395 Projection GL, 3 396 Proxy GL, 7 397 Push GL 398 Quad Quadrilateral GL 399 Quadratic GL 400 Query 11 401 Range GL 402 Raster GL 403 Read GL, 10, 28 404 Rect Rectangle GL 405 Red GL, 9 406 RGB Red Green Blue GL, 12, 17, 19, 20 407 RGBA Red Green Blue Alpha GL, 9, 12, 19, 20 408 Reduce GL 409 Ref Reference GL 410 Reflection GL, 7 411 Region GL, 4 412 Register 26 413 Render GL 414 Renderer GL 415 Repeat GL, 21 416 Replace GL, 17 417 Replicate GL 418 Rescale GL 419 Reset GL 420 Resident GL 421 Return GL 422 Rev (4) Reverse GL 423 Right GL, 20 424 Rotate, Rotated GL 425 Row GL 426 Sample GL, 5 427 Saturate GL 428 Scale, Scaled GL, 17 429 Scissor GL 430 Secondary GL, 28 431 Segment GL 432 Select GL 433 Selection GL 434 Separable GL 435 Separate GL 436 Set (noun only!) GL 437 Shade GL 438 Shade Model Shading Model 439 Shift GL, 9 440 Shininess GL 441 Short GL 442 Side GL, 26 443 Signed GL, 17 444 Single GL 445 Sink GL 446 Size GL, 7, 12, 14, 15, 16, 22, 26, 28 447 Skip GL 448 Smooth GL 449 Src Source GL, 17 450 Specular GL 451 Sphere GL 452 Spot GL 453 Stack GL, 16, 26, 27 454 Start GL 455 State GL 456 Static 28 457 Stencil GL, 9 458 Stereo GL, 9 459 Stipple GL 460 Store GL 461 Stream 28 462 Stride GL, 15, 16, 26 463 String GL, 5, 26, 27 464 Strip GL 465 Sub GL, 12 466 Subtract 17 467 Sub Image 12 468 Subpixel GL 469 Sub Table GL 470 Sum GL, 15, 26 471 Swap GL, 9 472 Table GL 473 Target 20 474 Temporary 26, 27 475 Test GL 476 Tex (1), Texture GL, 3, 7, 12, 17, 18, 20, 22, 23, 477 T(5) 24, 27, 28 478 Threshold GL, 14 479 Through GL 480 To GL, 9, 11, 13, 20, 23 481 Token GL 482 Transfer GL 483 Transform GL 484 Translate, Translated GL 485 Transpose GL, 3, 26, 27 486 Triangle GL 487 True GL 488 Two GL, 26 489 Type GL, 9, 10, 15, 16, 26 490 Under 26, 27 491 Underflow GL 492 Unit GL, 15, 27 493 Unity 15 494 Unmap 28 495 Unpack GL 496 Unsigned GL 497 Ubyte Unsigned Byte GL 498 Uint Unsigned Int GL 499 Ushort Unsigned Short GL 500 Usage 28 501 Valid GL 502 Value GL, 5, 9, 24 503 Vendor GL 504 Version GL 505 V (5) Vertex GL, 15, 26, 28 506 Vertices GL 507 Viewer GL 508 Viewport GL 509 Weight 15, 28 510 Width GL, 11 511 Window GL, 25 512 Wrap GL 513 Write 28 514 Writemask GL 515 Zero GL 516 Zoom GL 517 518 519 520Abbreviations specifically not allowed 521-------------------------------------- 522 Bgn Begin 523 Mat Matrix 524 Pnt Point 525 Poly Polygon 526 Tri Triangle 527 528 529 530Used in WGL specs only (or differently) 531--------------------------------------- 532 533 Abbrev. Term or phrase Specification(s) used in 534 ------- -------------- ------------------------ 535 Acceleration 9 536 Create 4, 11 537 DC ??? 10 538 Declare 11 539 Device 10 540 Exchange 9 541 Full 9 542 Generic 9 543 GDI ??? 9 544 Handle 11 545 HP ??? 11 546 Incompatible 10 547 Largest 11 548 Layer 9 549 Lost 11 550 Method 9 551 Need 9 552 Number Number Of 9 553 OpenGL 9 554 Overlay 9 555 Release 20 556 Restore 4 557 Save 4 558 Share 9 559 Support 9 560 System 9 561 Transparent 9 562 Undefined 9 563 Underlay 9 564 565 566 567Name rules (for all names) 568-------------------------- 569 570 Always use the specified abbreviations. Never abbreviate terms 571 that are already in the OpenGL API and are not abbreviated. If you 572 add terms to your extensions, abbreviate consistently, maintaining 573 a local version of additions to the list of abbreviations. 574 575 Use Depth, never Z. 576 577 The word "object" should not be used in a function name unless it 578 operates on all object types. 579 580 Longer descriptive names are desired if they are believed to help 581 developers identify the purpose of a name. 582 583 The opposite of "create" is "destroy." "delete" marks an object for 584 later destruction. 585 586 All names should describe what functionality does, never its expected 587 usage. 588 589 Begin each word with a capital letter, except the second word of 590 compound words. 591 592 593Procedure name rules 594-------------------- 595 596 Never use set, as in SetFeedbackBuffer. Set is implicit, unless 597 otherwise specified. 598 599 Use Verb-noun (DeleteList) and adjective-noun (EdgeFlag) formats. 600 601 Append a corporate-specific suffix to all procedures. For example: 602 glNewCommandSGI. All upper case is preferred for this suffix, but 603 is not required. The suffix is always last, following OpenGL type 604 and count suffixes. (e.g. glNewVertex3iSGI, not glNewVertexSGI3i.) 605 606 607Definition name rules 608--------------------- 609 610 Use all capital letters. 611 612 Separate words with underscores, except words within compound words. 613 614 Append simple numeric suffixes directly to the end of definition 615 tokens (LIGHT0). Begin these sequences with 0. 616 617 Use an underscore to separate complex suffixes from the token body 618 (MAP_3V). 619 620 Append a corporate-specific suffix to the token, after any other 621 suffixes. For example: GL_NEW_TOKEN0_SGI. All upper case is 622 required. 623 624 All tokens that are used only for a single use should be grouped 625 together using enum types. 626 627 628Parameter name rules 629-------------------- 630 631 <target> is reserved for the notion of "which is affected", and for 632 the corresponding "which is returned" get commands. 633 634 <params> is reserved for an array of parameters whose contents are 635 defined by a second enumerated argument, called <pname>. 636 637 Begin number sequences with 1, not 0. (e.g. u1,u2, not u0,u1) 638 639 Any parameters that contain more then one word should have the 640 second and subsequent words capitalized. 641 642 Long descriptive parameters are encouraged. 643 644 645Parameter order 646--------------- 647 648 <X> precedes <Y> precedes <Z> precedes <W>. 649 650 <R> precedes <G> precedes <B> precedes <A>. 651 652 <S> precedes <T> precedes <R> precedes <Q>. 653 654 <U> precedes <V>. 655 656 The array being passed is always the last argument. 657 658 If a passed array has a type, the type specification argument immediately 659 precedes the array. 660 661 <pname> always precedes <params>. 662 663 <x> and <y> precede <width> and <height>. 664 665 <format> precedes <type>. 666 667 <target> is first. 668 669 <face> is first. 670 671 <object> is first. 672 673 <count> always precedes the thing that it counts. 674 675 Any time the function parameters contain an address of what they 676 operate on, the address is last. 677 678 Arrays are never terminated by NULL or any other termination but are 679 always specified by length. 680 681 For variable length arrays passed into the GL, the parameter list should 682 end with: "sizei count, const void* data" 683 684 For variable length arrays passed back from the GL, the parameter list 685 should end with: "sizei maxCount, sizei* count, void* data" 686 687 688Parameter types 689--------------- 690 691 All integer quantity parameters (widths, heights, array lengths, etc.) 692 should be typed GLsizei, not GLint or GLuint. Note that GLsizei 693 generates an error only for negative values, so all integer quantity 694 parameters should accept the value zero. 695 696 Handles to specific object types are typed as pointers to the corresponding 697 abstract structs. Generic objects are passed around as void pointers. 698 699 Generic masks that do not have explicitly defined bit values (e.g. 700 color index write masks and stencil write masks) should be typed 701 GLuint. GLuint is also used for unsigned integer components, such as 702 color components and depth components. 703 704 Masks that do have explicitly defined bit values (e.g. attribute mask, 705 clear mask) should be typed GLbitfield, not GLuint. 706 707 All floating point parameters that are clamped to the range [0,1] when 708 received should be typed GLclampf or GLclampd, not GLfloat or GLdouble. 709 710 711Extension name rules 712-------------------- 713 714 An extension name is prefixed with the same string that suffixes its 715 procedures and definitions. The prefix and the individual words are 716 separated with underscores, the prefix is all upper case, and the other 717 text is all lower case. For example, extension ARB_cool_feature, which 718 specifies glCoolProcedureARB() and defines GL_COOL_DEFINITION_ARB. 719 720 721Suffix codes 722------------ 723 724 i signed 32-bit integer 725 ui unsigned 32-bit integer 726 s signed 16-bit integer 727 us unsigned 16-bit integer 728 b signed 8-bit integer 729 ub unsigned 8-bit integer 730 l signed 64-bit integer 731 ul unsigned 64-bit integer 732 f 32-bit float 733 d 64-bit float 734 t token enum 735 v vector format 736 N normalize values 737 738 # number of components (e.g. 3) 739 #x# matrix dimensions (e.g. 2x4) 740 741 742Shared extensions 743----------------- 744 745 An OpenGL extension may be deemed a shared extension if either: 746 747 1. Two or more OpenGL licensees agree in good faith to implement 748 and ship the extension, or 749 750 2. The OpenGL ARB determines that it is in the best interest of 751 the licensees that the extension be shared. 752 753 The procedures and definitions that are defined by a shared extension 754 are suffixed with EXT, rather than by a company-specific suffix. 755 Likewise, the extension name is prefixed by EXT. To avoid name 756 conflicts Silicon Graphics will maintain a registry of EXT extensions, 757 including all their procedures and definitions, in a location that is 758 accessible to all licensees. 759