OpenGL allows applications to render pixel rectangles to the framebuffer with the glDrawPixels() command. glDrawPixels() copies pixel data from an address in application-addressable memory to the framebuffer. OpenGL places the pixel rectangle's bottom-left corner at the current raster position. The next section, "The Current Raster Position," explains how to set the current raster position and how OpenGL transforms it into window space. The section "Drawing Pixel Rectangles with glDrawPixels()" later in this chapter covers the glDrawPixels() command in greater detail.
When your application issues a glDrawPixels() command, several state values affect how OpenGL interprets and displays the pixel rectangle.
These state values allow applications to specify the byte ordering, row alignment, color table lookup, pixel zoom, and other aspects of OpenGL pixel processing. These state values have several applications in image processing and data sharing. If your application uses RGBA unsigned byte pixel data for simple display and texture mapping, however, the default state is sufficient in most cases. To familiarize yourself with these state values, see Chapter 8, "Drawing Pixels, Bitmaps, Fonts, and Images," of OpenGL® Programming Guide.
5.1.1. The Current Raster Position
When your application issues a glDrawPixels() command, OpenGL draws the pixels at the current raster position Although glDrawPixels() displays a pixel rectangle in window coordinates, applications often specify the raster position in object coordinates, which OpenGL transforms into window coordinates. OpenGL transforms both the raster position and vertices by using the transformation pipeline described in Chapter 3, "Transformation and Viewing."
OpenGL offers several ways to set the raster position. Many applications use the glRasterPos*() set of commands.
void glRasterPos[234][sifd]( TYPE x, TYPE y, TYPE z, TYPE w );
Specifies the object coordinates of the raster position. x, y, z, and w are the object coordinates of the desired raster position. When using glRasterPos3*(), the w coordinate defaults to 1.0, and when specifying two parameters, z defaults to 0.0, and w defaults to 1.0.
The glRasterPos*() command is similar to the glVertex*() set of commands mentioned briefly in Chapters 1 and 2.
Just as vertices have vertex states associated with them, the current raster position uses states, such as the current texture coordinate. There are very few applications for applying a single texture coordinate to an entire pixel rectangle, however. For this reason, most applications disable texture mapping when rendering pixel rectangles.
5.1.1.1. Handling Clipped Raster Positions
OpenGL transforms the raster position into clip coordinates and tests it against the clip volume. If the raster position is inside the clip volume, OpenGL marks it as valid and continues transforming it into window coordinates. When your application issues a glDrawPixels() command, OpenGL rasterizes the pixel rectangle with the bottom-left corner at the window-coordinate raster position. Figure 5-1 shows a pixel rectangle rendered with a valid raster position.
Figure 5-1. An image of the Sun rendered at a valid raster position.[1]
[1] Astronomical images reproduced in this chapter are owned by NASA. The Earth image was created by the Earth Observatory team (http://earthobservatory.nasa.gov/).
If the raster position is outside the clip volume, OpenGL marks it as invalid. When the raster position is invalid, subsequent glDrawPixels() commands have no effect; no pixels are rasterized.
OpenGL's treatment of glDrawPixels() for invalid raster positions often results in unexpected clipping of the entire pixel rectangle. Figures 5-2 and 5-3 illustrate this behavior.
Figure 5-2. A screenshot from the PixelRectangles example program. The raster position for the image of the Earth is unclipped and valid.
Figure 5-3. As the Earth orbits the Sun, its raster position goes outside the left side of the clip volume, and OpenGL marks it as invalid. In this case, OpenGL ignores the glDrawPixels() for the Earth, even though part of the image would be visible if OpenGL had rendered it.
As shown in Figure 5-3, the entire image is missing when the raster position is clipped at the left or bottom. To manage this issue, use the glBitmap() command.
Renders the bitmap (1 bit per pixel) stored in data with width w and height h such that the image origin described by ( xOrigin, yOrigin ) corresponds to the current raster position.
After rendering, glBitmap() shifts the raster position by ( xInc, yInc ) in window coordinates. If data is NULL, and w and h are zero, or if the current raster position is invalid, glBitmap() renders nothing but still shifts the raster position.
glBitmap() was intended for rendering raster text, but this use has fallen into disfavor because texture mapped text generally performs better and produces higher-quality results. Modern OpenGL applications typically use glBitmap() to shift the raster position.
To use glBitmap() to render pixel rectangles that are clipped on the left or bottom:
Set the raster position to a valid (unclipped) position, using glRasterPos().
Call glBitmap() with xInc and yInc set to shift the raster position in window coordinates to the desired location outside the viewport.
Issue the glDrawPixels() call. The visible portion of the pixel rectangle will appear inside the viewport.
The PixelRectangles example code uses glBitmap() to shift the position of pixel rectangles so that their centers correspond to the current raster position.
5.1.1.2. Pixel Rectangles in 2D
Applications often use glDrawPixels() during 2D rendering and, therefore, need to specify the raster position directly in window coordinates.
As described in Chapter 3, "Transformation and Viewing," applications can set the model-view matrix to the identity and use glOrtho() to create a projection matrix that allows rendering directly in window coordinates. After this initialization, applications can position pixel rectangles in two dimensions with the glRasterPos*() command. OpenGL version 1.4, however, provides the glWindowPos*() command, which allows the application to set the raster position directly in window coordinates. glWindowPos*() bypasses the transformation and clipping stage of the of the transformation pipeline, and is generally more efficient for setting the raster position in window coordinates than changing the model-view and projection matrices.
void glWindowPos[23][sifd]( TYPE x, TYPE y, TYPE z );
Specifies the raster position directly in window coordinates. x, y, and z specify the window-coordinate location of the current raster position. Unlike glRasterPos*(), OpenGL doesn't transform or clip glWindowPos*(). When using glWindowPos2*(), z defaults to 0.0.
Most applications use glRasterPos3f() when placing pixel rectangles in three dimensions and use glWindowPos2i() when rendering pixel rectangles in 2D window coordinates.
5.1.2. Drawing Pixel Rectangles with glDrawPixels()
You render a pixel rectangle with the glDrawPixels() command.
void glDrawPixels( GLsizei width, GLsizei height, GLenum format, GLenum type, const GLvoid* data );
Renders the width x height rectangle of color, depth, or stencil pixel data pointed to by data.
The format parameter tells OpenGL what the pixel data represents. The most common format values are GL_RGB and GL_RGBA, for sending pixel data composed of three RGB components per pixel or four RGBA components per pixel. Use GL_STENCIL_INDEX or GL_DEPTH_COMPONENT to send single-component stencil or depth pixel data.
The type parameter describes the pixel data type. Applications usually specify a type parameter of GL_UNSIGNED_BYTE to send RGB and RGBA color data. OpenGL supports several other useful type values, including GL_UNSIGNED_SHORT, GL_UNSIGNED_INT, and GL_FLOAT.
glDrawPixels() does nothing if the current raster position is not valid. Check whether the current raster position is valid or not by calling glGetBooleanv() as the following code segment shows:
If the raster position is valid, glDrawPixels() reads the specified pixel rectangle from client memory and writes it to the framebuffer at the current raster position. The data parameter points to the pixel in the bottom-left corner of the pixel rectangle, and pixels must be in row-major order proceeding left to right and bottom to top.
Rows of pixels are aligned on 4-byte boundaries by default. To change this default behavior, see "glPixelTransfer" in OpenGL® Reference Manual. If your application draws only RGBA color unsigned byte pixel data, the default 4-byte alignment will produce correct results.
OpenGL allows applications to render rectangles of color, depth, or stencil values as specified with the format parameter.
OpenGL generates fragments when it rasterizes the pixel rectangle and processes them using the same per-fragment operations as for 3D geometry. Rasterization state, including texture mapping, affects the appearance of rendered pixel rectangles. Most applications disable texture mapping with glDisable( GL_TEXTURE_2D ) before calling glDrawPixels().
When drawing a pixel rectangle of color data, each fragment generated during rasterization uses the window-space z value from the current raster position. This value is used in the depth test, if enabled.
RGBA pixel data can contain varying alpha values. Applications enable the alpha test and blend operations to draw blocks of pixels that are partially transparent. The PixelRectangles example program from this book's Web site uses these features to render partially transparent solar flares, as well as to antialias the outlines of the Earth and Moon, as shown in Figure 5-4 and Plate 2.
Figure 5-4. Screenshot from the PixelRectangles example program. The code uses glDrawPixels() to render images of the Sun, Earth, and Moon. The varying alpha values in the RGBA data allow transparency and translucency.
