GLPIXELTRANSFER(3G)

📦 version 24.3.3, in opensuse-leap 16.0

💖 GLPIXELTRANSFER(3G) 💖

okay so hi bestie, this is the manual page for glPixelTransferf and glPixelTransferi — yes both of them, they're twinsies, one takes floats one takes ints, we'll get there. grab a snack, this one's a long one. 🍓

✨ NAME ✨

glPixelTransferf, glPixelTransferi — set pixel transfer modes

no cap, that's the whole name section, it's giving minimalism 💅

🌸 C SPECIFICATION 🌸

void glPixelTransferf( GLenum pname,
                       GLfloat param )
void glPixelTransferi( GLenum pname,
                       GLint param )
also there's a lil delim $$ sitting in the original right under this, which is just the troff girlies setting up their math delimiters so the $...$ formulas later actually render. iconic behavior, we love to see it. 🎀

🎀 PARAMETERS 🎀

  • pname — the symbolic name of the pixel transfer parameter you're setting, bestie. It has to be one of these, no substitutes: GL_MAP_COLOR, GL_MAP_STENCIL, GL_INDEX_SHIFT, GL_INDEX_OFFSET, GL_RED_SCALE, GL_RED_BIAS, GL_GREEN_SCALE, GL_GREEN_BIAS, GL_BLUE_SCALE, GL_BLUE_BIAS, GL_ALPHA_SCALE, GL_ALPHA_BIAS, GL_DEPTH_SCALE, or GL_DEPTH_BIAS.

and — plot twist — if the GL_ARB_imaging extension is supported, these symbolic names are accepted too: GL_POST_COLOR_MATRIX_RED_SCALE, GL_POST_COLOR_MATRIX_GREEN_SCALE, GL_POST_COLOR_MATRIX_BLUE_SCALE, GL_POST_COLOR_MATRIX_ALPHA_SCALE, GL_POST_COLOR_MATRIX_RED_BIAS, GL_POST_COLOR_MATRIX_GREEN_BIAS, GL_POST_COLOR_MATRIX_BLUE_BIAS, GL_POST_COLOR_MATRIX_ALPHA_BIAS, GL_POST_CONVOLUTION_RED_SCALE, GL_POST_CONVOLUTION_GREEN_SCALE, GL_POST_CONVOLUTION_BLUE_SCALE, GL_POST_CONVOLUTION_ALPHA_SCALE, GL_POST_CONVOLUTION_RED_BIAS, GL_POST_CONVOLUTION_GREEN_BIAS, GL_POST_CONVOLUTION_BLUE_BIAS, and GL_POST_CONVOLUTION_ALPHA_BIAS. 😌✨

  • param — the value that pname gets set to. that's it. that's the whole job. 🫶

🦋 DESCRIPTION 🦋

okay so glPixelTransfer sets the pixel transfer modes — and those modes change how a whole stack of later commands behave: glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D. that's the list, we don't skip entries in this house 💅

and if the GL_ARB_imaging subset is supported, these routines are affected as well: glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glHistogram, glMinmax, and glSeparableFilter2D. 🔥

the algorithms that the pixel transfer modes specify operate on pixels after they're read from the frame buffer — that's glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, and glReadPixels — or after they're unpacked from client memory — that's glDrawPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D. 🧚

the way the pixel transfer operations happen? same order, same manner, every single time, no matter which command kicked off the pixel operation. it's consistent, it's reliable, it's the main character of the pipeline. 👑

meanwhile, pixel storage modes (peep glPixelStore) are a whole different thing — those control the unpacking of pixels being read from client memory, and the packing of pixels being written back into client memory. two separate systems bestie, don't mix them up. 🙈

🌈 the four fundamental pixel types 🌈

pixel transfer operations handle four fundamental pixel types: color, color index, depth, and stencil.

  • color — four floating-point values, with unspecified mantissa and exponent sizes, scaled such that 0 represents zero intensity and 1 represents full intensity. ✨
  • color index — a single fixed-point value, with unspecified precision to the right of the binary point. 💜
  • depth — a single floating-point value, with unspecified mantissa and exponent sizes, scaled such that 0.0 represents the minimum depth buffer value, and 1.0 represents the maximum depth buffer value. 🌊
  • stencil — a single fixed-point value, with unspecified precision to the right of the binary point. 🍃

