<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd">
<html
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:mml="http://www.w3.org/1998/Math/MathML"
><head><title>glColorTable</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.59.1"/><link rel="home" href="index.xml" title="PyOpenGL 2.0.1.07 Man Pages"/><link rel="up" href="reference-GL.xml" title="GL"/><link rel="previous" href="glColorSubTable.3G.xml" title="glColorSubTable"/><link rel="next" href="glColorTableParameter.3G.xml" title="glColorTableParameter"/></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">glColorTable</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="glColorSubTable.3G.xml">Prev</a> </td><th width="60%" align="center">GL</th><td width="20%" align="right"> <a accesskey="n" href="glColorTableParameter.3G.xml">Next</a></td></tr></table><hr/></div><div class="refentry" lang="en"><a name="glColorTable.3G"/><div class="titlepage"/><div class="refnamediv"><a name="glColorTable.3G-name"/><h2>Name</h2><p>glColorTable &#8212; define a color lookup table</p></div><div class="refsynopsisdiv"><a name="glColorTable.3G-c_spec"/><h2>C Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code>void <tt>glColorTable</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code>GLenum <i><tt>target</tt></i>, GLenum <i><tt>internalformat</tt></i>, GLsizei <i><tt>width</tt></i>, GLenum <i><tt>format</tt></i>, GLenum <i><tt>type</tt></i>, const GLvoid *<i><tt>table</tt></i>);</code></td></tr></table></div><div class="refsynopsisdiv"><a name="glColorTable.3G-python_spec"/><h2>Python Specification</h2><table class="funcprototype" border="0" cellpadding="0" cellspacing="0"><tr><td valign="top"><code><tt>glColorTable</tt></code></td><td valign="top"><code>(</code></td><td valign="top"><code><i><tt>target</tt></i>, <i><tt>internalformat</tt></i>, <i><tt>width</tt></i>, <i><tt>format</tt></i>, <i><tt>type</tt></i>, <i><tt>table</tt></i>) &#8594; </code></td></tr></table></div><div class="refsect1" lang="en"><a name="glColorTable.3G-parameters"/><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><i><tt>target</tt></i></span></dt><dd>
						Must be one of <tt>GL_COLOR_TABLE</tt>, <tt>GL_POST_CONVOLUTION_COLOR_TABLE</tt>,
						<tt>GL_POST_COLOR_MATRIX_COLOR_TABLE</tt>, <tt>GL_PROXY_COLOR_TABLE</tt>,
						<tt>GL_PROXY_POST_CONVOLUTION_COLOR_TABLE</tt>, or
						<tt>GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE</tt>.
					</dd><dt><span class="term"><i><tt>internalformat</tt></i></span></dt><dd>
						The internal of the color table. The allowable values are <tt>GL_ALPHA</tt>,
						<tt>GL_ALPHA4</tt>, <tt>GL_ALPHA8</tt>, <tt>GL_ALPHA12</tt>,
						<tt>GL_ALPHA16</tt>, <tt>GL_LUMINANCE</tt>, <tt>GL_LUMINANCE4</tt>,
						<tt>GL_LUMINANCE8</tt>, <tt>GL_LUMINANCE12</tt>,
						<tt>GL_LUMINANCE16</tt>, <tt>GL_LUMINANCE_ALPHA</tt>,
						<tt>GL_LUMINANCE4_ALPHA4</tt>, <tt>GL_LUMINANCE6_ALPHA2</tt>,
						<tt>GL_LUMINANCE8_ALPHA8</tt>, <tt>GL_LUMINANCE12_ALPHA4</tt>,
						<tt>GL_LUMINANCE12_ALPHA12</tt>, <tt>GL_LUMINANCE16_ALPHA16</tt>,
						<tt>GL_INTENSITY</tt>, <tt>GL_INTENSITY4</tt>, <tt>GL_INTENSITY8</tt>,
						<tt>GL_INTENSITY12</tt>, <tt>GL_INTENSITY16</tt>, <tt>GL_R3_G3_B2</tt>,
						<tt>GL_RGB</tt>, <tt>GL_RGB4</tt>, <tt>GL_RGB5</tt>,
						<tt>GL_RGB8</tt>, <tt>GL_RGB10</tt>, <tt>GL_RGB12</tt>,
						<tt>GL_RGB16</tt>, <tt>GL_RGBA</tt>, <tt>GL_RGBA2</tt>,
						<tt>GL_RGBA4</tt>, <tt>GL_RGB5_A1</tt>, <tt>GL_RGBA8</tt>,
						<tt>GL_RGB10_A2</tt>, <tt>GL_RGBA12</tt>, and <tt>GL_RGBA16</tt>.
					</dd><dt><span class="term"><i><tt>width</tt></i></span></dt><dd>
						The number of entries in the color lookup table specified by <i><tt>table</tt></i>.
					</dd><dt><span class="term"><i><tt>format</tt></i></span></dt><dd>
						The of the pixel data in <i><tt>table</tt></i>. The allowable values are
						<tt>GL_RED</tt>, <tt>GL_GREEN</tt>, <tt>GL_BLUE</tt>,
						<tt>GL_ALPHA</tt>, <tt>GL_LUMINANCE</tt>, <tt>GL_LUMINANCE_ALPHA</tt>,
						<tt>GL_RGB</tt>, <tt>GL_BGR</tt>, <tt>GL_RGBA</tt>, and
						<tt>GL_BGRA</tt>.
					</dd><dt><span class="term"><i><tt>type</tt></i></span></dt><dd>
						The type of the pixel data in <i><tt>table</tt></i>. The allowable values are
						<tt>GL_UNSIGNED_BYTE</tt>, <tt>GL_BYTE</tt>,
						<tt>GL_UNSIGNED_SHORT</tt>, <tt>GL_SHORT</tt>,
						<tt>GL_UNSIGNED_INT</tt>, <tt>GL_INT</tt>, <tt>GL_FLOAT</tt>,
						<tt>GL_UNSIGNED_BYTE_3_3_2</tt>, <tt>GL_UNSIGNED_BYTE_2_3_3_REV</tt>,
						<tt>GL_UNSIGNED_SHORT_5_6_5</tt>, <tt>GL_UNSIGNED_SHORT_5_6_5_REV</tt>,
						<tt>GL_UNSIGNED_SHORT_4_4_4_4</tt>, <tt>GL_UNSIGNED_SHORT_4_4_4_4_REV</tt>,
						<tt>GL_UNSIGNED_SHORT_5_5_5_1</tt>, <tt>GL_UNSIGNED_SHORT_1_5_5_5_REV</tt>,
						<tt>GL_UNSIGNED_INT_8_8_8_8</tt>, <tt>GL_UNSIGNED_INT_8_8_8_8_REV</tt>,
						<tt>GL_UNSIGNED_INT_10_10_10_2</tt>, and <tt>GL_UNSIGNED_INT_2_10_10_10_REV</tt>.
					</dd><dt><span class="term"><i><tt>table</tt></i></span></dt><dd>
						Pointer to a one-dimensional array of pixel data that is processed to build the color table.
					</dd></dl></div></div><div class="refsect1" lang="en"><a name="glColorTable.3G-description"/><h2>Description</h2><p>
			<tt>glColorTable</tt> 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
			<tt>GL_PROXY_*</tt> for the first case and the other targets for the second case.
		</p><p>
			If <i><tt>target</tt></i> is <tt>GL_COLOR_TABLE</tt>,
			<tt>GL_POST_CONVOLUTION_COLOR_TABLE</tt>, or <tt>GL_POST_COLOR_MATRIX_COLOR_TABLE</tt>,
			<tt>glColorTable</tt> builds a color lookup table from an array of pixels. The pixel array specified by
			<i><tt>width</tt></i>, <i><tt>format</tt></i>, <i><tt>type</tt></i>, and
			<i><tt>table</tt></i> is extracted from memory and processed just as if <a href="glDrawPixels.3G.xml"><tt>glDrawPixels</tt></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 <tt>glColorTableParameter</tt> to set
			these scale and bias parameters.)
		</p><p>
			Next, the R, G, B, and A values are clamped to the range <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mfenced separator="," open="[" close="]">
						<mml:mn>0</mml:mn>
						<mml:mn>1</mml:mn>
					</mml:mfenced>
				</mml:math>. Each pixel is then converted to the internal specified
			by <i><tt>internalformat</tt></i>. 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:
		</p><div class="informaltable"><table border="1"><colgroup><col/><col align="center"/><col align="center"/><col align="center"/><col align="center"/><col align="center"/><col align="center"/></colgroup><thead><tr><th><span class="bold"><b>Internal Format</b></span></th><th align="center"><span class="bold"><b>Red</b></span></th><th align="center"><span class="bold"><b>Green</b></span></th><th align="center"><span class="bold"><b>Blue</b></span></th><th align="center"><span class="bold"><b>Alpha</b></span></th><th align="center"><span class="bold"><b>Luminance</b></span></th><th align="center"><span class="bold"><b>Intensity</b></span></th></tr></thead><tbody><tr><td><tt>GL_ALPHA</tt></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">A</td><td align="center"> </td><td align="center"> </td></tr><tr><td><tt>GL_LUMINANCE</tt></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">R</td><td align="center"> </td></tr><tr><td><tt>GL_LUMINANCE_ALPHA</tt></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">A</td><td align="center">R</td><td align="center"> </td></tr><tr><td><tt>GL_INTENSITY</tt></td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center"> </td><td align="center">R</td></tr><tr><td><tt>GL_RGB</tt></td><td align="center">R</td><td align="center">G</td><td align="center">B</td><td align="center"> </td><td align="center"> </td><td align="center"> </td></tr><tr><td><tt>GL_RGBA</tt></td><td align="center">R</td><td align="center">G</td><td align="center">B</td><td align="center">A</td><td align="center"> </td><td align="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 <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mfenced separator="," open="[" close="]">
						<mml:mn>0</mml:mn>
						<mml:mrow>
							<mml:mi>width</mml:mi>
							<mml:mo>-</mml:mo>
							<mml:mn>1</mml:mn>
						</mml:mrow>
					</mml:mfenced>
				</mml:math>.
		</p><p>
			If <i><tt>target</tt></i> is <tt>GL_PROXY_*</tt>, <tt>glColorTable</tt> recomputes and
			stores the values of the proxy color table's state variables <tt>GL_COLOR_TABLE_FORMAT</tt>,
			<tt>GL_COLOR_TABLE_WIDTH</tt>, <tt>GL_COLOR_TABLE_RED_SIZE</tt>,
			<tt>GL_COLOR_TABLE_GREEN_SIZE</tt>, <tt>GL_COLOR_TABLE_BLUE_SIZE</tt>,
			<tt>GL_COLOR_TABLE_ALPHA_SIZE</tt>, <tt>GL_COLOR_TABLE_LUMINANCE_SIZE</tt>, and
			<tt>GL_COLOR_TABLE_INTENSITY_SIZE</tt>. 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 <tt>glColorTable</tt> 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 <tt>glGetColorTableParameter</tt>
			with a target of <tt>GL_PROXY_*</tt>. This allows the application to decide if a particular
			<tt>glColorTable</tt> 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 of the table.
		</p><p>
			Each pixel group has color components (R, G, B, A) that are in the range <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
					<mml:mfenced separator="," open="[" close="]">
						<mml:mn>0</mml:mn>
						<mml:mn>1</mml:mn>
					</mml:mfenced>
				</mml: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 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><div class="informaltable"><table border="1"><colgroup><col align="center"/><col/></colgroup><thead><tr><th align="center"><span class="bold"><b>Representation</b></span></th><th align="center"><span class="bold"><b>Meaning</b></span></th></tr></thead><tbody><tr><td align="center">r</td><td>Table index computed from R</td></tr><tr><td align="center">g</td><td>Table index computed from G</td></tr><tr><td align="center">b</td><td>Table index computed from B</td></tr><tr><td align="center">a</td><td>Table index computed from A</td></tr><tr><td align="center">L[i]</td><td>Luminance value at table index i</td></tr><tr><td align="center">I[i]</td><td>Intensity value at table index i</td></tr><tr><td align="center">R[i]</td><td>Red value at table index i</td></tr><tr><td align="center">G[i]</td><td>Green value at table index i</td></tr><tr><td align="center">B[i]</td><td>Blue value at table index i</td></tr><tr><td align="center">A[i]</td><td>Alpha value at table index i</td></tr></tbody></table></div><p>
			then the result of color table lookup is as follows:
		</p><div class="informaltable"><table border="1"><colgroup><col/><col/><col/><col/><col/></colgroup><thead><tr><th> </th><th colspan="4">Resulting Texture Components</th></tr><tr><th>Table Internal Format</th><th>R</th><th>G</th><th>B</th><th>A</th></tr></thead><tbody><tr><td><tt>GL_ALPHA</tt></td><td>R</td><td>G</td><td>B</td><td>A[a]</td></tr><tr><td><tt>GL_LUMINANCE</tt></td><td>L[r]</td><td>L[g]</td><td>L[b]</td><td>At</td></tr><tr><td><tt>GL_LUMINANCE_ALPHA</tt></td><td>L[r]</td><td>L[g]</td><td>L[b]</td><td>A[a]</td></tr><tr><td><tt>GL_INTENSITY</tt></td><td>I[r]</td><td>I[g]</td><td>I[b]</td><td>I[a]</td></tr><tr><td><tt>GL_RGB</tt></td><td>R[r]</td><td>G[g]</td><td>B[b]</td><td>A</td></tr><tr><td><tt>GL_RGBA</tt></td><td>R[r]</td><td>G[g]</td><td>B[b]</td><td>A[a]</td></tr></tbody></table></div><p>
			When <tt>GL_COLOR_TABLE</tt> 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
			<tt>GL_POST_CONVOLUTION_COLOR_TABLE</tt> is enabled. These modified colors are then sent to the color
			matrix operation. Finally, if <tt>GL_POST_COLOR_MATRIX_COLOR_TABLE</tt> 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></div><div class="refsect1" lang="en"><a name="glColorTable.3G-notes"/><h2>Notes</h2><p>
			<tt>glColorTable</tt> is present only if <tt>GL_ARB_imaging</tt> is returned when <a href="glGetString.3G.xml"><tt>glGetString</tt></a> is called with an argument of <tt>GL_EXTENSIONS</tt>.
		</p><p>
			If <i><tt>target</tt></i> is set to <tt>GL_COLOR_TABLE</tt>,
			<tt>GL_POST_CONVOLUTION_COLOR_TABLE</tt>, or <tt>GL_POST_COLOR_MATRIX_COLOR_TABLE</tt>, then
			<i><tt>width</tt></i> must be a power of two or a <tt>GL_INVALID_VALUE</tt> error is generated.
		</p></div><div class="refsect1" lang="en"><a name="glColorTable.3G-errors"/><h2>Errors</h2><p>
			<tt>GL_INVALID_ENUM</tt> is generated if <i><tt>target</tt></i> is not one of the allowable values.
		</p><p>
			<tt>GL_INVALID_ENUM</tt> is generated if <i><tt>internalformat</tt></i> is not one of the allowable
			values.
		</p><p>
			<tt>GL_INVALID_VALUE</tt> is generated if <i><tt>width</tt></i> is less than zero.
		</p><p>
			<tt>GL_INVALID_ENUM</tt> is generated if <i><tt>format</tt></i> is not one of the allowable values.
		</p><p>
			<tt>GL_INVALID_ENUM</tt> is generated if <i><tt>type</tt></i> is not one of the allowable values.
		</p><p>
			<tt>GL_TABLE_TOO_LARGE</tt> is generated if the requested color table is too large to be supported by the
			implementation, and <i><tt>target</tt></i> is not a <tt>GL_PROXY_*</tt> target.
		</p><p>
			<tt>GL_INVALID_OPERATION</tt> is generated if <tt>glColorTable</tt> is executed between the
			execution of <a href="glBegin.3G.xml"><tt>glBegin</tt></a> and the corresponding execution of <a href="glBegin.3G.xml"><tt>glEnd</tt></a>.
		</p></div><div class="refsect1" lang="en"><a name="glColorTable.3G-associated_gets"/><h2>Associated Gets</h2><p>
			<tt>glGetColorTableParameter</tt>
		</p></div><div class="refsect1" lang="en"><a name="glColorTable.3G-see_also"/><h2>See Also</h2><p>
			<span class="simplelist"><a href="glColorSubTable.3G.xml">glColorSubTable</a>, <a href="glColorTableParameter.3G.xml">glColorTableParameter</a>, <a href="glCopyColorTable.3G.xml">glCopyColorTable</a>, <a href="glCopyColorSubTable.3G.xml">glCopyColorSubTable</a>, <a href="glGetColorTable.3G.xml">glGetColorTable</a></span>
		</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="glColorSubTable.3G.xml">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-GL.xml">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="glColorTableParameter.3G.xml">Next</a></td></tr><tr><td width="40%" align="left" valign="top">glColorSubTable </td><td width="20%" align="center"><a accesskey="h" href="index.xml">Home</a></td><td width="40%" align="right" valign="top"> glColorTableParameter</td></tr></table></div></body></html>
