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.
CALL KPG1_GDNEW( COMMNT, MARGIN, NP, PNAME, PSIDE, PSIZE,
SASPEC, BOX, IPICD, IPICF, IPIC, STATUS )
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.