Pictures

Pictures represent rectangular areas on a display. The pictures have default coordinate systems that are linear and increase left to right and bottom to top, corresponding to GKS rules. Each picture can optionally have an associated transformation to allow for other coordinate systems. Pictures are stored in the database in the order they were created, so when recalling the last picture of a given name, for example, the most recently created picture of that name will be recovered.

The AGI interface to each graphics package will interpret the meaning of a picture to suit the design of that particular package. When used in conjunction with SGS a picture is made equivalent to an SGS zone. For example to save an SGS zone as a picture use

CALL AGS_SZONE( PNAME, COMENT, PICID, STATUS )

PNAME and COMENT are used to identify the picture in the database as described in the sections below. PICID returns the identifier for the new picture in the database.

There is one routine, AGI_NUPIC, that allows new pictures to be created in the database without necessarily opening a graphics package first.

          CALL AGI_NUPIC( WX1, WX2, WY1, WY2, PNAME, COMENT,
         :                NEWX1, NEWX2, NEWY1, NEWY2, PICID, STATUS )

WX1, WX2, WY1, WY2 define the rectangular extent of the new picture in terms of the world coordinates of the current picture. PNAME and COMENT describe the picture as discussed in the following sections. NEWX1, NEWX2, NEWY1, NEWY2 specify the world coordinate system of the new picture. PICID returns the identifier for the new picture in the database.

AGI works with a current picture in an analogous manner to SGS and its current zone. A new picture has to be created within the bounds of the current one, and this then becomes the current picture. Pictures are recalled from the database only if they lie within the physical bounds of the current one; the recalled picture then becomes the current one. A picture can be made current by calling the routine AGI_SELP.

The picture recall routines, AGI_RC*, provide the means of traversing the database. The key to the search is the picture name, and the search ends when a picture of the given name is found that lies within completely the bounds of the current picture. This picture then becomes the current picture. If no suitable picture is found then an error status is returned. The search can be made more general by giving an empty name string. This results in the first picture on the search path, that lies within the current one, being recalled. AGI_RCL searches backwards from the last (most recent) picture in the database. AGI_RCF searches forwards from the first (most ancient) picture in the database. AGI_RCP searches backwards starting at the picture given by the PSTART identifier, and AGI_RCS does the same searching forwards.

A further restriction on the search can be introduced by using the AGI_RC*P routines. With these, a picture is only recalled if it corresponds to the given name, lies within the bounds of the current picture, and encompasses a given point in the world coordinate space of the current picture. This type of recall is useful when a cursor has been put up on the display, and the user asked to select a picture with the cursor.

A potential problem arises when searching backwards through the database. The hierarchy of pictures in the database implies that previous pictures will usually be larger than the current one, but the search strategy requires the current picture to be larger than the picture being sought. This problem can be overcome by selecting a picture known to be larger than any picture being sought as the current one. The base picture is the most convenient as this is larger than any picture in the database. The following example shows how to search backwards through the database for a picture with a particular label (labels are discussed in this section).

    *   Get an identifier for the base picture and select it as current.
          CALL AGI_IBASE( BASEID, STATUS )
          CALL AGI_SELP( BASEID, STATUS )

    *   Recall the last picture in the database of any name and get its label.
          CALL AGI_RCL( ' ', PICID, STATUS )
          CALL AGI_ILAB( PICID, PLABEL, STATUS )

    *   Loop through the database until the a match with LABEL is found.
          DO WHILE ( ( PLABEL .NE. LABEL ) .AND. ( STATUS .EQ. SAI__OK ) )

    *   Reselect the base picture as the current one.
    *   This ensures the search does not fail because a picture is not
    *   within the current one.
             CALL AGI_SELP( BASEID, STATUS )

    *   Search backwards starting at the previously recalled picture
             PICIDS = PICID
             CALL AGI_RCP( ' ', PICIDS, PICID, STATUS )

    *   Inquire the label of this picture
             CALL AGI_ILAB( PICID, PLABEL, STATUS )
          ENDDO