and now, the pixel transfer operations performed on those four basic pixel types, one by one, no skipping:

💖 Color 💖

each of the four color components gets multiplied by a scale factor, then added to a bias factor. literally:

  • red gets multiplied by GL_RED_SCALE, then added to GL_RED_BIAS
  • green gets multiplied by GL_GREEN_SCALE, then added to GL_GREEN_BIAS
  • blue gets multiplied by GL_BLUE_SCALE, then added to GL_BLUE_BIAS
  • alpha gets multiplied by GL_ALPHA_SCALE, then added to GL_ALPHA_BIAS

after all four color components are scaled and biased, each one is clamped to the range [0,1]. all the color, scale, and bias values are specified with glPixelTransfer. 💅

now, if GL_MAP_COLOR is true — each color component gets scaled by the size of the corresponding color-to-color map, then replaced by the contents of that map indexed by the scaled component. so:

  • red is scaled by GL_PIXEL_MAP_R_TO_R_SIZE, then replaced by the contents of GL_PIXEL_MAP_R_TO_R indexed by itself
  • green is scaled by GL_PIXEL_MAP_G_TO_G_SIZE, then replaced by the contents of GL_PIXEL_MAP_G_TO_G indexed by itself
  • blue is scaled by GL_PIXEL_MAP_B_TO_B_SIZE, then replaced by the contents of GL_PIXEL_MAP_B_TO_B indexed by itself
  • alpha is scaled by GL_PIXEL_MAP_A_TO_A_SIZE, then replaced by the contents of GL_PIXEL_MAP_A_TO_A indexed by itself

all components taken from the maps are then clamped to the range [0,1]. GL_MAP_COLOR is specified with glPixelTransfer. the contents of the various maps are specified with glPixelMap. 🗺️✨

if the GL_ARB_imaging extension is supported, each of the four color components may be scaled and biased after transformation by the color matrix. that means:

  • red is multiplied by GL_POST_COLOR_MATRIX_RED_SCALE, then added to GL_POST_COLOR_MATRIX_RED_BIAS
  • green is multiplied by GL_POST_COLOR_MATRIX_GREEN_SCALE, then added to GL_POST_COLOR_MATRIX_GREEN_BIAS
  • blue is multiplied by GL_POST_COLOR_MATRIX_BLUE_SCALE, then added to GL_POST_COLOR_MATRIX_BLUE_BIAS
  • alpha is multiplied by GL_POST_COLOR_MATRIX_ALPHA_SCALE, then added to GL_POST_COLOR_MATRIX_ALPHA_BIAS

after all four color components are scaled and biased, each is clamped to the range [0,1]. 😤

