underl(3G)

NAME
     underl - allocates bitplanes for display of underlay colors

FORTRAN 77 SPECIFICATION
     subroutine underl(planes)
     integer*4 planes

PARAMETERS
     planes   expects the number of bitplanes to be allocated for underlay
              colors.  Valid values are 0 (the default), 2, 4, and 8.

DESCRIPTION
     The IRIS physical framebuffer is divided into four separate GL
     framebuffers:  normal, popup, overlay, underlay.  Because a single
     physical framebuffer is used to implement the four GL framebuffers,
     bitplanes must be allocated among the GL framebuffers.  underl specifies
     the number of bitplanes to be allocated to the underlay framebuffer.
     underl does not take effect immediately.  Rather, it is considered only
     when gconfi is called, at which time all requests for bitplane resources
     are resolved.

     While only one of the four GL framebuffers can be drawn to at a time (see
     drawmo), all four are displayed simultaneously.  The decision of which to
     display at each pixel is made based on the contents of the four
     framebuffers at that pixel location, using the following hierarchical
     rule:

     if           the popup pixel contents are non-zero

     then         display the popup bitplanes

     else if      overlay bitplanes are allocated AND
                  the overlay pixel contents are non-zero

     then         display the overlay bitplanes

     else if      the normal pixel contents are non-zero OR
                  no underlay bitplanes are allocated

     then         display the normal bitplanes

     else         display the underlay bitplanes

     Thus images drawn into the overlay framebuffer appear over images in the
     normal framebuffer, and images drawn into the underlay framebuffer appear
     under images in the normal framebuffer.  Popup images appear over
     everything else.

     The default configuration of the underlay framebuffer is 0 bitplanes.  To
     make a change to this configuration other than to change the bitplane
     size, the drawing mode must be UNDERD.  For example, the underlay
     framebuffer can be configured to be double buffered by calling double
     while draw mode is UNDERD.

     On models that cannot support overlay and underlay bitplanes
     simultaneously, calling underl with a non-zero argument forces overla to
     zero.  When simultaneous overlay and underlay operation is supported,
     calling underl may have no effect on the number of overlay bitplanes.

SEE ALSO
     double, drawmo, gconfi, getgde, single, underl

NOTES
     This routine is available only in immediate mode.

     IRIS-4D G, GT, and GTX models, and the Personal Iris, support only single
     buffered, color map mode underlay bitplanes.

     The Iris Indy supports 8 underlay single buffered bitplanes, if
     configured with 24 bit normal color planes.

     The Personal Iris supports 0 or 2 underlay bitplanes.  There are no
     overlay or underlay bitplanes in the minimum configuration of the
     Personal Iris.

     IRIS-4D GT and GTX models support 0, 2, or 4 underlay bitplanes.  Because
     4-bitplane allocation reduces the popup framebuffer to zero bitplanes,
     however, its use is strongly discouraged.  The window manager cannot
     operate properly when no popup bitplanes are available.

     IRIS-4D VGX models support 0, 2, 4, or 8 underlay bitplanes, either
     single or double buffered, in color map mode only.  The 4 and 8 bitplane
     allocations utilize the alpha bitplanes, which must be present, and which
     therefore are unavailable in draw mode NORMAL.

     Use getgde to determine the maximum number of bitplanes supported for the
     underlay framebuffer.

     Iris Indigo does not support underl so getgde returns zero for the number
     of underlay bitplanes on Iris Indigo.

BUGS
     The Personal Iris does not support shade model GOURAU in the underlay
     framebuffer.