PixelTransfer

NAME

C SPECIFICATION

void glPixelTransferf(GLenum pname,
                      GLfloat param)

void glPixelTransferi(GLenum pname,
                      GLint param)

PARAMETERS

DESCRIPTION

Pixel transfer operations handle four fundamental pixel types: color, color index, depth, and stencil. Color pixels are made up of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0.0 represents zero intensity and 1.0 represents full intensity. Color indexes 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, and then added to a bias factor. That is, the red component is multiplied by GL_RED_SCALE, and then added to GL_RED_BIAS; the green component is multiplied by GL_GREEN_SCALE, and then added to GL_GREEN_BIAS; the blue component is multiplied by GL_BLUE_SCALE, and then added to GL_BLUE_BIAS; and the alpha component is multiplied by GL_ALPHA_SCALE, and 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, and 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, and 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, and 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, and then replaced by the contents of GL_PIXEL_MAP_B_TO_B indexed by itself. The alpha component is scaled by GL_PIXEL_MAP_A_TO_A_SIZE, and then replaced by the contents of GL_PIXEL_MAP_A_TO_A indexed by itself. GL_MAP_COLOR is specified with glPixelTransfer. The contents of the various maps are specified with glPixelMap.

If GL_COLOR_TABLE_EXT is true and a non-zero width color table is defined, then each RGBA color component may be replaced depending on the internal format of the color table. The components to be replaced are converted to indices by clamping to [0,1], multiplying by an integer one less than the width of the table, and rounding to the nearest integer. The appropriate components are replaced by the table entry at the index.

If GL_CONVOLUTION_1D_EXT is true, the one-dimensional convolution filter is applied only to the one-dimensional texture images. If GL_CONVOLUTION_2D_EXT is true, the two-dimensional convolution filter is applied only to the two-dimensional images If GL_SEPARABLE_2D_EXT is true and GL_CONVOLUTION_2D_EXT is false, the separable two-dimensional convolution filter is instead applied to these images. After convolution, each component of the resulting image is scaled by the corresponding PixelTransfer parameters: GL_POST_CONVOLUTION_RED_SCALE_EXT for a red component, GL_POST_CONVOLUTION_GREEN_SCALE_EXT for a green component, GL_POST_CONVOLUTION_BLUE_SCALE_EXT for a blue component, and GL_POST_CONVOLUTION_ALPHA_SCALE_EXT for an alpha component. The result is added to the corresponding bias: GL_POST_CONVOLUTION_RED_BIAS_EXT, GL_POST_CONVOLUTION_GREEN_BIAS_EXT, GL_POST_CONVOLUTION_BLUE_BIAS_EXT, or GL_POST_CONVOLUTION_ALPHA_BIAS_EXT.

If GL_POST_CONVOLUTION_COLOR_TABLE_EXT is true and a non-zero width post convolution color table is defined, then each RGBA color component may be replaced depending on the internal format of the post convolution color table. The components to be replaced are converted to indices by clamping to [0,1], multiplying by an integer one less than the width of the post convolution color table, and rounding to the nearest integer. The appropriate components are replaced by the table entry at the index.

The components are then transformed by the current color matrix. Each transformed component is multiplied by the appropriate scale factor: GL_POST_COLOR_MATRIX_RED_SCALE_EXT for a red component, GL_POST_COLOR_MATRIX_GREEN_SCALE_EXT for a green component, GL_POST_COLOR_MATRIX_BLUE_SCALE_EXT for a blue component, and GL_POST_COLOR_MATRIX_ALPHA_SCALE_EXT for a alpha component, and added to the corresponding bias: GL_POST_COLOR_MATRIX_RED_BIAS_EXT, GL_POST_COLOR_MATRIX_GREEN_BIAS_EXT, GL_POST_COLOR_MATRIX_BLUE_BIAS_EXT, or GL_POST_COLOR_MATRIX_ALPHA_BIAS_EXT. The resulting components replace each component of the original group.

If GL_POST_COLOR_MATRIX_COLOR_TABLE_EXT is true and a non-zero width post color matrix color table is defined, then each RGBA color component may be replaced depending on the internal format of the post color matrix color table. The components to be replaced are converted to indices by clamping to [0,1], multiplying by an integer one less than the width of the post color matrix color table, and rounding to the nearest integer. The appropriate components are replaced by the table entry at the index.

Each color component is clamped to the range specified by the corresponding minimum and maximum clamp values. The red component is clamped to the range specified by [GL_RED_MIN_CLAMP_I3D, GL_RED_MAX_CLAMP_I3D], the green component is clamped to the range specified by [GL_GREEN_MIN_CLAMP_I3D, GL_GREEN_MAX_CLAMP_I3D], the blue component is clamped to the range specified by [GL_BLUE_MIN_CLAMP_I3D, GL_BLUE_MAX_CLAMP_I3D], and the alpha component is clamped to the range specified by [GL_ALPHA_MIN_CLAMP_I3D, GL_ALPHA_MAX_CLAMP_I3D].

