NAME

glColorTable - define a color lookup table

C SPECIFICATION

void ggllCCoolloorrTTaabbllee( GLenum _t_a_r_g_e_t,
                   GLenum _i_n_t_e_r_n_a_l_f_o_r_m_a_t,
                   GLsizei _w_i_d_t_h,
                   GLenum _f_o_r_m_a_t,
                   GLenum _t_y_p_e,
                   const GLvoid _*_t_a_b_l_e )

PARAMETERS

_t_a_r_g_e_t
Must be one of GGLL__CCOOLLOORR__TTAABBLLEE, GGLL__PPOOSSTT__CCOONNVVOOLLUUTTIIOONN__CCOOLLOORR__TTAABBLLEE, GGLL__PPOOSSTT__CCOOLLOORR__MMAATTRRIIXX__CCOOLLOORR__TTAABBLLEE, GGLL__PPRROOXXYY__CCOOLLOORR__TTAABBLLEE, GGLL__PPRROOXXYY__PPOOSSTT__CCOONNVVOOLLUUTTIIOONN__CCOOLLOORR__TTAABBLLEE, or GGLL__PPRROOXXYY__PPOOSSTT__CCOOLLOORR__MMAATTRRIIXX__CCOOLLOORR__TTAABBLLEE.
_i_n_t_e_r_n_a_l_f_o_r_m_a_t
The internal of the color table. The allowable values are GGLL__AALLPPHHAA, GGLL__AALLPPHHAA44, GGLL__AALLPPHHAA88, GGLL__AALLPPHHAA1122, GGLL__AALLPPHHAA1166, GGLL__LLUUMMIINNAANNCCEE, GGLL__LLUUMMIINNAANNCCEE44, GGLL__LLUUMMIINNAANNCCEE88, GGLL__LLUUMMIINNAANNCCEE1122, GGLL__LLUUMMIINNAANNCCEE1166, GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA, GGLL__LLUUMMIINNAANNCCEE44__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE66__AALLPPHHAA22, GGLL__LLUUMMIINNAANNCCEE88__AALLPPHHAA88, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA44, GGLL__LLUUMMIINNAANNCCEE1122__AALLPPHHAA1122, GGLL__LLUUMMIINNAANNCCEE1166__AALLPPHHAA1166, GGLL__IINNTTEENNSSIITTYY, GGLL__IINNTTEENNSSIITTYY44, GGLL__IINNTTEENNSSIITTYY88, GGLL__IINNTTEENNSSIITTYY1122, GGLL__IINNTTEENNSSIITTYY1166, GGLL__RR33__GG33__BB22, GGLL__RRGGBB, GGLL__RRGGBB44, GGLL__RRGGBB55, GGLL__RRGGBB88, GGLL__RRGGBB1100, GGLL__RRGGBB1122, GGLL__RRGGBB1166, GGLL__RRGGBBAA, GGLL__RRGGBBAA22, GGLL__RRGGBBAA44, GGLL__RRGGBB55__AA11, GGLL__RRGGBBAA88, GGLL__RRGGBB1100__AA22, GGLL__RRGGBBAA1122, and GGLL__RRGGBBAA1166.
_w_i_d_t_h
The number of entries in the color lookup table specified by _t_a_b_l_e.
_f_o_r_m_a_t
The of the pixel data in _t_a_b_l_e. The allowable values are GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, GGLL__LLUUMMIINNAANNCCEE, GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA, GGLL__RRGGBB, GGLL__BBGGRR, GGLL__RRGGBBAA, and GGLL__BBGGRRAA.
_t_y_p_e
The type of the pixel data in _t_a_b_l_e. The allowable values are GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE, GGLL__BBYYTTEE, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT, GGLL__SSHHOORRTT, GGLL__UUNNSSIIGGNNEEDD__IINNTT, GGLL__IINNTT, GGLL__FFLLOOAATT, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, and GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV.
_t_a_b_l_e
Pointer to a one-dimensional array of pixel data that is processed to build the color table.

DESCRIPTION

ggllCCoolloorrTTaabbllee 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 GGLL__PPRROOXXYY__** for the first case and the other targets for the second case.

If _t_a_r_g_e_t is GGLL__CCOOLLOORR__TTAABBLLEE, GGLL__PPOOSSTT__CCOONNVVOOLLUUTTIIOONN__CCOOLLOORR__TTAABBLLEE, or GGLL__PPOOSSTT__CCOOLLOORR__MMAATTRRIIXX__CCOOLLOORR__TTAABBLLEE, ggllCCoolloorrTTaabbllee builds a color lookup table from an array of pixels. The pixel array specified by _w_i_d_t_h, _f_o_r_m_a_t, _t_y_p_e, and _t_a_b_l_e is extracted from memory and processed just as if ggllDDrraawwPPiixxeellss 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 ggllCCoolloorrTTaabblleePPaarraammeetteerr 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 specified by _i_n_t_e_r_n_a_l_f_o_r_m_a_t. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:

center;
lb cb cb cb cb cb cb
l c c c c c c.
_
Internal Format    RedGreenBlueAlphaLuminanceIntensity
_
GGLL__AALLPPHHAA           A
GGLL__LLUUMMIINNAANNCCEE       R
GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA AR
GGLL__IINNTTEENNSSIITTYY       R
GGLL__RRGGBB             RGB
GGLL__RRGGBBAA            RGBA
_

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, _w_i_d_t_h - 1].

