<div class="refentry" lang="en" xml:lang="en"><a id="glColorTable"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glColorTable — define a color lookup table</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table><tr><td><code class="funcdef">void <b class="fsfunc">glColorTable</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">internalformat</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">width</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">format</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const GLvoid *  </td><td><var class="pdparam">data</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>

Must be one of

<code class="constant">GL_COLOR_TABLE</code>,

<code class="constant">GL_POST_CONVOLUTION_COLOR_TABLE</code>,

<code class="constant">GL_POST_COLOR_MATRIX_COLOR_TABLE</code>,

<code class="constant">GL_PROXY_COLOR_TABLE</code>,

<code class="constant">GL_PROXY_POST_CONVOLUTION_COLOR_TABLE</code>,

or

<code class="constant">GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE</code>.

</p></dd><dt><span class="term"><em class="parameter"><code>internalformat</code></em></span></dt><dd><p>

The internal format of the color table.

The allowable values are

<code class="constant">GL_ALPHA</code>,

<code class="constant">GL_ALPHA4</code>,

<code class="constant">GL_ALPHA8</code>,

<code class="constant">GL_ALPHA12</code>,

<code class="constant">GL_ALPHA16</code>,

<code class="constant">GL_LUMINANCE</code>,

<code class="constant">GL_LUMINANCE4</code>,

<code class="constant">GL_LUMINANCE8</code>,

<code class="constant">GL_LUMINANCE12</code>,

<code class="constant">GL_LUMINANCE16</code>,

<code class="constant">GL_LUMINANCE_ALPHA</code>,

<code class="constant">GL_LUMINANCE4_ALPHA4</code>,

<code class="constant">GL_LUMINANCE6_ALPHA2</code>,

<code class="constant">GL_LUMINANCE8_ALPHA8</code>,

<code class="constant">GL_LUMINANCE12_ALPHA4</code>,

<code class="constant">GL_LUMINANCE12_ALPHA12</code>,

<code class="constant">GL_LUMINANCE16_ALPHA16</code>,

<code class="constant">GL_INTENSITY</code>,

<code class="constant">GL_INTENSITY4</code>,

<code class="constant">GL_INTENSITY8</code>,

<code class="constant">GL_INTENSITY12</code>,

<code class="constant">GL_INTENSITY16</code>,

<code class="constant">GL_R3_G3_B2</code>,

<code class="constant">GL_RGB</code>,

<code class="constant">GL_RGB4</code>,

<code class="constant">GL_RGB5</code>,

<code class="constant">GL_RGB8</code>,

<code class="constant">GL_RGB10</code>,

<code class="constant">GL_RGB12</code>,

<code class="constant">GL_RGB16</code>,

<code class="constant">GL_RGBA</code>,

<code class="constant">GL_RGBA2</code>,

<code class="constant">GL_RGBA4</code>,

<code class="constant">GL_RGB5_A1</code>,

<code class="constant">GL_RGBA8</code>,

<code class="constant">GL_RGB10_A2</code>,

<code class="constant">GL_RGBA12</code>, and

<code class="constant">GL_RGBA16</code>.

</p></dd><dt><span class="term"><em class="parameter"><code>width</code></em></span></dt><dd><p>

The number of entries in the color lookup table specified by <em class="parameter"><code>data</code></em>.

</p></dd><dt><span class="term"><em class="parameter"><code>format</code></em></span></dt><dd><p>

The format of the pixel data in <em class="parameter"><code>data</code></em>.

The allowable values are

<code class="constant">GL_RED</code>,

<code class="constant">GL_GREEN</code>,

<code class="constant">GL_BLUE</code>,

<code class="constant">GL_ALPHA</code>,

<code class="constant">GL_LUMINANCE</code>,

<code class="constant">GL_LUMINANCE_ALPHA</code>,

<code class="constant">GL_RGB</code>,

<code class="constant">GL_BGR</code>,

<code class="constant">GL_RGBA</code>, and

<code class="constant">GL_BGRA</code>.

</p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>

The type of the pixel data in <em class="parameter"><code>data</code></em>.

The allowable values are

<code class="constant">GL_UNSIGNED_BYTE</code>,

<code class="constant">GL_BYTE</code>,

<code class="constant">GL_UNSIGNED_SHORT</code>,

<code class="constant">GL_SHORT</code>,

<code class="constant">GL_UNSIGNED_INT</code>,

<code class="constant">GL_INT</code>,

<code class="constant">GL_FLOAT</code>,

<code class="constant">GL_UNSIGNED_BYTE_3_3_2</code>,

<code class="constant">GL_UNSIGNED_BYTE_2_3_3_REV</code>,

