|
|
* 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 <pname>.** 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 <pname> 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 Operationsand 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 --------- ----------- ---- -------
|
