* Template for documenting an extension to OpenGL * * Notes: * * Comments in this template document are preceded by an asterisk. * This entire section is one big comment. * * Extension documents are simple ASCII text, 132 characters wide. * Here is a line of 132 characters to use as a calibration: * *00000000011111111112222222222333333333344444444445555555555666666666677777777778888888888999999999900000000001111111111222222222233 * * Although the extension file is formally 132 characters wide, * text is limited to 80 characters, and only tables that require * more than 80 character width extend to the full file width. * * The extension is completely described in the "Additions to * Chapter N ..." sections. These sections are written as though * the additions described by previous extensions had actually been * made to GL specification chapters 2 through 6. The "Dependencies * on Extension N" 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, it is preferred * that the entire table be recreated in the extension document, * just as it would be if the GL Specification were modified by the * extension. Subsequent extensions that modify the same table * incorporate all the changes of the previous extensions, * representing the table in its completely updated form. * * To be consistent with the 1.0 OpenGL Specification, 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. Also, the OpenGL * Specification is referred to as the GL Specification, and OpenGL * is referred to as GL. To be consistent with the GLX * specification, however, extension documents include glX prefixes * on command names and GLX_ prefixes on token names. * * An extension document should include all the headers in this * template. If there is no text to follow a header, this is * indicated by the word "None", such as: * * Dependencies * * None * * 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 . * * Here's the template: XXX - Not complete yet!!! * Leave this warning in until the specification is complete. Name * The formal name of the extension. The prefix of the name is * one of SGI, SGIS, or SGIX, indicating that the extension * is for all SGI machines (SGI), for a subset of SGI machines * (SGIS), or is experimental, and may not be supported in any * future implementations (SGIX). The prefix may also be EXT * if two or more GL vendors have agreed to support the extension. * * 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 * If the extension name is returned by glGetString, then it is * listed here with the prefix GL_. If it is returned by * glXQueryExtensionsString, then it is listed here with the * prefix GLX_. Finally, if the extension name is returned by * gluGetString, then it is listed here with the prefix GLU. * For example, an extension which adds entry points to both * GLX and OpenGL would be listed as: * * GL_SGI_new_extension * GLX_SGI_new_extension * * These strings are included in the header files, and are returned * by the string query functions. Version $Date: 1995/03/31 04:40:57 $ $Revision: 1.11 $ Number * Extensions are numbered for documentation purposes. Each * extension must document its interactions with the core OpenGL * specification and with all other extensions that have lower * numbers. For example, extension 3 must document its * interactions with the core document and 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. Dependencies * Separately list all extensions that MUST be present for this * extension to be implemented, and all extensions whose presence or * absence modifies the operation of this extension. Overview * What does the extension do? What problem does it solve? 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. * For example: * * void NewCommandSGI(int arg1, * float arg2); 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. For example: * * Accepted by the parameters of GetBooleanv, GetIntegerv, * GetFloatv, and GetDoublev: * * NEW_TOKEN_SGI Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) * Include any new command suffixs here (2.3) * Include any new error types here (2.5) Additions to Chapter 3 of the 1.0 Specification (Rasterization) Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations and the Frame Buffer) Additions to Chapter 5 of the 1.0 Specification (Special Functions) * List commands that are not included in display lists (typically Get* * commands) Additions to Chapter 6 of the 1.0 Specification (State and State Requests) * The lists of state and implementation-dependent state are below, * however. Add queries and new attributes here. Additions to the GLX 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 from SGI; 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 SGI_extension_name * Separately list only the extensions with lower indexes on which this * extension is dependent. Do not list null dependencies - this just * creates unnecessary documentation dependencies! Errors * This list should be complete. New State * Description of all state values in table format. Note that client * state should have "client" listed in the Attrib column. Initial Get Value Get Command Type Value Attrib --------- ----------- ---- ------- ------ New Implementation Dependent State * Description of all implementation dependent state in table format. Minimum Get Value Get Command Type Value --------- ----------- ---- -------