similiarly (yes, that's how it's spelled in the original, we're keeping it, no notes 💀) — if the GL_ARB_imaging extension is supported, each of the four color components may be scaled and biased after processing by the enabled convolution filter:

  • red is multiplied by GL_POST_CONVOLUTION_RED_SCALE, then added to GL_POST_CONVOLUTION_RED_BIAS
  • green is multiplied by GL_POST_CONVOLUTION_GREEN_SCALE, then added to GL_POST_CONVOLUTION_GREEN_BIAS
  • blue is multiplied by GL_POST_CONVOLUTION_BLUE_SCALE, then added to GL_POST_CONVOLUTION_BLUE_BIAS
  • alpha is multiplied by GL_POST_CONVOLUTION_ALPHA_SCALE, then added to GL_POST_CONVOLUTION_ALPHA_BIAS

after all four color components are scaled and biased, each is clamped to the range [0,1]. periodt. 🫶

🎀 Color index 🎀

each color index gets shifted left by GL_INDEX_SHIFT bits, and any bits beyond the number of fraction bits carried by the fixed-point index are filled with zeros. if GL_INDEX_SHIFT is negative, the shift goes to the right instead, again zero filled. ✨

then GL_INDEX_OFFSET is added to the index. both GL_INDEX_SHIFT and GL_INDEX_OFFSET are specified with glPixelTransfer. 💅

from this point, the operation diverges depending on the required ␣ of the resulting pixels — yeah there's literally a missing word in the original there, we're not fixing it, we're respecting the artifact 🙈 — so, the branch:

  • if the resulting pixels are to be written to a color index buffer, or if they're being read back to client memory in GL_COLOR_INDEX, the pixels keep being treated as indices. and if GL_MAP_COLOR is true, each index is masked by $2 sup n ~-~ 1$, where $n$ is GL_PIXEL_MAP_I_TO_I_SIZE, then replaced by the contents of GL_PIXEL_MAP_I_TO_I indexed by the masked value. GL_MAP_COLOR is specified with glPixelTransfer. the contents of the index map is specified with glPixelMap. 🗺️
  • if the resulting pixels are to be written to an RGBA color buffer, or if they're read back to client memory in anything other than GL_COLOR_INDEX, the pixels get converted from indices to colors by referencing the four maps GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A. before being dereferenced, the index is masked by $2 sup n ~-~ 1$, where $n$ is:
    • GL_PIXEL_MAP_I_TO_R_SIZE for the red map
    • GL_PIXEL_MAP_I_TO_G_SIZE for the green map
    • GL_PIXEL_MAP_I_TO_B_SIZE for the blue map
    • GL_PIXEL_MAP_I_TO_A_SIZE for the alpha map

all components taken from the maps are then clamped to the range [0,1]. the contents of the four maps is specified with glPixelMap. 🌈

🦋 Depth 🦋

each depth value is multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, then clamped to the range [0,1]. three steps, that's the whole vibe. 🫧

🧚 Stencil 🧚

each index is shifted GL_INDEX_SHIFT bits just like a color index is, then added to GL_INDEX_OFFSET. and if GL_MAP_STENCIL is true, each index is masked by $2 sup n ~-~ 1$, where $n$ is GL_PIXEL_MAP_S_TO_S_SIZE, then replaced by the contents of GL_PIXEL_MAP_S_TO_S indexed by the masked value. 👑

and then — bestie, we're not done — the original says:

the following table gives the type, initial value, and range of valid values for each of the pixel transfer parameters that are set with glPixelTransfer.

and that table is coming right up in the next part, so don't go anywhere 💖✨

okay so here's the whole roster of pixel-transfer knobs you can pass as pname — every one of them, with its type, its starting value, and the range it's allowed to vibe in 💖:

  • GL_MAP_COLOR — it's a boolean, starts out as false, and its valid range is true/false.
  • GL_MAP_STENCIL — also a boolean, defaulting to false, valid range true/false.
  • GL_INDEX_SHIFT — an integer, initial value 0, valid range (-∞,∞).
  • GL_INDEX_OFFSET — integer, starts at 0, valid range (-∞,∞).
  • GL_RED_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_GREEN_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_BLUE_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_ALPHA_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_DEPTH_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_RED_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_GREEN_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_BLUE_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_ALPHA_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_DEPTH_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_RED_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_GREEN_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_BLUE_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_ALPHA_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_RED_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_GREEN_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_BLUE_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_COLOR_MATRIX_ALPHA_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_RED_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_GREEN_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_BLUE_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_ALPHA_SCALE — float, initial value 1, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_RED_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_GREEN_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_BLUE_BIAS — float, initial value 0, valid range (-∞,∞).
  • GL_POST_CONVOLUTION_ALPHA_BIAS — float, initial value 0, valid range (-∞,∞).

and fr fr, glPixelTransferf can set any pixel transfer parameter. if the parameter type is boolean, then 0 means false and literally any other value means true. and if pname is an integer parameter, param gets rounded to the nearest integer. ✨

same energy with glPixelTransferi — it can also set any of the pixel transfer parameters. boolean parameters go false when param is 0 and true otherwise. and before param gets assigned to any real-valued parameter, it's converted to floating point. 💅

📝 NOTES 📝

okay bestie, listen up, this part matters 👀

if a glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glReadPixels, glSeparableFilter2D, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, or glTexSubImage3D command gets placed in a display list (peep glNewList and glCallList), then the pixel transfer mode settings that are in effect when the display list is executed are the ones that actually get used. and yes, those can absolutely be different from the settings that were active when the command was compiled into the display list. no cap. 😭

🚨 ERRORS 🚨

  • GL_INVALID_ENUM gets generated if pname is not an accepted value. 🙅‍♀️
  • GL_INVALID_OPERATION gets generated if glPixelTransfer is executed between the execution of glBegin and the corresponding execution of glEnd. don't do that bestie, that's illegal behavior 💀

🔍 ASSOCIATED GETS 🔍

  • glGet with argument GL_MAP_COLOR
  • glGet with argument GL_MAP_STENCIL
  • glGet with argument GL_INDEX_SHIFT
  • glGet with argument GL_INDEX_OFFSET
  • glGet with argument GL_RED_SCALE
  • glGet with argument GL_RED_BIAS
  • glGet with argument GL_GREEN_SCALE
  • glGet with argument GL_GREEN_BIAS
  • glGet with argument GL_BLUE_SCALE
  • glGet with argument GL_BLUE_BIAS
  • glGet with argument GL_ALPHA_SCALE
  • glGet with argument GL_ALPHA_BIAS
  • glGet with argument GL_DEPTH_SCALE
  • glGet with argument GL_DEPTH_BIAS
  • glGet with argument GL_POST_COLOR_MATRIX_RED_SCALE
  • glGet with argument GL_POST_COLOR_MATRIX_RED_BIAS
  • glGet with argument GL_POST_COLOR_MATRIX_GREEN_SCALE
  • glGet with argument GL_POST_COLOR_MATRIX_GREEN_BIAS
  • glGet with argument GL_POST_COLOR_MATRIX_BLUE_SCALE
  • glGet with argument GL_POST_COLOR_MATRIX_BLUE_BIAS
  • glGet with argument GL_POST_COLOR_MATRIX_ALPHA_SCALE
  • glGet with argument GL_POST_COLOR_MATRIX_ALPHA_BIAS
  • glGet with argument GL_POST_CONVOLUTION_RED_SCALE
  • glGet with argument GL_POST_CONVOLUTION_RED_BIAS
  • glGet with argument GL_POST_CONVOLUTION_GREEN_SCALE
  • glGet with argument GL_POST_CONVOLUTION_GREEN_BIAS
  • glGet with argument GL_POST_CONVOLUTION_BLUE_SCALE
  • glGet with argument GL_POST_CONVOLUTION_BLUE_BIAS
  • glGet with argument GL_POST_CONVOLUTION_ALPHA_SCALE
  • glGet with argument GL_POST_CONVOLUTION_ALPHA_BIAS

🌈 SEE ALSO 🌈

  • glCallList(3G)
  • glColorTable(3G)
  • glColorSubTable(3G)
  • glConvolutionFilter1D(3G)
  • glConvolutionFilter2D(3G)
  • glCopyPixels(3G)
  • glCopyTexImage1D(3G)
  • glCopyTexImage2D(3G)
  • glCopyTexSubImage1D(3G)
  • glCopyTexSubImage2D(3G)
  • glCopyTexSubImage3D(3G)
  • glDrawPixels(3G)
  • glNewList(3G)
  • glPixelMap(3G)
  • glPixelStore(3G)
  • glPixelZoom(3G)
  • glReadPixels(3G)
  • glTexImage1D(3G)
  • glTexImage2D(3G)
  • glTexImage3D(3G)
  • glTexSubImage1D(3G)
  • glTexSubImage2D(3G)
  • glTexSubImage3D(3G)

and that's the whole page bestie, you ate that 🫶 the footer says GLPIXELTRANSFER(3G) so like, that's the name and the section, periodt 💅✨

📦 where this page comes from