1GLCOPYPIXELS(3G) GLCOPYPIXELS(3G)
2
6 glCopyPixels - copy pixels in the frame buffer
7
10 void glCopyPixels( GLint x,
11 GLint y,
12 GLsizei width,
13 GLsizei height,
14 GLenum type )
15
18 x, y Specify the window coordinates of the lower left corner of the
19 rectangular region of pixels to be copied.
20 width, height
22 Specify the dimensions of the rectangular region of pixels to be
23 copied. Both must be nonnegative.
24 type Specifies whether color values, depth values, or stencil values
26 are to be copied. Symbolic constants GL_COLOR, GL_DEPTH, and
27 GL_STENCIL are accepted.
28
30 glCopyPixels copies a screen-aligned rectangle of pixels from the spec‐
31 ified frame buffer location to a region relative to the current raster
32 position. Its operation is well defined only if the entire pixel
33 source region is within the exposed portion of the window. Results of
34 copies from outside the window, or from regions of the window that are
35 not exposed, are hardware dependent and undefined.
36 x and y specify the window coordinates of the lower left corner of the
38 rectangular region to be copied. width and height specify the dimen‐
39 sions of the rectangular region to be copied. Both width and height
40 must not be negative.
41 Several parameters control the processing of the pixel data while it is
43 being copied. These parameters are set with three commands:
44 glPixelTransfer, glPixelMap, and glPixelZoom. This reference page
45 describes the effects on glCopyPixels of most, but not all, of the
46 parameters specified by these three commands.
47 glCopyPixels copies values from each pixel with the lower left-hand
49 corner at (x + i, y + j) for 0 ≤ i < width and 0 ≤ j < height. This
50 pixel is said to be the ith pixel in the jth row. Pixels are copied in
51 row order from the lowest to the highest row, left to right in each
52 row.
53 type specifies whether color, depth, or stencil data is to be copied.
55 The details of the transfer for each data type are as follows:
56 GL_COLOR Indices or RGBA colors are read from the buffer cur‐
58 rently specified as the read source buffer (see
59 glReadBuffer). If the GL is in color index mode, each
60 index that is read from this buffer is converted to a
61 fixed-point with an unspecified number of bits to the
62 right of the binary point. Each index is then shifted
63 left by GL_INDEX_SHIFT bits, and added to
64 GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the
65 shift is to the right. In either case, zero bits fill
66 otherwise unspecified bit locations in the result. If
67 GL_MAP_COLOR is true, the index is replaced with the
68 value that it references in lookup table
69 GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of
70 the index is done or not, the integer part of the index
71 is then ANDed with 2b−1, where b is the number of bits
72 in a color index buffer.
73 If the GL is in RGBA mode, the red, green, blue, and
75 alpha components of each pixel that is read are con‐
76 verted to an internal floating-point with unspecified
77 precision. The conversion maps the largest repre‐
78 sentable component value to 1.0, and component value 0
79 to 0.0. The resulting floating-point color values are
80 then multiplied by GL_c_SCALE and added to GL_c_BIAS,
81 where c is RED, GREEN, BLUE, and ALPHA for the respec‐
82 tive color components. The results are clamped to the
83 range [0,1]. If GL_MAP_COLOR is true, each color compo‐
84 nent is scaled by the size of lookup table
85 GL_PIXEL_MAP_c_TO_c, then replaced by the value that it
86 references in that table. c is R, G, B, or A.
87 If the GL_ARB_imaging extension is supported, the color
89 values may be additionally processed by color-table
90 lookups, color-matrix transformations, and convolution
91 filters.
92 The GL then converts the resulting indices or RGBA col‐
94 ors to fragments by attaching the current raster posi‐
95 tion z coordinate and texture coordinates to each pixel,
96 then assigning window coordinates (xr+i,yr+j), where
97 (xr,yr) is the current raster position, and the pixel
98 was the ith pixel in the jth row. These pixel fragments
99 are then treated just like the fragments generated by
100 rasterizing points, lines, or polygons. Texture map‐
101 ping, fog, and all the fragment operations are applied
102 before the fragments are written to the frame buffer.
103 GL_DEPTH Depth values are read from the depth buffer and con‐
105 verted directly to an internal floating-point with
106 unspecified precision. The resulting floating-point
107 depth value is then multiplied by GL_DEPTH_SCALE and
108 added to GL_DEPTH_BIAS. The result is clamped to the
109 range [0,1].
110 The GL then converts the resulting depth components to
112 fragments by attaching the current raster position color
113 or color index and texture coordinates to each pixel,
114 then assigning window coordinates (xr+i,yr+j), where
115 (xr,yr) is the current raster position, and the pixel
116 was the ith pixel in the jth row. These pixel fragments
117 are then treated just like the fragments generated by
118 rasterizing points, lines, or polygons. Texture map‐
119 ping, fog, and all the fragment operations are applied
120 before the fragments are written to the frame buffer.
121 GL_STENCIL Stencil indices are read from the stencil buffer and
123 converted to an internal fixed-point with an unspecified
124 number of bits to the right of the binary point. Each
125 fixed-point index is then shifted left by GL_INDEX_SHIFT
126 bits, and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT
127 is negative, the shift is to the right. In either case,
128 zero bits fill otherwise unspecified bit locations in
129 the result. If GL_MAP_STENCIL is true, the index is
130 replaced with the value that it references in lookup ta‐
131 ble GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement
132 of the index is done or not, the integer part of the
133 index is then ANDed with 2b−1, where b is the number of
134 bits in the stencil buffer. The resulting stencil
135 indices are then written to the stencil buffer such that
136 the index read from the ith location of the jth row is
137 written to location (xr+i,yr+j), where (xr,yr) is the
138 current raster position. Only the pixel ownership test,
139 the scissor test, and the stencil writemask affect these
140 write operations.
141 The rasterization described thus far assumes pixel zoom factors of 1.0.
143 If
144 glPixelZoom is used to change the x and y pixel zoom factors, pixels
145 are converted to fragments as follows. If (xr, yr) is the current
146 raster position, and a given pixel is in the ith location in the jth
147 row of the source pixel rectangle, then fragments are generated for
148 pixels whose centers are in the rectangle with corners at
149 (xr+zoomxi, yr+zoomyj)
151 and
152 (xr+zoomx(i+1), yr+zoomy(j+1))
153 where zoomx is the value of GL_ZOOM_X and zoomy is the value of
155 GL_ZOOM_Y.
156
158 To copy the color pixel in the lower left corner of the window to the
159 current raster position, use glCopyPixels(0, 0, 1, 1, GL_COLOR);
160
162 Modes specified by glPixelStore have no effect on the operation of
163 glCopyPixels.
164
166 GL_INVALID_ENUM is generated if type is not an accepted value.
167 GL_INVALID_VALUE is generated if either width or height is negative.
169 GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no
171 depth buffer.
172 GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no
174 stencil buffer.
175 GL_INVALID_OPERATION is generated if glCopyPixels is executed between
177 the execution of glBegin and the corresponding execution of glEnd.
178
180 glGet with argument GL_CURRENT_RASTER_POSITION
181 glGet with argument GL_CURRENT_RASTER_POSITION_VALID
182
184 glColorTable(3G), glConvolutionFilter1D(3G), glConvolutionFilter2D(3G),
185 glDepthFunc(3G), glDrawBuffer(3G), glDrawPixels(3G), glMatrixMode(3G),
186 glPixelMap(3G), glPixelTransfer(3G), glPixelZoom(3G), glRasterPos(3G),
187 glReadBuffer(3G), glReadPixels(3G), glSeparableFilter2D(3G),
188 glStencilFunc(3G)
189 GLCOPYPIXELS(3G)