If _t_a_r_g_e_t is GGLL__PPRROOXXYY__**, ggllCCoolloorrTTaabbllee recomputes and stores the values of the proxy color table's state variables GGLL__CCOOLLOORR__TTAABBLLEE__FFOORRMMAATT, GGLL__CCOOLLOORR__TTAABBLLEE__WWIIDDTTHH, GGLL__CCOOLLOORR__TTAABBLLEE__RREEDD__SSIIZZEE, GGLL__CCOOLLOORR__TTAABBLLEE__GGRREEEENN__SSIIZZEE, GGLL__CCOOLLOORR__TTAABBLLEE__BBLLUUEE__SSIIZZEE, GGLL__CCOOLLOORR__TTAABBLLEE__AALLPPHHAA__SSIIZZEE, GGLL__CCOOLLOORR__TTAABBLLEE__LLUUMMIINNAANNCCEE__SSIIZZEE, and GGLL__CCOOLLOORR__TTAABBLLEE__IINNTTEENNSSIITTYY__SSIIZZEE. 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 ggllCCoolloorrTTaabbllee 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 ggllGGeettCCoolloorrTTaabblleePPaarraammeetteerr with a target of GGLL__PPRROOXXYY__**. This allows the application to decide if a particular ggllCCoolloorrTTaabbllee 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 of the table.

Each pixel group has color components (R, G, B, A) that 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 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:

center;
cb cb
c l.
_
Representation     Meaning
_
r                  TTaabbllee iinnddeexx ccoommppuutteedd ffrroomm RR
g                  TTaabbllee iinnddeexx ccoommppuutteedd ffrroomm GG
b                  TTaabbllee iinnddeexx ccoommppuutteedd ffrroomm BB
a                  TTaabbllee iinnddeexx ccoommppuutteedd ffrroomm AA
L[i]               LLuummiinnaannccee vvaalluuee aatt ttaabbllee iinnddeexx ii
I[i]               IInntteennssiittyy vvaalluuee aatt ttaabbllee iinnddeexx ii
R[i]               RReedd vvaalluuee aatt ttaabbllee iinnddeexx ii
G[i]               GGrreeeenn vvaalluuee aatt ttaabbllee iinnddeexx ii
B[i]               BBlluuee vvaalluuee aatt ttaabbllee iinnddeexx ii
A[i]               AAllpphhaa vvaalluuee aatt ttaabbllee iinnddeexx ii
_

then the result of color table lookup is as follows:

center;
l l s s s
l l l l l
l l l l l.
_
                   Resulting Texture Components
Table Internal FormatRGBA
_
GGLL__AALLPPHHAA           RGBA[a]
GGLL__LLUUMMIINNAANNCCEE       L[r]L[g]L[b]At
GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA L[r]L[g]L[b]A[a]
GGLL__IINNTTEENNSSIITTYY       I[r]I[g]I[b]I[a]
GGLL__RRGGBB             R[r]G[g]B[b]A
GGLL__RRGGBBAA            R[r]G[g]B[b]A[a]
_

When GGLL__CCOOLLOORR__TTAABBLLEE 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 GGLL__PPOOSSTT__CCOONNVVOOLLUUTTIIOONN__CCOOLLOORR__TTAABBLLEE is enabled. These modified colors are then sent to the color matrix operation. Finally, if GGLL__PPOOSSTT__CCOOLLOORR__MMAATTRRIIXX__CCOOLLOORR__TTAABBLLEE 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

ggllCCoolloorrTTaabbllee is present only if GGLL__AARRBB__iimmaaggiinngg is returned when ggllGGeettSSttrriinngg is called with an argument of GGLL__EEXXTTEENNSSIIOONNSS.

If _t_a_r_g_e_t is set to GGLL__CCOOLLOORR__TTAABBLLEE, GGLL__PPOOSSTT__CCOONNVVOOLLUUTTIIOONN__CCOOLLOORR__TTAABBLLEE, or GGLL__PPOOSSTT__CCOOLLOORR__MMAATTRRIIXX__CCOOLLOORR__TTAABBLLEE, then _w_i_d_t_h must be a power of two or a GGLL__IINNVVAALLIIDD__VVAALLUUEE error is generated.

ERRORS

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_a_r_g_e_t is not one of the allowable values.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _i_n_t_e_r_n_a_l_f_o_r_m_a_t is not one of the allowable values.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _w_i_d_t_h is less than zero.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _f_o_r_m_a_t is not one of the allowable values.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_y_p_e is not one of the allowable values.

GGLL__TTAABBLLEE__TTOOOO__LLAARRGGEE is generated if the requested color table is too large to be supported by the implementation, and _t_a_r_g_e_t is not a GGLL__PPRROOXXYY__** target.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllCCoolloorrTTaabbllee is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

ASSOCIATED GETS

ggllGGeettCCoolloorrTTaabblleePPaarraammeetteerr

SEE ALSO

ggllCCoolloorrSSuubbTTaabbllee((33GG)), ggllCCoolloorrTTaabblleePPaarraammeetteerr((33GG)), ggllCCooppyyCCoolloorrTTaabbllee((33GG)), ggllCCooppyyCCoolloorrSSuubbTTaabbllee((33GG)), ggllGGeettCCoolloorrTTaabbllee((33GG))