Underlay and Overlay Modes

Underlay and overlay modes in GL overlays and underlays are independent frame buffers that lie over and lie under, respectively, the principal frame buffer. They can be drawn into and cleared independently from the main frame buffer. In this way, they provide a convenience to the graphics programmer: color values in the underlays and overlays can be changed without destroying the contents of the main frame buffer. If the picture in the main frame buffer took a long time to draw, and the program needs to put up a quick status indicator, or perform some other temporary communications with the user, the overlay planes may be the ideal place to do so. For example, GL pop-up menus use the overlay planes. When the pop-up menus are erased, the contents of the principal frame buffer are unharmed. In some ways, overlays and underlays are not as powerful as the main frame buffer: they contain fewer bitplanes (2 or 4, depending on the graphics adapter) and thus a more limited selection of colors; they can be used only in color index mode, and they do not support Gouraud shading.

The concept of partitions is in many ways similar to that of overlays. Partitions can be independently cleared and drawn into; their stacking order can be changed, and they can be made invisible. Partitions, unlike overlays, are not separate bitplanes, but are a partitioning of the principal frame buffer; thus their name. For more information on partitions, please refer to Partitions.

You can control information overlaid on top of, and placed underneath, the main color frame buffer by setting the number of bitplanes used for overlay and underlay.

Overlay bitplanes supply additional bits of information at each pixel. You can configure the system to have 0, 2, or 4 overlay bitplanes, depending on the installed adapter. Whenever all the overlay bitplanes contain 0 at a pixel, the color of the pixel from the main color bitplanes is presented on the screen.

If any of the overlay planes contains a nonzero entry (there are three ways for this to happen with two overlay bitplanes: 01, 10, and 11), the overlay value is looked up in a separate color table, and that color is presented instead. The overlay color lookup table behaves exactly like the standard color map, except that the lookup table only has three usable entries.

Underlay bitplanes are similar in concept, in that there are extra bits for each pixel. The values of these extra bits are normally ignored unless the color in the standard bitplanes is 0. In that case, the underlay color is looked up in a color map and presented. Thus, the underlay color shows up only if there is nothing (the pixel value equals 0) in the standard bitplanes. With two underlay bitplanes, there are four possible underlay colors.

Overlay and underlay planes can be used in single or double buffer mode, and in color map or RGB mode. Overlay bitplanes are useful for such things as menus, construction lines, rubber-banding lines, and so forth. Underlay planes might be used for background grids that appear wherever nothing else is drawn. (See the figure entitled Frame Buffer Configuration.)

Many of the same operations are available for operating on overlay or underlay bitplanes as are available for the standard bitplanes in color map mode. The color map subroutines (the color, getcolor, getmcolor, getmcolors, mapcolor, and mapcolors subroutines) affect the overlay and underlay bitplanes if the system is in overlay or underlay mode.

For example, in overlay mode, the color subroutine sets the overlay color, the getcolor subroutine gets the current overlay color, the mapcolor subroutine affects entries in the overlay map, and the getmcolor subroutine reads those entries. In overlay mode, all drawing routines draw into the overlay bitplanes rather than the standard bitplanes. The routines are similarly redefined for underlay mode. Use the drawmode subroutine to set the overlay or underlay mode.

To set the number of user-defined bitplanes you want to use for underlay color or overlay color, call the underlay and overlay subroutines. You cannot use the user-defined bitplanes for overlay and underlay color simultaneously. Call the gconfig subroutine after the overlay or underlay subroutines to activate their settings.

List of Underlay and Overlay Mode Subroutines

Default Configuration

By default, the auxiliary (overlay and underlay) planes are always enabled, for all windows, including the root window. Overlays can be disabled for a window only by the application that created the window (Overlays are disabled by making the subroutine calling sequence overlay(0); gconfig(); . When overlays are disabled, their contents are not visible.)

Overlays are by default enabled for the root window. The default has the following results:

1. When an application renders into the overlays while in fullscreen mode, the rendered drawing is visible even if it overlies other windows.
2. Garbage generated by other applications can be left behind in the overlay planes. Since the overlay planes are not automatically cleared when a program terminates, drawings intentionally or unintentionally left behind in the overlay remain visible. You can use the following code fragment to clear garbage left in the overlay planes:

   {
    fullscrn();      /* Gain access to the entire screen    */
    drawmode(OVERDRAW);  /* Access the overlay planes specifically */
    color(0);       /* The transparent overlay color     */
    clear();
    drawmode(NORMALDRAW); /* Return to normal operation       */
    endfullscrn();     /* Reset clipping to window boundaries  */
    }

The /usr/lpp/GL/examples/clover.c file contains an example of the prior code segment.

Configuring Underlay and Overlay Planes

Overlays are configured by making the overlay(n); gconfig; subroutine calling sequence , after having set n equal to the number of desired overlay planes. The number of acceptable values for n are extremely limited, and depend on the installed adapter. Refer to the section "Understanding the Adapter" for information about the number of supported overlay planes for a given adapter. This number can also be queried at run time with the getgdesc subroutine. When overlays are disabled (equivalently, when zero overlay planes are configured, by calling overlay(0); gconfig); ), they become invisible. Although the actual bitplanes are still physically present, their actual contents are no longer visible on the screen. For most of the currently supported graphics adapters, the overlay planes are not cleared when they are disabled;any data stored in them remains more or less intact.

drawmode Subroutine

The drawmode subroutine is used to put the system into overlay or underlay mode, or back into normal mode after drawing into the overlay bitplanes is finished. The OVERDRAW and UNDERDRAW settings in the drawmode subroutine put the system into overlay and underlay mode. The NORMALDRAW setting returns the system to the default, where the color subroutines refer to the standard bitplanes. The other settings for this subroutine are PUPDRAW, which sets operations for the pop-up menu, and CURSORDRAW, which sets operations for the cursor. The syntax is as follows:

void drawmode(Int32 mode)