<code class="constant">GL_UNSIGNED_SHORT_5_6_5</code>,

<code class="constant">GL_UNSIGNED_SHORT_5_6_5_REV</code>,

<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4</code>,

<code class="constant">GL_UNSIGNED_SHORT_4_4_4_4_REV</code>,

<code class="constant">GL_UNSIGNED_SHORT_5_5_5_1</code>,

<code class="constant">GL_UNSIGNED_SHORT_1_5_5_5_REV</code>,

<code class="constant">GL_UNSIGNED_INT_8_8_8_8</code>,

<code class="constant">GL_UNSIGNED_INT_8_8_8_8_REV</code>,

<code class="constant">GL_UNSIGNED_INT_10_10_10_2</code>, and

<code class="constant">GL_UNSIGNED_INT_2_10_10_10_REV</code>.

</p></dd><dt><span class="term"><em class="parameter"><code>data</code></em></span></dt><dd><p>

Pointer to a one-dimensional array of pixel data that is processed to

build the color table.

</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>

<code class="function">glColorTable</code> 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 <code class="constant">GL_PROXY_*</code> for the first case

and the other targets for the second case.

</p><p>

If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target

(see <a class="citerefentry" href="glBindBuffer"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a color table is

specified, <em class="parameter"><code>data</code></em> is treated as a byte offset into the buffer object's data store.

</p><p>

If <em class="parameter"><code>target</code></em> is <code class="constant">GL_COLOR_TABLE</code>,

<code class="constant">GL_POST_CONVOLUTION_COLOR_TABLE</code>,

or

<code class="constant">GL_POST_COLOR_MATRIX_COLOR_TABLE</code>,

<code class="function">glColorTable</code> builds a color lookup table from an array of pixels.

The pixel array specified by <em class="parameter"><code>width</code></em>, <em class="parameter"><code>format</code></em>, <em class="parameter"><code>type</code></em>, and <em class="parameter"><code>data</code></em>

is extracted from memory and

processed just as if <a class="citerefentry" href="glDrawPixels"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a> were called, but processing

stops after the final expansion to RGBA is completed.

</p><p>

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 <code class="function">glColorTableParameter</code> to set these scale and bias

parameters.)

</p><p>

Next, the R, G, B, and A values are clamped to the range

<math overflow="scroll">

<mfenced open="[" close="]">

<mn>0</mn>

<mn>1</mn>

</mfenced>

</math>.

Each pixel is then converted to the internal format specified by

<em class="parameter"><code>internalformat</code></em>.

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:

</p><p>

</p><div class="informaltable"><table><colgroup><col /><col /><col /><col /><col /><col /><col /></colgroup><thead><tr><th><span class="bold"><strong>

Internal Format

</strong></span></th><th class="center"><span class="bold"><strong>

Red

</strong></span></th><th class="center"><span class="bold"><strong>

Green

</strong></span></th><th class="center"><span class="bold"><strong>

Blue

</strong></span></th><th class="center"><span class="bold"><strong>

Alpha

</strong></span></th><th class="center"><span class="bold"><strong>

Luminance

</strong></span></th><th class="center"><span class="bold"><strong>

Intensity

</strong></span></th></tr></thead><tbody><tr><td>

<code class="constant">GL_ALPHA</code>

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

A

</td><td class="center">

</td><td class="center">

</td></tr><tr><td>

<code class="constant">GL_LUMINANCE</code>

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

R

</td><td class="center">

</td></tr><tr><td>

<code class="constant">GL_LUMINANCE_ALPHA</code>

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

A

</td><td class="center">

R

</td><td class="center">

</td></tr><tr><td>

<code class="constant">GL_INTENSITY</code>

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td><td class="center">

R

</td></tr><tr><td>

<code class="constant">GL_RGB</code>

</td><td class="center">

R

</td><td class="center">

G

</td><td class="center">

B

</td><td class="center">

</td><td class="center">

</td><td class="center">

</td></tr><tr><td>

<code class="constant">GL_RGBA</code>

</td><td class="center">

R

</td><td class="center">

G

</td><td class="center">

B

</td><td class="center">

A

</td><td class="center">

</td><td class="center">

</td></tr></tbody></table></div><p>

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

<math overflow="scroll">

<mfenced open="[" close="]">

<mn>0</mn>

<mrow>

<mi mathvariant="italic">width</mi>

<mo>-</mo>

<mn>1</mn>

</mrow>

</mfenced>

</math>.

</p><p>

If <em class="parameter"><code>target</code></em> is <code class="constant">GL_PROXY_*</code>,

<code class="function">glColorTable</code> recomputes and stores the values of the proxy color table's state

variables

