--- name: "glPixelTransfer" 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/glPixelTransfer" --- # glPixelTransfer(3x) set pixel transfer modes ## NAME **glPixelTransferf, glPixelTransferi** - set pixel transfer modes ## C SPECIFICATION void **glPixelTransferf**( GLenum *pname*, ``` GLfloat param ) ``` void **glPixelTransferi**( GLenum *pname*, ``` GLint param ) ``` delim $$ ## PARAMETERS - *pname* Specifies the symbolic name of the pixel transfer parameter to be set. Must be one of the following: **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**. - Additionally, if the **GL\_ARB\_imaging** extension is supported, the following symbolic names are accepted: **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* Specifies the value that *pname* is set to. ## DESCRIPTION **glPixelTransfer** sets pixel transfer modes that affect the operation of subsequent **glCopyPixels**, **glCopyTexImage1D**, **glCopyTexImage2D**, **glCopyTexSubImage1D**, **glCopyTexSubImage2D**, **glCopyTexSubImage3D**, **glDrawPixels**, **glReadPixels**, **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, and **glTexSubImage3D** commands. Additionally, if the **GL\_ARB\_imaging** subset is supported, the routines **glColorTable**, **glColorSubTable**, **glConvolutionFilter1D**, **glConvolutionFilter2D**, **glHistogram**, **glMinmax**, and **glSeparableFilter2D** are also affected. The algorithms that are specified by pixel transfer modes operate on pixels after they are read from the frame buffer (**glCopyPixels** **glCopyTexImage1D**, **glCopyTexImage2D**, **glCopyTexSubImage1D**, **glCopyTexSubImage2D**, **glCopyTexSubImage3D**, and **glReadPixels**), or unpacked from client memory (**glDrawPixels**, **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, and **glTexSubImage3D**). Pixel transfer operations happen in the same order, and in the same manner, regardless of the command that resulted in the pixel operation. Pixel storage modes (see **glPixelStore**) control the unpacking of pixels being read from client memory, and the packing of pixels being written back into client memory. Pixel transfer operations handle four fundamental pixel types: *color*, *color index*, *depth*, and *stencil*. *Color* pixels consist of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0 represents zero intensity and 1 represents full intensity. *Color indices* comprise a single fixed-point value, with unspecified precision to the right of the binary point. *Depth* pixels comprise 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. Finally, *stencil* pixels comprise a single fixed-point value, with unspecified precision to the right of the binary point. The pixel transfer operations performed on the four basic pixel types are as follows: - Color Each of the four color components is multiplied by a scale factor, then added to a bias factor. That is, the red component is multiplied by **GL\_RED\_SCALE**, then added to **GL\_RED\_BIAS**; the green component is multiplied by **GL\_GREEN\_SCALE**, then added to **GL\_GREEN\_BIAS**; the blue component is multiplied by **GL\_BLUE\_SCALE**, then added to **GL\_BLUE\_BIAS**; and the alpha component is multiplied by **GL\_ALPHA\_SCALE**, then added to **GL\_ALPHA\_BIAS**. After all four color components are scaled and biased, each is clamped to the range \[0,1\]. All color, scale, and bias values are specified with **glPixelTransfer**. - If **GL\_MAP\_COLOR** is true, each color component is scaled by the size of the corresponding color-to-color map, then replaced by the contents of that map indexed by the scaled component. That is, the red component 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. The green component 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. The blue component 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. And the alpha component 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 is, the red component is multiplied by **GL\_POST\_COLOR\_MATRIX\_RED\_SCALE**, then added to **GL\_POST\_COLOR\_MATRIX\_RED\_BIAS**; the green component is multiplied by **GL\_POST\_COLOR\_MATRIX\_GREEN\_SCALE**, then added to **GL\_POST\_COLOR\_MATRIX\_GREEN\_BIAS**; the blue component is multiplied by **GL\_POST\_COLOR\_MATRIX\_BLUE\_SCALE**, then added to **GL\_POST\_COLOR\_MATRIX\_BLUE\_BIAS**; and the alpha component 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, 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. That is, the red component is multiplied by **GL\_POST\_CONVOLUTION\_RED\_SCALE**, then added to **GL\_POST\_CONVOLUTION\_RED\_BIAS**; the green component is multiplied by **GL\_POST\_CONVOLUTION\_GREEN\_SCALE**, then added to **GL\_POST\_CONVOLUTION\_GREEN\_BIAS**; the blue component is multiplied by **GL\_POST\_CONVOLUTION\_BLUE\_SCALE**, then added to **GL\_POST\_CONVOLUTION\_BLUE\_BIAS**; and the alpha component 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\]. - Color index Each color index is shifted left by **GL\_INDEX\_SHIFT** bits; 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 is to the right, again zero filled. Then **GL\_INDEX\_OFFSET** is added to the index. **GL\_INDEX\_SHIFT** and **GL\_INDEX\_OFFSET** are specified with \ **glPixelTransfer**. - From this point, operation diverges depending on the required of the resulting pixels. If the resulting pixels are to be written to a color index buffer, or if they are being read back to client memory in **GL\_COLOR\_INDEX** , the pixels continue to be treated as indices. 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 are read back to client memory in a other than **GL\_COLOR\_INDEX**, the pixels are 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, and **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\]. - Stencil Each index is shifted **GL\_INDEX\_SHIFT** bits just as a color index is, then added to **GL\_INDEX\_OFFSET**. 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. 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**. | | | | | | --- | --- | --- | --- | | ***pname*** | **Type** | **Initial Value** | **Valid Range** | | **GL\_MAP\_COLOR** | boolean | false | true/false | | **GL\_MAP\_STENCIL** | boolean | false | true/false | | **GL\_INDEX\_SHIFT** | integer | 0 | (-∞,∞) | | **GL\_INDEX\_OFFSET** | integer | 0 | (-∞,∞) | | **GL\_RED\_SCALE** | float | 1 | (-∞,∞) | | **GL\_GREEN\_SCALE** | float | 1 | (-∞,∞) | | **GL\_BLUE\_SCALE** | float | 1 | (-∞,∞) | | **GL\_ALPHA\_SCALE** | float | 1 | (-∞,∞) | | **GL\_DEPTH\_SCALE** | float | 1 | (-∞,∞) | | **GL\_RED\_BIAS** | float | 0 | (-∞,∞) | | **GL\_GREEN\_BIAS** | float | 0 | (-∞,∞) | | **GL\_BLUE\_BIAS** | float | 0 | (-∞,∞) | | **GL\_ALPHA\_BIAS** | float | 0 | (-∞,∞) | | **GL\_DEPTH\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_RED\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_GREEN\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_BLUE\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_ALPHA\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_RED\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_GREEN\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_BLUE\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_COLOR\_MATRIX\_ALPHA\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_RED\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_GREEN\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_BLUE\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_ALPHA\_SCALE** | float | 1 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_RED\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_GREEN\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_BLUE\_BIAS** | float | 0 | (-∞,∞) | | **GL\_POST\_CONVOLUTION\_ALPHA\_BIAS** | float | 0 | (-∞,∞) | **glPixelTransferf** can be used to set any pixel transfer parameter. If the parameter type is boolean, 0 implies false and any other value implies true. If *pname* is an integer parameter, *param* is rounded to the nearest integer. Likewise, **glPixelTransferi** can be used to set any of the pixel transfer parameters. Boolean parameters are set to false if *param* is 0 and to true otherwise. *param* is converted to floating point before being assigned to real-valued parameters. ## NOTES If a **glColorTable**, **glColorSubTable**, **glConvolutionFilter1D**, **glConvolutionFilter2D**, **glCopyPixels**, **glCopyTexImage1D**, **glCopyTexImage2D**, **glCopyTexSubImage1D**, **glCopyTexSubImage2D**, **glCopyTexSubImage3D**, **glDrawPixels**, **glReadPixels**, **glSeparableFilter2D**, **glTexImage1D**, **glTexImage2D**, **glTexImage3D**, **glTexSubImage1D**, **glTexSubImage2D**, or **glTexSubImage3D**. command is placed in a display list (see **glNewList** and **glCallList**), the pixel transfer mode settings in effect when the display list is *executed* are the ones that are used. They may be different from the settings when the command was compiled into the display list. ## ERRORS **GL\_INVALID\_ENUM** is generated if *pname* is not an accepted value. **GL\_INVALID\_OPERATION** is generated if **glPixelTransfer** is executed between the execution of **glBegin** and the corresponding execution of **glEnd**. ## 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)**