1GLCOPYPIXELS(3G) OpenGL Manual GLCOPYPIXELS(3G)
2
6 glCopyPixels - copy pixels in the frame buffer
7
9 void glCopyPixels(GLint x, GLint y, GLsizei width, GLsizei height,
10 GLenum type);
11
13 x, y
14 Specify the window coordinates of the lower left corner of the
15 rectangular region of pixels to be copied.
16 width, height
18 Specify the dimensions of the rectangular region of pixels to be
19 copied. Both must be nonnegative.
20 type
22 Specifies whether color values, depth values, or stencil values are
23 to be copied. Symbolic constants GL_COLOR, GL_DEPTH, and GL_STENCIL
24 are accepted.
25
27 glCopyPixels copies a screen-aligned rectangle of pixels from the
28 specified frame buffer location to a region relative to the current
29 raster position. Its operation is well defined only if the entire pixel
30 source region is within the exposed portion of the window. Results of
31 copies from outside the window, or from regions of the window that are
32 not exposed, are hardware dependent and undefined.
33 x and y specify the window coordinates of the lower left corner of the
35 rectangular region to be copied. width and height specify the
36 dimensions of the rectangular region to be copied. Both width and
37 height must not be negative.
38 Several parameters control the processing of the pixel data while it is
40 being copied. These parameters are set with three commands:
41 glPixelTransfer(), glPixelMap(), and glPixelZoom(). This reference page
42 describes the effects on glCopyPixels of most, but not all, of the
43 parameters specified by these three commands.
44 glCopyPixels copies values from each pixel with the lower left-hand
46 corner at x + i y + j for 0 <= i < width and 0 <= j < height. This
47 pixel is said to be the ith pixel in the jth row. Pixels are copied in
48 row order from the lowest to the highest row, left to right in each
49 row.
50 type specifies whether color, depth, or stencil data is to be copied.
52 The details of the transfer for each data type are as follows:
53 GL_COLOR
55 Indices or RGBA colors are read from the buffer currently specified
56 as the read source buffer (see glReadBuffer()). If the GL is in
57 color index mode, each index that is read from this buffer is
58 converted to a fixed-point format with an unspecified number of
59 bits to the right of the binary point. Each index is then shifted
60 left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. If
61 GL_INDEX_SHIFT is negative, the shift is to the right. In either
62 case, zero bits fill otherwise unspecified bit locations in the
63 result. If GL_MAP_COLOR is true, the index is replaced with the
64 value that it references in lookup table GL_PIXEL_MAP_I_TO_I.
65 Whether the lookup replacement of the index is done or not, the
66 integer part of the index is then ANDed with 2 b - 1, where b is
67 the number of bits in a color index buffer.
68 If the GL is in RGBA mode, the red, green, blue, and alpha
70 components of each pixel that is read are converted to an internal
71 floating-point format with unspecified precision. The conversion
72 maps the largest representable component value to 1.0, and
73 component value 0 to 0.0. The resulting floating-point color values
74 are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c
75 is RED, GREEN, BLUE, and ALPHA for the respective color components.
76 The results are clamped to the range [0,1]. If GL_MAP_COLOR is
77 true, each color component is scaled by the size of lookup table
78 GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references
79 in that table. c is R, G, B, or A.
80 If the ARB_imaging extension is supported, the color values may be
82 additionally processed by color-table lookups, color-matrix
83 transformations, and convolution filters.
84 The GL then converts the resulting indices or RGBA colors to
86 fragments by attaching the current raster position z coordinate and
87 texture coordinates to each pixel, then assigning window
88 coordinates x r + i y r + j, where x r y r is the current raster
89 position, and the pixel was the ith pixel in the jth row. These
90 pixel fragments are then treated just like the fragments generated
91 by rasterizing points, lines, or polygons. Texture mapping, fog,
92 and all the fragment operations are applied before the fragments
93 are written to the frame buffer.
94 GL_DEPTH
96 Depth values are read from the depth buffer and converted directly
97 to an internal floating-point format with unspecified precision.
98 The resulting floating-point depth value is then multiplied by
99 GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to
100 the range [0,1].
101 The GL then converts the resulting depth components to fragments by
103 attaching the current raster position color or color index and
104 texture coordinates to each pixel, then assigning window
105 coordinates x r + i y r + j, where x r y r is the current raster
106 position, and the pixel was the ith pixel in the jth row. These
107 pixel fragments are then treated just like the fragments generated
108 by rasterizing points, lines, or polygons. Texture mapping, fog,
109 and all the fragment operations are applied before the fragments
110 are written to the frame buffer.
111 GL_STENCIL
113 Stencil indices are read from the stencil buffer and converted to
114 an internal fixed-point format with an unspecified number of bits
115 to the right of the binary point. Each fixed-point index is then
116 shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET.
117 If GL_INDEX_SHIFT is negative, the shift is to the right. In either
118 case, zero bits fill otherwise unspecified bit locations in the
119 result. If GL_MAP_STENCIL is true, the index is replaced with the
120 value that it references in lookup table GL_PIXEL_MAP_S_TO_S.
121 Whether the lookup replacement of the index is done or not, the
122 integer part of the index is then ANDed with 2 b - 1, where b is
123 the number of bits in the stencil buffer. The resulting stencil
124 indices are then written to the stencil buffer such that the index
125 read from the ith location of the jth row is written to location x
126 r + i y r + j, where x r y r is the current raster position. Only
127 the pixel ownership test, the scissor test, and the stencil
128 writemask affect these write operations.
129 The rasterization described thus far assumes pixel zoom factors of 1.0.
131 If glPixelZoom() is used to change the x and y pixel zoom factors,
132 pixels are converted to fragments as follows. If x r y r is the current
133 raster position, and a given pixel is in the ith location in the jth
134 row of the source pixel rectangle, then fragments are generated for
135 pixels whose centers are in the rectangle with corners at
136 x r + zoom x i y r + zoom y j
138 and
140 x r + zoom x i + 1 y r + zoom y j + 1
142 where zoom x is the value of GL_ZOOM_X and zoom y is the value of
144 GL_ZOOM_Y.
145
147 To copy the color pixel in the lower left corner of the window to the
148 current raster position, use
149 glCopyPixels(0, 0, 1, 1, GL_COLOR);
151
154 Modes specified by glPixelStore() have no effect on the operation of
155 glCopyPixels.
156
158 GL_INVALID_ENUM is generated if type is not an accepted value.
159 GL_INVALID_VALUE is generated if either width or height is negative.
161 GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no
163 depth buffer.
164 GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no
166 stencil buffer.
167 GL_INVALID_OPERATION is generated if glCopyPixels is executed between
169 the execution of glBegin() and the corresponding execution of glEnd().
170
172 glGet() with argument GL_CURRENT_RASTER_POSITION
173 glGet() with argument GL_CURRENT_RASTER_POSITION_VALID
175
177 glColorTable(), glConvolutionFilter1D(), glConvolutionFilter2D(),
178 glDepthFunc(), glDrawBuffer(), glDrawPixels(), glMatrixMode(),
179 glPixelMap(), glPixelTransfer(), glPixelZoom(), glRasterPos(),
180 glReadBuffer(), glReadPixels(), glSeparableFilter2D(), glStencilFunc(),
181 glWindowPos()
182
184 Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
185 under the SGI Free Software B License. For details, see
186 http://oss.sgi.com/projects/FreeB/.
187
189 opengl.org
190opengl.org 06/10/2014 GLCOPYPIXELS(3G)