path: root/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.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|eqn)_C_
_C_      eqn is automatically replaced with neqn for nroff
_header(ReadPixels,read a block of pixels from the frame buffer)
_names(ReadPixels)
.EQ
delim $$
.EN
.SH PARAMETERS
_phead(_param1 _param2)
Specify the window coordinates of the first pixel
that is read from the frame buffer.
This location is the lower left corner of a rectangular block of pixels.
_phead(_param3 _param4)
Specify the dimensions of the pixel rectangle.
_param3 and _param4 of one correspond to a single pixel.
_phead(_param5)
Specifies the format of the pixel data.
The following symbolic values are accepted:
_const(COLOR_INDEX),
_const(STENCIL_INDEX),
_const(DEPTH_COMPONENT),
_const(RED),
_const(GREEN),
_const(BLUE),
_const(ALPHA),
_const(RGB),
_const(BGR),
_const(RGBA),
_const(BGRA),
_C_ _const(ABGR_EXT),
_const(LUMINANCE), and
_const(LUMINANCE_ALPHA).
_phead(_param6)
Specifies the data type of the pixel data.
Must be one of
_const(UNSIGNED_BYTE),
_const(BYTE),
_const(BITMAP),
_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), or
_const(UNSIGNED_INT_2_10_10_10_REV).
_phead(_param7)
Returns the pixel data.
.SH DESCRIPTION
_cmnd returns pixel data from the frame buffer,
starting with the pixel whose lower left corner
is at location (_param1, _param2),
into client memory starting at location _param7.
Several parameters control the processing of the pixel data before
it is placed into client memory.
These parameters are set with three commands:
_cmnd(PixelStore),
_cmnd(PixelTransfer), and
_cmnd(PixelMap).
This reference page describes the effects on _cmnd of most,
but not all of the parameters specified by these three commands.
.P
When the _arbstring(imaging) extension is supported, the pixel data may
be processed by additional operations including color table lookup,
color matrix tranformations, convolutions, histograms and minimum and
maximun pixel value computations.
.P
_cmnd returns values from each pixel with lower left corner at
(_param1 + $i$, _param2 + $j$) for 0 \(<= $i$ < _param3 and 
0 \(<= $j$ < _param4.
This pixel is said to be the $i$th pixel in the $j$th row. 
Pixels are returned in row order from the lowest to the highest row,
left to right in each row.
.P
_param5 specifies the format for the returned pixel values;
accepted values are:
.TP 10
_const(COLOR_INDEX)
Color indices are read from the color buffer
selected by _cmnd(ReadBuffer).
Each index is converted to fixed point,
shifted left or right depending on the value and sign of _const(INDEX_SHIFT),
and added to _const(INDEX_OFFSET). 
If _const(MAP_COLOR) is _const(TRUE),
indices are replaced by their mappings in the table _const(PIXEL_MAP_I_TO_I).
.TP
_const(STENCIL_INDEX)
Stencil values are read from the stencil buffer.
Each index is converted to fixed point,
shifted left or right depending on the value and sign of _const(INDEX_SHIFT),
and added to _const(INDEX_OFFSET). 
If _const(MAP_STENCIL) is _const(TRUE),
indices are replaced by their mappings in the table _const(PIXEL_MAP_S_TO_S).
.TP
_const(DEPTH_COMPONENT)
Depth values are read from the depth buffer.
Each component is converted to floating point such that the minimum depth
value maps to 0 and the maximum value maps to 1.
Each component is then multiplied by _const(DEPTH_SCALE),
added to _const(DEPTH_BIAS),
and finally clamped to the range [0,1].
.TP
_const(RED)
.TP
_const(GREEN)
.TP
_const(BLUE)
.TP
_const(ALPHA)
.TP
_const(RGB)
.TP
_const(BGR)
.TP
_const(RGBA)
.TP
_const(BGRA)
.TP
_C_ _const(ABGR_EXT)
_const(LUMINANCE)
.TP
_const(LUMINANCE_ALPHA)
Processing differs depending on whether color buffers store color indices
or RGBA color components.
If color indices are stored,
they are read from the color buffer selected by _cmnd(ReadBuffer).
Each index is converted to fixed point,
shifted left or right depending on the value and sign of _const(INDEX_SHIFT),
and added to _const(INDEX_OFFSET). 
Indices are then replaced by the red,
green,
blue,
and alpha values obtained by indexing the tables
_const(PIXEL_MAP_I_TO_R),
_const(PIXEL_MAP_I_TO_G),
_const(PIXEL_MAP_I_TO_B), and
_const(PIXEL_MAP_I_TO_A).
Each table must be of size $2 sup n$, but $n$ may be different for 
different tables. 
Before an index is used to look up a value in a table of
size $2 sup n$, it must be masked against $2 sup n - 1$.
.IP
If RGBA color components are stored in the color buffers,
they are read from the color buffer selected by _cmnd(ReadBuffer).
Each color component is converted to floating point such that zero intensity
maps to 0.0 and full intensity maps to 1.0.
Each component is then multiplied by _const(c_SCALE) and
added to _const(c_BIAS),
where \f2c\fP is RED, GREEN, BLUE, or ALPHA. 
Finally,
if _const(MAP_COLOR) is _const(TRUE),
each component is clamped to the range [0,\ 1],
scaled to the size of its corresponding table, and is then 
replaced by its mapping in the table
_const(PIXEL_MAP_c_TO_c),
where \f2c\fP is R, G, B, or A.
.IP
Unneeded data is then discarded.
For example,
_const(RED) discards the green, blue, and alpha components,
while _const(RGB) discards only the alpha component.
_const(LUMINANCE) computes a single-component value as the sum of
the red,
green,
and blue components,
and _const(LUMINANCE_ALPHA) does the same,
while keeping alpha as a second value.
The final values are clamped to the range [0,\ 1].
.P
The shift,
scale,
bias,
and lookup factors just described are all specified by 
.br
_cmnd(PixelTransfer).
The lookup table contents themselves are specified by _cmnd(PixelMap).
.P 
Finally, the indices or components
are converted to the proper format,
as specified by _param6.
If _param5 is _const(COLOR_INDEX) or _const(STENCIL_INDEX)
and _param6 is not _const(FLOAT),
each index is masked with the mask value given in the following table.
If _param6 is _const(FLOAT), then each integer index is converted to
single-precision floating-point format.
.P 
If _param5 is
_const(RED),
_const(GREEN),
_const(BLUE),
_const(ALPHA),
_const(RGB),
_const(BGR),
_const(RGBA),
_const(BGRA),
_C_ _const(ABGR_EXT),
_const(LUMINANCE), or
_const(LUMINANCE_ALPHA) and _param6 is not _const(FLOAT),
each component is multiplied by the multiplier shown in the following table.
If type is _const(FLOAT), then each component is passed as is
(or converted to the client's single-precision floating-point format if
it is different from the one used by the GL).
.P
.TS
center tab(:);
l cb cb
l c c.
_
_param6:index mask:component conversion
_
.sp .5
_const(UNSIGNED_BYTE):$2"^"8 - 1$:$(2"^"8 - 1)  c$
_const(BYTE):$2"^"7 - 1$:$[(2"^"8 - 1) c - 1] / 2$
_const(BITMAP):$1$:$1$
_const(UNSIGNED_SHORT):$2"^"16 - 1$:$(2"^"16 - 1) c$
_const(SHORT):$2"^"15 - 1$:$[(2"^"16 - 1) c - 1] / 2$
_const(UNSIGNED_INT):$2"^"32 - 1$:$(2"^"32 - 1) c$
_const(INT):$2"^"31 - 1$:$[(2"^"32 - 1) c - 1] / 2$
_const(FLOAT):none:$c$
_
.TE
.P
Return values are placed in memory as follows.
If _param5 is
_const(COLOR_INDEX),
_const(STENCIL_INDEX),
_const(DEPTH_COMPONENT),
_const(RED),
_const(GREEN),
_const(BLUE),
_const(ALPHA), or 
_const(LUMINANCE),
a single value is returned and the data for the $i$th pixel in the $j$th row
is placed in location $(j)~_eqnparam3~+~i$.
_const(RGB) and _const(BGR) return three values,
_const(RGBA) and _const(BGRA) return four values,
_C_ and _const(ABGR_EXT) return four values,
and _const(LUMINANCE_ALPHA) returns two values for each pixel,
with all values corresponding to a single pixel occupying contiguous space
in _param7.
Storage parameters set by _cmnd(PixelStore),
such as _const(PACK_LSB_FIRST) and _const(PACK_SWAP_BYTES),
affect the way that data is written into memory.
See _cmnd(PixelStore) for a description.
.SH NOTES
Values for pixels that lie outside the window
connected to the current GL context are undefined.
.P
If an error is generated,
no change is made to the contents of _param7.
.SH ERRORS
_const(INVALID_ENUM) is generated if _param5 or _param6 is not an
accepted value.
.P
_const(INVALID_ENUM) is generated if _param6 is _const(BITMAP) and _param5 is
not _const(COLOR_INDEX) or _const(STENCIL_INDEX).
.P
_const(INVALID_VALUE) is generated if either _param3 or _param4 is negative.
.P
_const(INVALID_OPERATION) is generated if _param5 is _const(COLOR_INDEX)
and the color buffers store RGBA color components.
.P
_const(INVALID_OPERATION) is generated if _param5 is _const(STENCIL_INDEX)
and there is no stencil buffer.
.P
_const(INVALID_OPERATION) is generated if _param5 is _const(DEPTH_COMPONENT)
and there is no depth buffer.
.P
_const(INVALID_OPERATION) is generated if _cmnd
is executed between the execution of _cmnd(Begin)
and the corresponding execution of _cmnd(End).
.P
_const(INVALID_OPERATION) is generated if _param6 is one of
_const(UNSIGNED_BYTE_3_3_2),
_const(UNSIGNED_BYTE_2_3_3_REV),
_const(UNSIGNED_SHORT_5_6_5), or
_const(UNSIGNED_SHORT_5_6_5_REV)
and _param5 is not _const(RGB).
.P
_const(INVALID_OPERATION) is generated if _param6 is one of
_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), or
_const(UNSIGNED_INT_2_10_10_10_REV)
and _param5 is neither _const(RGBA) nor _const(BGRA).
.P
The formats _const(BGR), and _const(BGRA) and types 
_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) are available only if the GL version 
is 1.2 or greater.
.SH ASSOCIATED GETS
_cmnd(Get) with argument _const(INDEX_MODE)
.SH SEE ALSO
_cmnd(CopyPixels),
_cmnd(DrawPixels),
_cmnd(PixelMap),
_cmnd(PixelStore),
_cmnd(PixelTransfer),
.br
_cmnd(ReadBuffer)