Color Index

Each color index is shifted left by GL_INDEX_SHIFT bits, filling with zeros any bits beyond the number of fraction bits carried by the fixed-point index. If GL_INDEX_SHIFT is negative, the shift is to the right, again zero filled. GL_INDEX_OFFSET is then added to the index. GL_INDEX_SHIFT and GL_INDEX_OFFSET are specified with glPixelTransfer.

From this point, operation diverges depending on the required format 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 format, the pixels continue to be treated as indexes. If GL_MAP_COLOR is true, then each index is masked by 2ⁿ - 1, where n is GL_PIXEL_MAP_I_TO_I_SIZE, and 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 are specified with glPixelMap.

If the resulting pixels are to be written to an RGBA color buffer, or if they are being read back to client memory in a format other than GL_COLOR_INDEX, the pixels are converted from indexes 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ⁿ - 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 are specified with glPixelMap.

Depth

Each depth value is multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and then clamped to the range [0,1].

Stencil

Each index is shifted GL_INDEX_SHIFT bits just as a color index is, and then added to GL_INDEX_OFFSET. If GL_MAP_STENCIL is true, each index is masked by 2ⁿ - 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.

pname	Type	Initial Value	Valid Range
GL_MAP_COLOR	Boolean	GL_FALSE	GL_TRUE/GL_FALSE
GL_MAP_STENCIL	Boolean	GL_FALSE	GL_TRUE/GL_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_CONVOLUTION_RED_SCALE_EXT	float	1	[-∞,∞]
GL_POST_CONVOLUTION_GREEN_SCALE_EXT	float	1	[-∞,∞]
GL_POST_CONVOLUTION_BLUE_SCALE_EXT	float	1	[-∞,∞]
GL_POST_CONVOLUTION_ALPHA_SCALE_EXT	float	1	[-∞,∞]
GL_POST_CONVOLUTION_RED_BIAS_EXT	float	0	[-∞,∞]
GL_POST_CONVOLUTION_GREEN_BIAS_EXT	float	0	[-∞,∞]
GL_POST_CONVOLUTION_BLUE_BIAS_EXT	float	0	[-∞,∞]
GL_POST_CONVOLUTION_ALPHA_BIAS_EXT	float	0	[-∞,∞]
GL_POST_COLOR_MATRIX_RED_SCALE_EXT	float	1	[-∞,∞]
GL_POST_COLOR_MATRIX_GREEN_SCALE_EXT	float	1	[-∞,∞]
GL_POST_COLOR_MATRIX_BLUE_SCALE_EXT	float	1	[-∞,∞]
GL_POST_COLOR_MATRIX_ALPHA_SCALE_EXT	float	1	[-∞,∞]
GL_POST_COLOR_MATRIX_RED_BIAS_EXT	float	0	[-∞,∞]
GL_POST_COLOR_MATRIX_GREEN_BIAS_EXT	float	0	[-∞,∞]
GL_POST_COLOR_MATRIX_BLUE_BIAS_EXT	float	0	[-∞,∞]
GL_POST_COLOR_MATRIX_ALPHA_BIAS_EXT	float	0	[-∞,∞]
GL_RED_MIN_CLAMP_I3D	float	0	[0,1]
GL_GREEN_MIN_CLAMP_I3D	float	0	[0,1]
GL_BLUE_MIN_CLAMP_I3D	float	0	[0,1]
GL_ALPHA_MIN_CLAMP_I3D	float	0	[0,1]
GL_RED_MAX_CLAMP_I3D	float	0	[0,1]
GL_GREEN_MAX_CLAMP_I3D	float	0	[0,1]
GL_BLUE_MAX_CLAMP_I3D	float	0	[0,1]
GL_ALPHA_MAX_CLAMP_I3D	float	0	[0,1]

The glPixelTransferf function can be used to set any pixel transfer parameter. If the parameter type is Boolean, 0.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 also be used to set any of the pixel transfer parameters. Boolean parameters are set to false if param is 0 and true otherwise. The param parameter is converted to floating point before being assigned to real-valued parameters.

NOTES

EXTENSIONS

GL_I3D_color_clamp

GL_RED_MIN_CLAMP_I3D, GL_GREEN_MIN_CLAMP_I3D, GL_BLUE_MIN_CLAMP_I3D, GL_ALPHA_MIN_CLAMP_I3D, GL_RED_MAX_CLAMP_I3D, GL_GREEN_MAX_CLAMP_I3D, GL_BLUE_MAX_CLAMP_I3D, GL_ALPHA_MAX_CLAMP_I3D are part of the I3D_color_clamp extension.