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=
"glColorSubTable">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glColorSubTable
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glColorSubTable
</refname>
17 <refpurpose>respecify a portion of a color table
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glColorSubTable
</function></funcdef>
23 <paramdef>GLenum
<parameter>target
</parameter></paramdef>
24 <paramdef>GLsizei
<parameter>start
</parameter></paramdef>
25 <paramdef>GLsizei
<parameter>count
</parameter></paramdef>
26 <paramdef>GLenum
<parameter>format
</parameter></paramdef>
27 <paramdef>GLenum
<parameter>type
</parameter></paramdef>
28 <paramdef>const GLvoid *
<parameter>data
</parameter></paramdef>
32 <refsect1 id=
"parameters"><title>Parameters
</title>
35 <term><parameter>target
</parameter></term>
39 <constant>GL_COLOR_TABLE
</constant>,
40 <constant>GL_POST_CONVOLUTION_COLOR_TABLE
</constant>, or
41 <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE
</constant>.
46 <term><parameter>start
</parameter></term>
49 The starting index of the portion of the color table to be replaced.
54 <term><parameter>count
</parameter></term>
57 The number of table entries to replace.
62 <term><parameter>format
</parameter></term>
65 The format of the pixel data in
<parameter>data
</parameter>.
66 The allowable values are
67 <constant>GL_RED
</constant>,
68 <constant>GL_GREEN
</constant>,
69 <constant>GL_BLUE
</constant>,
70 <constant>GL_ALPHA
</constant>,
71 <constant>GL_LUMINANCE
</constant>,
72 <constant>GL_LUMINANCE_ALPHA
</constant>,
73 <constant>GL_RGB
</constant>,
74 <constant>GL_BGR
</constant>,
75 <constant>GL_RGBA
</constant>, and
76 <constant>GL_BGRA
</constant>.
81 <term><parameter>type
</parameter></term>
84 The type of the pixel data in
<parameter>data
</parameter>.
85 The allowable values are
86 <constant>GL_UNSIGNED_BYTE
</constant>,
87 <constant>GL_BYTE
</constant>,
88 <constant>GL_UNSIGNED_SHORT
</constant>,
89 <constant>GL_SHORT
</constant>,
90 <constant>GL_UNSIGNED_INT
</constant>,
91 <constant>GL_INT
</constant>,
92 <constant>GL_FLOAT
</constant>,
93 <constant>GL_UNSIGNED_BYTE_3_3_2
</constant>,
94 <constant>GL_UNSIGNED_BYTE_2_3_3_REV
</constant>,
95 <constant>GL_UNSIGNED_SHORT_5_6_5
</constant>,
96 <constant>GL_UNSIGNED_SHORT_5_6_5_REV
</constant>,
97 <constant>GL_UNSIGNED_SHORT_4_4_4_4
</constant>,
98 <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV
</constant>,
99 <constant>GL_UNSIGNED_SHORT_5_5_5_1
</constant>,
100 <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV
</constant>,
101 <constant>GL_UNSIGNED_INT_8_8_8_8
</constant>,
102 <constant>GL_UNSIGNED_INT_8_8_8_8_REV
</constant>,
103 <constant>GL_UNSIGNED_INT_10_10_10_2
</constant>, and
104 <constant>GL_UNSIGNED_INT_2_10_10_10_REV
</constant>.
109 <term><parameter>data
</parameter></term>
112 Pointer to a one-dimensional array of pixel data that is processed to
113 replace the specified region of the color table.
119 <refsect1 id=
"description"><title>Description
</title>
121 <function>glColorSubTable
</function> is used to respecify a contiguous portion of a color table previously
122 defined using
<citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>. The pixels referenced by
<parameter>data
</parameter> replace the
123 portion of the existing table from indices
<parameter>start
</parameter> to
124 <inlineequation><mml:math>
125 <!-- eqn: start + count - 1:-->
127 <mml:mi mathvariant=
"italic">start
</mml:mi>
129 <mml:mi mathvariant=
"italic">count
</mml:mi>
133 </mml:math></inlineequation>,
134 inclusive. This region may not include any
135 entries outside the range of the color table as it was originally specified.
136 It is not an error to specify a subtexture with width of
0, but such a
137 specification has no effect.
140 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
141 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a portion of a color table is
142 respecified,
<parameter>data
</parameter> is treated as a byte offset into the buffer object's data store.
145 <refsect1 id=
"notes"><title>Notes
</title>
147 <function>glColorSubTable
</function> is present only if
<code>ARB_imaging
</code> is returned when
<citerefentry><refentrytitle>glGetString
</refentrytitle></citerefentry>
148 is called with an argument of
<constant>GL_EXTENSIONS
</constant>.
153 <refsect1 id=
"errors"><title>Errors
</title>
155 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>target
</parameter> is not one of the allowable
159 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>format
</parameter> is not one of the allowable
163 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>type
</parameter> is not one of the allowable
167 <constant>GL_INVALID_VALUE
</constant> is generated if
168 <inlineequation><mml:math>
169 <!-- eqn: start + count > width:-->
172 <mml:mi mathvariant=
"italic">start
</mml:mi>
174 <mml:mi mathvariant=
"italic">count
</mml:mi>
176 <mml:mo>></mml:mo>
177 <mml:mi mathvariant=
"italic">width
</mml:mi>
179 </mml:math></inlineequation>.
182 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
183 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
186 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
187 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
188 object such that the memory reads required would exceed the data store size.
191 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
192 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and
<parameter>data
</parameter> is not evenly divisible
193 into the number of bytes needed to store in memory a datum indicated by
<parameter>type
</parameter>.
196 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glColorSubTable
</function> is executed
197 between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry> and the corresponding
198 execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
201 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
203 <citerefentry><refentrytitle>glGetColorTable
</refentrytitle></citerefentry>,
204 <citerefentry><refentrytitle>glGetColorTableParameter
</refentrytitle></citerefentry>
207 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
210 <refsect1 id=
"seealso"><title>See Also
</title>
212 <citerefentry><refentrytitle>glColorTable
</refentrytitle></citerefentry>,
213 <citerefentry><refentrytitle>glColorTableParameter
</refentrytitle></citerefentry>,
214 <citerefentry><refentrytitle>glCopyColorTable
</refentrytitle></citerefentry>,
215 <citerefentry><refentrytitle>glCopyColorSubTable
</refentrytitle></citerefentry>,
216 <citerefentry><refentrytitle>glGetColorTable
</refentrytitle></citerefentry>
219 <refsect1 id=
"Copyright"><title>Copyright
</title>
221 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
222 Silicon Graphics, Inc. This document is licensed under the SGI
223 Free Software B License. For details, see
224 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.