KPG1_PLOTA - Opens the graphics device and see if there is an existing DATA picture with which the new DATA picture could be aligned

Description:

This routine opens a graphics device, clearing it or not as specified by the user. If it is not cleared an attempt is made to find a DATA picture within the current picture. If found it becomes the current AGI picture, the corresponding PGPLOT viewport is established as the current PGPLOT viewport, and an AST Plot is returned for it in which the Base (GRAPHICS) Frame corresponds to PGPLOT world co-ordinates. If no DATA picture is found, or if the device was not cleared on opening, the current AGI picture and PGPLOT viewport are unchanged on exit and no Plot is returned.

Various environment parameters are used to obtain options, etc. The names of these parameters are hard-wired into this subroutine in order to ensure conformity between applications.

Invocation:

CALL KPG1_PLOTA( IWCS, STAT, DOMAIN, IPIC0, IPICD, IPLOT, STATUS )

Arguments:

IWCS = INTEGER (Given)

An AST pointer to a FrameSet. This may be AST__NULL. The Current and Base Frames are unchanged on exit. If an existing DATA picture was created by a non-AST application it will not have a Plot stored with it. A default Plot will be created in this case, containing two Frames; a GRAPHICS Frame corresponding to millimetres from the bottom-left corner of the view surface, and a Frame corresponding to AGI world co-ordinates. The AGI database does not contain any information describing world co-ordinates and so such information must be supplied by the calling application, on some assumption such as "AGI world co-ordinates are PIXEL co-ordinates". This information is provided through a FrameSet (IWCS) and a Domain name (DOMAIN). DOMAIN specifies the Domain in which AGI world co-ordinates are assumed to live. A FrameSet may then be supplied using argument IWCS containing a Frame with the same Domain which will be used to describe AGI world co-ordinates in the returned Plot (a default two-dimensional Frame with the specified Domain is used if no FrameSet is supplied or if it does not contain a Frame with the specified Domain). If DOMAIN is supplied Blank, a default two-dimensional Frame with Domain AGI_WORLD will be used to describe AGI world co-ordinates.

If the existing DATA picture was created by an AST application, it will have a Plot stored with it which means that AGI world co-ordinates will be ignored. Consequently, the values supplied for IWCS and DOMAIN will also be ignored.

STAT = CHARACTER $*$ ( $*$ ) (Given)

Determines whether or not the new DATA picture creted by the calling application is to be aligned with an existing DATA picture.

• "NEW" - no attempt is made to align the new DATA picture with an existing DATA picture, even if the CLEAR parameter is given a FALSE value.

• "OLD" - the new DATA picture is always aligned with an existing DATA picture. The CLEAR parameter is not accessed (it is assumed to have a FALSE value) and an error is reported if no DATA picture is available.

• "UNKNOWN" - If CLEAR is given a FALSE value then the new DATA picture is aligned with any existing DATA picture, but no error is reported if no DATA picture exists.

DOMAIN = CHARACTER $*$ ( $*$ ) (Given)

The Domain for AGI world co-ordinates. Only used if a FrameSet is supplied (IWCS). If a blank value is supplied then "AGI_WORLD" will be used. See description of argument IWCS above for more details.

IPIC0 = INTEGER (Returned)

An AGI identifier for the original current picture.

IPICD = INTEGER (Returned)

An AGI identifier for the existing DATA picture. Returned equal to -1 if there is no existing DATA picture or if the device was cleared on opening.

IPLOT = INTEGER (Returned)

An AST pointer to a Plot associated with an existing DATA picture. Returned equal to AST__NULL if an error occurs, or if there is no existing DATA picture, or if the device was cleared on opening.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• Close down AGI and PGPLOT using KPG1_PGCLS.

Environment Parameters :

CLEAR = _LOGICAL (Read)

TRUE if the graphics device is to be cleared on opening. See argument STAT.

DEVICE = DEVICE (Read)

The plotting device.