GLPIXELSTORE(3G)

📦
version 1.1 · 3 versions
, in centos-stream 9

🎀 GLPIXELSTORE(3G) 🎀

okay bestie, welcome to glPixelStore — the little function that decides how your pixel bytes get packed up and unpacked, and honestly it's giving "underrated icon" because when it's wrong, everything looks cursed. the header on this bad boy literally reads GLPIXELSTORE(3G) with a [FIXME: manual] sitting in the middle of it, and we're just gonna let that be iconic. 🌈

✨ NAME ✨

glPixelStore — set pixel storage modes. that's it. that's the whole vibe. 💅

🌸 C SPECIFICATION 🌸

void glPixelStoref(GLenum pname, GLfloat param);

void glPixelStorei(GLenum pname, GLint param);

two flavors, one for float girlies and one for int girlies. pick your fighter. 🫶

💖 PARAMETERS 💖

  • pname — the symbolic name of the parameter you wanna set. and listen, there's a lot of them: six values affect the packing of pixel data into memory: GL_PACK_SWAP_BYTES, GL_PACK_LSB_FIRST, GL_PACK_ROW_LENGTH, GL_PACK_IMAGE_HEIGHT, GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, GL_PACK_SKIP_IMAGES, and GL_PACK_ALIGNMENT. and then six more affect the unpacking of pixel data from memory: GL_UNPACK_SWAP_BYTES, GL_UNPACK_LSB_FIRST, GL_UNPACK_ROW_LENGTH, GL_UNPACK_IMAGE_HEIGHT, GL_UNPACK_SKIP_PIXELS, GL_UNPACK_SKIP_ROWS, GL_UNPACK_SKIP_IMAGES, and GL_UNPACK_ALIGNMENT. yes the count says six and the list says eight, we are simply not addressing that today, moving on 🫶
  • param — the value that pname gets set to. the actual number. the substance. 🍓

🦋 DESCRIPTION 🦋

glPixelStore sets pixel storage modes that affect how subsequent glReadPixels() behaves, plus the unpacking of texture patterns — and here comes the whole squad: glTexImage1D(), glTexImage2D(), glTexImage3D(), glTexSubImage1D(), glTexSubImage2D(), glTexSubImage3D(), glCompressedTexImage1D(), glCompressedTexImage2D(), glCompressedTexImage3D(), glCompressedTexSubImage1D(), glCompressedTexSubImage2D() or glCompressedTexSubImage1D(). (yes, glCompressedTexSubImage1D() is in there twice. she said "and I'll say it again." 💀)

pname is a symbolic constant saying which parameter you're setting, and param is the brand new value. Six of the twelve storage parameters affect how pixel data is returned to client memory. they are, in order, and yes I'm listing every single one:

🌟 the PACK girlies (data going OUT to client memory) 🌟

  • GL_PACK_SWAP_BYTES — if true, byte ordering for multibyte color components, depth components, or stencil indices gets reversed. so if a four-byte component consists of bytes b 0, b 1, b 2, b 3, it lands in memory as b 3, b 2, b 1, b 0 when GL_PACK_SWAP_BYTES is true. and lowkey important: GL_PACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indices. example time: the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, no matter what GL_PACK_SWAP_BYTES is doing. red stays first. she's not moving. 👑
  • GL_PACK_LSB_FIRST — if true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. little-endian energy vs. big-endian energy, byte edition. ⭐
  • GL_PACK_ROW_LENGTH — if greater than 0, GL_PACK_ROW_LENGTH defines the number of pixels in a row. if the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a

components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to the pixel routine otherwise), a is the value of GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s). in the case of 1-bit values, the location of the next row is obtained by skipping

k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a

components or indices. (and no, that's genuinely how the formula came out of the typesetter — I'm preserving the crime scene, not fixing it 💀)

the word component in this description refers to the nonindex values red, green, blue, alpha, and depth. storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. 🌸

  • GL_PACK_IMAGE_HEIGHT — if greater than 0, GL_PACK_IMAGE_HEIGHT defines the number of pixels in an image three-dimensional texture volume, where "image" is defined by all pixels sharing the same third dimension index. if the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a

components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to glTexImage3D() otherwise), h is the number of rows in a pixel image (GL_PACK_IMAGE_HEIGHT if it is greater than 0, the height argument to the glTexImage3D() routine otherwise), a is the value of GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s).

again: the word component here refers to the nonindex values red, green, blue, alpha, and depth. storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. 🧚

  • GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, and GL_PACK_SKIP_IMAGES — these are literally just a convenience for the programmer, bestie. they provide no functionality that can't be duplicated simply by incrementing the pointer passed to glReadPixels(). setting GL_PACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by i n components or indices, where n is the number of components or indices in each pixel. setting GL_PACK_SKIP_ROWS to j is equivalent to incrementing the pointer by j m components or indices, where m is the number of components or indices per row, as just computed in the GL_PACK_ROW_LENGTH section. setting GL_PACK_SKIP_IMAGES to k is equivalent to incrementing the pointer by k p, where p is the number of components or indices per image, as computed in the GL_PACK_IMAGE_HEIGHT section. it's giving "we built you a shortcut but also the shortcut is just maths." 🔥
  • GL_PACK_ALIGNMENT — specifies the alignment requirements for the start of each pixel row in memory. the allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows start on double-word boundaries). that's the whole menu, no substitutions. 👑

