1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4 <refentry id=
"glSecondaryColorPointer">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glSecondaryColorPointer
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glSecondaryColorPointer
</refname>
17 <refpurpose>define an array of secondary colors
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glSecondaryColorPointer
</function></funcdef>
23 <paramdef>GLint
<parameter>size
</parameter></paramdef>
24 <paramdef>GLenum
<parameter>type
</parameter></paramdef>
25 <paramdef>GLsizei
<parameter>stride
</parameter></paramdef>
26 <paramdef>const GLvoid *
<parameter>pointer
</parameter></paramdef>
30 <!-- eqn: ignoring delim $$ -->
31 <refsect1 id=
"parameters"><title>Parameters
</title>
34 <term><parameter>size
</parameter></term>
37 Specifies the number of components per color. Must be
3.
42 <term><parameter>type
</parameter></term>
45 Specifies the data type of each color component in the array.
47 <constant>GL_BYTE
</constant>,
48 <constant>GL_UNSIGNED_BYTE
</constant>,
49 <constant>GL_SHORT
</constant>,
50 <constant>GL_UNSIGNED_SHORT
</constant>,
51 <constant>GL_INT
</constant>,
52 <constant>GL_UNSIGNED_INT
</constant>,
53 <constant>GL_FLOAT
</constant>,
55 <constant>GL_DOUBLE
</constant>
57 The initial value is
<constant>GL_FLOAT
</constant>.
62 <term><parameter>stride
</parameter></term>
65 Specifies the byte offset between consecutive colors.
66 If
<parameter>stride
</parameter> is
0, the colors are understood to be
67 tightly packed in the array. The initial value is
0.
72 <term><parameter>pointer
</parameter></term>
75 Specifies a pointer to the first component of the first color element
76 in the array. The initial value is
0.
82 <refsect1 id=
"description"><title>Description
</title>
84 <function>glSecondaryColorPointer
</function> specifies the location and data format of an array of color components
85 to use when rendering.
86 <parameter>size
</parameter> specifies the number of components per color, and must be
3.
87 <parameter>type
</parameter> specifies the data type of each color component, and
<parameter>stride
</parameter>
88 specifies the byte stride from one color to the next, allowing vertices and
89 attributes to be packed into a single array or stored in separate arrays.
92 If a non-zero named buffer object is bound to the
<constant>GL_ARRAY_BUFFER
</constant> target
93 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a secondary color array is
94 specified,
<parameter>pointer
</parameter> is treated as a byte offset into the buffer object's data store.
95 Also, the buffer object binding (
<constant>GL_ARRAY_BUFFER_BINDING
</constant>) is saved as secondary color vertex array
96 client-side state (
<constant>GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING
</constant>).
99 When a secondary color array is specified,
100 <parameter>size
</parameter>,
<parameter>type
</parameter>,
<parameter>stride
</parameter>, and
<parameter>pointer
</parameter> are saved as client-side
101 state, in addition to the current vertex array buffer object binding.
104 To enable and disable the secondary color array, call
<citerefentry><refentrytitle>glEnableClientState
</refentrytitle></citerefentry> and
105 <citerefentry><refentrytitle>glDisableClientState
</refentrytitle></citerefentry> with the argument
106 <constant>GL_SECONDARY_COLOR_ARRAY
</constant>. If enabled, the secondary color array is used when
107 <citerefentry><refentrytitle>glArrayElement
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays
</refentrytitle></citerefentry>,
108 <citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawElements
</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glDrawRangeElements
</refentrytitle></citerefentry>
112 <refsect1 id=
"notes"><title>Notes
</title>
114 <function>glSecondaryColorPointer
</function> is available only if the GL version is
1.4 or greater.
117 Secondary colors are not supported for interleaved vertex array formats
118 (see
<citerefentry><refentrytitle>glInterleavedArrays
</refentrytitle></citerefentry>).
121 The secondary color array is initially disabled and isn't accessed when
122 <citerefentry><refentrytitle>glArrayElement
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements
</refentrytitle></citerefentry>,
123 <citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays
</refentrytitle></citerefentry>, or
<citerefentry><refentrytitle>glMultiDrawElements
</refentrytitle></citerefentry>
127 Execution of
<function>glSecondaryColorPointer
</function> is not allowed between the execution of
128 <citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>,
129 but an error may or may not be generated. If no error is generated,
130 the operation is undefined.
133 <function>glSecondaryColorPointer
</function> is typically implemented on the client side.
136 Secondary color array parameters are client-side state and are therefore
137 not saved or restored by
<citerefentry><refentrytitle>glPushAttrib
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPopAttrib
</refentrytitle></citerefentry>. Use
138 <citerefentry><refentrytitle>glPushClientAttrib
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPopClientAttrib
</refentrytitle></citerefentry> instead.
141 <refsect1 id=
"errors"><title>Errors
</title>
143 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>size
</parameter> is not
3.
146 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not an accepted value.
149 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>stride
</parameter> is negative.
152 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
154 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY
</constant>
157 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY_SIZE
</constant>
160 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY_TYPE
</constant>
163 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY_STRIDE
</constant>
166 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING
</constant>
169 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_ARRAY_BUFFER_BINDING
</constant>
172 <citerefentry><refentrytitle>glGetPointerv
</refentrytitle></citerefentry> with argument
<constant>GL_SECONDARY_COLOR_ARRAY_POINTER
</constant>
175 <refsect1 id=
"seealso"><title>See Also
</title>
177 <citerefentry><refentrytitle>glArrayElement
</refentrytitle></citerefentry>,
178 <citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>,
179 <citerefentry><refentrytitle>glColorPointer
</refentrytitle></citerefentry>,
180 <citerefentry><refentrytitle>glDisableClientState
</refentrytitle></citerefentry>,
181 <citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
182 <citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
183 <citerefentry><refentrytitle>glDrawRangeElements
</refentrytitle></citerefentry>,
184 <citerefentry><refentrytitle>glEdgeFlagPointer
</refentrytitle></citerefentry>,
185 <citerefentry><refentrytitle>glEnableClientState
</refentrytitle></citerefentry>,
186 <citerefentry><refentrytitle>glFogCoordPointer
</refentrytitle></citerefentry>,
187 <citerefentry><refentrytitle>glIndexPointer
</refentrytitle></citerefentry>,
188 <citerefentry><refentrytitle>glInterleavedArrays
</refentrytitle></citerefentry>,
189 <citerefentry><refentrytitle>glMultiDrawArrays
</refentrytitle></citerefentry>,
190 <citerefentry><refentrytitle>glMultiDrawElements
</refentrytitle></citerefentry>,
191 <citerefentry><refentrytitle>glNormalPointer
</refentrytitle></citerefentry>,
192 <citerefentry><refentrytitle>glPopClientAttrib
</refentrytitle></citerefentry>,
193 <citerefentry><refentrytitle>glPushClientAttrib
</refentrytitle></citerefentry>,
194 <citerefentry><refentrytitle>glSecondaryColor
</refentrytitle></citerefentry>,
195 <citerefentry><refentrytitle>glTexCoordPointer
</refentrytitle></citerefentry>,
196 <citerefentry><refentrytitle>glVertexAttribPointer
</refentrytitle></citerefentry>,
197 <citerefentry><refentrytitle>glVertexPointer
</refentrytitle></citerefentry>
200 <refsect1 id=
"Copyright"><title>Copyright
</title>
202 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
203 Silicon Graphics, Inc. This document is licensed under the SGI
204 Free Software B License. For details, see
205 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.