<code class="constant">GL_COLOR_TABLE_FORMAT</code>,

<code class="constant">GL_COLOR_TABLE_WIDTH</code>,

<code class="constant">GL_COLOR_TABLE_RED_SIZE</code>,

<code class="constant">GL_COLOR_TABLE_GREEN_SIZE</code>,

<code class="constant">GL_COLOR_TABLE_BLUE_SIZE</code>,

<code class="constant">GL_COLOR_TABLE_ALPHA_SIZE</code>,

<code class="constant">GL_COLOR_TABLE_LUMINANCE_SIZE</code>, and

<code class="constant">GL_COLOR_TABLE_INTENSITY_SIZE</code>.

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 <code class="function">glColorTable</code>

using the corresponding non-proxy target,

and the proxy state variables are set as if that target were being defined.

</p><p>

The proxy state variables can be retrieved by calling

<a class="citerefentry" href="glGetColorTableParameter"><span class="citerefentry"><span class="refentrytitle">glGetColorTableParameter</span></span></a> with a target of

<code class="constant">GL_PROXY_*</code>.

This allows the application to decide if a particular <code class="function">glColorTable</code>

command would succeed, and to determine what the resulting color table

attributes would be.

</p><p>

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.

</p><p>

Each pixel group has color components (R, G, B, A)

that are in the range

<math overflow="scroll">

<mfenced open="[" close="]">

<mn>0.0</mn>

<mn>1.0</mn>

</mfenced>

</math>.

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:

</p><p>

</p><div class="informaltable"><table><colgroup><col /><col /></colgroup><thead><tr><th class="center"><span class="bold"><strong>

Representation

</strong></span></th><th class="center"><span class="bold"><strong>

Meaning

</strong></span></th></tr></thead><tbody><tr><td class="center">

<code class="code">r</code>

</td><td>

Table index computed from <code class="code">R</code>

</td></tr><tr><td class="center">

<code class="code">g</code>

</td><td>

Table index computed from <code class="code">G</code>

</td></tr><tr><td class="center">

<code class="code">b</code>

</td><td>

Table index computed from <code class="code">B</code>

</td></tr><tr><td class="center">

<code class="code">a</code>

</td><td>

Table index computed from <code class="code">A</code>

</td></tr><tr><td class="center">

<code class="code">L[i]</code>

</td><td>

Luminance value at table index <code class="code">i</code>

</td></tr><tr><td class="center">

<code class="code">I[i]</code>

</td><td>

Intensity value at table index <code class="code">i</code>

</td></tr><tr><td class="center">

<code class="code">R[i]</code>

</td><td>

Red value at table index <code class="code">i</code>

</td></tr><tr><td class="center">

<code class="code">G[i]</code>

</td><td>

Green value at table index <code class="code">i</code>

</td></tr><tr><td class="center">

<code class="code">B[i]</code>

</td><td>

Blue value at table index <code class="code">i</code>

</td></tr><tr><td class="center">

<code class="code">A[i]</code>

</td><td>

Alpha value at table index <code class="code">i</code>

</td></tr></tbody></table></div><p>

then the result of color table lookup is as follows:

</p><p>

</p><div class="informaltable"><table><colgroup><col /><col /><col /><col /><col /></colgroup><thead><tr><th><span class="bold"><strong>

</strong></span></th><th colspan="4" class="center"><span class="bold"><strong>

Resulting Texture Components

</strong></span></th></tr><tr><th><span class="bold"><strong>

Table Internal Format

</strong></span></th><th class="center"><span class="bold"><strong>

R

</strong></span></th><th class="center"><span class="bold"><strong>

G

</strong></span></th><th class="center"><span class="bold"><strong>

B

</strong></span></th><th class="center"><span class="bold"><strong>

A

</strong></span></th></tr></thead><tbody><tr><td>

<code class="constant">GL_ALPHA</code>

</td><td class="center">

<code class="code">R</code>

</td><td class="center">

<code class="code">G</code>

</td><td class="center">

<code class="code">B</code>

</td><td class="center">

<code class="code">A[a]</code>

</td></tr><tr><td>

<code class="constant">GL_LUMINANCE</code>

</td><td class="center">

<code class="code">L[r]</code>

</td><td class="center">

<code class="code">L[g]</code>

</td><td class="center">

<code class="code">L[b]</code>

</td><td class="center">

<code class="code">At</code>

</td></tr><tr><td>

<code class="constant">GL_LUMINANCE_ALPHA</code>

</td><td class="center">

<code class="code">L[r]</code>

</td><td class="center">

<code class="code">L[g]</code>

</td><td class="center">

<code class="code">L[b]</code>

</td><td class="center">

<code class="code">A[a]</code>