💜 the UNPACK girlies (data coming IN from client memory) 💜

the other six of the twelve storage parameters affect how pixel data is read from client memory. these values are significant for glTexImage1D(), glTexImage2D(), glTexImage3D(), glTexSubImage1D(), glTexSubImage2D(), and glTexSubImage3D(). and here they are:

  • GL_UNPACK_SWAP_BYTES — if true, byte ordering for multibyte color components, depth components, or stencil indices is reversed. that is, if a four-byte component consists of bytes b 0, b 1, b 2, b 3, it is taken from memory as b 3, b 2, b 1, b 0 if GL_UNPACK_SWAP_BYTES is true. and same as her PACK sister: GL_UNPACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indices. for example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_UNPACK_SWAP_BYTES. red. stays. first. periodt. 💅
  • GL_UNPACK_LSB_FIRST — if true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. 🌈
  • GL_UNPACK_ROW_LENGTH — if greater than 0, GL_UNPACK_ROW_LENGTH defines the number of pixels in a row. if the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
k = n ⁢ l a s ⁢ s ⁢ n ⁢ l a ⁢ s >= a s < a

components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument to the pixel routine otherwise), a is the value of GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s). in the case of 1-bit values, the location of the next row is obtained by skipping

k = 8 ⁢ a ⁢ n ⁢ l 8 ⁢ a

components or indices.

the word component in this description refers to the nonindex values red, green, blue, alpha, and depth. storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. 🎀

  • GL_UNPACK_IMAGE_HEIGHT — if greater than 0, GL_UNPACK_IMAGE_HEIGHT defines the number of pixels in an image of a three-dimensional texture volume, where "image" is defined by all pixel sharing the same third dimension index. if the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
k = n ⁢ l ⁢ h a s ⁢ s ⁢ n ⁢ l ⁢ h a ⁢ s >= a s < a

components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument to glTexImage3D() otherwise), h is the number of rows in an image (GL_UNPACK_IMAGE_HEIGHT if it is greater than 0, the height argument to glTexImage3D() otherwise), a is the value of GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a < s, then it is as if a = s).

the word component in this description refers to the nonindex values red, green, blue, alpha, and depth. storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. 🌸

  • GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS — convenience for the programmer, no cap. they provide no functionality that cannot be duplicated by incrementing the pointer passed to glTexImage1D(), glTexImage2D(), glTexSubImage1D() or glTexSubImage2D(). setting GL_UNPACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by i n components or indices, where n is the number of components or indices in each pixel. setting GL_UNPACK_SKIP_ROWS to j is equivalent to incrementing the pointer by j k components or indices, where k is the number of components or indices per row, as just computed in the GL_UNPACK_ROW_LENGTH section. 🦋
  • GL_UNPACK_ALIGNMENT — specifies the alignment requirements for the start of each pixel row in memory. the allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows start on double-word boundaries). same menu, different section. ⭐

okay so the next thing on the page is a table situation: the following table gives the type, initial value, and range of valid values for each storage parameter that can be set with glPixelStore — and that table is coming at you in the next part, so don't go anywhere, we're not done here yet 👀💖

okay so before we get into the chaos, here's the full roster of every pname you can throw at these functions — type, where it starts out, and what it's allowed to be. bookmark this bestie, it's the whole vibe check 💅

  • GL_PACK_SWAP_BYTES — type boolean, initial value false, valid range true or false
  • GL_PACK_LSB_FIRST — type boolean, initial value false, valid range true or false
  • GL_PACK_ROW_LENGTH — type integer, initial value 0, valid range 0 to ∞
  • GL_PACK_IMAGE_HEIGHT — type integer, initial value 0, valid range 0 to ∞
  • GL_PACK_SKIP_ROWS — type integer, initial value 0, valid range 0 to ∞
  • GL_PACK_SKIP_PIXELS — type integer, initial value 0, valid range 0 to ∞
  • GL_PACK_SKIP_IMAGES — type integer, initial value 0, valid range 0 to ∞
  • GL_PACK_ALIGNMENT — type integer, initial value 4, valid range 1, 2, 4, or 8
  • GL_UNPACK_SWAP_BYTES — type boolean, initial value false, valid range true or false
  • GL_UNPACK_LSB_FIRST — type boolean, initial value false, valid range true or false
  • GL_UNPACK_ROW_LENGTH — type integer, initial value 0, valid range 0 to ∞
  • GL_UNPACK_IMAGE_HEIGHT — type integer, initial value 0, valid range 0 to ∞
  • GL_UNPACK_SKIP_ROWS — type integer, initial value 0, valid range 0 to ∞
  • GL_UNPACK_SKIP_PIXELS — type integer, initial value 0, valid range 0 to ∞
  • GL_UNPACK_SKIP_IMAGES — type integer, initial value 0, valid range 0 to ∞
  • GL_UNPACK_ALIGNMENT — type integer, initial value 4, valid range 1, 2, 4, or 8

