diff options
Diffstat (limited to 'nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/copypixels.gl')
| -rw-r--r-- | nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/copypixels.gl | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/copypixels.gl b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/copypixels.gl new file mode 100644 index 000000000..d7edced77 --- /dev/null +++ b/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/copypixels.gl @@ -0,0 +1,258 @@ +_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,eqn)_C_ +_header(CopyPixels,copy pixels in the frame buffer) +_names(CopyPixels) +.EQ +delim $$ +.EN +.SH PARAMETERS +_phead(_param1 _param2) +Specify the window coordinates of the lower left corner +of the rectangular region of pixels to be copied. +_phead(_param3 _param4) +Specify the dimensions of the rectangular region of pixels to be copied. +Both must be nonnegative. +_phead(_param5) +Specifies whether color values, +depth values, +or stencil values are to be copied. +Symbolic constants +_const(COLOR), +_const(DEPTH), +and _const(STENCIL) are accepted. +.SH DESCRIPTION +_cmnd copies a screen-aligned rectangle of pixels +from the specified frame buffer location to a region relative to the +current raster position. +Its operation is well defined only if the entire pixel source region +is within the exposed portion of the window. +Results of copies from outside the window, +or from regions of the window that are not exposed, +are hardware dependent and undefined. +.P +_param1 and _param2 specify the window coordinates of +the lower left corner of the rectangular region to be copied. +_param3 and _param4 specify the dimensions of the +rectangular region to be copied. +Both _param3 and _param4 must not be negative. +.P +Several parameters control the processing of the pixel data +while it is being copied. +These parameters are set with three commands: +_cmnd(PixelTransfer), +_cmnd(PixelMap), and +_cmnd(PixelZoom). +This reference page describes the effects on _cmnd of most, +but not all, of the parameters specified by these three commands. +.P +_cmnd copies values from each pixel with the lower left-hand 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 copied in row order from the lowest to the highest row, +left to right in each row. +.P +_param5 specifies whether color, depth, or stencil data is to be copied. +The details of the transfer for each data type are as follows: +.TP 15 +_const(COLOR) +Indices or RGBA colors are read from the buffer currently specified as the +read source buffer (see _cmnd(ReadBuffer)). +If the GL is in color index mode, +each index that is read from this buffer is converted +to a fixed-point format with an unspecified +number of bits to the right of the binary point. +Each index is then shifted left by _const(INDEX_SHIFT) bits, +and added to _const(INDEX_OFFSET). +If _const(INDEX_SHIFT) is negative, +the shift is to the right. +In either case, zero bits fill otherwise unspecified bit locations in the +result. +If _const(MAP_COLOR) is true, +the index is replaced with the value that it references in lookup table +_const(PIXEL_MAP_I_TO_I). +Whether the lookup replacement of the index is done or not, +the integer part of the index is then ANDed with $2 sup b -1$, +where $b$ is the number of bits in a color index buffer. +.IP +If the GL is in RGBA mode, +the red, green, blue, and alpha components of each pixel that is read +are converted to an internal floating-point format with unspecified +precision. +The conversion maps the largest representable component value to 1.0, +and component value 0 to 0.0. +The resulting floating-point color values are then multiplied +by _const(c_SCALE) and added to _const(c_BIAS), +where \f2c\fP is RED, GREEN, BLUE, and ALPHA +for the respective color components. +The results are clamped to the range [0,1]. +If _const(MAP_COLOR) is true, +each color component is scaled by the size of lookup table +_const(PIXEL_MAP_c_TO_c), +then replaced by the value that it references in that table. +\f2c\fP is R, G, B, or A. +.IP +If the _arbstring(imaging) extension is supported, the color values may +be +additionally processed by color-table lookups, color-matrix +transformations, and convolution filters. +.IP +The GL then converts the resulting indices or RGBA colors to fragments +by attaching the current raster position \f2z\fP coordinate and +texture coordinates to each pixel, +then assigning window coordinates +($x sub r ~+~ i , y sub r ~+~ j$), +where ($x sub r , y sub r$) is the current raster position, +and the pixel was the $i$th pixel in the $j$th row. +These pixel fragments are then treated just like the fragments generated by +rasterizing points, lines, or polygons. +Texture mapping, +fog, +and all the fragment operations are applied before the fragments are written +to the frame buffer. +.TP +_const(DEPTH) +Depth values are read from the depth buffer and +converted directly to an internal floating-point format +with unspecified precision. +The resulting floating-point depth value is then multiplied +by _const(DEPTH_SCALE) and added to _const(DEPTH_BIAS). +The result is clamped to the range [0,1]. +.IP +The GL then converts the resulting depth components to fragments +by attaching the current raster position color or color index and +texture coordinates to each pixel, +then assigning window coordinates +($x sub r ~+~ i , y sub r ~+~ j$), +where ($x sub r , y sub r$) is the current raster position, +and the pixel was the $i$th pixel in the $j$th row. +These pixel fragments are then treated just like the fragments generated by +rasterizing points, lines, or polygons. +Texture mapping, +fog, +and all the fragment operations are applied before the fragments are written +to the frame buffer. +.TP +_const(STENCIL) +Stencil indices are read from the stencil buffer and +converted to an internal fixed-point format +with an unspecified number of bits to the right of the binary point. +Each fixed-point index is then shifted left by _const(INDEX_SHIFT) bits, +and added to _const(INDEX_OFFSET). +If _const(INDEX_SHIFT) is negative, +the shift is to the right. +In either case, zero bits fill otherwise unspecified bit locations in the +result. +If _const(MAP_STENCIL) is true, +the index is replaced with the value that it references in lookup table +_const(PIXEL_MAP_S_TO_S). +Whether the lookup replacement of the index is done or not, +the integer part of the index is then ANDed with $2 sup b -1$, +where $b$ is the number of bits in the stencil buffer. +The resulting stencil indices are then written to the stencil buffer +such that the index read from the $i$th location of the $j$th row +is written to location +($x sub r ~+~ i , y sub r ~+~ j$), +where ($x sub r , y sub r$) is the current raster position. +Only the pixel ownership test, +the scissor test, +and the stencil writemask affect these write operations. +.P +The rasterization described thus far assumes pixel zoom factors of 1.0. +If +.br +_cmnd(PixelZoom) is used to change the $x$ and $y$ pixel zoom factors, +pixels are converted to fragments as follows. +If ($x sub r$, $y sub r$) is the current raster position, +and a given pixel is in the $i$th location in the $j$th row of the source +pixel rectangle, +then fragments are generated for pixels whose centers are in the rectangle +with corners at +.P +.ce +($x sub r ~+~ zoom sub x^ i$, $y sub r ~+~ zoom sub y^j$) +.sp .5 +.ce + and +.sp .5 +.ce +($x sub r ~+~ zoom sub x^ (i ~+~ 1)$, $y sub r ~+~ zoom sub y^ ( j ~+~ 1 )$) +.P +where $zoom sub x$ is the value of _const(ZOOM_X) and +$zoom sub y$ is the value of _const(ZOOM_Y). +.SH EXAMPLES +To copy the color pixel in the lower left corner of the window to the current raster position, +use +.Ex +glCopyPixels(0, 0, 1, 1, _const(COLOR)); +.En +.SH NOTES +Modes specified by _cmnd(PixelStore) have no effect on the operation +of _cmnd. +.SH ERRORS +_const(INVALID_ENUM) is generated if _param5 is not an accepted value. +.P +_const(INVALID_VALUE) is generated if either _param3 or _param4 is negative. +.P +_const(INVALID_OPERATION) is generated if _param5 is _const(DEPTH) +and there is no depth buffer. +.P +_const(INVALID_OPERATION) is generated if _param5 is _const(STENCIL) +and there is no stencil buffer. +.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(Get) with argument _const(CURRENT_RASTER_POSITION) +.br +_cmnd(Get) with argument _const(CURRENT_RASTER_POSITION_VALID) +.SH SEE ALSO +_cmnd(ColorTable), +_cmnd(ConvolutionFilter1D), +_cmnd(ConvolutionFilter2D), +_cmnd(DepthFunc), +_cmnd(DrawBuffer), +_cmnd(DrawPixels), +_cmnd(MatrixMode), +_cmnd(PixelMap), +_cmnd(PixelTransfer), +_cmnd(PixelZoom), +_cmnd(RasterPos), +_cmnd(ReadBuffer), +_cmnd(ReadPixels), +_cmnd(SeparableFilter2D), +_cmnd(StencilFunc) |