diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.gl')
-rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/readpixels.gl | 357 |
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) |