glColorTable — define a color lookup table
void glColorTable( | GLenum | target, |
GLenum | internalformat, | |
GLsizei | width, | |
GLenum | format, | |
GLenum | type, | |
const GLvoid * | data) ; |
target
Must be one of
GL_COLOR_TABLE
,
GL_POST_CONVOLUTION_COLOR_TABLE
,
GL_POST_COLOR_MATRIX_COLOR_TABLE
,
GL_PROXY_COLOR_TABLE
,
GL_PROXY_POST_CONVOLUTION_COLOR_TABLE
,
or
GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE
.
internalformat
The internal format of the color table.
The allowable values are
GL_ALPHA
,
GL_ALPHA4
,
GL_ALPHA8
,
GL_ALPHA12
,
GL_ALPHA16
,
GL_LUMINANCE
,
GL_LUMINANCE4
,
GL_LUMINANCE8
,
GL_LUMINANCE12
,
GL_LUMINANCE16
,
GL_LUMINANCE_ALPHA
,
GL_LUMINANCE4_ALPHA4
,
GL_LUMINANCE6_ALPHA2
,
GL_LUMINANCE8_ALPHA8
,
GL_LUMINANCE12_ALPHA4
,
GL_LUMINANCE12_ALPHA12
,
GL_LUMINANCE16_ALPHA16
,
GL_INTENSITY
,
GL_INTENSITY4
,
GL_INTENSITY8
,
GL_INTENSITY12
,
GL_INTENSITY16
,
GL_R3_G3_B2
,
GL_RGB
,
GL_RGB4
,
GL_RGB5
,
GL_RGB8
,
GL_RGB10
,
GL_RGB12
,
GL_RGB16
,
GL_RGBA
,
GL_RGBA2
,
GL_RGBA4
,
GL_RGB5_A1
,
GL_RGBA8
,
GL_RGB10_A2
,
GL_RGBA12
, and
GL_RGBA16
.
width
The number of entries in the color lookup table specified by data
.
format
The format of the pixel data in data
.
The allowable values are
GL_RED
,
GL_GREEN
,
GL_BLUE
,
GL_ALPHA
,
GL_LUMINANCE
,
GL_LUMINANCE_ALPHA
,
GL_RGB
,
GL_BGR
,
GL_RGBA
, and
GL_BGRA
.
type
The type of the pixel data in data
.
The allowable values are
GL_UNSIGNED_BYTE
,
GL_BYTE
,
GL_UNSIGNED_SHORT
,
GL_SHORT
,
GL_UNSIGNED_INT
,
GL_INT
,
GL_FLOAT
,
GL_UNSIGNED_BYTE_3_3_2
,
GL_UNSIGNED_BYTE_2_3_3_REV
,
GL_UNSIGNED_SHORT_5_6_5
,
GL_UNSIGNED_SHORT_5_6_5_REV
,
GL_UNSIGNED_SHORT_4_4_4_4
,
GL_UNSIGNED_SHORT_4_4_4_4_REV
,
GL_UNSIGNED_SHORT_5_5_5_1
,
GL_UNSIGNED_SHORT_1_5_5_5_REV
,
GL_UNSIGNED_INT_8_8_8_8
,
GL_UNSIGNED_INT_8_8_8_8_REV
,
GL_UNSIGNED_INT_10_10_10_2
, and
GL_UNSIGNED_INT_2_10_10_10_REV
.
data
Pointer to a one-dimensional array of pixel data that is processed to build the color table.
glColorTable
may be used in two ways:
to test the actual size and color resolution of a lookup table
given a particular set of parameters,
or to load the contents of a color lookup
table.
Use the targets GL_PROXY_*
for the first case
and the other targets for the second case.
If a non-zero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER
target
(see glBindBuffer) while a color table is
specified, data
is treated as a byte offset into the buffer object's data store.
If target
is GL_COLOR_TABLE
,
GL_POST_CONVOLUTION_COLOR_TABLE
,
or
GL_POST_COLOR_MATRIX_COLOR_TABLE
,
glColorTable
builds a color lookup table from an array of pixels.
The pixel array specified by width
, format
, type
, and data
is extracted from memory and
processed just as if glDrawPixels were called, but processing
stops after the final expansion to RGBA is completed.
The four scale parameters and the four bias parameters that are defined
for the table are then used to scale and bias the R, G, B, and A components
of each pixel.
(Use glColorTableParameter
to set these scale and bias
parameters.)
Next, the R, G, B, and A values are clamped to the range
internalformat
.
This conversion simply maps the component values of the pixel (R, G, B,
and A) to the values included in the internal format (red, green, blue,
alpha, luminance, and intensity). The mapping is as follows:
Internal Format | Red | Green | Blue | Alpha | Luminance | Intensity |
---|---|---|---|---|---|---|
GL_ALPHA
| A | |||||
GL_LUMINANCE
| R | |||||
GL_LUMINANCE_ALPHA
| A | R | ||||
GL_INTENSITY
| R | |||||
GL_RGB
| R | G | B | |||
GL_RGBA
| R | G | B | A |
Finally, the red, green, blue, alpha, luminance, and/or intensity components of
the resulting pixels are stored in the color table.
They form a one-dimensional table with indices in the range
If target
is GL_PROXY_*
,
glColorTable
recomputes and stores the values of the proxy color table's state
variables
GL_COLOR_TABLE_FORMAT
,
GL_COLOR_TABLE_WIDTH
,
GL_COLOR_TABLE_RED_SIZE
,
GL_COLOR_TABLE_GREEN_SIZE
,
GL_COLOR_TABLE_BLUE_SIZE
,
GL_COLOR_TABLE_ALPHA_SIZE
,
GL_COLOR_TABLE_LUMINANCE_SIZE
, and
GL_COLOR_TABLE_INTENSITY_SIZE
.
There is no effect on the image or state of any actual color table.
If the specified color table is too large to be supported, then all the
proxy state variables listed above are set to zero.
Otherwise, the color table could be supported by glColorTable
using the corresponding non-proxy target,
and the proxy state variables are set as if that target were being defined.
The proxy state variables can be retrieved by calling
glGetColorTableParameter with a target of
GL_PROXY_*
.
This allows the application to decide if a particular glColorTable
command would succeed, and to determine what the resulting color table
attributes would be.
If a color table is enabled, and its width is non-zero, then its contents are used to replace a subset of the components of each RGBA pixel group, based on the internal format of the table.
Each pixel group has color components (R, G, B, A)
that are in the range
Representation | Meaning |
---|---|
r
|
Table index computed from R
|
g
|
Table index computed from G
|
b
|
Table index computed from B
|
a
|
Table index computed from A
|
L[i]
|
Luminance value at table index i
|
I[i]
|
Intensity value at table index i
|
R[i]
|
Red value at table index i
|
G[i]
|
Green value at table index i
|
B[i]
|
Blue value at table index i
|
A[i]
|
Alpha value at table index i
|
then the result of color table lookup is as follows:
Resulting Texture Components | ||||
---|---|---|---|---|
Table Internal Format | R | G | B | A |
GL_ALPHA
|
R
|
G
|
B
|
A[a]
|
GL_LUMINANCE
|
L[r]
|
L[g]
|
L[b]
|
At
|
GL_LUMINANCE_ALPHA
|
L[r]
|
L[g]
|
L[b]
|
A[a]
|
GL_INTENSITY
|
I[r]
|
I[g]
|
I[b]
|
I[a]
|
GL_RGB
|
R[r]
|
G[g]
|
B[b]
|
A
|
GL_RGBA
|
R[r]
|
G[g]
|
B[b]
|
A[a]
|
When GL_COLOR_TABLE
is enabled, the colors resulting from
the pixel map operation (if it is enabled) are mapped
by the color lookup table before being passed to the convolution
operation. The colors resulting from the convolution operation
are modified by the post convolution color lookup table when
GL_POST_CONVOLUTION_COLOR_TABLE
is enabled. These modified colors are then sent to the color matrix operation.
Finally, if GL_POST_COLOR_MATRIX_COLOR_TABLE
is enabled, the colors resulting from the color matrix operation
are mapped by the post color matrix color lookup table before being
used by the histogram operation.
glColorTable
is present only if ARB_imaging
is returned when glGetString
is called with an argument of GL_EXTENSIONS
.
If target
is set to GL_COLOR_TABLE
,
GL_POST_CONVOLUTION_COLOR_TABLE
,
or GL_POST_COLOR_MATRIX_COLOR_TABLE
,
then width
must be a power of two or a GL_INVALID_VALUE
error is generated.
GL_INVALID_ENUM
is generated if target
is not one of the allowable
values.
GL_INVALID_ENUM
is generated if internalformat
is not one of the
allowable values.
GL_INVALID_ENUM
is generated if format
is not one of the allowable
values.
GL_INVALID_ENUM
is generated if type
is not one of the allowable
values.
GL_INVALID_VALUE
is generated if width
is less than zero.
GL_TABLE_TOO_LARGE
is generated if the requested color table
is too large to be supported by the implementation, and target
is
not a GL_PROXY_*
target.
GL_INVALID_OPERATION
is generated if a non-zero buffer object name is bound to the
GL_PIXEL_UNPACK_BUFFER
target and the buffer object's data store is currently mapped.
GL_INVALID_OPERATION
is generated if a non-zero buffer object name is bound to the
GL_PIXEL_UNPACK_BUFFER
target and the data would be unpacked from the buffer
object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION
is generated if a non-zero buffer object name is bound to the
GL_PIXEL_UNPACK_BUFFER
target and data
is not evenly divisible
into the number of bytes needed to store in memory a datum indicated by type
.
GL_INVALID_OPERATION
is generated if glColorTable
is executed
between the execution of glBegin and the corresponding
execution of glEnd.
glColorSubTable,
glColorTableParameter
,
glCopyColorTable,
glCopyColorSubTable,
glGetColorTable
Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.