1* Template for specifying an extension to OpenGL, OpenGL ES, 2* and related APIs. 3* 4* Last Modified Date: January 20, 2010 5* Revision: 8 6* 7* Document Source: the OpenGL Extension Registry at 8* 9* http://www.opengl.org/registry/ 10* 11* and the OpenGL ES Extension Registry at 12* 13* http://www.khronos.org/registry/gles/ 14* 15* Notes: 16* 17* Comments in this template document are preceded by an asterisk. 18* This entire section is one big comment. 19* 20* Extension documents are simple fixed-width ASCII text, up to 132 21* characters wide. Here is a line of 132 characters for calibration: 22* 23*00000000011111111112222222222333333333344444444445555555555666666666677777777778888888888999999999900000000001111111111222222222233 24* 25* Lines should end with a hard newline. Do not assume that any 26* special formatting or interpretation will be made by software 27* displaying the specification. 28* 29* Although the extension file is formally 132 characters wide, 30* text is limited to 72 characters, and only tables that require 31* more than 72 character width extend to the full file width. 32* Here is a line of 72 characters for calibration: 33* 34*00000000011111111112222222222333333333344444444445555555555666666666677 35* 36* The extension is completely described by its specification, mostly 37* in the "Additions to <section name>" sections. These sections are 38* written as though the additions described by previous extensions 39* had actually been made to specified portions of the OpenGL, OpenGL 40* ES, OpenGL Shading Language, GLX, EGL, or other Specification 41* documents. 42* 43* The "Dependencies on Extension" sections are used to describe how 44* the extension semantics are modified if a previous extension is not 45* supported, or to indicate that a previous extension must be 46* supported. 47* 48* When changes are made to the contents of a table, new, changed, 49* and removed table entries must be identified. All fields of 50* changed table entires should be included, even if not all fields 51* have changed. 52* 53* An extension specification is always written against given 54* version(s) of Specifications, which must be identified in the 55* Dependencies section. That is, the references and modifications in 56* the extension are applied to that version of the Specification. 57* 58* The latest Khronos-approved version of Specifications should be 59* used when writing an extension. If it is possible for the extension 60* to be used with older versions of a Specification, this should also 61* be described in the Dependencies section. 62* 63* For consistency with OpenGL and ES Specifications, extension 64* documents omit gl prefixes on command names, GL_ prefixes on 65* token names, and GL prefixes on type names. Vendor-specific 66* suffixes are included in these files, however. The terms 67* "GL" and "ES" below should be taken to refer to OpenGL and 68* OpenGL ES, respectively. 69* 70* To be consistent with the GLX Specification, however, extensions 71* defining GLX functionality include glX prefixes on command names 72* and GLX_ prefixes on token names. Similarly, WGL extensions 73* include wgl and WGL_ prefixes on command and token names. 74* 75* An extension document should by preference include all the 76* sections in this template unless a particular section indicates 77* its inclusion is optional. If there is no text in a section, 78* this is indicated by the word "None", such as: 79* 80* Dependencies 81* 82* None 83* 84* While this may appear excessively verbose, the purpose is to ensure 85* that extension authors document all affected parts of Specifications. 86* An exception is that headers for sections of Specifications that 87* are not altered by the extension may be omitted, once the extension 88* has been completed. Thus for example a GLX extension need not 89* retain "Changes to Chapter <N> of the OpenGL 1.X Specification" 90* headers, and an OpenGL extension that does not affect per-vertex 91* processing in any way need not retain "Changes to Chapter 2...". 92* 93* Lower-case or numeric subscripts of upper-case variables are 94* simply appended to the variable. For example "R subscript t" 95* is written as Rt. If it is not easy to distinguish the variable 96* from the subscript, an underbar is used to separate them. For 97* example, "R subscript T" is written as R_T. 98* 99* Multiplication is indicated with an asterisk, not by adjacency 100* of two variables. 101* 102* In text, parameter names are distinguished by being surrounded 103* with angle brackets. For example, the pname parameter to 104* TexParameter is written as <pname>. 105* 106* Math symbols (such as the 'tau', 'lambda', and 'rho' defined 107* by the texturing section) should be completely written out 108* in ASCII as described, rather than assuming a non-ASCII 109* character set. 110* 111* The template proper follows. 112 113************************************************************************ 114 115Name 116 117 * The formal name of the extension. The prefix of the name is a 118 * vendor-specific tag. This is a short, capitalized string unique 119 * to that vendor, such as "SGI" and "IBM" for those respective 120 * companies. The prefix may also be "EXT" is two or more vendors 121 * have agreed to support the extension, "ARB" if the OpenGL ARB 122 * Working Group has voted to approve the extension, "OES" is the 123 * OpenGL ES Working Group has voted to approve the extension, 124 * and "KHR" if the EGL Working Group has voted to approve 125 * the extension. 126 * 127 * Some vendors use an additional convention where the vendor 128 * tag may be followed by "S" to indicate an extension 129 * only supported on a subset of their supported platforms, 130 * and may be followed by an "X" to indicate an experimental 131 * extension, which may be changed or withdrawn in the future. 132 * 133 * The prefix is separated from the body of the name by an 134 * underscore. Words within the name are also separated by 135 * underscores. There is no capitalization used in the body of the 136 * name. For example: 137 138 * Name 139 * 140 * SGI_new_extension 141 142Name Strings 143 144 * Extensions may apply to several different APIs, and extension 145 * names are prefixed accordingly. The possible categories are: 146 * 147 * Extension of String query function Name prefixed by 148 * ------------ --------------------- ---------------- 149 * GL and/or ES glGetString GL_ 150 * GLU gluGetString GLU_ 151 * GLX glXQueryExtensionsString GLX_ 152 * EGL eglQueryString EGL_ 153 * WGL glGetString, WGL_ 154 * wglGetExtensionsStringEXT(*) 155 * AGL ??? ???_ 156 * 157 * (*) Note: WGL extension strings are returned by both glGetString 158 * and (if the WGL_EXT_extensions_string extension is supported) by 159 * wglGetExtensionsStringEXT. 160 * 161 * For example, an SGI-specific extension which adds entry points to 162 * both GLX and OpenGL would be listed as: 163 164 * Name Strings 165 * 166 * GL_SGI_new_extension 167 * GLX_SGI_new_extension 168 169 * A multivendor extension which adds an entry point to WGL would be 170 * listed as: 171 172 * Name Strings 173 * 174 * WGL_EXT_new_extension 175 176 * The name strings are included in header files, and are returned 177 * by the string query functions as shown in the table above. 178 * In most cases the Name String is simply the Name prefixed 179 * by the relevant API. 180 181Contact 182 183 * Name, company, and email address of people responsible for the 184 * extension. We suggest using 'at' instead of '@' in email 185 * addresses, to help prevent spam. For multivendor extensions, 186 * contacts from each vendor supporting the extension are preferred. 187 * A backup contact, in case the principal moves on, will be 188 * helpful. Example: 189 190 * Contact 191 * 192 * Jon Leech, Khronos (jon 'at' alumni.caltech.edu) 193 194Contributors 195 196 * Name and company of other people who helped develop the 197 * extension. Credit may be given to an entire Working 198 * Group if contributions are too diffuse. 199 200 * Contributors 201 * Members of the Khronos ARB-ES Convergence TSG 202 203Status 204 205 * If the specification is incomplete, the Status section should 206 * be something like 207 * 208 * XXX - Not complete yet. Do not ship!!! 209 * 210 * to indicate that nobody should ship the extension in its 211 * current, unfinished state. Once it is complete, Status should be 212 * changed to "Complete". For extensions approved by Khronos, this 213 * should be extended to note when the extension was approved by 214 * the relevant Working Group(s) and by the Khronos Promoters. 215 * 216 * Once the extension ships, its status should be changed to 217 * indicate this, as well as what the version number at shipping 218 * time is. Finally, if an extension is withdrawn (or never shipped 219 * due to e.g. cancellation of a product), it should be marked 220 * obsolete. Examples: 221 222 * Status 223 * 224 * XXX - Not complete yet!!! 225 226 * Status 227 * 228 * Complete. Approved by the Khronos Promoters on April 1, 2009. 229 230 * Status 231 * 232 * Shipping (version Major.minor) 233 234 * Status 235 * 236 * Obsolete 237 238Version 239 240 * It's hard to generate good version numbers with version control 241 * systems, since extension specs may live in many different source 242 * trees. We now suggest including a manually-inserted date of last 243 * modification and version number. These should be updated only 244 * for meaningful changes to the extension, not just formatting. 245 246 * Version 247 * 248 * Last Modified Date: January 20, 2010 249 * Revision: 8 250 251 * If you do not include a date and version number when submitting 252 * an extension to the registry, Khronos will generate one based on 253 * the date the specification was received. 254 255Number 256 257 * Extensions are numbered for documentation purposes. Each 258 * extension should document its interactions with the core 259 * Specification and with all other extensions (that are also 260 * supported by the vendors shipping this extension) that have lower 261 * numbers. For example, extension 3 should document its interactions 262 * with the core document and (if any) with extensions 1 and 2. 263 * 264 * The extension number has no meaning outside of the documentation. 265 * In particular, it is not revealed to programmers who use OpenGL. 266 * Extension numbers are assigned by Khronos when an extension is 267 * submitted to the registry. 268 * 269 * ARB and ES extensions follow separate numbering schemes from 270 * vendor extensions. If an extension can be implemented against 271 * both GL and ES, assign numbers from both registries. 272 273 Examples: 274 275 * Number 276 * 277 * 12 278 279 * Number 280 * 281 * ARB Extension #12 282 283 * Number 284 * 285 * ARB Extension #23 286 * OpenGL ES Extension #17 287 288Dependencies 289 290 * List the oldest version of GL, ES, OpenGL Shading Language, GLX, 291 * etc.) against which this extension can be implemented, as well 292 * as the version and, if relevant, profile against which the 293 * extension is written. Because specifications can be revised 294 * after their initial release, affecting page and table numbering, 295 * also include the release date of the specifications. It is 296 * usually best to write the extension against the current 297 * versions of Specifications even if it can be successfully 298 * implemented against older versions). 299 * 300 * Separately list all API profiles and extensions that must be 301 * present for this extension to be implemented, and all extensions 302 * whose presence or absence modifies the operation of this 303 * extension. 304 * 305 * If an extension can be implemented against both GL and ES, 306 * document both requirements, and note if their are any 307 * functionality differences (typically an extension which 308 * works with both GL and ES will not support interactions 309 * with GL features not present in ES in the ES version, but 310 * it is still valuable to have a common extension spec). 311 312 * Dependencies 313 * OpenGL 3.2 (either core or compatibility profiles) is 314 * required. 315 * 316 * This extension is written against the OpenGL 3.2 317 * (Core Profile) Specification (August 3, 2009). 318 319 * Dependencies 320 * OpenGL 2.0 or OpenGL ES 2.0 are required. 321 * 322 * Some of the functionality of this extension is not supported 323 * when implemented against OpenGL ES 2.0. 324 * 325 * This extension is written against the OpenGL 2.0 326 * Specification (October 22, 2004). 327 328 * Dependencies 329 * OpenGL 1.2 is required. 330 * 331 * ARB_texture_float affects the definition of this extension. 332 * 333 * This extension is written against the OpenGL 2.1 334 * Specification (May 16, 2008). 335 336Overview 337 338 * What does the extension do? What problem does it solve? This 339 * can include background and rationale (unlike the specification 340 * language proper). A common format is a single sentence 341 * summarizing the extension, followed by greater levels of detail 342 * which will help people understand the extension. Note that the 343 * GL Specification explicitly does not include rationale, so the 344 * overview is a good place to put it instead. 345 346IP Status 347 348 * Document any known patents or other IP claims that may prohibit 349 * royalty-free implementation of an extension, or impose other 350 * constraints on implementations. It is better to write "No 351 * known IP claims" rather than "None", since Khronos, or the 352 * vendor for vendor extensions, may not know of relevant IP. 353 * 354 * Examples: 355 356 * IP Status 357 * 358 * ReallyBigCo has made unspecified IP claims against 359 * all implementations of this extension. 360 361 * IP Status 362 * 363 * US Patent #7,654,321, owned by ReallyBigCo, may 364 * be infringed by implementations of this extension. 365 366 * (note: extensions which have been approved by the Khronos 367 * Promoters fall under the Khronos IP agreements, which 368 * offer mutual protections to the members who implement 369 * such extensions). 370 371 * IP Status 372 * 373 * No known IP claims. 374 375New Procedures and Functions 376 377 * List all the procedures and functions that are defined by this 378 * extension. Each should be suffixed using the same string as was 379 * chosen as the extension name prefix. All parameter names and 380 * types must be included, including the return values of functions. 381 * Follow the style used in the appropriate Specifications. 382 * Example: 383 384 * New Procedures and Functions 385 * 386 * void NewCommandEXT(int arg1, float arg2); 387 388New Types 389 390 * List all new GL types defined by this extension. Include enough 391 * information to define a common underlying C-language binding 392 * definition on a per-architecture basis. For example, instead 393 * of saying "GLhandleARB", say: 394 395 * New Types 396 * 397 * typedef unsigned int GLhandleARB; 398 399New Tokens 400 401 * This list should be complete. It should separate the new tokens 402 * based on which procedures and parameters accept them, and 403 * explicitly list those procedures and parameters. Token suffixes 404 * must match the prefix chosen for the extension name. If 405 * enumerant values have been assigned, include them; otherwise 406 * list the values as "0x????". For example: 407 408 * New Tokens 409 * 410 * Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 411 * GetInteger64v, GetFloatv, and GetDoublev: 412 * 413 * NEW_TOKEN_EXT 0x6042 414 * ANOTHER_TOKEN_EXT 0x???? 415 416* Now, for each section of the relevant Specification (GL, ES, GLX, 417* EGL, etc.), show in detail all changes to the Specification 418* document required to completely describe this extension. Changes 419* should be written in the style of the specifications and should be 420* phrased as changes to specific, identifiable parts of the document. 421* In each section heading, include the version of the specification 422* being modified. If an extension is being written against both GL 423* and ES, it is usually best to show changes against the GL 424* Specification, then summarize differences when implemented with 425* ES in a "Dependencies" section following the changes (see below). 426 427Additions to Chapter 2 of the OpenGL 3.2 (Core Profile) Specification 428(OpenGL Operation) 429 430 * Include any new command suffixes here (section 2.3) 431 * Include any new error types here (section 2.5) 432 433Additions to Chapter 3 of the OpenGL 3.2 (Core Profile) Specification 434(Rasterization) 435 436Additions to Chapter 4 of the OpenGL 3.2 (Core Profile) Specification 437(Per-Fragment Operations and the Frame Buffer) 438 439Additions to Chapter 5 of the OpenGL 3.2 (Core Profile) Specification 440(Special Functions) 441 442 * List commands that are not included in display lists 443 * (typically, Get* commands) 444 445Additions to Chapter 6 of the OpenGL 3.2 (Core Profile) Specification 446(State and State Requests) 447 448 * The lists of state and implementation-dependent state are added 449 * in the "New State" section. Add queries and new attributes here. 450 451Additions to Appendix A of the OpenGL 3.2 (Core Profile) Specification 452(Invariance) 453 454 * If the utility of the extension would be increased by 455 * specification of invariance relationships, note that here. 456 457Additions to Appendix D of the OpenGL 3.2 (Core Profile) Specification 458(Shared Objects and Multiple Contexts) 459 460 * If object sharing behavior is affected by the extension, 461 * describe that in the set of sharing rules in this section. 462 463************************************************************************ 464 465* If this is an OpenGL Shading Language extension, include a separate 466* section for each affected chapter of the 1.50 (or specified version) 467* Specification. 468 469Additions to Chapter 1 of the OpenGL Shading Language 1.50 Specification 470(Introduction) 471 472Additions to Chapter 2 of the OpenGL Shading Language 1.50 Specification 473(Overview of OpenGL Shading) 474 475Additions to Chapter 3 of the OpenGL Shading Language 1.50 Specification 476(Basics) 477 478Additions to Chapter 4 of the OpenGL Shading Language 1.50 Specification 479(Variables and Types) 480 481Additions to Chapter 5 of the OpenGL Shading Language 1.50 Specification 482(Operators and Expressions) 483 484Additions to Chapter 6 of the OpenGL Shading Language 1.50 Specification 485(Statements and Structure) 486 487Additions to Chapter 7 of the OpenGL Shading Language 1.50 Specification 488(Built-in Variables) 489 490Additions to Chapter 8 of the OpenGL Shading Language 1.50 Specification 491(Built-in Functions) 492 493Additions to Chapter 9 of the OpenGL Shading Language 1.50 Specification 494(Shading Language Grammar) 495 496Additions to Chapter 10 of the OpenGL Shading Language 1.50 Specification 497(Issues) 498 499************************************************************************ 500 501* If none of the window-system integration APIs are affected by 502* this extension, indicate this by 503 504Additions to the AGL/EGL/GLX/WGL Specifications 505 506 None 507 508* Otherwise, for a WGL or AGL extension, include a description of how 509* the extension affects those APIs. WGL and AGL don't have spec 510* documents, but we still phrase these sections as "Changes to the 511* Specification" in anticipation of specifications being written. 512 513Additions to the WGL Specification 514 515Additions to the AGL Specification 516 517************************************************************************ 518 519* For a GLX extension (since GLX has a formal Specification), 520* include a separate section for each affected chapter of 521* the GLX Specification: 522 523Additions to Chapter 1 of the GLX 1.4 Specification (Overview) 524 525Additions to Chapter 2 of the GLX 1.4 Specification (GLX Operation) 526 527Additions to Chapter 3 of the GLX 1.4 Specification 528(Functions and Errors) 529 530Additions to Chapter 4 of the GLX 1.4 Specification 531(Encoding on the X Byte Stream) 532 533Additions to Chapter 5 of the GLX 1.4 Specification (Extending OpenGL) 534 535Additions to Chapter 6 of the GLX 1.4 Specification (GLX Versions) 536 537************************************************************************ 538 539* Likewise for an EGL extension. 540 541Additions to Chapter 1 of the EGL 1.4 Specification (Overview) 542 543Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) 544 545Additions to Chapter 3 of the EGL 1.4 Specification 546(EGL Functions and Errors) 547 548Additions to Chapter 4 of the EGL 1.4 Specification (Extending EGL) 549 550Additions to Chapter 5 of the EGL 1.4 Specification 551(EGL Versions and Enumerants) 552 553Additions to Chapter 6 of the EGL 1.4 Specification (Glossary) 554 555************************************************************************ 556 557* For an extension of any type which is to be supported by GLX indirect 558* rendering, include additions to the GLX Protocol Specification. 559 560GLX Protocol 561 562 * Add protocol here using the same format as the GLX protocol 563 * document. Be sure to specify the values of enumerated types. 564 * 565 * Use glXVendorPrivate for extended requests without a reply 566 * (e.g., new GLX commands) : 567 * glXVendorPrivate 568 * 569 * 1 CARD8 opcode (X assigned) 570 * 1 16 GLX opcode 571 * 2 2+(n+p)/4 request length 572 * 4 CARD32 vendor-specific opcode 573 * n LISTofBYTE vendor-specific data 574 * p unused, p=pad(n) 575 * 576 * Make sure to reserve a vendor-specific opcode by request from 577 * Khronos (just as enumerant values are assigned on request), then 578 * define the layout of the vendor-specific data. 579 * 580 * Use glXVendorPrivateWithReply for extended requests with a reply 581 * (e.g., new gets for OpenGL): 582 * 583 * glXVendorPrivateWithReply 584 * 585 * 1 CARD8 opcode (X assigned) 586 * 1 17 GLX opcode 587 * 2 2+(n+p)/4 request length 588 * 4 CARD32 vendor-specific opcode 589 * n LISTofBYTE vendor-specific data 590 * p unused, p=pad(n) 591 * => 592 * 1 1 reply 593 * 1 unused 594 * 2 CARD16 sequence number 595 * 4 n reply length 596 * 24 LISTofBYTE returned data 597 * 4*n LISTofBYTE more returned data 598 * 599 * This is similar to glXVendorPrivate except you also need to 600 * define the layout of the returned data. 601 * 602 * For extended OpenGL commands, be sure to specify whether it is a 603 * rendering command or a non-rendering command, and if it is a 604 * rendering command, whether or not it can be large. 605 * 606 * To specify an extended visual attribute, specify a property 607 * type/property value pair to use with glXGetVisualConfigs. 608 609 ******************************************************************** 610 611Dependencies on GL and ES profiles, versions, and other extensions 612 613 * Separately list each interaction which affects the behavior 614 * of this extension depending on which other extensions 615 * are present or on which version of Specifications this 616 * extension is implemented against. Examples: 617 618 * Dependencies on ARB_texture_float 619 * 620 * If ARB_texture_float is not supported, then 621 * delete all references to the R*F* pixel formats. 622 623 * Dependencies on OpenGL ES 624 * 625 * If implemented for OpenGL ES, this extension 626 * behaves as specified, except: 627 * 628 * - Ignore all references to display lists and 629 * immediate mode, including changes to section 5.4. 630 * - Ignore all references to GLX and GLX Protocol. 631 632Errors 633 634 * This list summarizes all possible errors generated by the 635 * extension and should be complete (however, errors are best 636 * described in the extension body text as well). 637 638New State 639 640 * Include modifications to the state tables in chapter 6 of the 641 * GL and/or ES Specifications (other Specifications do not 642 * have state tables). For each affected table, identify the 643 * table and describe all new or modified state values in the 644 * format of that table. Client state (for e.g. vertex arrays or 645 * pixel packing parameters) should have "client" listed in the 646 * Attribute column. Example: 647 648 * Changes to table 6.99, p. 516 (Funky Geometry State) 649 * 650 * Initial 651 * Get Value Type Get Command Value Description Sec. Attribute 652 * --------- ---- ----------- ------- ----------- ---- --------- 653 * RADIUS R GetFloatv 1.0 Disk radius 2.6 vertex 654 655New Implementation Dependent State 656 657 * Describe all implementation dependent state in the same 658 * fashion. Example: 659 660 * (Changes to table 6.100, p. 518 (Implementation-Dependent State) 661 * 662 * Minimum 663 * Get Value Type Get Command Value Description Sec. Attribute 664 * --------- ---- ----------- ------- ----------- ---- --------- 665 * MAX_DISKS Z+ GetIntegerv 1000 Max. # of 2.5 - 666 * disks. 667 668Sample Code 669 670 * For complex extensions, it may be worthwhile to include 671 * code samples of how to use the extension. 672 673Conformance Tests 674 675 * If a conformance test is defined for the extension, 676 * summarize its basic purpose, if not necessarily its 677 * source code, here. If no test has been defined, note that 678 * they are needed. 679 680Issues 681 682 * List remaining open issues, or closed issues whose resolution 683 * set a precedent or was otherwise especially interesting. 684 * Briefly describe each issue, options considered, the choice 685 * made, and the reason for that choice. The Issues section 686 * documents motivation, rationale, etc. while not being a 687 * normative part of the extension. We suggest a numerically 688 * order list so that issues can refer to other issues. 689 * 690 * We now recommend placing the Issues list near the end of 691 * the extension, since it can grow very long yet is ancillary 692 * to the specification itself. 693 694Revision History 695 696 * Include important changes in the evolution of the extension. 697 * It's especially important to include this section if the 698 * extension is modified after a version has been shipped. 699 * 700 * Example (and actual revision history of the template): 701 702* Revision 8, 2010/01/20 703* - Minor updates for completeness and consistency. Push updated 704* template to the public Registry. 705* Revision 7, 2009/12/07 706* - Generalize template to allow for ES and GL extensions 707* and change references from SGI to Khronos as the 708* Registry owner. 709* Revision 6, 2006/10/09 710* - Move registry URL to www.opengl.org. 711* Revision 5, 2004/06/22 712* - Update template to allow OpenGL Shading Language and EGL 713* extensions. Add "Sample Code" section. Include more examples 714* under "IP Status". Add the template's revision history. 715* Add state table examples. Cleanup overall formatting to make 716* clear what are the section headers which must be present, 717* in contrast to the examples which are just part of this 718* template. Add document source URL. 719* Revision 4, 2003/12/19 720* - Add "New Types" section. 721* Revision 3, 2000/04/26 722* - Add "Author Revision" field to Version section, instead of 723* relying on source code control versions. 724