readsource(3G)

NAME
     readsource - sets the source for pixels that various routines read

C SPECIFICATION
     void readsource(src)
     long src;

PARAMETERS
     src   expects a symbolic constant that identifies the pixel source that
           is to be used:

           SRC_AUTO selects the front color buffer when the current
           framebuffer, as specified by drawmode, is in single buffer mode. It
           selects the back color buffer when the current framebuffer is in
           double buffer mode.  This is the default.

           SRC_FRONT selects the front color buffer of the current
           framebuffer, as specified by drawmode.  This source is valid for
           both single buffer and double buffer operation.

           SRC_BACK selects the back color buffer of the current framebuffer,
           as specified by drawmode.  This source is valid only while the
           current framebuffer is in double buffer mode.

           SRC_ZBUFFER selects the z-buffer of the current framebuffer.
           Because only the normal framebuffer has a z-buffer, this source is
           currently valid only while draw mode is NORMALDRAW.

           SRC_FRAMEGRABBER selects the Live Video Digitizer as the pixel
           source, regardless of the current draw mode.  This source is valid
           only on IRIS-4D GTX and VGX models with the Live Video Digitizer
           option board.  IRIS-4D GTX models support this source only during
           rectcopy, not rectread or lrectread.

           SRC_OVER selects the overlay planes, and is valid only while draw
           mode is NORMALDRAW.  This source is valid only on the Personal
           Iris.

           SRC_UNDER selects the underlay planes, and is valid only while draw
           mode is NORMALDRAW.  This source is valid only on the Personal
           Iris.

           SRC_PUP selects the pop-up planes, and is valid only while draw
           mode is NORMALDRAW.  This source is valid only on the Personal
           Iris.

           SRC_ILBUFFER_1 SRC_ILBUFFER_2 SRC_ILBUFFER_3 SRC_ILBUFFER_4
           SRC_ILBUFFER_5 SRC_ILBUFFER_6 SRC_ILBUFFER_7 SRC_ILBUFFER_8
           SRC_ILBUFFER_9 SRC_ILBUFFER_10 SRC_ILBUFFER_11 SRC_ILBUFFER_12
           SRC_ILBUFFER_13 SRC_ILBUFFER_14 SRC_ILBUFFER_15 SRC_ILBUFFER_16
           selects the ilbuffers previously allocated with ilbuffer.  This
           source is valid only on the RealityEngine systems running 5.0.1 or
           later.

DESCRIPTION
     readsource specifies the pixel source buffer that rectcopy, readpixels,
     readRGB, rectread, and lrectread use. A separate read source is
     maintained for each of the GL framebuffers:  normal, pop-up, overlay, and
     underlay.  Calls to readsource change the read source of the currently
     active framebuffer, as specified by drawmode.  By default the read source
     for each framebuffer is SRC_AUTO.

     Because read sources, with the exception of some implemented only on the
     Personal Iris, always specify a source within the current framebuffer, it
     is not possible to copy pixels from one framebuffer to another.  Such a
     copy must be implemented by first reading pixels out of the source
     framebuffer, then changing the draw mode to the destination framebuffer,
     and writing the pixels.

SEE ALSO
     lrectread, readpixels, readRGB, rectcopy

NOTES
     This subroutine is available only in immediate mode.

     On the IRIS-4D B or G models, SRC_ZBUFFER is not available.

     Read sources SRC_OVER, SRC_UNDER, and SRC_PUP operate only on the
     Personal Iris.

BUGS
     On the IRIS-4D GT and GTX models, and on all Personal IRIS, XS, XS24, XZ,
     Elan and Extreme systems, a single readsource variable is shared between
     the four framebuffers.

     On the Personal Iris, the source for pixel reads does not change when
     changing framebuffers (via drawmode) unless the current selected read
     source is SRC_AUTO (the default).

     On some IRIS-4D GT and GTX models, while copying rectangles with blending
     active, readsource also specifies the bank from which destination color
     and alpha are read (overriding the blendfunction setting).