245 lines
8.6 KiB
Plaintext
245 lines
8.6 KiB
Plaintext
|
* 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 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
|
||
|
|
--------- ----------- ---- -------
|