Interface to PGPLOT

As described previously versions of the PGPLOT interface routines with prefix AGP_ exist in two libraries. The AGI library includes these and SGS routines based on GKS graphics together with IDI routines. The AGP library is designed to only interface to native-PGPLOT and has its own link commands described here. The AGP_ routines have indentical names and argument lists for both libraries. Note, however, that the AGP library does not support the concept of PGPLOT plotting into an SGS zone.

A set of routines are supplied to interface the database to the PGPLOT graphics package, these are prefixed by AGP_ instead of AGI_. A picture in the database is equated with a PGPLOT viewport. Previous versions of PGPLOT only allowed one device to be open at one time and this restriction still exists in the AGP_ routines. The PGPLOT interface to AGI signifies this by returning an error status if another device is requested while a current PGPLOT device is open.

PGPLOT is activated with a call to AGP_ACTIV, but it does not actually open a device for plotting. A device is opened when the first call to AGP_NVIEW is made. The actual device that is opened will be the one associated with the current picture in the database. AGP_NVIEW creates a new PGPLOT viewport from the current AGI picture. If the border argument in AGP_NVIEW is false then the new viewport fills the area specified by the picture and the world coordinate system of the database picture is recreated in the viewport. If however the border argument in AGP_NVIEW is true then the viewport is created smaller than the area defined by the picture so that a standard width border surrounds the viewport. The world coordinates of this viewport are given the default values of 0 to 1 in each axis.

The current viewport can be saved as a picture in the database using a call to AGP_SVIEW. The size of the new picture must be less than or equal to the size of the current picture in the database, otherwise an error status is returned. Although PGPLOT uses the concept of a border around a plot in which to put annotations, it does not let an application inquire the size of this border and so it is not possible to save the border area as a 'FRAME' picture in the database from within the associated viewport. If such a 'FRAME' picture is required in the database then it must be saved before the viewport is created, or must be recreated from an existing picture.

PGPLOT is shut down using AGP_DEACT.

The following code segment gives an example of an application that creates a viewport that matches the size of the current picture if the overlay flag is true, or creates a viewport with a border for annotation if the overlay flag is false.

    *   Open AGI on a device obtained from the parameter system.
    *   Do not clear the viewport if overlay mode is requested.
          IF ( OVER ) THEN
             CALL AGI_ASSOC( 'DEVICE', 'UPDATE', ID1, STATUS )
          ELSE
             CALL AGI_ASSOC( 'DEVICE', 'WRITE', ID1, STATUS )
          ENDIF

    *   Activate the PGPLOT interface to AGI
          CALL AGP_ACTIV( STATUS )

    *   If plotting over previous plot find the last data picture and
    *   match the PGPLOT viewport to it
          IF ( OVER ) THEN

    *   Use the current picture if it is a data picture otherwise 
    *   find the last data picture that fits within the current one
             CALL AGI_INAME( CNAME, STATUS )
             IF ( CNAME .NE. 'DATA' ) THEN
                CALL AGI_RCL( 'DATA', ID2, STATUS )
             ENDIF

    *   If a suitable data picture was not found then abort
             IF ( STATUS .NE. SAI__OK ) <goto closedown>

    *   Create the viewport to match the data picture
             CALL AGP_NVIEW( .FALSE., STATUS )

    *   If not using an overlay then create a viewport with a border
          ELSE
             CALL AGP_NVIEW( .TRUE., STATUS )
          ENDIF

The next piece of code shows how the viewport and frame from the previous example can be stored in the database as pictures. If the overlay mode has been used then the viewport and associated frame will be the same size.

    *   Select the picture within which the viewport was created
    *   and inquire its world coordinates
          CALL AGI_SELP( ID1, STATUS )
          CALL AGI_IWOCO( WX1, WX2, WY1, WY2, STATUS )

    *   Save this in the database as the frame picture using the
    *   full extent of the picture.
    *   Define a default world coordinate system for the new picture.
          CALL AGI_NUPIC( WX1, WX2, WY1, WY2, 'FRAME', 'Frame picture',
         :                0.0, 1.0, 0.0, 1.0, FID, STATUS )

    *   Save the current viewport as the data picture
          CALL AGP_SVIEW( 'DATA', 'Data picture', VID, STATUS )

There are wrap-up routines to open and close AGI and PGPLOT within the ADAM environment using single calls. The sequence of calls AGI_ASSOC, AGI_BEGIN, AGP_ACTIV, AGP_NVIEW can be replaced by a single call to AGP_ASSOC. As with AGS_ASSOC an optional call to AGI_RCL can be made by passing a non-blank name argument. The sequence of calls AGP_DEACT, AGI_END, AGI_CANCL or AGI_ANNUL can be replaced by a single call to AGP_DEASS.

PGPLOT can be used as a stand-alone package. When GKS-based PGPLOT is used from the AGI library PGPLOT can also be started from within an SGS zone. In this case PGPLOT is initialised while SGS is still open. This is the only situation where AGI allows more than one graphics package to be open at one time. The following simplified program section illustrates the opening of PGPLOT from within an SGS zone.

    *   Open AGI and SGS on a device obtained from the parameter system
          CALL AGS_ASSOC( 'DEVICE', 'WRITE', ID, IZONE, STATUS )

    *   Create a new SGS zone of the required size and shape
          <Create a new zone with SGS calls>

    *   Open up PGPLOT and create a new viewport matching the current zone
          CALL AGP_ACTIV( STATUS )
          CALL AGP_NVIEW( .FALSE., STATUS )

    *   Create a new PGPLOT environment and draw the picture
          <Use PGPLOT to draw the picture>

    *   Close down PGPLOT, SGS and AGI
          CALL AGP_DEACT( STATUS )
          CALL AGS_DEASS( 'DEVICE', .TRUE., STATUS )

Note that when using the AGP routines to open PGPLOT in the current SGS zone it is essential that SGS has been opened using the AGS routines. Normally AGP_NVIEW creates a viewport that matches the size of the current picture in the database, but in this instance the size of the viewport matches the current SGS zone. The new viewport inherits the world coordinate system of the current picture in the usual way.

The job of opening and closing the device is handled by the AGP_ routines and therefore PGBEGIN and PGEND should not be called in an application using AGI. Similarly the routines PGENV, PGPAPER and PGVSTAND should not be called as these subvert the underlying coordinate system.