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 parameter of Enable, Disable, and IsEnabled, and by the parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: COLOR_SUM_EXT 0x8458 Accepted by the 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 parameter of GetPointerv: SECONDARY_COLOR_ARRAY_POINTER_EXT 0x845D Accepted by the 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 Vertexv, where is one of [2,3,4], and 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, TexCoordv, Colorv, SecondaryColor3vEXT, Indexv, and Normalv, 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 is not 3. INVALID_ENUM is generated if SecondaryColorPointerEXT parameter is not BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT, UNSIGNED_INT, FLOAT, or DOUBLE. INVALID_VALUE is generated if SecondaryColorPointerEXT parameter 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