</td></tr><tr><td>

<code class="constant">GL_INTENSITY</code>

</td><td class="center">

<code class="code">I[r]</code>

</td><td class="center">

<code class="code">I[g]</code>

</td><td class="center">

<code class="code">I[b]</code>

</td><td class="center">

<code class="code">I[a]</code>

</td></tr><tr><td>

<code class="constant">GL_RGB</code>

</td><td class="center">

<code class="code">R[r]</code>

</td><td class="center">

<code class="code">G[g]</code>

</td><td class="center">

<code class="code">B[b]</code>

</td><td class="center">

<code class="code">A</code>

</td></tr><tr><td>

<code class="constant">GL_RGBA</code>

</td><td class="center">

<code class="code">R[r]</code>

</td><td class="center">

<code class="code">G[g]</code>

</td><td class="center">

<code class="code">B[b]</code>

</td><td class="center">

<code class="code">A[a]</code>

</td></tr></tbody></table></div><p>

When <code class="constant">GL_COLOR_TABLE</code> 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

<code class="constant">GL_POST_CONVOLUTION_COLOR_TABLE</code>

is enabled. These modified colors are then sent to the color matrix operation.

Finally, if <code class="constant">GL_POST_COLOR_MATRIX_COLOR_TABLE</code>

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.

</p><p>

</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>

<code class="function">glColorTable</code> is present only if <code class="code">ARB_imaging</code> is returned when <a class="citerefentry" href="glGetString"><span class="citerefentry"><span class="refentrytitle">glGetString</span></span></a>

is called with an argument of <code class="constant">GL_EXTENSIONS</code>.

</p><p>

If <em class="parameter"><code>target</code></em> is set to <code class="constant">GL_COLOR_TABLE</code>,

<code class="constant">GL_POST_CONVOLUTION_COLOR_TABLE</code>,

or <code class="constant">GL_POST_COLOR_MATRIX_COLOR_TABLE</code>,

then <em class="parameter"><code>width</code></em> must be a power of two or a <code class="constant">GL_INVALID_VALUE</code>

error is generated.

</p><p>

</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>

<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not one of the allowable

values.

</p><p>

<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>internalformat</code></em> is not one of the

allowable values.

</p><p>

<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>format</code></em> is not one of the allowable

values.

</p><p>

<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>type</code></em> is not one of the allowable

values.

</p><p>

<code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>width</code></em> is less than zero.

</p><p>

<code class="constant">GL_TABLE_TOO_LARGE</code> is generated if the requested color table

is too large to be supported by the implementation, and <em class="parameter"><code>target</code></em> is

not a <code class="constant">GL_PROXY_*</code> target.

</p><p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the

<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the buffer object's data store is currently mapped.

</p><p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the

<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and the data would be unpacked from the buffer

object such that the memory reads required would exceed the data store size.

</p><p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the

<code class="constant">GL_PIXEL_UNPACK_BUFFER</code> target and <em class="parameter"><code>data</code></em> is not evenly divisible

into the number of bytes needed to store in memory a datum indicated by <em class="parameter"><code>type</code></em>.

</p><p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glColorTable</code> is executed

between the execution of <a class="citerefentry" href="glBegin"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding

execution of <a class="citerefentry" href="glEnd"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.

</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>

<a class="citerefentry" href="glGetColorTableParameter"><span class="citerefentry"><span class="refentrytitle">glGetColorTableParameter</span></span></a>

</p><p>

<a class="citerefentry" href="glGet"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_PIXEL_UNPACK_BUFFER_BINDING</code>

</p></div>

{$pipelinestall}{$examples}

<div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>

<a class="citerefentry" href="glColorSubTable"><span class="citerefentry"><span class="refentrytitle">glColorSubTable</span></span></a>,

<code class="function">glColorTableParameter</code>,

<a class="citerefentry" href="glCopyColorTable"><span class="citerefentry"><span class="refentrytitle">glCopyColorTable</span></span></a>,

<a class="citerefentry" href="glCopyColorSubTable"><span class="citerefentry"><span class="refentrytitle">glCopyColorSubTable</span></span></a>,

<a class="citerefentry" href="glGetColorTable"><span class="citerefentry"><span class="refentrytitle">glGetColorTable</span></span></a>

</p></div><div class="refsect1" lang="en" xml:lang="en"><div id="Copyright"><h2>Copyright</h2><p>

Copyright © 1991-2006

Silicon Graphics, Inc. This document is licensed under the SGI

Free Software B License. For details, see

<a class="ulink" href="https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/" target="_top">https://web.archive.org/web/20171022161616/http://oss.sgi.com/projects/FreeB/</a>.

</p></div></div></div>