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=
"glColorPointer">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glColorPointer
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glColorPointer
</refname>
17 <refpurpose>define an array of colors
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glColorPointer
</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 or
4.
38 The initial value is
4.
43 <term><parameter>type
</parameter></term>
46 Specifies the data type of each color component in the array.
48 <constant>GL_BYTE
</constant>,
49 <constant>GL_UNSIGNED_BYTE
</constant>,
50 <constant>GL_SHORT
</constant>,
51 <constant>GL_UNSIGNED_SHORT
</constant>,
52 <constant>GL_INT
</constant>,
53 <constant>GL_UNSIGNED_INT
</constant>,
54 <constant>GL_FLOAT
</constant>,
56 <constant>GL_DOUBLE
</constant>
58 The initial value is
<constant>GL_FLOAT
</constant>.
63 <term><parameter>stride
</parameter></term>
66 Specifies the byte offset between consecutive colors.
67 If
<parameter>stride
</parameter> is
0, the colors are understood to be
68 tightly packed in the array. The initial value is
0.
73 <term><parameter>pointer
</parameter></term>
76 Specifies a pointer to the first component of the first color element
77 in the array. The initial value is
0.
83 <refsect1 id=
"description"><title>Description
</title>
85 <function>glColorPointer
</function> specifies the location and data format of an array of color components
86 to use when rendering.
87 <parameter>size
</parameter> specifies the number of components per color, and must be
3 or
4.
88 <parameter>type
</parameter> specifies the data type of each color component, and
<parameter>stride
</parameter>
89 specifies the byte stride from one color to the next, allowing vertices and
90 attributes to be packed into a single array or stored in separate arrays.
91 (Single-array storage may be more efficient on some implementations;
92 see
<citerefentry><refentrytitle>glInterleavedArrays
</refentrytitle></citerefentry>.)
95 If a non-zero named buffer object is bound to the
<constant>GL_ARRAY_BUFFER
</constant> target
96 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a color array is
97 specified,
<parameter>pointer
</parameter> is treated as a byte offset into the buffer object's data store.
98 Also, the buffer object binding (
<constant>GL_ARRAY_BUFFER_BINDING
</constant>) is saved as color vertex array
99 client-side state (
<constant>GL_COLOR_ARRAY_BUFFER_BINDING
</constant>).
102 When a color array is specified,
103 <parameter>size
</parameter>,
<parameter>type
</parameter>,
<parameter>stride
</parameter>, and
<parameter>pointer
</parameter> are saved as client-side
104 state, in addition to the current vertex array buffer object binding.
107 To enable and disable the color array, call
108 <citerefentry><refentrytitle>glEnableClientState
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisableClientState
</refentrytitle></citerefentry> with the argument
109 <constant>GL_COLOR_ARRAY
</constant>. If
110 enabled, the color array is used
111 when
<citerefentry><refentrytitle>glDrawArrays
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMultiDrawArrays
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawElements
</refentrytitle></citerefentry>,
112 <citerefentry><refentrytitle>glMultiDrawElements
</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glDrawRangeElements
</refentrytitle></citerefentry>, or
113 <citerefentry><refentrytitle>glArrayElement
</refentrytitle></citerefentry> is called.
116 <refsect1 id=
"notes"><title>Notes
</title>
118 <function>glColorPointer
</function> is available only if the GL version is
1.1 or greater.
121 The 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>glColorPointer
</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>glColorPointer
</function> is typically implemented on the client side.
136 Color array parameters are client-side state and are therefore not saved
137 or restored by
<citerefentry><refentrytitle>glPushAttrib
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glPopAttrib
</refentrytitle></citerefentry>.
138 Use
<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 or
4.
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_COLOR_ARRAY
</constant>
157 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_COLOR_ARRAY_SIZE
</constant>
160 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_COLOR_ARRAY_TYPE
</constant>
163 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_COLOR_ARRAY_STRIDE
</constant>
166 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_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_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>glColor
</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>glSecondaryColorPointer
</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>.