--- name: "glPixelStore" section: "3x" platform: "linux" package: "xlibmesa-gl-dev" version: "4.3.0.dfsg.1-14sarge7" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/glPixelStore" --- # glPixelStore(3x) set pixel storage modes ## NAME **glPixelStoref, glPixelStorei** - set pixel storage modes ## C SPECIFICATION void **glPixelStoref**( GLenum *pname*, ``` GLfloat param ) ``` void **glPixelStorei**( GLenum *pname*, ``` GLint param ) ``` delim $$ ## PARAMETERS - *pname* Specifies the symbolic name of the parameter to be set. 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**. 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**. - *param* Specifies the value that *pname* is set to. ## DESCRIPTION **glPixelStore** sets pixel storage modes that affect the operation of subsequent **glDrawPixels** and **glReadPixels** as well as the unpacking of polygon stipple patterns (see **glPolygonStipple**), bitmaps (see **glBitmap**), texture patterns (see **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, **glTexSubImage3D**). Additionally, if the **GL\_ARB\_imaging** extension is supported, pixle storage modes affect convlution filters (see **glConvolutionFilter1D**, **glConvolutionFilter2D**, and **glSeparableFilter2D**, color table (see **glColorTable**, and **glColorSubTable**, and unpacking histogram (See **glHistogram**), and minmax (See **glMinmax**) data. *pname* is a symbolic constant indicating the parameter to be set, and *param* is the new value. Six of the twelve storage parameters affect how pixel data is returned to client memory. They are as follows: - **GL\_PACK\_SWAP\_BYTES** If true, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four-byte component consists of bytes $b sub 0$, $b sub 1$, $b sub 2$, $b sub 3$, it is stored in memory as $b sub 3$, $b sub 2$, $b sub 1$, $b sub 0$ if **GL\_PACK\_SWAP\_BYTES** is true. **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. For example, the three components of a **GL\_RGB** pixel are always stored with red first, green second, and blue third, regardless of the value of **GL\_PACK\_SWAP\_BYTES**. - **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. This parameter is significant for bitmap data only. - **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 ~=~~ left { ^ lpile { n l above {a over s left ceiling { s n l } over a right ceiling}} ~~ lpile {s ~\>=~ a above 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 left ceiling { n l } over { 8 a } ^ right ceiling$ components or indices. - The word *component* in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage **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 ~=~~ left { ~ lpile { n l h above {a over s left ceiling { s n l h } over a ^ right ceiling}} ~~ lpile {s ~\>=~ a above 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$). - The word *component* in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage **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 values are provided as a convenience to the programmer; they provide no functionality that cannot 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. - **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). The other six of the twelve storage parameters affect how pixel data is read from client memory. These values are significant for **glDrawPixels**, **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, **glTexSubImage3D**, **glBitmap**, and **glPolygonStipple**. Additionally, if the **GL\_ARB\_imaging** extension is supported, **glColorTable**, **glColorSubTable**, **glConvolutionFilter1D**, **glConvolutionFilter2D**, and **glSeparableFilter2D**. They are as follows: - **GL\_UNPACK\_SWAP\_BYTES** If true, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four-byte component consists of bytes $b sub 0$, $b sub 1$, $b sub 2$, $b sub 3$, it is taken from memory as $b sub 3$, $b sub 2$, $b sub 1$, $b sub 0$ if **GL\_UNPACK\_SWAP\_BYTES** is true. **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** pixel are always stored with red first, green second, and blue third, regardless of the value of **GL\_UNPACK\_SWAP\_BYTES**. - **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. This is relevant only for bitmap data. - **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 ~=~~ left { ~ lpile { n l above {a over s left ceiling { s n l } over a ^ right ceiling}} ~~ lpile {s ~\>=~ a above 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 left ceiling { n l } over { 8 a } right ceiling$ components or indices. - The word *component* in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage **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 ~=~~ left {~ lpile { n l h above {a over s left ceiling { s n l h } over a ^ right ceiling}} ~~ lpile {s ~ \>=~ a above 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 **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** These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated by incrementing the pointer passed to **glDrawPixels**, **glTexImage1D**, **glTexImage2D**, **glTexSubImage1D**, **glTexSubImage2D**, **glBitmap**, or **glPolygonStipple**. 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). The following table gives the type, initial value, and range of valid values for each storage parameter that can be set with **glPixelStore**. | | | | | | --- | --- | --- | --- | | ***pname*** | **Type** | **Initial Value** | **Valid Range** | | **GL\_PACK\_SWAP\_BYTES** | boolean | false | true or false | | **GL\_PACK\_LSB\_FIRST** | boolean | false | true or false | | **GL\_PACK\_ROW\_LENGTH** | integer | 0 | \[0,∞) | | **GL\_PACK\_IMAGE\_HEIGHT** | integer | 0 | \[0, ∞) | | **GL\_PACK\_SKIP\_ROWS** | integer | 0 | \[0,∞) | | **GL\_PACK\_SKIP\_PIXELS** | integer | 0 | \[0,∞) | | **GL\_PACK\_SKIP\_IMAGES** | integer | 0 | \[0,∞) | | **GL\_PACK\_ALIGNMENT** | integer | 4 | 1, 2, 4, or 8 | | **GL\_UNPACK\_SWAP\_BYTES** | boolean | false | true or false | | **GL\_UNPACK\_LSB\_FIRST** | boolean | false | true or false | | **GL\_UNPACK\_ROW\_LENGTH** | integer | 0 | \[0,∞) | | **GL\_UNPACK\_IMAGE\_HEIGHT** | integer | 0 | \[0,∞) | | **GL\_UNPACK\_SKIP\_ROWS** | integer | 0 | \[0,∞) | | **GL\_UNPACK\_SKIP\_PIXELS** | integer | 0 | \[0,∞) | | **GL\_UNPACK\_SKIP\_IMAGES** | integer | 0 | \[0,∞) | | **GL\_UNPACK\_ALIGNMENT** | integer | 4 | 1, 2, 4, or 8 | **glPixelStoref** can be used to set any pixel store parameter. If the parameter type is boolean, then if *param* is 0, the parameter is false; otherwise it is set to true. If *pname* is a integer type parameter, *param* is rounded to the nearest integer. Likewise, **glPixelStorei** can also be used to set any of the pixel store parameters. Boolean parameters are set to false if *param* is 0 and true otherwise. ## NOTES The pixel storage modes in effect when **glDrawPixels**, **glReadPixels**, **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, **glTexSubImage3D**, **glBitmap**, or **glPolygonStipple** is placed in a display list control the interpretation of memory data. Likewise, if the **GL\_ARB\_imaging** extension is supported, the pixel storage modes in effect when **glColorTable**, **glColorSubTable**, **glConvolutionFilter1D**, **glConvolutionFilter2D**, of **glSeparableFilter2D** is placed in a display list control the interpretation of memory data. The pixel storage modes in effect when a display list is executed are not significant. Pixel storage modes are client state and must be pushed and restored using \ **glPushClientAttrib** and **glPopClientAttrib**. ## ERRORS **GL\_INVALID\_ENUM** is generated if *pname* is not an accepted value. **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. **GL\_INVALID\_OPERATION** is generated if **glPixelStore** is executed between the execution of **glBegin** and the corresponding execution of **glEnd**. ## ASSOCIATED GETS **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** ## SEE ALSO **glBitmap(3G)**, **glColorTable(3G)**, **glColorSubTable(3G)**, **glConvolutionFilter1D(3G)**, **glConvolutionFilter2D(3G)**, **glSeparableFilter2D(3G)**, **glDrawPixels(3G)**, **glHistogram(3G)**, **glMinmax(3G)**, **glPixelMap(3G)**, **glPixelTransfer(3G)**, **glPixelZoom(3G)**, **glPolygonStipple(3G)**, **glPushClientAttrib(3G)**, **glReadPixels(3G)**, **glTexImage1D(3G)**, **glTexImage2D(3G)**, **glTexImage3D(3G)**, **glTexSubImage1D(3G)**, **glTexSubImage2D(3G)**, **glTexSubImage3D(3G)**