GLCOLORTABLE(3G)

📦 version 1.1, in centos-stream 9, fedora 43, fedora 44

🌸 NAME 🌸

glColorTable — define a color lookup table 💅

Okay so bestie, we're in the GLCOLORTABLE(3G) page, section 3G, and this is the whole entire tea on building color lookup tables. Buckle up. 🎀

📜 C SPECIFICATION 📜

void glColorTable( GLenum target,
                   GLenum internalformat,
                   GLsizei width,
                   GLenum format,
                   GLenum type,
                   const GLvoid *table )

🎀 PARAMETERS 🎀

  • target — has to 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. No substitutions, no vibes-based guessing. ✨
  • 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. That's the whole list, don't @ me. 💀
  • width — how many entries live in the color lookup table that table specifies. 🔢
  • format — the format of the pixel data in table. 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 table. Allowable values: 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. 🦋
  • table — pointer to a one-dimensional array of pixel data that gets processed to build the color table. 🫶

💖 DESCRIPTION 💖

glColorTable can be used two whole ways, and honestly? Versatile queen. ✨

  1. To test the actual size and color resolution of a lookup table given a particular set of parameters, or
  2. To load the contents of a color lookup table.

Use the GL_PROXY_* targets for the first case, and the other targets for the second case. No cap. 💅

🧚 The "actually build a table" targets 🧚

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 table is extracted from memory and processed just as if glDrawPixels were called — but processing stops after the final expansion to RGBA is completed. That's it, we're done there, no further processing, bye. 😌

Then the four scale parameters and the four bias parameters that are defined for the table get used to scale and bias the R, G, B, and A components of each pixel. (Set those scale and bias parameters with glColorTableParameter, iykyk.)

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
────────────────────────────────────────────────────────────────────────
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 [0, width - 1]. 🎯

👑 The proxy targets 👑

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
  • GL_COLOR_TABLE_INTENSITY_SIZE

There is no effect on the image or state of any actual color table. It's just a vibe check, bestie. 🫧

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 lets the application decide if a particular glColorTable command would succeed, and figure out what the resulting color table attributes would be. Very "let me check before I commit" of it. 💅

🌈 What happens when the table is enabled 🌈

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 [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]
─────────────────────────────────────────────────────

🎬 The pipeline, in order 🎬

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. It's a whole assembly line and everyone plays their part. 🔥

🦋 NOTES 🦋

glColorTable is present only if GL_ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS. If it's not there, it's not there, bestie. 🙈

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. Powers of two only, periodt. ✋

💀 ERRORS 💀

  • 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_VALUE is generated if width is less than zero.
  • 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_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 glColorTable is executed between the execution of glBegin and the corresponding execution of glEnd.
🚨 Heads up: you cannot sneak glColorTable in between glBegin and glEnd. The GL will catch you and it will not be cute. 💀

🔍 ASSOCIATED GETS 🔍

glGetColorTableParameter

🫶 SEE ALSO 🫶

  • glColorSubTable(3G)
  • glColorTableParameter(3G)
  • glCopyColorTable(3G)
  • glCopyColorSubTable(3G)
  • glGetColorTable(3G)

and that's the whole page, bestie 💖 — straight from the GLCOLORTABLE(3G) manual, section 3G. Go build something iconic with your lookup tables, you main character. 🌈👑✨

📦 where this page comes from