Information in this section includes the following:
A pixel is a rectangular picture element. The display screen is composed of an array of pixels. In a black-and-white system, pixels are turned on and off to form images. In a color system, each pixel has three components: red, green, and blue. The intensity of each component can be controlled.
Pixels, like raster fonts, are not as easy to transform as geometric figures. Coding for pixel representation on the screen often requires information about the window dimensions, the screen resolution, and so forth.
Another problem with reading and writing pixels is that the contents of each pixel can mean different things depending on the display mode. The same physical bitplanes are used to store either color index information or RGB information. Accordingly, the mode of the window determines whether the contents are interpreted as RGB triples or as indexes into the color map.
The GL pixel-handling subroutines operate on arbitrarily sized rectangles, and they operate in all modes.
| logicop | |
| Specifies a logical operation for pixel writes. | |
| pixmode | |
| Controls the operation of the lrectread and lrectwrite subroutines. | |
| readpixels | |
| Returns a row of specific pixels in color map mode. | |
| readRGB | |
| Returns a row of specific pixels in RGB mode. | |
| readsource | |
| Specifies the source for pixels to be read. | |
| rectcopy | |
| Copies a rectangle of pixels screen to screen with optional zoom. | |
| rectread, lrectread | |
| Reads a rectangular array of pixels into host memory. | |
| rectwrite, lrectwrite | |
| Draws a rectangular array of pixels into the frame buffer. | |
| rectzoom | |
| Specifies the zoom factor for rectangle copies and writes. | |
| writepixels | |
| Paints a row of pixels on screen in color map mode. | |
| writeRGB | |
| Paints a row of pixels on screen in RGB mode. | |
The following three pixel formats constitute the standard GL pixel formats:
Note: Alpha functions require specialized alpha hardware. The High-Performance 3-D Color Graphics Processor does not have alpha bitplanes.
This section describes subroutines that read and write pixels with the highest possible performance.
Note: These subroutines do not check to make sure that the data is valid. If you read pixel data from a window in color map mode and then write the data into an RGB window or into the z buffer, the data is interpreted according to the new mode. The results are unpredictable.
The pixmode subroutine controls the format in which pixmaps are transferred to and from the adapter. You can use the pixmode subroutine to specify the format of a pixmap as handled by your application. The pixmode subroutine performs the following functions:
Note: The pixmap subroutine is not intended to be an "image processing function" or to be used for pixmap format conversion.
After you specify the pixmap format, the lrectread and lrectwrite subroutines automatically perform the transfer from this format to the internal format of the frame buffer. The syntax is as follows:
void pixmode (Int32 mode, Int32 value)
FASTMODE is useful when it is important to store and retrieve images quickly, and when the internal format of the image is not important. A compatible mode is supplied by setting FASTMODE to FALSE. Using FASTMODE on certain adapters, for example the Supergraphics Processor Subsystem, can result in significantly improved pixel transfer capabilities.
The rectread subroutine reads a rectangular array of pixels from the window where the xll, yll parameters are the coordinates for the lower-left corner of the rectangle and the xur, yur parameters are the coordinates for the upper-right corner. All coordinates are relative to the lower-left corner of the window in screen coordinates. The syntax is as follows:
Int32 rectread(Screencoord xll, Screencoord yll, Screencoord xur, Screencoord xur, Int16 *parray)
The parray parameter is an array of 16-bit values. Only the low-order 16 bits of each pixel are read, so the rectread subroutine is useful primarily for windows drawn in color map mode. The data is loaded into the parray parameter left to right, and then bottom to top. In other words, if the pixel data on the screen looked like this:
1 2 3 4
5 6 7 8
9 10 11 12
The parray parameter would contain parray[0] = 9, parray[1] = 10 , or {9, 10, 11, 12, 5, 6, 7, 8, 1, 2, 3, 4} , and so forth. The rectread subroutine returns the number of pixels successfully read. Normally, this is defined as:
(x2 - x1 + 1)(y2 - y1 + 1)
If any part of the specified rectangle is off the screen, or if the coordinates are mixed up, the behavior of the rectread subroutine is undefined.
Errors occur only outside the screen, not in the window. It is possible to read pixels outside a window, as long as they are on the physical screen. This can be useful for certain applications that magnify data in other windows or that process images produced by other programs. The main difficulty is that the data can come from areas of the screen that are in different modes (color map mode or RGB mode). Because the rectread subroutine is not restricted to the current window, any or all of the coordinates can be negative.
The lrectread subroutine is very similar to the rectread subroutine. It differs in that its operation is controlled by the pixmode subroutine and that the parray parameter contains 32-bit quantities. Although the lrectread subroutine is useful for any kind of data, it wastes space if the data is known to be from a window in color map mode. The syntax is as follows:
Int32 lrectread(Screencoord xll, Screencoord yll, Screencoord xur, Screencoord xur, Int32 *parray)
The readsource subroutine determines the source of pixels read by the rectread, lrectread, rectcopy, readpixels, and readRGB subroutines. The source parameter has four possible values defined in the /usr/include/gl/gl.h file. They are SRC_AUTO, SRC_FRONT, SRC_BACK, and SRC_ZBUFFER.
The default value is SRC_AUTO, which selects the front buffer in single buffer mode and the back buffer in double buffer mode. The SRC_FRONT value always reads from the front buffer (this is always valid), and the SRC_BACK value always reads from the back buffer (valid only in double buffer mode). Finally, SRC_ZBUFFER reads 24-bit data from the z buffer. The SRC_ZBUFFER value is valid in both single and double buffer modes. The syntax is as follows:
void readsource(Int32 source)
The subroutines that draw rectangular arrays of pixels, rectwrite and lrectwrite, are similar to those that read pixels. The data in the parray parameter is 16-bit quantities for the rectwrite subroutine, and 32-bit quantities for the lrectwrite subroutine. The destination buffer is determined by the frontbuffer, backbuffer, and zdraw subroutines (see "Double and Single Buffering" and "Z-Buffering"). The syntax for the rectwrite and lrectwrite subroutines is as follows:
Int32 rectwrite(Screencoord xll, Screencoord yll, Screencoord xur, Screencoord xur, Int16 *parray)
Int32 lrectwrite(Screencoord xll, Screencoord yll, Screencoord xur, Screencoord xur, Int32 *parray)
Data is stored in the same order as in the rectread subroutine. In other words, if you call the rectread subroutine and then the rectwrite (or lrectread followed by lrectwrite) subroutine with the same parameters, exactly the same data is written as is read. The rectwrite and lrectwrite subroutines obey the zoom factors set by the rectzoom subroutine.
The rectcopy subroutine copies the pixels from a rectangular region of the screen to a new region. As was the case with the rectread and lrectread subroutines, the source rectangle must be on the physical screen, but not necessarily constrained to the current window. The bitplane source for the pixels is determined by the readsource subroutine, and the destination is determined by the frontbuffer, backbuffer, and zdraw subroutines (see "Double and Single Buffering" and "Z-Buffering"). Self-intersecting rectangles work correctly in all cases. The syntax is as follows:
void rectcopy(Screencoord xll, Screencoord yll, Screencoord xur, Screencoord xur, Screencoord newx, Screencoord newy)
With the rectcopy subroutine, the source rectangle can be zoomed by independent amounts in both the x and y directions. The rectzoom subroutine accomplishes this, where its xfactor and yfactor parameters are floating-point values defaulting to 1.0. The syntax is as follows:
void rectzoom(Float32 xfactor, Float32 yfactor)
The current system supports only integer values for the xfactor and yfactor parameters. If rectzoom(2.0, 3.0) is called and the following rectangle is copied:
1 2
3 4
1 1 2 2
1 1 2 2
1 1 2 2
3 3 4 4
3 3 4 4
3 3 4 4
The following program, zoom , magnifies the rectangular area above and to the right of the cursor to fill the window:
#include <gl/gl.h> #include <device.h>
main()
{
Int32 xsize, ysize, readxsize, readysize, x, y;
Int32 xorg, yorg;
winopen("zoom");
getsize(&xsize, &ysize);
getorigin(&xorg, &yorg);
readxsize = xsize/3;
readysize = ysize/3;
rectzoom(3.0, 3.0);
while (1) {
x = getvaluator(MOUSEX);
y = getvaluator(MOUSEY);
rectcopy(x-xorg,y-yorg,x-xorg+readxsize,
y-yorg+readysize,0,0);
}
}
After determining the size and shape of the window, the program simply loops, copying a properly sized rectangle above and to the right of the cursor into the window magnified by a factor of 3 in each direction. The expressions x-xorg and y-yorg convert the cursor's screen coordinates into window coordinates.
If you use the previous program as it is, note that regions of the screen drawn in RGB mode appear incorrect, and color-mapped portions look fine. Also, notice that with double-buffered programs, the zoom window appears to blink. This happens because the program is continually switching buffers, while zoom is always reading the same buffer. If you magnify the program's own window some fairly interesting effects can appear; that is, a sort of recursion takes place. These effects are enhanced if the zoom factor is set to (1.0,1.0).
To read from the overlay planes, set the pixel source with readsource (SRC_OVER). The rectread subroutine returns one pixel per short word; the lrectread subroutine returns one pixel per long word. When reading, all other bits in the short or long word are set to zero.
To write to the overlay planes, set drawmode (OVERDRAW), and then use the rectwrite or lrectwrite subroutine. Pixels must be specified one pixel per short word for the rectwrite subroutine and one pixel per long word for the lrectwrite subroutine. The pixel must lie in the lowest order bits of the short or long word. All other bits in the short or long word are ignored during a write.
To copy from one location in the overlay planes to another, specify readsource (SRC_OVER) and drawmode (OVERDRAW), and then use the rectcopy subroutine. The rectcopy subroutine does not support pixel block copies from the main frame buffer to the overlays, or vice versa. To copy to or from the main frame buffer to or from the overlays, adjust the readsource subroutine, use either the rectread or lrectread subroutine, adjust the drawmode subroutine, and then use either the lrectwrite or rectwrite subroutine.
The setting for pixmode (PM_SIZE) is ignored when performing transfers to or from the overlay planes.
The following GL subroutines provide other types of access to pixel blocks:
The readpixels subroutine returns values of specific pixels from the frame buffer in color map mode. It reads them into the array starting from the current character position along a single scan line (constant y) in the direction of increasing x. The syntax is as follows:
Int32 readpixels(Int16 number, Colorindex colors[])
The readRGB subroutine attempts to read specific pixel values from the frame buffer in RGB mode. The returned value of this function is the number of pixels actually read. A returned function value of 0 (zero) indicates that the starting point is not a valid character position.
Note: The rectread subroutine provides significantly better performance for pixel block transfers. Even when only one row of pixels needs to be read, use the rectread subroutine. Do not use the readpixels or readRGB subroutines in new development.
Int32 readRGB(Int16 number, RGBvalue red[], RGBvalue green[], RGBvalue blue[])
The writepixels subroutine paints a row of pixels on the screen in color map mode.The system reads elements from the colors array and draws a pixel of the appropriate color for each. The syntax is as follows:
void writepixels(Int16 number, Colorindex colors[])
The writeRGB subroutine paints a row of pixels on the screen in RGB mode. The system reads elements from the red, green, and blue arrays and draws a pixel of the appropriate color for each.
Note: The rectwrite subroutine provides significantly better performance for pixel block transfers. Even when only one row of pixels needs to be read, use the rectwrite subroutine. Do not use the writepixels subroutine in new development.
void writeRGB(Int16 number, RGBvalue red[], RGBvalue green[], RGBvalue blue[])
Other topics affected by reading and writing pixels are "Creating Text Characters" and "Working in Color Map and RGB Modes".