glColorTable(3g)

1GLCOLORTABLE(3G)                                              GLCOLORTABLE(3G)
2
3
4

NAME

6       glColorTable - define a color lookup table
7
8

C SPECIFICATION

10       void glColorTable( GLenum target,
11                          GLenum internalformat,
12                          GLsizei width,
13                          GLenum format,
14                          GLenum type,
15                          const GLvoid *table )
16
17

PARAMETERS

19       target          Must        be       one       of       GL_COLOR_TABLE,
20                       GL_POST_CONVOLUTION_COLOR_TABLE,
21                       GL_POST_COLOR_MATRIX_COLOR_TABLE, GL_PROXY_COLOR_TABLE,
22                       GL_PROXY_POST_CONVOLUTION_COLOR_TABLE,               or
23                       GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE.
24
25       internalformat  The internal  of the color table.  The allowable values
26                       are   GL_ALPHA,   GL_ALPHA4,   GL_ALPHA8,   GL_ALPHA12,
27                       GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8,
28                       GL_LUMINANCE12,   GL_LUMINANCE16,   GL_LUMINANCE_ALPHA,
29                       GL_LUMINANCE4_ALPHA4,             GL_LUMINANCE6_ALPHA2,
30                       GL_LUMINANCE8_ALPHA8,            GL_LUMINANCE12_ALPHA4,
31                       GL_LUMINANCE12_ALPHA12,         GL_LUMINANCE16_ALPHA16,
32                       GL_INTENSITY,       GL_INTENSITY4,       GL_INTENSITY8,
33                       GL_INTENSITY12,  GL_INTENSITY16,  GL_R3_G3_B2,  GL_RGB,
34                       GL_RGB4,   GL_RGB5,   GL_RGB8,   GL_RGB10,    GL_RGB12,
35                       GL_RGB16,   GL_RGBA,  GL_RGBA2,  GL_RGBA4,  GL_RGB5_A1,
36                       GL_RGBA8, GL_RGB10_A2, GL_RGBA12, and GL_RGBA16.
37
38       width           The number of entries in the color lookup table  speci‐
39                       fied by table.
40
41       format          The   of the pixel data in table.  The allowable values
42                       are GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA,  GL_LUMINANCE,
43                       GL_LUMINANCE_ALPHA,   GL_RGB,   GL_BGR,   GL_RGBA,  and
44                       GL_BGRA.
45
46       type            The type of the pixel data  in  table.   The  allowable
47                       values       are       GL_UNSIGNED_BYTE,       GL_BYTE,
48                       GL_UNSIGNED_SHORT, GL_SHORT,  GL_UNSIGNED_INT,  GL_INT,
49                       GL_FLOAT,                       GL_UNSIGNED_BYTE_3_3_2,
50                       GL_UNSIGNED_BYTE_2_3_3_REV,    GL_UNSIGNED_SHORT_5_6_5,
51                       GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
52                       GL_UNSIGNED_SHORT_4_4_4_4_REV,
53                       GL_UNSIGNED_SHORT_5_5_5_1,
54                       GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
55                       GL_UNSIGNED_INT_8_8_8_8_REV,
56                       GL_UNSIGNED_INT_10_10_10_2,                         and
57                       GL_UNSIGNED_INT_2_10_10_10_REV.
58
59       table           Pointer  to  a one-dimensional array of pixel data that
60                       is processed to build the color table.
61

DESCRIPTION

