path: root/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/colortable.gl

_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_define(_filters,tbl)_C_
_header(ColorTable,define a color lookup table)
_names(ColorTable)
_define(@<__target>@,@<_param1>@)_C_
_define(@<__internalformat>@,@<_param2>@)_C_
_define(@<__width>@,@<_param3>@)_C_
_define(@<__format>@,@<_param4>@)_C_
_define(@<__type>@,@<_param5>@)_C_
_define(@<__table>@,@<_param6>@)_C_
.SH PARAMETERS
_phead(__target)
Must be one of
_const(COLOR_TABLE),
_const(POST_CONVOLUTION_COLOR_TABLE),
_const(POST_COLOR_MATRIX_COLOR_TABLE),
_const(PROXY_COLOR_TABLE),
_const(PROXY_POST_CONVOLUTION_COLOR_TABLE),
or
_const(PROXY_POST_COLOR_MATRIX_COLOR_TABLE).
_phead(__internalformat)
The internal format of the color table.
The allowable values are
_const(ALPHA),
_const(ALPHA4),
_const(ALPHA8),
_const(ALPHA12),
_const(ALPHA16),
_const(LUMINANCE),
_const(LUMINANCE4),
_const(LUMINANCE8),
_const(LUMINANCE12),
_const(LUMINANCE16),
_const(LUMINANCE_ALPHA),
_const(LUMINANCE4_ALPHA4),
_const(LUMINANCE6_ALPHA2),
_const(LUMINANCE8_ALPHA8),
_const(LUMINANCE12_ALPHA4),
_const(LUMINANCE12_ALPHA12),
_const(LUMINANCE16_ALPHA16),
_const(INTENSITY),
_const(INTENSITY4),
_const(INTENSITY8),
_const(INTENSITY12),
_const(INTENSITY16),
_const(R3_G3_B2),
_const(RGB),
_const(RGB4),
_const(RGB5),
_const(RGB8),
_const(RGB10),
_const(RGB12),
_const(RGB16),
_const(RGBA),
_const(RGBA2),
_const(RGBA4),
_const(RGB5_A1),
_const(RGBA8),
_const(RGB10_A2),
_const(RGBA12), and
_const(RGBA16).
_phead(__width)
The number of entries in the color lookup table specified by __table.
_phead(__format)
The format of the pixel data in __table.
The allowable values are
_const(RED),
_const(GREEN),
_const(BLUE),
_const(ALPHA),
_const(LUMINANCE),
_const(LUMINANCE_ALPHA),
_const(RGB),
_const(BGR),
_const(RGBA), and
_const(BGRA).
_phead(__type)
The type of the pixel data in __table.
The allowable values are
_const(UNSIGNED_BYTE),
_const(BYTE),
_const(UNSIGNED_SHORT),
_const(SHORT),
_const(UNSIGNED_INT),
_const(INT),
_const(FLOAT),
_const(UNSIGNED_BYTE_3_3_2),
_const(UNSIGNED_BYTE_2_3_3_REV),
_const(UNSIGNED_SHORT_5_6_5),
_const(UNSIGNED_SHORT_5_6_5_REV),
_const(UNSIGNED_SHORT_4_4_4_4),
_const(UNSIGNED_SHORT_4_4_4_4_REV),
_const(UNSIGNED_SHORT_5_5_5_1),
_const(UNSIGNED_SHORT_1_5_5_5_REV),
_const(UNSIGNED_INT_8_8_8_8),
_const(UNSIGNED_INT_8_8_8_8_REV),
_const(UNSIGNED_INT_10_10_10_2), and
_const(UNSIGNED_INT_2_10_10_10_REV).
_phead(__table)
Pointer to a one-dimensional array of pixel data that is processed to
build the color table.
.SH DESCRIPTION
_cmnd 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 _const(PROXY_*) for the first case
and the other targets for the second case. 
.P
If __target is _const(COLOR_TABLE),
_const(POST_CONVOLUTION_COLOR_TABLE),
or
_const(POST_COLOR_MATRIX_COLOR_TABLE),
_cmnd 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 _cmnd(DrawPixels) were called, but processing
stops after the final expansion to RGBA is completed.
.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 _cmnd(ColorTableParameter) to set these scale and bias
parameters.)
.P
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:
.P
.TS
center;
lb cb cb cb cb cb cb
l c c c c c c.
_
Internal Format	Red	Green	Blue	Alpha	Luminance	Intensity
_
_const(ALPHA)				A
_const(LUMINANCE)					R
_const(LUMINANCE_ALPHA)				A	R
_const(INTENSITY)						R
_const(RGB)	R	G	B
_const(RGBA)	R	G	B	A
_
.TE
.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
[0,\ __width\ \-\ 1].
.P
If __target is _const(PROXY_*),
_cmnd recomputes and stores the values of the proxy color table's state
variables
_const(COLOR_TABLE_FORMAT),
_const(COLOR_TABLE_WIDTH),
_const(COLOR_TABLE_RED_SIZE),
_const(COLOR_TABLE_GREEN_SIZE),
_const(COLOR_TABLE_BLUE_SIZE),
_const(COLOR_TABLE_ALPHA_SIZE),
_const(COLOR_TABLE_LUMINANCE_SIZE), and
_const(COLOR_TABLE_INTENSITY_SIZE).
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 _cmnd
using the corresponding non-proxy target,
and the proxy state variables are set as if that target were being defined.
.P
The proxy state variables can be retrieved by calling
_cmnd(GetColorTableParameter) with a target of
_const(PROXY_*).
This allows the application to decide if a particular _cmnd
command would succeed, and to determine what the resulting color table
attributes would be.
.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
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:
.P
.TS
center;
cb cb
c l.
_
Representation	Meaning
_
\f7r\fP	Table index computed from \f7R\fP
\f7g\fP	Table index computed from \f7G\fP
\f7b\fP	Table index computed from \f7B\fP
\f7a\fP	Table index computed from \f7A\fP
\f7L[i]\fP	Luminance value at table index \f7i\fP
\f7I[i]\fP	Intensity value at table index \f7i\fP
\f7R[i]\fP	Red value at table index \f7i\fP
\f7G[i]\fP	Green value at table index \f7i\fP
\f7B[i]\fP	Blue value at table index \f7i\fP
\f7A[i]\fP	Alpha value at table index \f7i\fP
_
.TE
.P
then the result of color table lookup is as follows:
.P
.ne 10
.TS
center;
l l s s s
l l l l l
l l l l l.
_
	Resulting Texture Components
