* Template for specifying an extension to OpenGL, OpenGL ES, * and related APIs. * * Last Modified Date: January 20, 2010 * Revision: 8 * * Document Source: the OpenGL Extension Registry at * * http://www.opengl.org/registry/ * * and the OpenGL ES Extension Registry at * * http://www.khronos.org/registry/gles/ * * Notes: * * Comments in this template document are preceded by an asterisk. * This entire section is one big comment. * * Extension documents are simple fixed-width ASCII text, up to 132 * characters wide. Here is a line of 132 characters for calibration: * *00000000011111111112222222222333333333344444444445555555555666666666677777777778888888888999999999900000000001111111111222222222233 * * Lines should end with a hard newline. Do not assume that any * special formatting or interpretation will be made by software * displaying the specification. * * Although the extension file is formally 132 characters wide, * text is limited to 72 characters, and only tables that require * more than 72 character width extend to the full file width. * Here is a line of 72 characters for calibration: * *00000000011111111112222222222333333333344444444445555555555666666666677 * * The extension is completely described by its specification, mostly * in the "Additions to
" sections. These sections are * written as though the additions described by previous extensions * had actually been made to specified portions of the OpenGL, OpenGL * ES, OpenGL Shading Language, GLX, EGL, or other Specification * documents. * * The "Dependencies on Extension" sections are used to describe how * the extension semantics are modified if a previous extension is not * supported, or to indicate that a previous extension must be * supported. * * When changes are made to the contents of a table, new, changed, * and removed table entries must be identified. All fields of * changed table entires should be included, even if not all fields * have changed. * * An extension specification is always written against given * version(s) of Specifications, which must be identified in the * Dependencies section. That is, the references and modifications in * the extension are applied to that version of the Specification. * * The latest Khronos-approved version of Specifications should be * used when writing an extension. If it is possible for the extension * to be used with older versions of a Specification, this should also * be described in the Dependencies section. * * For consistency with OpenGL and ES Specifications, extension * documents omit gl prefixes on command names, GL_ prefixes on * token names, and GL prefixes on type names. Vendor-specific * suffixes are included in these files, however. The terms * "GL" and "ES" below should be taken to refer to OpenGL and * OpenGL ES, respectively. * * To be consistent with the GLX Specification, however, extensions * defining GLX functionality include glX prefixes on command names * and GLX_ prefixes on token names. Similarly, WGL extensions * include wgl and WGL_ prefixes on command and token names. * * An extension document should by preference include all the * sections in this template unless a particular section indicates * its inclusion is optional. If there is no text in a section, * this is indicated by the word "None", such as: * * Dependencies * * None * * While this may appear excessively verbose, the purpose is to ensure * that extension authors document all affected parts of Specifications. * An exception is that headers for sections of Specifications that * are not altered by the extension may be omitted, once the extension * has been completed. Thus for example a GLX extension need not * retain "Changes to Chapter of the OpenGL 1.X Specification" * headers, and an OpenGL extension that does not affect per-vertex * processing in any way need not retain "Changes to Chapter 2...". * * Lower-case or numeric subscripts of upper-case variables are * simply appended to the variable. For example "R subscript t" * is written as Rt. If it is not easy to distinguish the variable * from the subscript, an underbar is used to separate them. For * example, "R subscript T" is written as R_T. * * Multiplication is indicated with an asterisk, not by adjacency * of two variables. * * In text, parameter names are distinguished by being surrounded * with angle brackets. For example, the pname parameter to * TexParameter is written as . * * Math symbols (such as the 'tau', 'lambda', and 'rho' defined * by the texturing section) should be completely written out * in ASCII as described, rather than assuming a non-ASCII * character set. * * The template proper follows. ************************************************************************ Name * The formal name of the extension. The prefix of the name is a * vendor-specific tag. This is a short, capitalized string unique * to that vendor, such as "SGI" and "IBM" for those respective * companies. The prefix may also be "EXT" is two or more vendors * have agreed to support the extension, "ARB" if the OpenGL ARB * Working Group has voted to approve the extension, "OES" is the * OpenGL ES Working Group has voted to approve the extension, * and "KHR" if the EGL Working Group has voted to approve * the extension. * * Some vendors use an additional convention where the vendor * tag may be followed by "S" to indicate an extension * only supported on a subset of their supported platforms, * and may be followed by an "X" to indicate an experimental * extension, which may be changed or withdrawn in the future. * * The prefix is separated from the body of the name by an * underscore. Words within the name are also separated by * underscores. There is no capitalization used in the body of the * name. For example: * Name * * SGI_new_extension Name Strings * Extensions may apply to several different APIs, and extension * names are prefixed accordingly. The possible categories are: * * Extension of String query function Name prefixed by * ------------ --------------------- ---------------- * GL and/or ES glGetString GL_ * GLU gluGetString GLU_ * GLX glXQueryExtensionsString GLX_ * EGL eglQueryString EGL_ * WGL glGetString, WGL_ * wglGetExtensionsStringEXT(*) * AGL ??? ???_ * * (*) Note: WGL extension strings are returned by both glGetString * and (if the WGL_EXT_extensions_string extension is supported) by * wglGetExtensionsStringEXT. * * For example, an SGI-specific extension which adds entry points to * both GLX and OpenGL would be listed as: * Name Strings * * GL_SGI_new_extension * GLX_SGI_new_extension * A multivendor extension which adds an entry point to WGL would be * listed as: * Name Strings * * WGL_EXT_new_extension * The name strings are included in header files, and are returned * by the string query functions as shown in the table above. * In most cases the Name String is simply the Name prefixed * by the relevant API. Contact * Name, company, and email address of people responsible for the * extension. We suggest using 'at' instead of '@' in email * addresses, to help prevent spam. For multivendor extensions, * contacts from each vendor supporting the extension are preferred. * A backup contact, in case the principal moves on, will be * helpful. Example: * Contact * * Jon Leech, Khronos (jon 'at' alumni.caltech.edu) Contributors * Name and company of other people who helped develop the * extension. Credit may be given to an entire Working * Group if contributions are too diffuse. * Contributors * Members of the Khronos ARB-ES Convergence TSG Status * If the specification is incomplete, the Status section should * be something like * * XXX - Not complete yet. Do not ship!!! * * to indicate that nobody should ship the extension in its * current, unfinished state. Once it is complete, Status should be * changed to "Complete". For extensions approved by Khronos, this * should be extended to note when the extension was approved by * the relevant Working Group(s) and by the Khronos Promoters. * * Once the extension ships, its status should be changed to * indicate this, as well as what the version number at shipping * time is. Finally, if an extension is withdrawn (or never shipped * due to e.g. cancellation of a product), it should be marked * obsolete. Examples: * Status * * XXX - Not complete yet!!! * Status * * Complete. Approved by the Khronos Promoters on April 1, 2009. * Status * * Shipping (version Major.minor) * Status * * Obsolete Version * It's hard to generate good version numbers with version control * systems, since extension specs may live in many different source * trees. We now suggest including a manually-inserted date of last * modification and version number. These should be updated only * for meaningful changes to the extension, not just formatting. * Version * * Last Modified Date: January 20, 2010 * Revision: 8 * If you do not include a date and version number when submitting * an extension to the registry, Khronos will generate one based on * the date the specification was received. Number * Extensions are numbered for documentation purposes. Each * extension should document its interactions with the core * Specification and with all other extensions (that are also * supported by the vendors shipping this extension) that have lower * numbers. For example, extension 3 should document its interactions * with the core document and (if any) with extensions 1 and 2. * * The extension number has no meaning outside of the documentation. * In particular, it is not revealed to programmers who use OpenGL. * Extension numbers are assigned by Khronos when an extension is * submitted to the registry. * * ARB and ES extensions follow separate numbering schemes from * vendor extensions. If an extension can be implemented against * both GL and ES, assign numbers from both registries. Examples: * Number * * 12 * Number * * ARB Extension #12 * Number * * ARB Extension #23 * OpenGL ES Extension #17 Dependencies * List the oldest version of GL, ES, OpenGL Shading Language, GLX, * etc.) against which this extension can be implemented, as well * as the version and, if relevant, profile against which the * extension is written. Because specifications can be revised * after their initial release, affecting page and table numbering, * also include the release date of the specifications. It is * usually best to write the extension against the current * versions of Specifications even if it can be successfully * implemented against older versions). * * Separately list all API profiles and extensions that must be * present for this extension to be implemented, and all extensions * whose presence or absence modifies the operation of this * extension. * * If an extension can be implemented against both GL and ES, * document both requirements, and note if their are any * functionality differences (typically an extension which * works with both GL and ES will not support interactions * with GL features not present in ES in the ES version, but * it is still valuable to have a common extension spec). * Dependencies * OpenGL 3.2 (either core or compatibility profiles) is * required. * * This extension is written against the OpenGL 3.2 * (Core Profile) Specification (August 3, 2009). * Dependencies * OpenGL 2.0 or OpenGL ES 2.0 are required. * * Some of the functionality of this extension is not supported * when implemented against OpenGL ES 2.0. * * This extension is written against the OpenGL 2.0 * Specification (October 22, 2004). * Dependencies * OpenGL 1.2 is required. * * ARB_texture_float affects the definition of this extension. * * This extension is written against the OpenGL 2.1 * Specification (May 16, 2008). Overview * What does the extension do? What problem does it solve? This * can include background and rationale (unlike the specification * language proper). A common format is a single sentence * summarizing the extension, followed by greater levels of detail * which will help people understand the extension. Note that the * GL Specification explicitly does not include rationale, so the * overview is a good place to put it instead. IP Status * Document any known patents or other IP claims that may prohibit * royalty-free implementation of an extension, or impose other * constraints on implementations. It is better to write "No * known IP claims" rather than "None", since Khronos, or the * vendor for vendor extensions, may not know of relevant IP. * * Examples: * IP Status * * ReallyBigCo has made unspecified IP claims against * all implementations of this extension. * IP Status * * US Patent #7,654,321, owned by ReallyBigCo, may * be infringed by implementations of this extension. * (note: extensions which have been approved by the Khronos * Promoters fall under the Khronos IP agreements, which * offer mutual protections to the members who implement * such extensions). * IP Status * * No known IP claims. New Procedures and Functions * List all the procedures and functions that are defined by this * extension. Each should be suffixed using the same string as was * chosen as the extension name prefix. All parameter names and * types must be included, including the return values of functions. * Follow the style used in the appropriate Specifications. * Example: * New Procedures and Functions * * void NewCommandEXT(int arg1, float arg2); New Types * List all new GL types defined by this extension. Include enough * information to define a common underlying C-language binding * definition on a per-architecture basis. For example, instead * of saying "GLhandleARB", say: * New Types * * typedef unsigned int GLhandleARB; New Tokens * This list should be complete. It should separate the new tokens * based on which procedures and parameters accept them, and * explicitly list those procedures and parameters. Token suffixes * must match the prefix chosen for the extension name. If * enumerant values have been assigned, include them; otherwise * list the values as "0x????". For example: * New Tokens * * Accepted by the parameters of GetBooleanv, GetIntegerv, * GetInteger64v, GetFloatv, and GetDoublev: * * NEW_TOKEN_EXT 0x6042 * ANOTHER_TOKEN_EXT 0x???? * Now, for each section of the relevant Specification (GL, ES, GLX, * EGL, etc.), show in detail all changes to the Specification * document required to completely describe this extension. Changes * should be written in the style of the specifications and should be * phrased as changes to specific, identifiable parts of the document. * In each section heading, include the version of the specification * being modified. If an extension is being written against both GL * and ES, it is usually best to show changes against the GL * Specification, then summarize differences when implemented with * ES in a "Dependencies" section following the changes (see below). Additions to Chapter 2 of the OpenGL 3.2 (Core Profile) Specification (OpenGL Operation) * Include any new command suffixes here (section 2.3) * Include any new error types here (section 2.5) Additions to Chapter 3 of the OpenGL 3.2 (Core Profile) Specification (Rasterization) Additions to Chapter 4 of the OpenGL 3.2 (Core Profile) Specification (Per-Fragment Operations and the Frame Buffer) Additions to Chapter 5 of the OpenGL 3.2 (Core Profile) Specification (Special Functions) * List commands that are not included in display lists * (typically, Get* commands) Additions to Chapter 6 of the OpenGL 3.2 (Core Profile) Specification (State and State Requests) * The lists of state and implementation-dependent state are added * in the "New State" section. Add queries and new attributes here. Additions to Appendix A of the OpenGL 3.2 (Core Profile) Specification (Invariance) * If the utility of the extension would be increased by * specification of invariance relationships, note that here. Additions to Appendix D of the OpenGL 3.2 (Core Profile) Specification (Shared Objects and Multiple Contexts) * If object sharing behavior is affected by the extension, * describe that in the set of sharing rules in this section. ************************************************************************ * If this is an OpenGL Shading Language extension, include a separate * section for each affected chapter of the 1.50 (or specified version) * Specification. Additions to Chapter 1 of the OpenGL Shading Language 1.50 Specification (Introduction) Additions to Chapter 2 of the OpenGL Shading Language 1.50 Specification (Overview of OpenGL Shading) Additions to Chapter 3 of the OpenGL Shading Language 1.50 Specification (Basics) Additions to Chapter 4 of the OpenGL Shading Language 1.50 Specification (Variables and Types) Additions to Chapter 5 of the OpenGL Shading Language 1.50 Specification (Operators and Expressions) Additions to Chapter 6 of the OpenGL Shading Language 1.50 Specification (Statements and Structure) Additions to Chapter 7 of the OpenGL Shading Language 1.50 Specification (Built-in Variables) Additions to Chapter 8 of the OpenGL Shading Language 1.50 Specification (Built-in Functions) Additions to Chapter 9 of the OpenGL Shading Language 1.50 Specification (Shading Language Grammar) Additions to Chapter 10 of the OpenGL Shading Language 1.50 Specification (Issues) ************************************************************************ * If none of the window-system integration APIs are affected by * this extension, indicate this by Additions to the AGL/EGL/GLX/WGL Specifications None * Otherwise, for a WGL or AGL extension, include a description of how * the extension affects those APIs. WGL and AGL don't have spec * documents, but we still phrase these sections as "Changes to the * Specification" in anticipation of specifications being written. Additions to the WGL Specification Additions to the AGL Specification ************************************************************************ * For a GLX extension (since GLX has a formal Specification), * include a separate section for each affected chapter of * the GLX Specification: Additions to Chapter 1 of the GLX 1.4 Specification (Overview) Additions to Chapter 2 of the GLX 1.4 Specification (GLX Operation) Additions to Chapter 3 of the GLX 1.4 Specification (Functions and Errors) Additions to Chapter 4 of the GLX 1.4 Specification (Encoding on the X Byte Stream) Additions to Chapter 5 of the GLX 1.4 Specification (Extending OpenGL) Additions to Chapter 6 of the GLX 1.4 Specification (GLX Versions) ************************************************************************ * Likewise for an EGL extension. Additions to Chapter 1 of the EGL 1.4 Specification (Overview) Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation) Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors) Additions to Chapter 4 of the EGL 1.4 Specification (Extending EGL) Additions to Chapter 5 of the EGL 1.4 Specification (EGL Versions and Enumerants) Additions to Chapter 6 of the EGL 1.4 Specification (Glossary) ************************************************************************ * For an extension of any type which is to be supported by GLX indirect * rendering, include additions to the GLX Protocol Specification. GLX Protocol * Add protocol here using the same format as the GLX protocol * document. Be sure to specify the values of enumerated types. * * Use glXVendorPrivate for extended requests without a reply * (e.g., new GLX commands) : * glXVendorPrivate * * 1 CARD8 opcode (X assigned) * 1 16 GLX opcode * 2 2+(n+p)/4 request length * 4 CARD32 vendor-specific opcode * n LISTofBYTE vendor-specific data * p unused, p=pad(n) * * Make sure to reserve a vendor-specific opcode by request from * Khronos (just as enumerant values are assigned on request), then * define the layout of the vendor-specific data. * * Use glXVendorPrivateWithReply for extended requests with a reply * (e.g., new gets for OpenGL): * * glXVendorPrivateWithReply * * 1 CARD8 opcode (X assigned) * 1 17 GLX opcode * 2 2+(n+p)/4 request length * 4 CARD32 vendor-specific opcode * n LISTofBYTE vendor-specific data * p unused, p=pad(n) * => * 1 1 reply * 1 unused * 2 CARD16 sequence number * 4 n reply length * 24 LISTofBYTE returned data * 4*n LISTofBYTE more returned data * * This is similar to glXVendorPrivate except you also need to * define the layout of the returned data. * * For extended OpenGL commands, be sure to specify whether it is a * rendering command or a non-rendering command, and if it is a * rendering command, whether or not it can be large. * * To specify an extended visual attribute, specify a property * type/property value pair to use with glXGetVisualConfigs. ******************************************************************** Dependencies on GL and ES profiles, versions, and other extensions * Separately list each interaction which affects the behavior * of this extension depending on which other extensions * are present or on which version of Specifications this * extension is implemented against. Examples: * Dependencies on ARB_texture_float * * If ARB_texture_float is not supported, then * delete all references to the R*F* pixel formats. * Dependencies on OpenGL ES * * If implemented for OpenGL ES, this extension * behaves as specified, except: * * - Ignore all references to display lists and * immediate mode, including changes to section 5.4. * - Ignore all references to GLX and GLX Protocol. Errors * This list summarizes all possible errors generated by the * extension and should be complete (however, errors are best * described in the extension body text as well). New State * Include modifications to the state tables in chapter 6 of the * GL and/or ES Specifications (other Specifications do not * have state tables). For each affected table, identify the * table and describe all new or modified state values in the * format of that table. Client state (for e.g. vertex arrays or * pixel packing parameters) should have "client" listed in the * Attribute column. Example: * Changes to table 6.99, p. 516 (Funky Geometry State) * * Initial * Get Value Type Get Command Value Description Sec. Attribute * --------- ---- ----------- ------- ----------- ---- --------- * RADIUS R GetFloatv 1.0 Disk radius 2.6 vertex New Implementation Dependent State * Describe all implementation dependent state in the same * fashion. Example: * (Changes to table 6.100, p. 518 (Implementation-Dependent State) * * Minimum * Get Value Type Get Command Value Description Sec. Attribute * --------- ---- ----------- ------- ----------- ---- --------- * MAX_DISKS Z+ GetIntegerv 1000 Max. # of 2.5 - * disks. Sample Code * For complex extensions, it may be worthwhile to include * code samples of how to use the extension. Conformance Tests * If a conformance test is defined for the extension, * summarize its basic purpose, if not necessarily its * source code, here. If no test has been defined, note that * they are needed. Issues * List remaining open issues, or closed issues whose resolution * set a precedent or was otherwise especially interesting. * Briefly describe each issue, options considered, the choice * made, and the reason for that choice. The Issues section * documents motivation, rationale, etc. while not being a * normative part of the extension. We suggest a numerically * order list so that issues can refer to other issues. * * We now recommend placing the Issues list near the end of * the extension, since it can grow very long yet is ancillary * to the specification itself. Revision History * Include important changes in the evolution of the extension. * It's especially important to include this section if the * extension is modified after a version has been shipped. * * Example (and actual revision history of the template): * Revision 8, 2010/01/20 * - Minor updates for completeness and consistency. Push updated * template to the public Registry. * Revision 7, 2009/12/07 * - Generalize template to allow for ES and GL extensions * and change references from SGI to Khronos as the * Registry owner. * Revision 6, 2006/10/09 * - Move registry URL to www.opengl.org. * Revision 5, 2004/06/22 * - Update template to allow OpenGL Shading Language and EGL * extensions. Add "Sample Code" section. Include more examples * under "IP Status". Add the template's revision history. * Add state table examples. Cleanup overall formatting to make * clear what are the section headers which must be present, * in contrast to the examples which are just part of this * template. Add document source URL. * Revision 4, 2003/12/19 * - Add "New Types" section. * Revision 3, 2000/04/26 * - Add "Author Revision" field to Version section, instead of * relying on source code control versions.