glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
NAME
glColorTableSGI - 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 GLTEXTURECOLORTABLESGI, GLCOLORTABLESGI,
GLPOSTCONVOLUTIONCOLORTABLESGI,
GLPOSTCOLORMATRIXCOLORTABLESGI,
GLPROXYTEXTURECOLORTABLESGI,
GLPROXYCOLORTABLESGI,
GLPROXYPOSTCONVOLUTIONCOLORTABLESGI, or
GLPROXYPOSTCOLORMATRIXCOLORTABLESGI.
internalformat The internal format of the color table. The allowable
values are GLALPHA, GLALPHA4EXT, GLALPHA8EXT,
GLALPHA12EXT, GLALPHA16EXT, GLLUMINANCE,
GLLUMINANCE4EXT, GLLUMINANCE8EXT, GLLUMINANCE12EXT,
GLLUMINANCE16EXT, GLLUMINANCEALPHA,
GLLUMINANCE4ALPHA4EXT, GLLUMINANCE6ALPHA2EXT,
GLLUMINANCE8ALPHA8EXT, GLLUMINANCE12ALPHA4EXT,
GLLUMINANCE12ALPHA12EXT, GLLUMINANCE16ALPHA16EXT,
GLINTENSITYEXT, GLINTENSITY4EXT, GLINTENSITY8EXT,
GLINTENSITY12EXT, GLINTENSITY16EXT, GLRGB,
GLRGB2EXT, GLRGB4EXT, GLRGB5EXT, GLRGB8EXT,
GLRGB10EXT, GLRGB12EXT, GLRGB16EXT, GLRGBA,
GLRGBA2EXT, GLRGBA4EXT, GLRGB5A1EXT, GLRGBA8EXT,
GLRGB10A2EXT, GLRGBA12EXT, and GLRGBA16EXT.
width The number of entries in the color lookup table specified
by table.
format The format of the pixel data in table. The allowable
values are GLRED, GLGREEN, GLBLUE, GLALPHA,
GLLUMINANCE, GLLUMINANCEALPHA, GLRGB, GLRGBA, and
GLABGREXT.
type The type of the pixel data in table. The allowable
values are GLUNSIGNEDBYTE, GLBYTE, GLUNSIGNEDSHORT,
GLSHORT, GLUNSIGNEDINT, GLINT, GLFLOAT,
GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT,
GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, and
Page 1
glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
GLUNSIGNEDINT1010102EXT.
table Pointer to a one-dimensional array of pixel data that is
processed to build the color table.
DESCRIPTION
glColorTableSGI is part of the SGIcolortable extension, and is also
used by the SGItexturecolortable 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 parameters,
or to load the contents of a color lookup table. Use the targets
GLPROXY* for the first case and the other targets for the second case.
If target is GLTEXTURECOLORTABLESGI, GLCOLORTABLESGI,
GLPOSTCONVOLUTIONCOLORTABLESGI, or
GLPOSTCOLORMATRIXCOLORTABLESGI, 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
components 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
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
_______________________________________________________________________
GLALPHA A
GLLUMINANCE R
GLLUMINANCEALPHA A R
GLINTENSITYEXT R
GLRGB R G B
GLRGBA 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 [0, width - 1].
If target is GLPROXY*, glColorTableSGI recomputes and stores the values
of the proxy color table's state variables GLCOLORTABLEFORMATSGI,
GLCOLORTABLEWIDTHSGI, GLCOLORTABLEREDSIZESGI,
GLCOLORTABLEGREENSIZESGI, GLCOLORTABLEBLUESIZESGI,
GLCOLORTABLEALPHASIZESGI, GLCOLORTABLELUMINANCESIZESGI, and
Page 2
glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
GLCOLORTABLEINTENSITYSIZESGI. 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
glGetColorTableParameterSGI with a target of GLPROXY*. 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 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) 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
_____________________________________________________
GLALPHA R G B A[a]
GLLUMINANCE L[r] L[g] L[b] At
GLLUMINANCEALPHA L[r] L[g] L[b] A[a]
GLINTENSITY I[r] I[g] I[b] I[a]
GLRGB R[r] G[g] B[b] A
GLRGBA R[r] G[g] B[b] A[a]
When GLTEXTURECOLORTABLESGI is enabled, the filtered colors resulting
from texturing are mapped by the texture color lookup table. The result
of the table lookup is passed to the texture environment function to be
Page 3
glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
applied to pixel fragments.
The texture color table can be used to expand the range of colors
represented 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
multidimensional texturing.
When GLCOLORTABLESGI 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 GLPOSTCONVOLUTIONCOLORTABLESGI is enabled. These
modified colors are then sent to the color matrix operation. Finally, if
GLPOSTCOLORMATRIXCOLORTABLESGI 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.
NOTES
If target is set to GLTEXTURECOLORTABLESGI, GLCOLORTABLESGI,
GLPOSTCONVOLUTIONCOLORTABLESGI or
GLPOSTCOLORMATRIXCOLORTABLESGI then width must be a power of two or
a GLINVALIDVALUE error is generated. All machines support table widths
up to and including 256; some machines also support larger tables.
If target is set to GLTEXTURECOLORTABLESGI and the
SGItexturecolortable extension is not supported then an
GLINVALIDENUM error is generated.
If target is set to GLCOLORTABLESGI,
GLPOSTCONVOLUTIONCOLORTABLESGI, or
GLPOSTCOLORMATRIXCOLORTABLESGI and the SGIcolortable extension is
not supported then an GLINVALIDENUM error is generated.
If type is set to GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, or GLUNSIGNEDINT1010102EXT and the
EXTpackedpixels extension is not supported then a GLINVALIDENUM error
is generated.
See glIntro for more information on using extensions.
ERRORS
GLINVALIDENUM is generated if target is not one of the allowable
values.
GLINVALIDENUM is generated if internalformat is not one of the
allowable values.
Page 4
glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
GLINVALIDVALUE is generated if width is less than zero.
GLINVALIDENUM is generated if format is not one of the allowable
values.
GLINVALIDENUM is generated if type is not one of the allowable values.
GLTABLETOOLARGEEXT is generated if the requested color table is too
large to be supported by the implementation, and target is not a
GLPROXY* target.
GLINVALIDOPERATION is generated if glColorTableSGI is executed between
the execution of glBegin and the corresponding execution of glEnd.
ASSOCIATED GETS
glGetColorTableParameterSGI
MACHINE DEPENDENCIES
On RealityEngine, RealityEngine2, and VTX systems, SGIcolortable is
supported with these restrictions:
1. Only the texture color table is supported. The target color
table must be GLTEXTURECOLORTABLESGI or
GLPROXYTEXTURECOLORTABLESGI.
2. The maximum image width is 256 pixels.
3. Only image types GLUNSIGNEDBYTE and GLUNSIGNEDSHORT are
supported.
4. The GLUNPACKSWAPBYTES pixel storage mode is not supported.
Calling glColorTableSGI when GLUNPACKSWAPBYTES is GLTRUE
results in a GLINVALIDOPERATION error.
5. The packed pixel types GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, and GLUNSIGNEDINT1010102EXT
are not supported.
The SGItexturecolortable extension is supported on RealityEngine,
RealityEngine2, and VTX systems and on InfiniteReality systems.
The SGItexturecolortable extension is supported on High Impact and
Maximum Impact. However, on Indigo2 systems certain combinations of
texture internal format and texture color table internal format do not
work:
Texture Texture Color Table
________________________________________
Page 5
glColorTableSGI(3G) OpenGL Reference glColorTableSGI(3G)
GLLUMINANCE GLRGB
GLLUMINANCEALPHA GLRGB
all formats GLRGBA
all formats GLINTENSITY
High Impact and Maximum Impact on Octane systems support all texture
color table formats except GLRGBA, or GLINTENSITY with texture format
GLRGBA.
On High Impact and Maximum Impact systems, the texture color table will
give incorrect results if GLFOGFUNCSGIS is enabled.
SEE ALSO
glColorTableParameterSGI, glCopyColorTableSGI, glGetColorTableSGI.
Page 6