1GLCOLORTABLE(3G) OpenGL Manual GLCOLORTABLE(3G)
2
3
4
6 glColorTable - define a color lookup table
7
9 void glColorTable(GLenum target, GLenum internalformat, GLsizei width,
10 GLenum format, GLenum type, const GLvoid * data);
11
13 target
14 Must be one of GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE,
15 GL_POST_COLOR_MATRIX_COLOR_TABLE, GL_PROXY_COLOR_TABLE,
16 GL_PROXY_POST_CONVOLUTION_COLOR_TABLE, or
17 GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE.
18
19 internalformat
20 The internal format of the color table. The allowable values are
21 GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16,
22 GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12,
23 GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4,
24 GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4,
25 GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY,
26 GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16,
27 GL_R3_G3_B2, GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12,
28 GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8,
29 GL_RGB10_A2, GL_RGBA12, and GL_RGBA16.
30
31 width
32 The number of entries in the color lookup table specified by data.
33
34 format
35 The format of the pixel data in data. The allowable values are
36 GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_LUMINANCE,
37 GL_LUMINANCE_ALPHA, GL_RGB, GL_BGR, GL_RGBA, and GL_BGRA.
38
39 type
40 The type of the pixel data in data. The allowable values are
41 GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
42 GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2,
43 GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5,
44 GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
45 GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1,
46 GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
47 GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and
48 GL_UNSIGNED_INT_2_10_10_10_REV.
49
50 data
51 Pointer to a one-dimensional array of pixel data that is processed
52 to build the color table.
53
55 glColorTable may be used in two ways: to test the actual size and color
56 resolution of a lookup table given a particular set of parameters, or
57 to load the contents of a color lookup table. Use the targets
58 GL_PROXY_* for the first case and the other targets for the second
59 case.
60
61 If a non-zero named buffer object is bound to the
62 GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer()) while a color table
63 is specified, data is treated as a byte offset into the buffer object's
64 data store.
65
66 If target is GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or
67 GL_POST_COLOR_MATRIX_COLOR_TABLE, glColorTable builds a color lookup
68 table from an array of pixels. The pixel array specified by width,
69 format, type, and data is extracted from memory and processed just as
70 if glDrawPixels() were called, but processing stops after the final
71 expansion to RGBA is completed.
72
73 The four scale parameters and the four bias parameters that are defined
74 for the table are then used to scale and bias the R, G, B, and A
75 components of each pixel. (Use glColorTableParameter to set these scale
76 and bias parameters.)
77
78 Next, the R, G, B, and A values are clamped to the range 0 1. Each
79 pixel is then converted to the internal format specified by
80 internalformat. This conversion simply maps the component values of the
81 pixel (R, G, B, and A) to the values included in the internal format
82 (red, green, blue, alpha, luminance, and intensity). The mapping is as
83 follows:
84
85 ┌─────────────────────────────────┬─────────────────────────────┬───────────────────────────────┬──────────────────────────────┬───────────────────────────────┬───────────────────────────────────┬───────────────────────────────────┐
86 │ │ │ │ │ │ │ │
87 │ Internal │ Red │ Green │ Blue │ Alpha │ Luminance │ Intensity │
88 │Format │ │ │ │ │ │ │
89 │ │ │ │ │ │ │ │
90 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
91 │GL_ALPHA │ │ │ │ A │ │ │
92 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
93 │GL_LUMINANCE │ │ │ │ │ R │ │
94 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
95 │GL_LUMINANCE_ALPHA │ │ │ │ A │ R │ │
96 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
97 │GL_INTENSITY │ │ │ │ │ │ R │
98 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
99 │GL_RGB │ R │ G │ B │ │ │ │
100 ├─────────────────────────────────┼─────────────────────────────┼───────────────────────────────┼──────────────────────────────┼───────────────────────────────┼───────────────────────────────────┼───────────────────────────────────┤
101 │GL_RGBA │ R │ G │ B │ A │ │ │
102 └─────────────────────────────────┴─────────────────────────────┴───────────────────────────────┴──────────────────────────────┴───────────────────────────────┴───────────────────────────────────┴───────────────────────────────────┘
103
104 Finally, the red, green, blue, alpha, luminance, and/or intensity
105 components of the resulting pixels are stored in the color table. They
106 form a one-dimensional table with indices in the range 0 width - 1.
107
108 If target is GL_PROXY_*, glColorTable recomputes and stores the values
109 of the proxy color table's state variables GL_COLOR_TABLE_FORMAT,
110 GL_COLOR_TABLE_WIDTH, GL_COLOR_TABLE_RED_SIZE,
111 GL_COLOR_TABLE_GREEN_SIZE, GL_COLOR_TABLE_BLUE_SIZE,
112 GL_COLOR_TABLE_ALPHA_SIZE, GL_COLOR_TABLE_LUMINANCE_SIZE, and
113 GL_COLOR_TABLE_INTENSITY_SIZE. There is no effect on the image or state
114 of any actual color table. If the specified color table is too large to
115 be supported, then all the proxy state variables listed above are set
116 to zero. Otherwise, the color table could be supported by glColorTable
117 using the corresponding non-proxy target, and the proxy state variables
118 are set as if that target were being defined.
119
120 The proxy state variables can be retrieved by calling
121 glGetColorTableParameter() with a target of GL_PROXY_*. This allows the
122 application to decide if a particular glColorTable command would
123 succeed, and to determine what the resulting color table attributes
124 would be.
125
126 If a color table is enabled, and its width is non-zero, then its
127 contents are used to replace a subset of the components of each RGBA
128 pixel group, based on the internal format of the table.
129
130 Each pixel group has color components (R, G, B, A) that are in the
131 range 0.0 1.0. The color components are rescaled to the size of the
132 color lookup table to form an index. Then a subset of the components
133 based on the internal format of the table are replaced by the table
134 entry selected by that index. If the color components and contents of
135 the table are represented as follows:
136
137 ┌───────────────────────────────────────┬─────────────────────────────────┐
138 │ │ │
139 │ Representation │ Meaning │
140 │ │ │
141 ├───────────────────────────────────────┼─────────────────────────────────┤
142 │ r │ Table index computed from R │
143 ├───────────────────────────────────────┼─────────────────────────────────┤
144 │ g │ Table index computed from G │
145 ├───────────────────────────────────────┼─────────────────────────────────┤
146 │ b │ Table index computed from B │
147 ├───────────────────────────────────────┼─────────────────────────────────┤
148 │ a │ Table index computed from A │
149 ├───────────────────────────────────────┼─────────────────────────────────┤
150 │ L[i] │ Luminance value at table index │
151 │ │ i │
152 ├───────────────────────────────────────┼─────────────────────────────────┤
153 │ I[i] │ Intensity value at table index │
154 │ │ i │
155 ├───────────────────────────────────────┼─────────────────────────────────┤
156 │ R[i] │ Red value at table index i │
157 ├───────────────────────────────────────┼─────────────────────────────────┤
158 │ G[i] │ Green value at table index i │
159 ├───────────────────────────────────────┼─────────────────────────────────┤
160 │ B[i] │ Blue value at table index i │
161 ├───────────────────────────────────────┼─────────────────────────────────┤
162 │ A[i] │ Alpha value at table index i │
163 └───────────────────────────────────────┴─────────────────────────────────┘
164
165 then the result of color table lookup is as follows:
166
167 ┌──────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
168 │ │ │
169 │ │ Resulting Texture Components │
170 │ │ │
171 ├──────────────────────────────┼───────────────────────────┬───────────────────────────┬───────────────────────────┬───────────────────────────┤
172 │ │ │ │ │ │
173 │ Table │ R │ G │ B │ A │
174 │Internal │ │ │ │ │
175 │Format │ │ │ │ │
176 │ │ │ │ │ │
177 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
178 │GL_ALPHA │ R │ G │ B │ A[a] │
179 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
180 │GL_LUMINANCE │ L[r] │ L[g] │ L[b] │ At │
181 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
182 │GL_LUMINANCE_ALPHA │ L[r] │ L[g] │ L[b] │ A[a] │
183 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
184 │GL_INTENSITY │ I[r] │ I[g] │ I[b] │ I[a] │
185 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
186 │GL_RGB │ R[r] │ G[g] │ B[b] │ A │
187 ├──────────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┼───────────────────────────┤
188 │GL_RGBA │ R[r] │ G[g] │ B[b] │ A[a] │
189 └──────────────────────────────┴───────────────────────────┴───────────────────────────┴───────────────────────────┴───────────────────────────┘
190
191 When GL_COLOR_TABLE is enabled, the colors resulting from the pixel map
192 operation (if it is enabled) are mapped by the color lookup table
193 before being passed to the convolution operation. The colors resulting
194 from the convolution operation are modified by the post convolution
195 color lookup table when GL_POST_CONVOLUTION_COLOR_TABLE is enabled.
196 These modified colors are then sent to the color matrix operation.
197 Finally, if GL_POST_COLOR_MATRIX_COLOR_TABLE is enabled, the colors
198 resulting from the color matrix operation are mapped by the post color
199 matrix color lookup table before being used by the histogram operation.
200
202 glColorTable is present only if ARB_imaging is returned when
203 glGetString() is called with an argument of GL_EXTENSIONS.
204
205 If target is set to GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or
206 GL_POST_COLOR_MATRIX_COLOR_TABLE, then width must be a power of two or
207 a GL_INVALID_VALUE error is generated.
208
210 GL_INVALID_ENUM is generated if target is not one of the allowable
211 values.
212
213 GL_INVALID_ENUM is generated if internalformat is not one of the
214 allowable values.
215
216 GL_INVALID_ENUM is generated if format is not one of the allowable
217 values.
218
219 GL_INVALID_ENUM is generated if type is not one of the allowable
220 values.
221
222 GL_INVALID_VALUE is generated if width is less than zero.
223
224 GL_TABLE_TOO_LARGE is generated if the requested color table is too
225 large to be supported by the implementation, and target is not a
226 GL_PROXY_* target.
227
228 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
229 bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object's data
230 store is currently mapped.
231
232 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
233 bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be
234 unpacked from the buffer object such that the memory reads required
235 would exceed the data store size.
236
237 GL_INVALID_OPERATION is generated if a non-zero buffer object name is
238 bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly
239 divisible into the number of bytes needed to store in memory a datum
240 indicated by type.
241
242 GL_INVALID_OPERATION is generated if glColorTable is executed between
243 the execution of glBegin() and the corresponding execution of glEnd().
244
246 glGetColorTableParameter()
247
248 glGet() with argument GL_PIXEL_UNPACK_BUFFER_BINDING
249
251 glColorSubTable(), glColorTableParameter, glCopyColorTable(),
252 glCopyColorSubTable(), glGetColorTable()
253
255 Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
256 under the SGI Free Software B License. For details, see
257 http://oss.sgi.com/projects/FreeB/.
258
260 opengl.org
261
262
263
264opengl.org 06/10/2014 GLCOLORTABLE(3G)