63       glColorTable may be used in two ways: to test the actual size and color
64       resolution  of  a lookup table given a particular set of parameters, or
65       to load the  contents  of  a  color  lookup  table.   Use  the  targets
66       GL_PROXY_*  for  the  first  case  and the other targets for the second
67       case.
68
69       If  target  is  GL_COLOR_TABLE,   GL_POST_CONVOLUTION_COLOR_TABLE,   or
70       GL_POST_COLOR_MATRIX_COLOR_TABLE,  glColorTable  builds  a color lookup
71       table from an array of pixels.  The pixel  array  specified  by  width,
72       format,  type, and table is extracted from memory and processed just as
73       if glDrawPixels were called,  but  processing  stops  after  the  final
74       expansion to RGBA is completed.
75
76       The four scale parameters and the four bias parameters that are defined
77       for the table are then used to scale and bias the R, G, B, and A compo‐
78       nents of each pixel.  (Use glColorTableParameter to set these scale and
79       bias parameters.)
80
81       Next, the R, G, B, and A values are clamped to the range [0, 1].   Each
82       pixel  is  then converted to the internal  specified by internalformat.
83       This conversion simply maps the component values of the pixel (R, G, B,
84       and  A)  to  the  values  included  in the internal  (red, green, blue,
85       alpha, luminance, and intensity).  The mapping is as follows:
86
87       ────────────────────────────────────────────────────────────────────────
88       Internal Format      Red   Green   Blue   Alpha   Luminance   Intensity
89       ────────────────────────────────────────────────────────────────────────
90       GL_ALPHA                                    A
91       GL_LUMINANCE                                          R
92       GL_LUMINANCE_ALPHA                          A         R
93       GL_INTENSITY                                                      R
94       GL_RGB                R      G      B
95       GL_RGBA               R      G      B       A
96       ────────────────────────────────────────────────────────────────────────
97
98       Finally, the red, green, blue, alpha, luminance, and/or intensity  com‐
99       ponents  of  the  resulting pixels are stored in the color table.  They
100       form a one-dimensional table with indices in the range [0, width - 1].
101
102       If target is GL_PROXY_*, glColorTable recomputes and stores the  values
103       of  the  proxy  color  table's  state  variables GL_COLOR_TABLE_FORMAT,
104       GL_COLOR_TABLE_WIDTH,                          GL_COLOR_TABLE_RED_SIZE,
105       GL_COLOR_TABLE_GREEN_SIZE,                    GL_COLOR_TABLE_BLUE_SIZE,
106       GL_COLOR_TABLE_ALPHA_SIZE,      GL_COLOR_TABLE_LUMINANCE_SIZE,      and
107       GL_COLOR_TABLE_INTENSITY_SIZE.   There  is  no  effect  on the image or
108       state of any actual color table.  If the specified color table  is  too
109       large  to be supported, then all the proxy state variables listed above
110       are set to zero.  Otherwise, the color  table  could  be  supported  by
111       glColorTable  using  the  corresponding non-proxy target, and the proxy
112       state variables are set as if that target were being defined.
113
114       The   proxy   state   variables   can   be   retrieved    by    calling
115       glGetColorTableParameter  with a target of GL_PROXY_*.  This allows the
116       application to decide if a particular glColorTable command  would  suc‐
117       ceed,  and to determine what the resulting color table attributes would
118       be.
119
120       If a color table is enabled, and its width is non-zero, then  its  con‐
121       tents are used to replace a subset of the components of each RGBA pixel
122       group, based on the internal  of the table.
123
124       Each pixel group has color components (R, G, B,  A)  that  are  in  the
125       range [0.0, 1.0].  The color components are rescaled to the size of the
126       color lookup table to form an index.  Then a subset of  the  components
127       based  on  the  internal   of the table are replaced by the table entry
128       selected by that index.  If the color components and  contents  of  the
129       table are represented as follows:
130
131                  ──────────────────────────────────────────────────
132                  Representation               Meaning
133                  ──────────────────────────────────────────────────
134                        r          Table index computed from R
135                        g          Table index computed from G
136                        b          Table index computed from B
137                        a          Table index computed from A
138                       L[i]        Luminance value at table index i
139                       I[i]        Intensity value at table index i
140                       R[i]        Red value at table index i
141                       G[i]        Green value at table index i
142                       B[i]        Blue value at table index i
143                       A[i]        Alpha value at table index i
144                  ──────────────────────────────────────────────────
145
146       then the result of color table lookup is as follows:
147
148                ─────────────────────────────────────────────────────
149                                        Resulting Texture Components
150                Table Internal Format   R       G      B       A
151                ─────────────────────────────────────────────────────
152                GL_ALPHA                R       G      B       A[a]
153                GL_LUMINANCE            L[r]    L[g]   L[b]    At
154                GL_LUMINANCE_ALPHA      L[r]    L[g]   L[b]    A[a]
155                GL_INTENSITY            I[r]    I[g]   I[b]    I[a]
156                GL_RGB                  R[r]    G[g]   B[b]    A
157                GL_RGBA                 R[r]    G[g]   B[b]    A[a]
158                ─────────────────────────────────────────────────────
159
160       When GL_COLOR_TABLE is enabled, the colors resulting from the pixel map
161       operation (if it is enabled) are  mapped  by  the  color  lookup  table
162       before  being passed to the convolution operation. The colors resulting
163       from the convolution operation are modified  by  the  post  convolution
164       color  lookup  table  when  GL_POST_CONVOLUTION_COLOR_TABLE is enabled.
165       These modified colors are then sent  to  the  color  matrix  operation.
166       Finally,  if  GL_POST_COLOR_MATRIX_COLOR_TABLE  is  enabled, the colors
167       resulting from the color matrix operation are mapped by the post  color
168       matrix color lookup table before being used by the histogram operation.
169

NOTES

171       glColorTable  is  present  only  if  GL_ARB_imaging  is  returned  when
172       glGetString is called with an argument of GL_EXTENSIONS.
173
174       If target is set to GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or
175       GL_POST_COLOR_MATRIX_COLOR_TABLE,  then width must be a power of two or
176       a GL_INVALID_VALUE error is generated.
177

ERRORS

179       GL_INVALID_ENUM is generated if target is not one of the allowable val‐
180       ues.
181
182       GL_INVALID_ENUM is generated if internalformat is not one of the allow‐
183       able values.
184
185       GL_INVALID_VALUE is generated if width is less than zero.
186
187       GL_INVALID_ENUM is generated if format is not one of the allowable val‐
188       ues.
189
190       GL_INVALID_ENUM  is  generated if type is not one of the allowable val‐
191       ues.
192
193       GL_TABLE_TOO_LARGE is generated if the requested  color  table  is  too
194       large  to  be  supported  by  the  implementation,  and target is not a
195       GL_PROXY_* target.
196
197       GL_INVALID_OPERATION is generated if glColorTable is  executed  between
198       the execution of glBegin and the corresponding execution of glEnd.
199

ASSOCIATED GETS

201       glGetColorTableParameter
202