see how the pack ones and the unpack ones are basically twins? 🧚 one set is for reading out, one set is for feeding in, and they both start at the exact same defaults. iconic symmetry, honestly.

so like, glPixelStoref can be used to set any pixel store parameter. cute, right? and if the parameter type is boolean, then if param is 0, the parameter is set to false — otherwise it's set to true. no in-between, it's giving binary. ✨

and if pname is an integer type parameter, param gets rounded to the nearest integer. so like, don't stress about handing it a float, it'll just snap to the closest whole number. 🫶

likewise, glPixelStorei can also be used to set any of the pixel store parameters. same deal: boolean parameters are set to false if param is 0 and true otherwise. periodt. 💖

💀 ERRORS 💀

okay so here's where it can go wrong, and ngl it will if you're not paying attention:

  • GL_INVALID_ENUM is generated if pname is not an accepted value. basically if you made up a name, bestie, it's not gonna fly 🙈
  • GL_INVALID_VALUE is generated if a negative row length, pixel skip, or row skip value is specified, or if alignment is specified as other than 1, 2, 4, or 8. so like… negative skips? absolutely not. and that alignment value has to be one of those four, no exceptions. 💀
fr fr, double-check your alignment constant before you ship. 1, 2, 4, or 8. that's the whole list. don't be the person who passes 3 and then stares at the error. 😭

🔍 ASSOCIATED GETS 🔍

you wanna check what a parameter is currently set to? there's a getter for literally every single one of them, no cap:

  • glGet() with argument GL_PACK_SWAP_BYTES
  • glGet() with argument GL_PACK_LSB_FIRST
  • glGet() with argument GL_PACK_ROW_LENGTH
  • glGet() with argument GL_PACK_IMAGE_HEIGHT
  • glGet() with argument GL_PACK_SKIP_ROWS
  • glGet() with argument GL_PACK_SKIP_PIXELS
  • glGet() with argument GL_PACK_SKIP_IMAGES
  • glGet() with argument GL_PACK_ALIGNMENT
  • glGet() with argument GL_UNPACK_SWAP_BYTES
  • glGet() with argument GL_UNPACK_LSB_FIRST
  • glGet() with argument GL_UNPACK_ROW_LENGTH
  • glGet() with argument GL_UNPACK_IMAGE_HEIGHT
  • glGet() with argument GL_UNPACK_SKIP_ROWS
  • glGet() with argument GL_UNPACK_SKIP_PIXELS
  • glGet() with argument GL_UNPACK_SKIP_IMAGES
  • glGet() with argument GL_UNPACK_ALIGNMENT

sixteen parameters, sixteen getters. one-to-one. it's giving organized. 🎀

🌈 VERSION SUPPORT 🌈

good news bestie, these two functions are everywhere. like, everywhere everywhere. here's the receipts, and yes, the answer to every single column is a big fat ✔:

  • glPixelStoref — supported in OpenGL 2.0 ✔, 2.1 ✔, 3.0 ✔, 3.1 ✔, 3.2 ✔, 3.3 ✔, 4.0 ✔, 4.1 ✔, 4.2 ✔, 4.3 ✔, 4.4 ✔, 4.5 ✔
  • glPixelStorei — supported in OpenGL 2.0 ✔, 2.1 ✔, 3.0 ✔, 3.1 ✔, 3.2 ✔, 3.3 ✔, 4.0 ✔, 4.1 ✔, 4.2 ✔, 4.3 ✔, 4.4 ✔, 4.5 ✔

twelve out of twelve for both. full sweep. main character energy from 2.0 all the way through 4.5 👑✨

and there's still more page coming, so don't go anywhere 🦋

👀 SEE ALSO

okay so if you wanna go deeper (and like, you should), these are the besties this page is linked to — go read up on all of them:

  • glReadPixels()
  • glTexImage1D()
  • glTexImage2D()
  • glTexImage3D()
  • glTexSubImage1D()
  • glTexSubImage2D()
  • glTexSubImage3D()
  • glCompressedTexImage1D()
  • glCompressedTexImage2D()
  • glCompressedTexImage3D()
  • glCompressedTexSubImage1D()
  • glCompressedTexSubImage2D()
  • glCompressedTexSubImage1D()

(and yes, glCompressedTexSubImage1D() is listed twice in the original — iconic of them, no cap, not me fixing it 💅)

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.

Copyright © 1991-2006 Silicon Graphics, Inc.

Copyright © 2010-2014 Khronos Group

and that's a wrap on GLPIXELSTORE(3G)!! 🎀✨ you made it to the end, I'm so proud of you fr fr 💖 the source for this one is literally just [FIXME: source] (lol, slay), it's dated 08/09/2021, and it goes by GLPIXELSTORE(3G) — go forth and store those pixels, main character 🦋👑

📦 where this page comes from