KPG1_GDNEW

Creates a new DATA picture with ancillary pictures

Description:

This routine returns identifiers for a new DATA picture together with various ancillary pictures in the graphics database. On exit, the new DATA picture is the current AGI picture, and the PGPLOT viewport matches the DATA picture.

A FRAME picture is only created if it would contain something other than the DATA picture (this is assumed to be the case if any ancillary pictures are requested, or if non-zero margins are requested around the DATA picture). If created, the FRAME picture has the maximum possible size. The DATA picture is then created with a size which allows all the requested ancillary pictures to be created within the FRAME picture.

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

Invocation

CALL KPG1_GDNEW( COMMNT, MARGIN, NP, PNAME, PSIDE, PSIZE, SASPEC, BOX, IPICD, IPICF, IPIC, STATUS )

Arguments

COMMENT = CHARACTER ∗ ( ∗ ) (Given)
A comment to store with the new pictures added to the AGI database. This will usually by an indication of the application being run (egKAPPA_DISPLAY).
MARGIN( 4 ) = REAL (Given)
The width of the borders to leave round the DATA picture, given as fractions of the corresponding dimension of the current picture. These should be supplied in the order bottom, right, top, left.
NP = INTEGER (Given)
The number of extra pictures to be included in the FRAME pictures (the DATA picture itself is not included in this list). Margins are left round the DATA picture with widths given by MARGIN. Any extra pictures are placed outside these margins, in positions described by PSIDE and PSIZE.
PNAME( NP ) = CHARACTER ∗ ( ∗ ) (Given)
The names to store in the AGI database with the NP extra pictures.
PSIDE( NP ) = CHARACTER ∗ 1 (Given)
Each element of this array should be one of L, R, T or B. It indicates which side of the FRAME picture an extra picture is to be placed. For Left and Right, the extra picture occupies the full height of the DATA picture, margins, and any previously created extra pictures. The picture is placed at the far Left or Right of all previously created pictures. For Top or Bottom, the extra picture occupies the full width of the DATA picture, margins, and any previously created extra pictures. The picture is placed at the top or bottom of all previously created pictures. Ignored if NP is zero.
PSIZE( NP ) = REAL (Given)
The size of each extra picture. For Left and Right pictures, this is the width of the picture, and the value is given as a fraction of the width of the current picture. For Top and Bottom pictures, it is the height of the picture, and it is given as a fraction of the height of the current picture. Ignored if NP is zero.
SASPEC = REAL (Given)
The aspect ratio with which a new DATA picture should be created. This is the height divided by the width of the DATA picture, assuming equal scales on each axis (egmetres). A value of zero causes the DATA picture to have the aspect ratio which produces the largest picture. The actual value used will depend on the value supplied for the FILL parameter (see above).
BOX( 4 ) = DOUBLE PRECISION (Given)
The world co-ordinate bounds to give to the DATA picture if a new DATA picture is created. These should normally be pixel co-ordinates. The (x,y) co-ordinates of the bottom left corner should be given in elements 1 and 2, and the (x,y) co-ordinates of the top right corner should be given in elements 3 and 4. If the box has zero area, then world co-ordinates are set to centimetres from the bottom left corner of the DATA picture.
IPICD = INTEGER (Returned)
An AGI identifier for the DATA picture.
IPICF = INTEGER (Returned)
An AGI identifier for the FRAME picture. The world co-ordinate system is inherited from the current picture on entry. If no FRAME picture was created, then an AGI identifier for the current picture is returned.
IPIC( NP ) = INTEGER (Returned)
An array of AGI identifiers corresponding to the extra pictures requested in ZSIDE and PSIZE. The world co-ordinate system for each picture is inherited from the FRAME picture. The actual size of a picture may be less than the requested size if there is insufficient room left in the FRAME picture to give it its requested size. Identifiers for pictures which would have zero size (i.e. fall completely outside the FRAME picture) are returned equal to -1, but no error is reported.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Environment Parameters :

FILL = _LOGICAL (Read)
TRUE if the supplied aspect ratio (SASPEC) is to be ignored, creating the largest possible DATA picture within the current picture. When FILL is FALSE, the DATA picture is created with the supplied aspect ratio. Not accessed if argument SASPEC is supplied equal to zero (i.e. (SASPEC .EQ. 0.0) implies FILL=YES)