gsrsav(3g) — AIX PS/2 1.2.1



GSRSAV(3g,L)                AIX Technical Reference                GSRSAV(3g,L)



-------------------------------------------------------------------------------
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.

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 determines 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.



Processed November 7, 1990       GSRSAV(3g,L)                                 1



GSRSAV(3g,L)                AIX Technical Reference                GSRSAV(3g,L)




                  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) * ((x2-x1+1) / 32+2 ))

                  integers per plane will hold all save images on planar
                  devices.  For pixel devices, a buffer of

                        (y2-y1+1) * (x2-x1+1)/4 +1

                  integers is sufficient.

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 displayed 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 possible to correctly move blocks
of pixels from one position 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."








Processed November 7, 1990       GSRSAV(3g,L)                                 2

Museum

Related Articles