Table Internal Format	R	G	B	A
_
_const(ALPHA)	R	G	B	A[a]
_const(LUMINANCE)	L[r]	L[g]	L[b]	At
_const(LUMINANCE_ALPHA)	L[r]	L[g]	L[b]	A[a]
_const(INTENSITY)	I[r]	I[g]	I[b]	I[a]
_const(RGB)	R[r]	G[g]	B[b]	A
_const(RGBA)	R[r]	G[g]	B[b]	A[a]
_
.TE
.P
When _const(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 
_const(POST_CONVOLUTION_COLOR_TABLE)
is enabled. These modified colors are then sent to the color matrix operation. 
Finally, if _const(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.
.P
.SH NOTES
_cmnd is present only if _arbstring(imaging) is returned when _cmnd(GetString)
is called with an argument of _const(EXTENSIONS).
.P
If __target is set to _const(COLOR_TABLE),
_const(POST_CONVOLUTION_COLOR_TABLE),
or _const(POST_COLOR_MATRIX_COLOR_TABLE),
then __width must be a power of two or a _const(INVALID_VALUE)
error is generated.
.P
.SH ERRORS
_const(INVALID_ENUM) is generated if __target is not one of the allowable
values.
.P
_const(INVALID_ENUM) is generated if __internalformat is not one of the
allowable values.
.P
_const(INVALID_VALUE) is generated if __width is less than zero.
.P
_const(INVALID_ENUM) is generated if __format is not one of the allowable
values.
.P
_const(INVALID_ENUM) is generated if __type is not one of the allowable
values.
.P
_const(TABLE_TOO_LARGE) is generated if the requested color table
is too large to be supported by the implementation, and __target is
not a _const(PROXY_*) target.
.P
_const(INVALID_OPERATION) is generated if _cmnd is executed
between the execution of _cmnd(Begin) and the corresponding
execution of _cmnd(End).
.SH ASSOCIATED GETS
_cmnd(GetColorTableParameter)
.SH SEE ALSO
_cmnd(ColorSubTable),
_cmnd(ColorTableParameter),
_cmnd(CopyColorTable),
_cmnd(CopyColorSubTable),
_cmnd(GetColorTable)