1 files changed, 357 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.gl b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.gl
new file mode 100644
index 000000000..ed699ffa1
--- /dev/null
+++ b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.gl
@@ -0,0 +1,357 @@
+_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)