OpenGL Programming Guide

Chapter 8Drawing Pixels, Bitmaps, Fonts, and Images

Storing, Transforming, and Mapping Pixels

Pixel-Transfer Operations

You can perform various operations on pixels as they're transferred from and to the framebuffer. The continuous components, including the red, green, blue, alpha, and depth components, can have an affine transformation applied. In addition, after transformation, these components - as well as the color-index and stencil values - can be transformed by an arbitrary table lookup.

Some of the pixel-transfer function characteristics are set with glPixelTransfer*(). The other characteristics are specified with glPixelMap*(), which is described in the next section. void glPixelTransfer{if}(GLenum pname, TYPEparam);

Sets pixel-transfer modes that affect the operation of glDrawPixels*(), glReadPixels*(), glCopyPixels(), glTexImage1D(), glTexImage2D(), and glGetTexImage(). The parameter pname must be one of those listed in the first column of Table 8-4 , and its value, param, must be in the valid range shown.

Table 8-4 : Parameters for Use with glPixelTransfer*()

Parameter Name	Type	Initial Value	Valid Range
GL_MAP_COLOR	GLboolean	FALSE	TRUE/FALSE
GL_MAP_STENCIL	GLboolean	FALSE	TRUE/FALSE
GL_INDEX_SHIFT	GLint	0	(- ∞ , ∞ )
GL_INDEX_OFFSET	GLint	0	(- ∞ , ∞ )
GL_RED_SCALE	GLfloat	1.0	(- ∞ , ∞ )
GL_GREEN_SCALE	GLfloat	1.0	(- ∞ , ∞ )
GL_BLUE_SCALE	GLfloat	1.0	(- ∞ , ∞ )
GL_ALPHA_SCALE	GLfloat	1.0	(- ∞ , ∞ )
GL_DEPTH_SCALE	GLfloat	1.0	(- ∞ , ∞ )
GL_RED_BIAS	GLfloat	0	(- ∞ , ∞ )
GL_GREEN_BIAS	GLfloat	0	(- ∞ , ∞ )
GL_BLUE_BIAS	GLfloat	0	(- ∞ , ∞ )
GL_ALPHA_BIAS	GLfloat	0	(- ∞ , ∞ )
GL_DEPTH_BIAS	GLfloat	0	(- ∞ , ∞ )

If the GL_MAP_COLOR or GL_MAP_STENCIL parameter is TRUE, then mapping is enabled. See the next section to learn how the mapping is done and how to change the contents of the maps. All the other parameters directly affect the pixel component values.

The pixel conversions performed when going from framebuffer to memory (reading) are similar but not identical to the conversions performed when going in the opposite direction (drawing), as explained in the following sections.

The Pixel Rectangle-Drawing Process in Detail

Figure 8-5 and the following paragraphs describe the operation of drawing pixels into the framebuffer.

Figure 8-5 : Drawing Pixels with glDrawPixels*()

1. If the pixels aren't indices (color or stencil), the first step is to convert the components to floating-point format if necessary. See Table 5-1 for the details of the conversion.
   
   

2. If the format is GL_LUMINANCE or GL_LUMINANCE_ALPHA, the luminance element is converted into R, G, and B, by using the luminance value for each of the R, G, and B components. In GL_LUMINANCE_ALPHA format, the alpha value becomes the A value. If A is missing, it's set to 1.0.
   
   

3. Each component (R, G, B, A, or depth) is multiplied by the appropriate scale, and the appropriate bias is added. For example, the R component is multiplied by the value corresponding to GL_RED_SCALE, and added to the value corresponding to GL_RED_BIAS.
   
   

4. If GL_MAP_COLOR is true, each of the R, G, B, and A components is clamped to the range [0.0,1.0], multiplied by an integer one less than the table size, truncated, and looked up in the table. See "Pixel Mapping" for more details.
   
   

5. Next, the R, G, B, and A components are clamped to [0.0,1.0] if they weren't already, and they're converted to fixed-point with as many bits to the left of the binary point as there are in the corresponding framebuffer component.
   
   

6. If you're working with index values (stencil or color indices), then the values are first converted to fixed-point (if they were initially floating-point numbers) with some unspecified bits to the right of the binary point. Indices that were initially fixed-point remain so, and any bits to the right of the binary point are set to zero.
   
   

7. The resulting index value is then shifted right or left by the absolute value of GL_INDEX_SHIFT bits; the value is shifted left if GL_INDEX_SHIFT > 0 and right otherwise. Finally, GL_INDEX_OFFSET is added to the index.
   
   

8. The next step with indices depends on whether you're using RGBA mode or index mode. In RGBA mode, a color index is converted to RGBA using the color components specified by 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 (see the next section for details). Otherwise, if GL_MAP_COLOR is TRUE, a color index is looked up through the table GL_PIXEL_MAP_I_TO_I. (If GL_MAP_COLOR is FALSE, the index is unchanged.) If the image is made up of stencil indices rather than color indices, and if GL_MAP_STENCIL is TRUE, the index is looked up in the table corresponding to GL_PIXEL_MAP_S_TO_S. If GL_MAP_STENCIL is FALSE, the stencil index is unchanged.

The Pixel Rectangle-Reading Process in Detail

During the pixel reading process, many of the same conversions are done, as shown in Figure 8-6 and as described in the following paragraphs.

Figure 8-6 : Reading Pixels with glReadPixels*()

If the pixels to be read aren't indices (color or stencil), the components are mapped to [0.0,1.0] - that is, in exactly the opposite way that they are when written. Next, the scales and biases are applied to each component. If GL_MAP_COLOR is TRUE, they're mapped and again clamped to [0.0,1.0]. If luminance is desired instead of RGB, the R, G, and B components are added (L = R + G + B). Finally, the results are packed into memory according to the GL_PACK* modes set with glPixelStore*().

If the pixels are indices (color or stencil), they're shifted and offset, and mapped if GL_MAP_COLOR is TRUE. If the storage format is either GL_COLOR_INDEX or GL_STENCIL_INDEX, the pixel indices are masked to the number of bits of the storage type (1, 8, 16, or 32) and packed into memory as described previously. If the storage format is one of the component kind (such as luminance or RGB), the pixels are always mapped by the index-to-RGBA maps. Then, they're treated as though they had been RGBA pixels in the first place (including perhaps being converted to luminance).

The scaling, bias, shift, and offset values are the same as those used when drawing pixels, so if you're doing both reading and drawing of pixels, be sure to reset these components to the appropriate values before doing a read or a draw. Similarly, the various maps (see the next section) must also be properly reset if you intend to use maps for both reading and drawing.

It might seem that luminance is handled incorrectly in both the reading and drawing operations. For example, luminance is not usually equally dependent on the R, G, and B components as it seems above. If you wanted your luminance to be calculated such that the R component contributed 30 percent, the G 59 percent, and the B 11 percent, you could set GL_RED_SCALE to .30, GL_RED_BIAS to 0.0, and so on. Then the computed L is then .30R + .59G + .11B.

OpenGL Programming Guide