In addition to the SPPS Functions,
there are several Utility Functions that augment the NCAR GKS package.
The members of this set functions discussed here are:
- NGCKOP - function to check if a given
workstation is open.
- NGDOTS - draws filled dots or circles
with any size or color.
- NGMFTC - temporarily close a metafile workstation.
- NGPICT - controls breaks in a picture
drawing sequence.
- NGREOP - reopens a metafile for appending.
- NGSRAT - Saves/restores/sets NCAR GKS primitive
attribute settings.
NGCKOP
NGCKOP is a function that takes a GKS workstation identifier as an
argument and returns a "1" if the workstation is open and a "0"
otherwise.
------------------------------------------------------
Argument | Type | Mode
------------------------------------------------------
INTEGER FUNCTION NGCKOP (WKID) | Integer | Input
------------------------------------------------------
- WKID
- Integer GKS workstation identifier.
The statement:
IOPEN = NGCKOP(WKID)
will set IOPEN to "1" if the workstation whose identifier is WKID is
currently open, otherwise IOPEN will be set to "0".
The GKS standard requires that marker type 1
always be displayed as the smallest possible dot. For this reason a
dot marker will not be scaled, regardless of the value of the
marker size scale factor supplied to
GSMKSZ. The NGDOTS utility has been added to allow for drawing
dots or circles at any size and in any color.
------------------------------------------------------
Argument | Type | Mode | Dimension
------------------------------------------------------
CALL NGDOTS (X, | Real | Input | NUM
Y, | Real | Input | NUM
NUM, | Integer | Input |
SIZE, | Real | Input |
ICOLOR) | Integer | Input |
------------------------------------------------------
- X
- Specifies the X world coordinates where a sequence of circular
filled dots (or circles) is to be drawn.
- Y
- Specifies the Y world coordinates where a sequence of circular
filled dots (or circles) is to be drawn.
- NUM
- The number of dots (or circles) to be drawn.
- SIZE
- Specifies the size, in world coordinate Y-axis units, of the
diameter of each dot to be drawn.
- ICOLOR
- The GKS color index specifying what color the dots will be.
The coordinates must be world coordinates and not
user coordinates. NGDOTS does not respect the log scaling or
axis reversal options of the
SET call and will report a warning
if these are not set to their default values.
The dots are scaled appropriately so that they will be circular
when the normalization transformation does not preserve aspect
ratio.
The algorithm is to construct a single circle and then translate
it to the various coordinate positions. The original circle is
computed by using trig functions to get points in the first
octant, and then using symmetries to get the rest of the points
on the circle.
The number of points used for the circle is adjusted depending
on the relative size of the circle. The maximum number of points
is 512 and the minimum is 8.
If circles are desired rather than dots, then toggle the ngmisc
parameter CT (see the man page for ngmisc_params which
describes all of the available ngmisc parameters) with a call to
NGSETI:
CALL NGSETI('CT',1)
before NGDOTS to get circles, and
CALL NGSETI('CT',0)
before calling NGDOTS to get dots. The default is to draw dots.
Assuming that normalization transformation 0 is in effect and
that color index 2 has been defined as red in a call to GSCR, then
CALL NGDOTS(0.5, 0.25, 1, 0.1, 2)
would draw a single red dot at world coordinate position (.5,.25)
with a diameter of 0.1 .
Assuming that normalization transformation 0 is in effect and
that color index 2 has been defined as red in a call to
GSCR, then
CALL NGDOTS(0.5, 0.25, 1, 0.1, 2)
would draw a single red dot at world coordinate position (.5,.25)
with a diameter of 0.1 .
Do an "ncargex
fngngdts" for a relevant example.
NGMFTC temporarily closes an NCGM, allowing for subsequent reopening
with NGREOP.
-----------------------------------------
Argument | Type | Mode
-----------------------------------------
CALL NGMFTC (WKID) | Integer | Input
-----------------------------------------
- WKID
- Integer GKS workstation identifier.
NGMFTC can be called at any time after a
metafile workstation has been opened, even in the middle of drawing
a picture. The primary use of NGMFTC
is to allow for writing to more than one metafile in a single job
execution. Since NCAR GKS does not allow for having more than a
single NCGM workstation open at a time, you can use NGMFTC to stop
output to one metafile while you write to another metafile and then
resume output to the initial metafile.
If you simply want to suspend output to a metafile workstation,
but do not need to write to another metafile workstation, simply
use the GKS entry GDAWK to deactivate
the workstation, thus suspending output, and
GOPWK to reactivate
the workstation when you want to resume output.
For saving the state of all primitive attribute values of an NCGM
workstation at the time of the temporary close and restoring them
at the time of the reopen with NGREOP, see the
documentation for NGSRAT.
If NGMFTC is used and NGREOP is not subsequently invoked to reopen
the file so that it can be terminated normally in the same job step,
then an improperly terminated metafile will result from the temporary close.
Do an "ncargex
pgkex27" for a relevant example.
NGPICT can be utilized to handle breaks in a GKS picture drawing
sequence. The actions taken depend on whether the designated
workstation is a metafile or an output/input workstation. An option
is provided for prompting the user when an output/input workstation is
ready and waiting after a pause.
NGPICT is designed to be used when more precise control over individual
workstations is desired than that offered by FRAME. This might be
desirable, for example, when an application is controlling several
simultaneously active workstations.
To use NGPICT one should be opening GKS workstations with
GOPWK rather
than with OPNGKS.
-----------------------------------------
Argument | Type | Mode
-----------------------------------------
CALL NGPICT (WKID, | Integer | Input
ACTION) | Integer | Input
-----------------------------------------
- WKID
- designates the workstation identifier of a workstation as it was
specified in a GOPWK call.
- ACTION
- specifies the action to be taken on the workstation WKID.
Legal values are:
- 0
- Execute an UPDATE WORKSTATION on WKID. All pending
action items for WKID are made current. All buffers are
flushed.
- 1
- Execute an UPDATE WORKSTATION followed by a CLEAR WORKSTATION.
The workstation screen is cleared after being made current.
- 2
- Execute an UPDATE WORKSTATION followed by a pause waiting for a
mouse click or a key click.
- 3
- Execute an UPDATE WORKSTATION followed by a pause followed by a
CLEAR WORKSTATION after the pause has been terminated by a mouse
click or a key click.
- 4
- Same as 3 except a "<READY>" prompt is issued in the
lower left
corner of the window after the UPDATE WORKSTATION.
If WKID designates a metafile, then a CLEAR WORKSTATION is done which
inserts an END PICTURE into the metafile. The result produced in this
case would be the same as that resulting from a call to FRAME. The
only valid actions for a metafile workstation are 0 and 1.
If WKID=2 designates a metafile workstation, then
CALL NGPICT(2,1)
would duplicate the action of a FRAME call.
If WKID=2 designates an X11 workstation, then
CALL NGPICT(2,4)
would cause a pause in the X11 window and wait for a key click or a
mouse click. A "<READY>" prompt, indicating that the window is waiting
for a mouse click or a key click, would appear at the lower left of
the X11 window after the window has been updated. After a mouse click
in the X11 window, that window will be cleared before program execution
continues.
NGREOP is called to reopen an existing NCAR Graphics metafile for appending.
The reopened metafile may be a complete metafile that was created in the
same job step, or a different job step, or the metafile may be an
incomplete one that has been temporarily closed with a call to
NGMFTC.
------------------------------------------------------
Argument | Type | Mode | Dimension
------------------------------------------------------
CALL NGREOP (WKID, | Integer | Input |
CONID, | Integer | Input |
ITYPE, | Integer | Input |
FNAME, | Character | Input |
IOPT, | Integer | Input |
IAT, | Integer | Input | 14
RAT, | Integer | Input | 7
NCOLRS, | Integer | Input |
NSTART, | Integer | Input |
CTAB) | Real | Input | 3 x NCOLRS
------------------------------------------------------
- WKID
- designates a GKS workstation identifier.
- CONID
- designates a GKS conection identifier.
- ITYPE
- specifies the workstation type. Currently the only valid
value is "1". This subroutine may be augmented to accommodate
PostScript files in the future.
- FNAME
- specifies the filename of the metafile being opened for appending.
- IOPT
- specifies the desired action:
- 0
- reestablish the color table only (using the color table in
argument CTAB described below). The attributes of the
reopened workstation will be set to default values and
may well be out of sync with the current GKS attributes.
action items for WKID are made current. All buffers are
flushed.
- 1
- reestablish the color table and GKS state (the GKS state as
supplied in arguments IAT and RAT described below). The
state values will not be flushed to the metafile.
- 2
- reestablish the color table and GKS state and flush the
GKS state values to the metafile.
- 3
- reestablish the color table and flush the current GKS state
values to the metafile (not the values in IAT and RAT).
- IAT
- contains GKS integer state variables as
detailed in the documentation for NGSRAT.
- RAT
- contains GKS floating-point state variables as
detailed in the documentation for NGSRAT.
- NCOLRS
- specifies the number of colors in the color table supplied in
argument CTAB, described below.
- NSTART
- specifies the color index associated with the first color in the
color table CTAB (all other color indices are filled in in sequence).
For example, if NCOLRS = 3 and NSTART = 4, then the color values
defined in CTAB would be used to define color indices 4, 5, and 6.
- CTAB
- specifies a color table used to initialize the reopened metafile.
This color table does not necessarily have to agree with the color
table in effect when the original metafile was created.
The most common usage of NGREOP would be in conjunction with usage
of NGSRAT and
NGMFTC. NGMFTC would be used to temporarily close
a metafile and NGSRAT used to save the state of the GKS primitive
attributes at the time of the close. To reopen the temporarily
closed metafile you would call NGREOP with the attribute settings
previously saved and a setting of IOPT of 2. NGMFTC can be used
to temporarily close a metafile any time after that metafile has been opened,
even in the middle of a picture.
NGREOP only reopens the metafile and does not activate it. It will
be necessary to call GACWK before
sending graphics primitives to the
reopened metafile.
NGREOP can also be used to reopen a previously created metafile -
either created in an independent job step, or in the same job step.
The following sequence:
CALL NGMFTC(1)
CALL NGSRAT(2, IAT, RAT)
... do stuff
CALL NGREOP(CALL NGREOP(1, 2, 1, 'gmeta1', 2,
+ IAT, RAT, NCOLS, 0, CTAB)
would temporarily close the metafile with workstation ID of 1 (in this
case a metafile with name "gmeta1") and save the GKS state variables
at the time of the close. Then the call to NGREOP would reopen the
metafile for appending.
Do an "ncargex
pgkex27" for a relevant example.
NGSRAT can be used to save, restore, or set all NCAR GKS primitive attribute
values in a single call.
------------------------------------------------------
Argument | Type | Mode | Dimension
------------------------------------------------------
CALL NGSRAT (IOPT, | Integer | Input |
IAT, | Integer | Input | 14
RAT) | Real | Input | 7
------------------------------------------------------
- IOPT
- specifies the desired action:
- 0
- save the current settings of all attributes internal to
the subroutine, i.e. not in the IAT and RAT arrays.
- 1
- restore the context from the most recently saved state.
- 2
- return the current context in the
output arrays IAT (integer
attributes) and RAT (floating-point attributes) as follows:
- IAT(1)
- Clip indicator
- IAT(2)
- Line type
- IAT(3)
- Polyline color index
- IAT(4)
- Marker type
- IAT(5)
- Polymarker color index
- IAT(6)
- Text font
- IAT(7)
- Text precision
- IAT(8)
- Text color index
- IAT(9)
- Text path
- IAT(10)
- Text horizontal alignment
- IAT(11)
- Text vertical alignment
- IAT(12)
- Fill area interior style
- IAT(13)
- Fill are style index
- IAT(14)
- Fill area color index
- RAT(1)
- Linewidth scale factor
- RAT(2)
- Marker scale factor
- RAT(3)
- Character expansion factor
- RAT(4)
- Character spacing
- RAT(5)
- Character height in world coordinates
- RAT(6)
- Character up vector, X component in world coordinates
- RAT(7)
- Character up vector, Y component in world coordinates
- 3
- set the context to the values specified in the IAT and RAT
arrays (as described above).
- IAT
- An integer array, of length 14, that has meaning only if IOPT
equals 2 or 3.
- RAT
- A real array, of length 7, that has meaning only if IOPT
equals 2 or 3.
If you want to save the state of the NCAR GKS primitive attribute
settings, call NGSRAT with a first argument of 0. When the first
argument is 0, the IAT and RAT arrays (second and third arguments)
are ignored and the state values are stored internally to NGSRAT.
To restore the NCAR GKS primitive attribute values to what they
were as of the last time NGSRAT was called with argument IOPT = 0,
then call NGSRAT with first argument of 1. IAT and RAT are ignored
in this case.
If you call NGSRAT with a fist argument of 2, then the current
settings of the NCAR GKS primitive attribute values are returned
in arrays IAT and RAT as per the description of IAT and RAT above.
If you call NGSRAT with a fist argument of 3, then arrays IAT and
RAT must be supplied and the values therein will be used to set
the NCAR GKS primitive attribute values as per the description of
IAT and RAT above.
A common use of NGSRAT would be in conjunction with
NGMFTC and
NGREOP for saving the GKS state after writing
to one metafile, writing
to a new metafile, and then restoring the GKS state when reopening
the initial metafile.
The following sequence:
CALL NGSRAT(0,IAT,RAT)
... do some setting and drawing
CALL NGSRAT(1,IAT,RAT)
would save the values of all NCAR GKS primitive attributes
before the code that does setting and drawing and then restore the
attribute values after the setting and drawing.
Do an "ncargex
pgkex27" for a relevant example.