rectwrite(3G)

NAME
     rectwrite, lrectwrite - draws a rectangular array of pixels into the
     frame buffer

C SPECIFICATION
     void rectwrite(Screencoord x1, Screencoord y1,
                    Screencoord x2, Screencoord y2, Colorindex parray[])

     void lrectwrite(x1, y1, x2, y2, parray)
     Screencoord x1, y1, x2, y2;
     unsigned long parray[];

PARAMETERS
     x1       expects the lower-left x coordinate of the rectangular region.

     y1       expects the lower-left y coordinate of the rectangular region.

     x2       expects the upper-right x coordinate of the rectangular region.

     y2       expects the upper-right y coordinate of the rectangular region.

     parray   expects the array which contains the values of the pixels to be
              drawn.  For RGBA values, pack the bits thusly:  0xAABBGGRR,
              where:

                   AA  contains the alpha value,
                   BB  contains the blue value,
                   GG  contains the green value, and
                   RR  contains the red value.

              RGBA component values range from 0 to 0xFF (255).  The alpha
              value will be ignored if blending is not active and the machine
              has no alpha bitplanes.

DESCRIPTION
     rectwrite and lrectwrite draw pixels taken from the array parray into the
     specified rectangular frame buffer region. The system usually draws
     pixels left-to-right, then bottom-to-top. All coordinates are relative to
     the lower-left corner of the window, not the screen or viewport.

     Pixels are written to the currently active framebuffer, as specified by
     drawmode.  Thus, to write pixel values to the overlay bitplanes, for
     example, simply set drawmode to OVERDRAW.

     The number of pixels in parray is always (x2-x1+1) * (y2-y1+1). If the
     zoom factors set by rectzoom are both 1.0, the screen region x1 through
     x2, y1 through y2, are filled.  Other zoom factors result in filling past
     x2 and/or past y2 (x1,y1 is always the lower-left corner of the filled
     region).
     rectwrite draws an array of 16-bit words, and therefore should be used
     only to write color index values.  lrectwrite draws an array of 32-bit
     words.  Based on the current pixmode, lrectwrite can draw pixels of 1, 2,
     4, 8, 12, 16, 24, or 32 bits each.  Use it to write packed RGB or RGBA
     values, color index values, or z values.

     pixmode affects the operation of lrectwrite substantialy, and has no
     effect on the operation of rectwrite.  By default, lrectwrite draws 32-
     bit pixels in the format used by cpack.  Different pixel sizes,
     framebuffer shifts, scan patterns through the framebuffer, and strides
     through memory, can all be specified using pixmode.

     rectwrite and lrectwrite leave the current character position
     unpredictable.

SEE ALSO
     blendfunction, dither, lrectread, pixmode, rectcopy, rectzoom

NOTES
     These routines are available only in immediate mode.

     On IRIS Indigo, Indy, and XL graphics the pixels written by rectwrite and
     lrectwrite will be dithered if dithering is enabled.  To write undithered
     pixels the dither command must be used to turn dithering off.  On the
     Indigo, if dithering is on, pixel images written, then read and written
     again will cause successive dithering to be done each time the pixels are
     written.  On Indy and XL graphics, successive dithering will not occur.

     On Indigo Entry graphics, when in color index mode with double-buffering
     enabled, 8-bit values are clamped to 4 bits, rather than being masked.

BUGS
     IRIS-4D Personal Iris requires that both |x2-x1| and |y2-y1| be less than
     2048.

     IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
     than 2048.

     The size of the array passed to lrectwrite is limited to the size of the
     screen.