The AGI database is useful in two basic contexts. The first is to pass information between separate applications that may or may not be plotting on the device with the same graphics package. An example of two independent PGPLOT based applications has been given in Section 3.11 while the use of the database file to allow native-PGPLOT based applications to interact with GKS-based applications is described in Section 4.2. For applications using the AGI GKS-based library a second use is to allow different graphics packages to interact within a single application, for example by using SGS to draw on top of an image displayed with IDI. These two packages have completely different models of the display device and AGI is used to mediate between them. The major restriction with this second mode of use is that the two graphics packages cannot both be open at the same time. There will be other restrictions depending on how the physical device characteristics are utilized by each graphics package; for example the size of the display area may be different in the different packages and this will cause problems if a picture defined by one package is beyond the limits of another.
The following simplified block diagram illustrates the recommended operation of AGI and two graphics packages within one application.
As described in Section 2 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 in Section 8. 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.
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.
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.
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.
A set of routines are supplied to interface the database to the SGS graphics package, these are prefixed by AGS_ instead of AGI_. A picture in the database is equated with an SGS zone. SGS is activated with a call to AGS_ACTIV. This does not open a device for plotting. A device is opened when the first call to AGS_NZONE is made. The actual device that is opened will be the one associated with the current picture in the database. This means that AGI has to be open before AGS_NZONE can be called. AGS_NZONE creates an SGS zone from the current AGI picture, and returns the zone identifier. An SGS zone is saved as a picture in the database using a call to AGS_SZONE. The size of the new picture must be less than or equal to the size of the current picture in the database otherwise and error status is returned. SGS is shut down using AGS_DEACT.
The job of opening and closing the device is handled by the AGS_ routines and therefore the routines SGS_ASSOC and SGS_CANCL or SGS_OPEN and SGS_CLOSE should not be called when using the AGS_ routines.
The first example shows how an application might save an SGS zone in the database.
The second example shows how another application could recreate a zone, perhaps to overlay one plot with another, or to obtain coordinates with a cursor. It assumes that the current picture in the database is the one that is wanted. If this is not the case the recall routines can be used to search the database for the correct picture.
These examples show that the AGI operations of accessing the database and opening the graphics package are common to both applications. These common opening and closing operations have been packaged up into single routines. Thus the sequence of calls AGI_ASSOC, AGI_BEGIN, AGS_ACTIV, AGS_NZONE can be replaced by a single call to AGS_ASSOC, and the sequence of calls AGS_DEACT, AGI_END, AGI_CANCL can be replaced by a single call to AGS_DEASS. Note that these wrap-up routines only exist for the ADAM interface. If the application is using the non-ADAM routines AGI_OPEN and AGI_CLOSE then the sequence of calls has to be made explicitly. Using these wrap-up routines then second application above would become
The third (picture name) argument in AGS_ASSOC can optionally be used to recall the last picture of the given name using AGI_RCL. If the name string is blank (as in the example above) then this recall routine is not called and the current database picture is returned. If the second argument in AGS_DEASS is false then the ADAM parameter is not cancelled and instead the picture identifier returned from AGS_ASSOC is annulled.
If GKS calls are mixed in with the SGS calls to produce the plot then some GKS operations may result in the plot being cleared when the device is shut down. This can happen if the device is opened with ’WRITE’ mode, which results in the zone being initially cleared, and then some aspect of the device, such as a pen colour, is changed using GKS calls. GKS believes that the original plot is now wrong because the colours are wrong and requests that the plot be redrawn in the new colours. By default this request does not happen immediately but is deferred until closedown. An application can force the update to happen immediately by setting the deferral mode:
A set of routines are supplied to interface the database to the IDI graphics package, these are prefixed by AGD_ instead of AGI_. IDI is a low-level graphics package that does not have the kind of abstraction that packages like SGS and PGPLOT have. The coordinate system is not device independent and there is no natural structure in the specification that corresponds to a picture in the way that an SGS zone does. The AGI interface to IDI is therefore more contrived than for the other packages.
IDI instructions are directed to a specific device by means of a display identifier that has to be supplied as an argument to the IDI subroutines. The routine AGD_NWIND returns a display identifier that corresponds to the device associated with the current picture. This identifier can then be used as input to the IDI routines. If the device is not already open then AGD_NWIND will open the relevant device. Subsequent calls to AGD_NWIND will return the same identifier if the current picture is associated with the same device.
The routines AGD_ACTIV and AGD_DEACT should be called before and after any other AGD_ routines.
IDI has no structure that matches the concept of a picture in the database, and so an abstract space has been defined, here called simply a window, which represents a rectangular space in the memory of the device. The definition of such a window is similar to a the definition of a transfer window in IDI, which is used to load images into the display memory. IDI works in pixel coordinates and a window is defined by its size in pixels along each axis (XSIZE and YSIZE), and by an offset, in pixels, of its bottom left hand corner from the memory origin (XOFF and YOFF). The routine AGD_SWIND will save such a window as a picture in the database. The following code segment shows how a transfer window which has been set up to load an image into a memory can be saved as a picture in the database.
As usual when creating a picture in the database if this new picture lies outside the current picture an error status is returned.
The routine AGD_NWIND will return the size and offsets of a window that matches the current picture in the database. The returned arguments should not be used to define a transfer window directly unless it is known that the picture exactly matches the size and shape of the image to be loaded into the transfer window. This is because IDI uses the transfer window to define where the end of one row occurs in the input stream of pixel values. If the transfer window is the wrong shape for the image then the line breaks will not occur in the correct place and the image will appear garbled. When using AGD_NWIND to set up a transfer window it is best to compare the returned arguments to the size of the image and set up the transfer window accordingly. The following code segment shows how a transfer window is set up so that the image loads from the bottom left of the picture. The transfer window is set up so that the bottom left corner of the image is aligned with the bottom left corner of the picture, but the size of the transfer window is defined by the size of the image and not the size of the picture.
There is a slight difference between the definition of an IDI window and a picture in the database due to the former being stored as integers and the latter being stored as floating point numbers. This does not matter when saving a window in the database because the integer coordinates are simply expressed as reals in the database, but a picture already defined in the database may have limits that correspond to partial pixels on the screen. In the latter case the pixel coordinates returned by the routine AGD_NWIND are rounded up from the picture coordinates so that the window contains the whole picture. This means that the resulting window may be slightly larger (by fractions of a pixel) than the original picture.
There are wrap-up routines to open and close AGI and IDI within the ADAM environment using single calls. The sequence of calls AGI_ASSOC, AGI_BEGIN, AGD_ACTIV, AGD_NWIND can be replaced by a single call to AGD_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 AGD_DEACT, AGI_END, AGI_CANCL or AGI_ANNUL can be replaced by a single call to AGD_DEASS.
The job of opening and closing the device is handled by the AGD_ routines and therefore the routines IDI_ASSOC and IDI_CANCL or IIDOPN and IIDCLO should not be called when using the AGD_ routines.