blob: 67d0e0f5258d965bb73ad8f1f424aef8a1f65f25 [file] [log] [blame]
Name
EXT_secondary_color
Name Strings
GL_EXT_secondary_color
Version
NVIDIA Date: February 24, 2000
$Date: 1999/06/21 19:57:47 $ $Revision: 1.8 $
Number
145
Dependencies
Either EXT_separate_specular_color or OpenGL 1.2 is required, to specify
the "Color Sum" stage and other handling of the secondary color. This is
written against the 1.2 specification (available from www.opengl.org).
Overview
This extension allows specifying the RGB components of the secondary
color used in the Color Sum stage, instead of using the default
(0,0,0,0) color. It applies only in RGBA mode and when LIGHTING is
disabled.
Issues
* Can we use the secondary alpha as an explicit fog weighting factor?
ISVs prefer a separate interface (see GL_EXT_fog_coord). The current
interface specifies only the RGB elements, leaving the option of a
separate extension for SecondaryColor4() entry points open (thus
the apparently useless ARRAY_SIZE state entry).
There is an unpleasant asymmetry with Color3() - one assumes A =
1.0, the other assumes A = 0.0 - but this appears unavoidable given
the 1.2 color sum specification language. Alternatively, the color
sum language could be rewritten to not sum secondary A.
* What about multiple "color iterators" for use with aggrandized
multitexture implementations?
We may need this eventually, but the secondary color is well defined
and a more generic interface doesn't seem justified now.
* Interleaved array formats?
No. The multiplicative explosion of formats is too great.
* Do we want to be able to query the secondary color value? How does it
interact with lighting?
The secondary color is not part of the GL state in the
separate_specular_color extension that went into OpenGL 1.2. There,
it can't be queried or obtained via feedback.
The secondary_color extension is slightly more general-purpose, so
the secondary color is explicitly in the GL state and can be queried
- but it's still somewhat limited and can't be obtained via
feedback, for example.
New Procedures and Functions
void SecondaryColor3[bsifd ubusui]EXT(T components)
void SecondaryColor3[bsifd ubusui]vEXT(T components)
void SecondaryColorPointerEXT(int size, enum type, sizei stride,
void *pointer)
New Tokens
Accepted by the <cap> parameter of Enable, Disable, and IsEnabled,
and by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv,
and GetDoublev:
COLOR_SUM_EXT 0x8458
Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev:
CURRENT_SECONDARY_COLOR_EXT 0x8459
SECONDARY_COLOR_ARRAY_SIZE_EXT 0x845A
SECONDARY_COLOR_ARRAY_TYPE_EXT 0x845B
SECONDARY_COLOR_ARRAY_STRIDE_EXT 0x845C
Accepted by the <pname> parameter of GetPointerv:
SECONDARY_COLOR_ARRAY_POINTER_EXT 0x845D
Accepted by the <array> parameter of EnableClientState and
DisableClientState:
SECONDARY_COLOR_ARRAY_EXT 0x845E
Additions to Chapter 2 of the 1.2 Draft Specification (OpenGL Operation)
These changes describe a new current state type, the secondary color, and
the commands to specify it:
- (2.6, p. 12) Second paragraph changed to:
"Each vertex is specified with two, three, or four coordinates. In
addition, a current normal, current texture coordinates, current
color, and current secondary color may be used in processing each
vertex."
Third paragraph, second sentence changed to:
"These associated colors are either based on the current color and
current secondary color, or produced by lighting, depending on
whether or not lighting is enabled."
- 2.6.3, p. 19) First paragraph changed to
"The only GL commands that are allowed within any Begin/End pairs
are the commands for specifying vertex coordinates, vertex colors,
normal coordinates, and texture coordinates (Vertex, Color,
SecondaryColorEXT, Index, Normal, TexCoord)..."
- (2.7, p. 20) Starting with the fourth paragraph, change to:
"Finally, there are several ways to set the current color and
secondary color. The GL stores a current single-valued color index
as well as a current four-valued RGBA color and secondary color.
Either the index or the color and secondary color are significant
depending as the GL is in color index mode or RGBA mode. The mode
selection is made when the GL is initialized.
The commands to set RGBA colors and secondary colors are:
void Color[34][bsifd ubusui](T components)
void Color[34][bsifd ubusui]v(T components)
void SecondaryColor3[bsifd ubusui]EXT(T components)
void SecondaryColor3[bsifd ubusui]vEXT(T components)
The color command has two major variants: Color3 and Color4. The
four value versions set all four values. The three value versions
set R, G, and B to the provided values; A is set to 1.0. (The
conversion of integer color components (R, G, B, and A) to
floating-point values is discussed in section 2.13.)
The secondary color command has only the three value versions.
Secondary A is always set to 0.0.
Versions of the Color and SecondaryColorEXT commands that take
floating-point values accept values nominally between 0.0 and
1.0...."
The last paragraph is changed to read:
"The state required to support vertex specification consists of four
floating-point numbers to store the current texture coordinates s,
t, r, and q, four floating-point values to store the current RGBA
color, four floating-point values to store the current RGBA
secondary color, and one floating-point value to store the current
color index. There is no notion of a current vertex, so no state is
devoted to vertex coordinates. The initial values of s, t, and r of
the current texture coordinates are zero; the initial value of q is
one. The initial current normal has coordinates (0,0,1). The initial
RGBA color is (R,G,B,A) = (1,1,1,1). The initial RGBA secondary
color is (R,G,B,A) = (0,0,0,0). The initial color index is 1."
- (2.8, p. 21) Added secondary color command for vertex arrays:
Change first paragraph to read:
"The vertex specification commands described in section 2.7 accept
data in almost any format, but their use requires many command
executions to specify even simple geometry. Vertex data may also be
placed into arrays that are stored in the client's address space.
Blocks of data in these arrays may then be used to specify multiple
geometric primitives through the execution of a single GL command.
The client may specify up to seven arrays: one each to store edge
flags, texture coordinates, colors, secondary colors, color indices,
normals, and vertices. The commands"
Add to functions listed following first paragraph:
void SecondaryColorPointerEXT(int size, enum type, sizei stride,
void *pointer)
Add to table 2.4 (p. 22):
Command Sizes Types
------- ----- -----
SecondaryColorPointerEXT 3 byte,ubyte,short,ushort,int,uint,
float,double
Starting with the second paragraph on p. 23, change to add
SECONDARY_COLOR_ARRAY_EXT:
"An individual array is enabled or disabled by calling one of
void EnableClientState(enum array)
void DisableClientState(enum array)
with array set to EDGE_FLAG_ARRAY, TEXTURE_COORD_ARRAY, COLOR_ARRAY,
SECONDARY_COLOR_ARRAY_EXT, INDEX_ARRAY, NORMAL_ARRAY, or
VERTEX_ARRAY, for the edge flag, texture coordinate, color,
secondary color, color index, normal, or vertex array, respectively.
The ith element of every enabled array is transferred to the GL by
calling
void ArrayElement(int i)
For each enabled array, it is as though the corresponding command
from section 2.7 or section 2.6.2 were called with a pointer to
element i. For the vertex array, the corresponding command is
Vertex<size><type>v, where <size> is one of [2,3,4], and <type> is
one of [s,i,f,d], corresponding to array types short, int, float,
and double respectively. The corresponding commands for the edge
flag, texture coordinate, color, secondary color, color index, and
normal arrays are EdgeFlagv, TexCoord<size><type>v,
Color<size><type>v, SecondaryColor3<type>vEXT, Index<type>v, and
Normal<type>v, respectively..."
Change pseudocode on p. 27 to disable secondary color array for
canned interleaved array formats. After the lines
DisableClientState(EDGE_FLAG_ARRAY);
DisableClientState(INDEX_ARRAY);
insert the line
DisableClientState(SECONDARY_COLOR_ARRAY_EXT);
Substitute "seven" for every occurence of "six" in the final paragraph
on p. 27.
- (2.12, p. 41) Add secondary color to the current rasterpos state.
Change the last paragraph to read
"The current raster position requires five single-precision
floating-point values for its x_w, y_w, and z_w window coordinates,
its w_c clip coordinate, and its eye coordinate distance, a single
valid bit, a color (RGBA color, RGBA secondary color, and color
index), and texture coordinates for associated data. In the initial
state, the coordinates and texture coordinates are both $(0,0,0,1)$,
the eye coordinate distance is 0, the valid bit is set, the
associated RGBA color is $(1,1,1,1)$, the associated RGBA secondary
color is $(0,0,0,0)$, and the associated color index color is 1. In
RGBA mode, the associated color index always has its initial value;
in color index mode, the RGBA color and and secondary color always
maintain their initial values."
- (2.13, p. 43) Change second paragraph to acknowledge two colors when
lighting is disabled:
"Next, lighting, if enabled, produces either a color index or
primary and secondary colors. If lighting is disabled, the current
color index or current color (primary color) and current secondary
color are used in further processing. After lighting, RGBA colors
are clamped..."
- (Figure 2.8, p. 42) Change to show primary and secondary RGBA colors in
both lit and unlit paths.
- (2.13.1, p. 44) Change so that the second paragraph starts:
"Lighting may be in one of two states:
1. Lighting Off. In this state, the current color and current secondary
color are assigned to the vertex primary color and vertex secondary
color, respectively.
2. ..."
- (2.13.1, p. 48) Change the sentence following equation 2.5 (for spot_i)
so that color sum is implicitly enabled when SEPARATE_SPECULAR_COLOR is
set:
"All computations are carried out in eye coordinates. When c_es =
SEPARATE_SPECULAR_COLOR, it is as if color sum (see section 3.9) were
enabled, regardless of the value of COLOR_SUM_EXT."
- (3.9, p. 136) Change the first paragraph to read
"After texturing, a fragment has two RGBA colors: a primary color c_pri
(which texturing, if enabled, may have modified) and a secondary color
c_sec.
If color sum is enabled, the components of these two colors are summed
to produce a single post-texturing RGBA color c (the A component of the
secondary color is always 0). The components of c are then clamped to
the range [0,1]. If color sum is disabled, then c_pri is assigned to the
post texturing color. Color sum is enabled or disabled using the generic
Enable and Disable commands, respectively, with the symbolic constant
COLOR_SUM_EXT.
The state required is a single bit indicating whether color sum is
enabled or disabled. In the initial state, color sum is disabled."
Additions to Chapter 6 of the 1.2 Specification (State and State Requests)
None
Additions to the GLX Specification
None
GLX Protocol
Eight new GL rendering commands are added. The following commands
are sent to the server as part of a glXRender request:
SecondaryColor3bvEXT
2 8 rendering command length
2 4126 rendering command opcode
1 INT8 v[0]
1 INT8 v[1]
1 INT8 v[2]
1 unused
SecondaryColor3svEXT
2 12 rendering command length
2 4127 rendering command opcode
2 INT16 v[0]
2 INT16 v[1]
2 INT16 v[2]
2 unused
SecondaryColor3ivEXT
2 16 rendering command length
2 4128 rendering command opcode
4 INT32 v[0]
4 INT32 v[1]
4 INT32 v[2]
SecondaryColor3fvEXT
2 16 rendering command length
2 4129 rendering command opcode
4 FLOAT32 v[0]
4 FLOAT32 v[1]
4 FLOAT32 v[2]
SecondaryColor3dvEXT
2 28 rendering command length
2 4130 rendering command opcode
8 FLOAT64 v[0]
8 FLOAT64 v[1]
8 FLOAT64 v[2]
SecondaryColor3ubvEXT
2 8 rendering command length
2 4131 rendering command opcode
1 CARD8 v[0]
1 CARD8 v[1]
1 CARD8 v[2]
1 unused
SecondaryColor3usvEXT
2 12 rendering command length
2 4132 rendering command opcode
2 CARD16 v[0]
2 CARD16 v[1]
2 CARD16 v[2]
2 unused
SecondaryColor3uivEXT
2 16 rendering command length
2 4133 rendering command opcode
4 CARD32 v[0]
4 CARD32 v[1]
4 CARD32 v[2]
Errors
INVALID_VALUE is generated if SecondaryColorPointerEXT parameter <size>
is not 3.
INVALID_ENUM is generated if SecondaryColorPointerEXT parameter <type>
is not BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT, UNSIGNED_INT,
FLOAT, or DOUBLE.
INVALID_VALUE is generated if SecondaryColorPointerEXT parameter
<stride> is negative.
New State
(table 6.5, p. 195)
Get Value Type Get Command Initial Value Description Sec Attribute
--------- ---- ----------- ------------- ----------- --- ---------
CURRENT_SECONDARY_COLOR_EXT C GetIntegerv, (0,0,0,0) Current 2.7 current
GetFloatv secondary color
(table 6.6, p. 197)
Get Value Type Get Command Initial Value Description Sec Attribute
--------- ---- ----------- ------------- ----------- --- ---------
SECONDARY_COLOR_ARRAY_EXT B IsEnabled False Sec. color array enable 2.8 vertex-array
SECONDARY_COLOR_ARRAY_SIZE_EXT Z+ GetIntegerv 3 Sec. colors per vertex 2.8 vertex-array
SECONDARY_COLOR_ARRAY_TYPE_EXT Z8 GetIntegerv FLOAT Type of sec. color components 2.8 vertex-array
SECONDARY_COLOR_ARRAY_STRIDE_EXT Z+ GetIntegerv 0 Stride between sec. colors 2.8 vertex-array
SECONDARY_COLOR_ARRAY_POINTER_EXT Y GetPointerv 0 Pointer to the sec. color array 2.8 vertex-array
(table 6.8, p. 198)
Get Value Type Get Command Initial Value Description Sec Attribute
--------- ---- ----------- ------------- ----------- --- ---------
COLOR_SUM_EXT B IsEnabled False True if color 3.9 fog/enable
sum enabled