gsrsav

Purpose

     Saves a rectangular block.

C Syntax

     int gsrsav_ (buffer, x1, y1, x2, y2)

     int *buffer, *x1, *y1, *x2, *y2;

FORTRAN Syntax

     INTEGER function gsrsav (buffer, x1, y1, x2, y2)

     INTEGER buffer (*), x1, y1, x2, y2

Pascal Syntax

     FUNCTION gsrsav_ (

     VAR buffer: ARRAY [1..k| of INTEGER;
     VAR x1, y1, x2, y2: INTEGER
     ): INTEGER [PUBLIC|;

Description

     The gsrsav subroutine saves a block of pixels, defined by
     the input  rectangle, in storage starting  at the address
     indicated.  This  stored block  can be restored  with the
     gsrrst subroutine.  (See "gsrrst.")

     The relevant attributes are:

     o   Plane mask
     o   Logical operation.

     Parameters

     buffer            Indicates where gsrsav  should save the
                       block of pixels.

                       The size  of the buffer depends  on the
                       size of the rectangle and on the device
                       organization.  For devices organized by
                       plane, the plane  mask attribute deter-
                       mines  the number  of planes  saved for
                       each pixel.   For devices  organized by
                       pixel,  the  entire   pixel  is  always
                       saved.   For  both  organizations,  the
                       unit of access to the frame buffer also

                       plays a role in calculating the size of
                       the buffer.  See "gscmap" for details.

                       Note  that the  gsrsav subroutine  does
                       not  check whether  the  buffer is  too
                       small  to  contain   the  pixel  block.
                       Serious consequences can  result if the
                       buffer is too small.  However, a buffer
                       size equal to

                             (((y2-y1+1)/32+2)*(x2-x1+1))

                       will hold all save images.

     x1, y1            Define  the lower  left  corner of  the
                       rectangular area to  save.  That is, x1
                       is  the  greatest  lower bound  of  the
                       pixels saved in x.

     x2, y2            Define  the upper-right  corner of  the
                       rectangular area to  save.  That is, x2
                       is the least upper  bound of the pixels
                       saved in x.

     The intended purpose of the gsrsav and gsrrst subroutines
     is efficient  saving and  restoring of pixel  blocks dis-
     played  temporarily  at a  fixed  location  in the  frame
     buffer.  Because the GSL  saves the frame buffer contents
     in a  device-dependent fashion, it is  generally not pos-
     sible to correctly  move blocks of pixels  from one posi-
     tion to another in  a plane-oriented adapter using gsrsav
     and gsrrst, nor  is it possible to  manipulate the buffer
     without careful consideration of adapter characteristics,
     block  size,  and position  of  the  block in  the  frame
     buffer.

     For further  information on moving and  storing blocks of
     pixels, see "gsxblt."

     For Pascal, the application must declare the array passed
     as  being  fixed  length   and  declare  the  routine  as
     accepting an array of that  length.  The k in the routine
     declaration must be a constant.

Return Value

     GS_SUCC   Successful.
     GS_CORD   Invalid coordinate.
     GS_INAC   Virtual terminal inactive.

Related Information

     In this book:  "gscmap,"  "gsrrst," and  "gsxblt."