Name

    EXT_secondary_color

Name Strings

    GL_EXT_secondary_color

Version

    $Date: 2005/06/02 18:11:10 $ $Revision: 1.1 $

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,4     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
