GLCOLORTABLESGI(3gl)GLCOLORTABLESGI(3gl)NAMEglColorTableSGI - define a color lookup table
C SPECIFICATION
void glColorTableSGI( GLenum target,
GLenum internalformat,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid* table)
PARAMETERS
target Must be GL_TEXTURE_COLOR_TABLE_SGI, GL_COLOR_TABLE_SGI,
GL_POST_CONVOLUTION_COLOR_TABLE_SGI, GL_PROXY_TEX‐
TURE_COLOR_TABLE_SGI, GL_PROXY_COLOR_TABLE_SGI or
GL_PROXY_POST_CONVOLUTION_COLOR_TABLE_SGI.
internalformat The internal storage format of the color table. Must
be one of the following symbolic constants: GL_ALPHA,
GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMI‐
NANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12,
GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMI‐
NANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMI‐
NANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMI‐
NANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY,
GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTEN‐
SITY16, 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,
GL_RGBA16.
width The number of entries in the color lookup table speci‐
fied by table.
format The format of the pixel data in table. The allowable
values are: GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA,
GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, GL_RGBA,
GL_ABGR_EXT.
type The type of the pixel data in table. Allowable values
are : GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT,
GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT.
table Pointer to a one-dimensional array of pixel data that
is processed to build the color table.
DESCRIPTIONglColorTableSGI is part of the GL_SGI_color_table extension, and is
also used by the GL_SGI_texture_color_table extension.
glColorTableSGI may be used in two ways: to test the actual size and
color resolution of a lookup table given a particular set of parame‐
ters, 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 target is GL_TEXTURE_COLOR_TABLE_SGI, GL_COLOR_TABLE_SGI,
GL_POST_CONVOLUTION_COLOR_TABLE_SGI. glColorTableSGI builds a color
lookup table from an array of pixels. The pixel array specified by
width, format, type, and table 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 compo‐
nents of each pixel. Use glColorTableParameterSGI to set these scale
and bias parameters.
Next, the R, G, B, and A values are clamped to the range [0,1]. Each
pixel is then converted to the internal format specified by internal‐
format. 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 fol‐
lows:
┌────────────────────────────────────────────────────────────────────────────────┐
│Base Stored values │
│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 │
└────────────────────────────────────────────────────────────────────────────────┘
The base internal format is derived from the user specified internal
formats as follows: All resolutions of a particular internal format,
for example GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA, GL_ALPHA16 are
of base internal format GL_ALPHA. Similarly, all resolutions of inter‐
nal format GL_LUMINANCE are of base internal format GL_LUMINANCE. All
resolutions of GL_INTENSITY are of base format GL_INTENSITY. All reso‐
lutions of GL_LUMINANCE_ALPHA are of base format GL_LUMINANCE_ALPHA.
All resolutions of GL_RGB are of base format GL_RGB and all resolutions
of GL_RGBA are of base format GL_RGBA.
Finally, the red, green, blue, alpha, luminance, and/or intensity com‐
ponents of the resulting pixels are stored in the color table. They
form a one-dimensional table with indices in the range [0, width -1].
If target is GL_PROXY_*, glColorTableSGI recomputes and stores the val‐
ues of the proxy color table's state variables GL_COLOR_TABLE_FOR‐
MAT_SGI, GL_COLOR_TABLE_WIDTH_SGI, GL_COLOR_TABLE_RED_SIZE_SGI,
GL_COLOR_TABLE_GREEN_SIZE_SGI, GL_COLOR_TABLE_BLUE_SIZE_SGI,
GL_COLOR_TABLE_ALPHA_SIZE_SGI, GL_COLOR_TABLE_LUMINANCE_SIZE_SGI, and
GL_COLOR_TABLE_INTENSITY_SIZE_SGI. 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
glColorTableSGI 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 glGetCol‐
orTableParameterSGI with a target of GL_PROXY_*. This allows the
application to decide if a particular glColorTableSGI command would
succeed, and determine what the resulting color table attributes would
be.
If a color table is enabled, and its width is non-zero, then its con‐
tents 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) which are in the
range [0.0, 1.0]. The color components are rescaled to the size of the
color lookup table to form an index. Then a subset of the components
based on the internal format of the table are replaced by the table
entry selected by that index. If the color components and contents of
the table are represented as follows:
┌──────────────────────────────────────────────────┐
│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_TEXTURE_COLOR_TABLE_SGI is enabled, the filtered colors result‐
ing from texturing are mapped by the texture color lookup table. The
result of the table lookup is passed to the texture environment func‐
tion to be applied to pixel fragments.
The texture color table can be used to expand the range of colors rep‐
resented by small texels, to select a small ``window'' from a texture
image with larger dynamic range, to provide simple lighting for volume
rendering, to implement a restricted kind of color-index texture, or to
linearize the results of color-space conversions performed by multidi‐
mensional texturing.
When GL_COLOR_TABLE_SGI is enabled, the pixel transfer (see glPixel‐
Transfer) stage adds an additional color table lookup after the pixel
map (glPixelMap) color-to-color map. All components after the color ta‐
ble lookup are clamped to the range [0 1]. The color table lookup when
enabled affects glDrawPixels, glCopyPixels, glReadPixels, glTexImage1D,
glTexImage2D, glTexImage3DEXT, glTexSubImage1D, glTexSubImage2D, glTex‐
SubImage3DEXT, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D,
glCopyTexSubImage2D, and glCopyTexSubImage3DEXT.
When GL_POST_CONVOLUTION_COLOR_TABLE_SGI is enabled, the pixel transfer
(see glPixelTransfer) stage adds an additional color table lookup after
the convolution (glConvolutionFilterEXT) operation. This color table
lookup only occurs if convolution is enabled. All components after the
color table lookup are clamped to the range [0 1]. The color table
lookup when enabled affects glDrawPixels, glCopyPixels, glReadPixels,
glTexImage1D, glTexImage2D, glTexImage3DEXT, glTexSubImage1D, glTex‐
SubImage2D, glTexSubImage3DEXT, glCopyTexImage1D, glCopyTexImage2D,
glCopyTexSubImage1D, glCopyTexSubImage2D, and glCopyTexSubImage3DEXT.
glPushAttrib that includes the symbolic mask constant GL_TEXTURE_BIT
will push the scale and bias values of texture color table.
glPushAttrib that includes the symbolic mask constant GL_PIXEL_MODE_BIT
will push the scale and bias values of the color table.
NOTES
If target is set to GL_TEXTURE_COLOR_TABLE_SGI or GL_COLOR_TABLE_SGI,
then width must be a power of two or a GL_INVALID_VALUE error is gener‐
ated. All machines support table widths up to and including 256; some
machines also support larger tables.
If target is set to GL_TEXTURE_COLOR_TABLE_SGI and the GL_SGI_tex‐
ture_color_table extension is not supported then an GL_INVALID_ENUM
error is generated.
ERRORS
GL_INVALID_ENUM is generated if target is not one of the allowable val‐
ues.
GL_INVALID_ENUM is generated if internalformat is not one of the allow‐
able values.
GL_INVALID_VALUE is generated if width is less than zero.
GL_INVALID_ENUM is generated if format is not one of the allowable val‐
ues.
GL_INVALID_ENUM is generated if type is not one of the allowable val‐
ues.
GL_TABLE_TOO_LARGE_EXT 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 glColorTableSGI is executed
between the execution of glBegin and the corresponding execution of
glEnd.
ASSOCIATED GETS
glGetColorTableParameterSGI
glIsEnabled with argument GL_COLOR_TABLE_SGI or GL_TEXTURE_COLOR_TA‐
BLE_SGI
SEE ALSO
glColorTableParameterSGI, glCopyColorTableSGI, glGetColorTableSGI.
glPushAttrib, glPixelTransfer, glPixelMap, glDrawPixels, glCopyPixels,
glReadPixels, glTexImage1D, glTexImage2D, glTexImage3DEXT, glTexSubIm‐
age1D, glTexSubImage2D, glTexSubImage3DEXT, glCopyTexImage1D, glCopy‐
TexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubIm‐
age3DEXT, glConvolutionFilter1DEXT, glConvolutionFilter2DEXT, glSepara‐
bleFilter2DEXT.
15 Mar 97 GLCOLORTABLESGI(3gl)
