GLCOPYPIXELS(3G)

💖 GLCOPYPIXELS 💖

okay so welcome to glCopyPixels(3G), straight out of the 3G OpenGL manual pages, and bestie this one is genuinely iconic — it's the "copy-paste but for pixels" function and I need you to be seated for it. 🫶

---

✨ NAME ✨

glCopyPixels — copy pixels in the frame buffer. that's the whole job. no notes. 💅

---

🌸 C SPECIFICATION 🌸

void glCopyPixels( GLint x,
                   GLint y,
                   GLsizei width,
                   GLsizei height,
                   GLenum type )

---

🎀 PARAMETERS 🎀

• x, y — the window coordinates of the lower left corner of the rectangular region of pixels you're copying. lowercase corner, that's the anchor. 🦋
• width, height — the dimensions of that rectangular region of pixels to be copied. both of them have to be nonnegative, no exceptions, no "but bestie I wanted negative width". 💀
• type — tells you what kind of values are getting copied: color values, depth values, or stencil values. the symbolic constants it accepts are GL_COLOR, GL_DEPTH, and GL_STENCIL. pick one, queen. 👑

---

💫 DESCRIPTION 💫

glCopyPixels copies a screen-aligned rectangle of pixels from the specified frame buffer location over to a region relative to the current raster position. main character energy, moving pixels around like it's nothing.

ok but real talk: 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. so like… don't. 🙈

x and y give the window coordinates of the lower left corner of the rectangular region being copied. width and height give the dimensions of that region. and again, both width and height must not be negative. 🚫

so there's a whole little committee of parameters that control how the pixel data gets processed while it's being copied. those parameters are set with three commands: glPixelTransfer, glPixelMap, and glPixelZoom. this reference page describes the effects on glCopyPixels of most, but not all, of the parameters specified by those three commands. so it's giving "here's the lore, but not all the lore". 😭

here's the actual pixel math, and it slays: glCopyPixels copies values from each pixel with the lower left-hand corner at (x + i, y + j) for 0 ≤ i < width and 0 ≤ j < height. this pixel is said to be the ith pixel in the jth row. pixels are copied in row order, from the lowest row to the highest row, and left to right within each row. so it's literally reading order but for rectangles. 📖

type specifies whether color, depth, or stencil data is being copied. the details of the transfer for each data type are as follows, and I'm giving you ALL of them because I love you:

🌈 GL_COLOR

Indices or RGBA colors are read from the buffer currently specified as the read source buffer (see glReadBuffer).

If the GL is in color index mode, each index that is read from this buffer is converted to a fixed-point with an unspecified number of bits to the right of the binary point. each index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. if GL_INDEX_SHIFT is negative, the shift is to the right. in either case, zero bits fill otherwise unspecified bit locations in the result. if GL_MAP_COLOR is true, the index is replaced with the value that it references in lookup table GL_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 2b−1, where b is the number of bits in a color index buffer.

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 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 GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. the results are clamped to the range [0,1]. if GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A.

If the GL_ARB_imaging extension is supported, the color values may be additionally processed by color-table lookups, color-matrix transformations, and convolution filters. ✨ fancy.

The GL then converts the resulting indices or RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning window coordinates (xr+i,yr+j), where (xr,yr) is the current raster position, and the pixel was the ith pixel in the jth 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. the full pipeline said "hold my boba". 🧋

🌊 GL_DEPTH

Depth values are read from the depth buffer and converted directly to an internal floating-point with unspecified precision. the resulting floating-point depth value is then multiplied by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. the result is clamped to the range [0,1].

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 (xr+i,yr+j), where (xr,yr) is the current raster position, and the pixel was the ith pixel in the jth 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.

🦄 GL_STENCIL

Stencil indices are read from the stencil buffer and converted to an internal fixed-point with an unspecified number of bits to the right of the binary point. each fixed-point index is then shifted left by GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET. if GL_INDEX_SHIFT is negative, the shift is to the right. in either case, zero bits fill otherwise unspecified bit locations in the result. if GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table GL_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 2b−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 ith location of the jth row is written to location (xr+i,yr+j), where (xr,yr) is the current raster position. only the pixel ownership test, the scissor test, and the stencil writemask affect these write operations. that's it, that's the whole guest list. 🎟️

---

🔍 the zoom part (do not skip, I'm serious)

The rasterization described thus far assumes pixel zoom factors of 1.0. if glPixelZoom is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. if (xr, yr) is the current raster position, and a given pixel is in the ith location in the jth row of the source pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at

                          (xr+zoomxi, yr+zoomyj)
                                    and
                      (xr+zoomx(i+1), yr+zoomy(j+1))

where zoomx is the value of GL_ZOOM_X and zoomy is the value of GL_ZOOM_Y. geometry girlies, this one's for you. 📐

---

🌟 EXAMPLES 🌟

To copy the color pixel in the lower left corner of the window to the current raster position, use:

glCopyPixels(0, 0, 1, 1, GL_COLOR);

one pixel. corner of the window. raster position. done and dusted. 🍓

---

📌 NOTES 📌

Modes specified by glPixelStore have no effect on the operation of glCopyPixels. so if you were about to set a pack or unpack mode and expect it to matter here… it does not, bestie. 💀

---

🚨 ERRORS 🚨

• GL_INVALID_ENUM is generated if type is not an accepted value.
• GL_INVALID_VALUE is generated if either width or height is negative.
• GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no depth buffer.
• GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no stencil buffer.
• GL_INVALID_OPERATION is generated if glCopyPixels is executed between the execution of glBegin and the corresponding execution of glEnd.

so basically: valid type, nonnegative dimensions, have the buffer you're asking for, and stay out of glBegin/glEnd. break any of those and the GL will be like "not today". 😭

---

👀 ASSOCIATED GETS 👀

• glGet with argument GL_CURRENT_RASTER_POSITION
• glGet with argument GL_CURRENT_RASTER_POSITION_VALID

---

💜 SEE ALSO 💜

• glColorTable(3G)
• glConvolutionFilter1D(3G)
• glConvolutionFilter2D(3G)
• glDepthFunc(3G)
• glDrawBuffer(3G)
• glDrawPixels(3G)
• glMatrixMode(3G)
• glPixelMap(3G)
• glPixelTransfer(3G)
• glPixelZoom(3G)
• glRasterPos(3G)
• glReadBuffer(3G)
• glReadPixels(3G)
• glSeparableFilter2D(3G)
• glStencilFunc(3G)

---

and that's the page!! this whole thing was GLCOPYPIXELS(3G) from the 3G OpenGL manual pages, so if you ever forget the vibe, just flip back to the 3G section and it'll be right there waiting for you like the loyal bestie it is. go forth and copy pixels responsibly, angel. 💖✨🎀🦋🌸💅🫶