ACD Atlas Computing Division STARLINK

Jump To Main Content

Jump Over Banner

Home

ACDSTARLINK

Jump Over Left Menu

SGS - Simple Graphics System

P T Wallace, J R Gallop, D L Terrett

October 1983

STARLINK used both GKS and GKS-3D on the STARLINK Vax machines. The joint Rutherford/ICL GKS implementation was enhanced by a set of routines relevant to the STARLINK community.

SGS is a set of subroutines which facilitates graphics output via the GKS package. GKS, which is described in the ISO document GKS 6. 2 and in SUN/11, is a device independent graphics system designed to be the kernel of a wide variety of graphics systems. It does not itself set out to provide the most convenient set of interfaces for all applications.

SGS, while preserving GKS concepts and indeed allowing direct GKS calls to be interspersed with SGS calls, is optimised for convenience in simple cases. Many of its features are low level (for example: open, draw a line, draw a text string, close), but there are some routines of a slightly higher level (drawing arcs and formatted numbers etc). SGS does not itself provide routines for high level operations like drawing annotated axes or complete graphs; these are facilities that will in due course be provided, using SGS as a basic support package.

Many plotting programs will be written entirely with SGS calls. There may, however, be occasions when GKS routines are required in addition, either because the GKS facility is sufficiently convenient in itself and has not been repackaged) or because a specialised feature of GKS is needed. Therefore the manual uses GKS concepts to describe SGS and the reference section (in Appendix A) describes SGS routines in terms of their effect on GKS. This will allow programmers to mix GKS and SGS calls without trouble. The unadventurous user may safely ignore (and indeed discard) the appendices.

The current version of CKS - 6.2 - is superseded by an implementation of the revised standard - 7.2. There are a number of important differences and changes will be needed to many GKS-based programs when the new implementation arrives. However, the revised GKS implementation that will be available at the same time will not, in general, appear to the programmer to have changed and so use of SGS now will obviate changes when the switch to GKS 7.2 is made. SGS has been designed with an eye on both these revisions, which is why one or two of the current routines contain very little code and why under 7.2 certain other routines will undergo considerable simplification.

The structure of this manual is:

This is a developing system and users are invited to make comments to any of the authors.

1. SUMMARY OF SGS CALLS

Control

SGS_OPEN (WKSTN, IZONID, ISTAT)
Open SGS and GKS, opening and activating one workstation.
SGS_CLOSE
Shut down SGS and GKS.
SGS_OPNWK (WKSTN, IZONID, ISTAT)
Open a new workstation and select it.
SGS_SPEN (NPEN)
Select pen for line and text drawing.
SGS_IPEN (NPEN)
Inquire current pen number.
SGS_FLUSH
Complete all pending output.

Zones

SGS_ZONE (X1, X2, Y1, Y2, IZONID, ISTAT)
Create and select a zone of the specified extent.
SGS_ZSHAP (AR, POS, IZONID, ISTAT)
Create and select a zone of the specified aspect ratio.
SGS_ZSIZE (XM, YM, POS, IZONID, ISTAT)
Create and select a zone of the specified size.
SGS_SW (X1, X2, Y1, Y2, ISTAT)
Set window of current zone to given bounds.
SGS_SELZ(IZONID, ISTAT)
Select another zone.
SGS_RELZ (IZONID)
Release the specified zone.
SGS_ICURZ (IZONID)
Inquire ID of current zone.
SGS_IZONE (X1, X2, Y1, Y2, XM, YM)
Inquire window bounds for the current zone, and its size on the display surface.
SGS_IDUN (DXW,DYW)
Inquire the plotting resolution of the current zone.
SGS_ICURW (IWKID)
Inquire workstation ID for the current zone.

Plotting lines

SGS_BPOLY (X, Y)
Begin a new polyline.
SGS_APOLY (X, Y)
Append a new line to the polyline.
SGS_OPOLY
Output the polyline.
SGS_IPLXY (X, Y)
Inquire end of current polyline.
SGS_LINE (X1, Y1, X2, Y2)
Begin a new polyline with a single line.
SGS_BOX (X1, X2, Y1, Y2)
Draw a rectangle.
SGS_CIRCL (X, Y, R)
Draw a circle.
SGS_ARC (X, Y, R, THETA1, THETA2)
Draw an arc of a circle.

Plotting text

SGS_BTEXT (X, Y)
Begin a new text string.
SGS_ATEXT (STRING)
Append text to the current string.
SGS_OTEXT
Output the text string.
SGS_ATXI (I, NFI)
Format an integer onto the current text string.
SGS_ATXR (R, NFI, NDP)
Format a real number onto the current text string.
SGS_ATXL (STRING)
Append text to the current text string omitting trailing blanks.
SGS_ATXB (STRING, NSPACE)
Append right justified field to the current text string.
SGS_TX (X, Y, STRING)
Begin a new text string with a string.
SGS_TXI (X, Y, I, NFI)
Begin a new text string with a formatted integer.
SGS_TXR (X, Y, R, NFI, NDP)
Begin a new text string with a formatted real number.
SGS_ITXB (X, Y, N, DX, DY)
Inquire status of current text string.

Plotting Markers

SGS_MARK (X, Y. MTYPE)
Draw a single marker.
SGS_MARKL (MTYPE)
Draw marker at current end of polyline.

Attributes of markers and characters

SGS_SHMK (HM)
Specify marker size.
SGS_SFONT (NF)
Select text font.
SGS_SPREC (NPR)
Specify text precision.
SGS_SHTX (HT)
Specify character height.
SGS_SARTX (AR)
Specify text aspect ratio.
SGS_SUPTX (XU,YU)
Specify character orientation.
SGS_SSPTX (SP)
Specify character spacing.
SGS_STXJ (TXJ)
Specify text alignment.
SGS_IMTX (HM, NF, NPR, HT, AR, XU, YU, SP, TXJ)
Inquire text attributes.

Input

SGS_CUVIS (VIS)
Set visibilty of cursor.
SGS_DEFCH (CHOSTR)
Define valid choice keys.
SGS_DISCU
Disable sample mode for cursor.
SGS_ENSCU
Enable sample node for cursor.
SGS_ICUAV (AVAIL)
Inquire cursor availability.
SGS_INCHO (NCHHDEV, N)
Inquire number of choices.
SGS_REGCH (N)
Request choice.
SGS_REQCU (X, Y, N)
Request cursor position.
SGS_SAMCU (X, Y)
Sample cursor position.
SGS_SELCH (NCHDEV)
Select choice device.
SGS_SETCU (X, Y)
Set cursor position.

2. CONTROL FUNCTIONS

2.1 Opening and closing SGS and GKS

Programs that are to perform graphics I/O via GKS must begin by calling a sequence of GKS routines, and must call a similar number to close down the system. These calls have been conveniently packaged in SGS:

      CALL SGS_OPEN(WKSTN, IZONID, ISTAT)
      ...
      CALL SGS_CLOSE

The call to SGS_OPEN is mandatory for any program that will subsequently use any of the SGS routines, and all such programs should call SGS_CLOSE when plotting is complete. The arguments of the OPEN call are as follows. WKSTN is a the workstation name, a character string specifying the required graphics workstation. IZONID receives from SGS the zone identifier, a number allocated by SGS which we may need later to refer back to this workstation. ISTAT is the status, which will be zero if the OPEN has succeeded.

Friendly workstation names (e.g. 'PLOTTER') can be given to GKS workstations, either by the user or by the VAX system manager, and then specified in the SGS_OPEN call. The mechanism which involves VAX logical names, is described in SGP/26; consult the manager of your VAX about local conventions. Alternatively, the two numbers which GKS needs - the workstation type (what sort of device) and the connection identifier (which one) - can be given directly, as a character string consisting of 2 numbers separated by a comma.

The workstation type is currently one of the following:

  1    Sigma ARGS
  2    Tektronix 4O1O
  3    Sigma T5671
  4    Tektronix 4O14
  5    Versatec
  6    HP 7221 plotter
  7    Printronix
  8    Sigma T5674
  9    Calcomp 81 plotter
 10    Site dependent
 11    Cifer 2634
 12    HP 2648A
 15    Sigma ARGS overlay planes
100    Metafile output
200    Metafile input
300    Segment storage

(SGS merely passes this number to GKS, so any workstation type acceptable to CKS will do - refer to the current SUN/11.)

Broadly speaking, the connection identifier specifies which of several workstations of the nominated type is to be opened. For all but the Versatec and Printronix, use 0. For those cases, the connection identifier is the Fortran unit to which the output will be sent for temporary storage on disc, prior to output to the graphics printing services. The commands to send the file to the Versatek and Printronix graphics queues are:

      PRINT/QUEUE=GAAO filename           [Versatek]
      PRINT/QUEUE=GABO filename         [Printronix]

As an example, we are working on a Tektronix 4010 terminal. The required call is:

      CALL SGS_OPEN('2,0', ITEK, ISTAT)

If, instead/ we wish to create a disc file suitable for plotting on the Versatec, we could use:

      CALL SGS_OPEN('5,9', IVERSA, ISTAT)

If the default assignment for Fortran unit 9 is used, then after the program has completed, a print command can be issued to send the graphics data to the Versatec:

      PRINT/QUEUE=GAAO FOR009.DAT 

The purpose of the zone identifier will become clearer later on, suffice it to say at this stage that this number (which is allocated by SGS and cannot be set or otherwise processed by the user's program) allows the program to refer back to the full display surface of the workstation that has been opened.

Should any error messages be output by the SGS or GKS routines, they will be sent to Fortran unit 22.

2.2 Multiple workstations

It is a central philosophy of SGS that only one workstation should be active at once. However, multiple workstations may be open at once, and plotting may switch between them.

Successive workstations may be opened with calls to the SGS routine OPNWK:

      CALL SGS_OPNWK(WKSm IZONID, ISTAT)

On each occasion that SGS_OPNWK is called, previously active workstations are deactivated before plotting switches to the new workstation. Thus, if the program is to plot first on a VDU then later on a plotter, it is best to open the plotter in the SGS_OPEN call and then to use SGS_OPNWK to open the VDU. Plotting on the latter can then begin.

Switching between multiple workstations is accomplished by the select zone routine which will be described in the next chapter.

If we want more flexible control - for example the ability to have several workstations active at once - this is available directly through the GKS activate/deactivate routines:

      CALL GKS_ACWK(IWKID)
      ...
      CALL GKS_DAWK(IWKID)

The GKS routine CLWK is available should selective close down of multiple workstations be required:

      CALL GKS_CLWK(IWKID)

A final call to SGS_CLOSE will always leave the system correctly terminated.

(N. B. Direct calling of GKS routines will reduce the usefulness of the ID returned bu. SGS_ICURW.)

2.3 Pens

It is sometimes necessary to distinguish between different parts of a graph. There are a variety of ways this might be achieved, depending on the characteristics of the particular graphics device concerned: for example by plotting in different colours, or by using dotted lines, or by varying the line width. Individual control over all of these options is possible within GKS; the SGS package offers instead a simplified facility where one of a small number of clearly distinguishable line qualities may be selected, each specified by an SGS pen number. The call is:

      CALL SGS_SPEN(NPEN)

where NPEN is the number of the SGS pen - an integer greater than or equal to 1.

SGS pen number 1 is the default, and is the normal pen for the device - a solid white line on a vdu, for example, or a black line of ordinary width on a plotter. SGS pens 1 to 4 may be assumed to be available and will correspond - depending on the device - to different colours or different styles of dashed line. Pen numbers greater than 4 may or may not be available depending on the device.

The last requested SGS pen number can be obtained by means of:

      CALL SGS_IPEN(NPEN)

Detailed control over line colour, etc, is available via GKS and it is permissible to use these facilities. A call to SGS_FLUSH (about to be described) should precede any such activities. Note that revisions 6.2 and 7.2 of GKS differ significantly in these areas.

2.4 Buffering

For efficiency, both SGS and GKS save up output in memory and send it to the graphics device in batches. Occasionally this may not be appropriate. For example an application program may plot a graph and then ask the user if the plot is satisfactory; it is clearly important that the whole plot must have been completed before user input is solicited. In such cases the call:

      CALL SGS_FLUSH

causes any pending output to be sent immediately (to all active workstations).

3. ZONES

An SGS zone is a block of display surface on a particular workstation, which behaves to some extent as if it were an independent plotting device.

A zone has an extent (in world coordinates), a position and size on the display surface (or, more correctly, in NDC) and a workstation. Clipping occurs at the zone boundary (unless disabled via GKS).

There are routines to create new zones and to switch plotting from the current one to another. When a zone is created it is allocated a zone identifier by SGS which is thereafter used by the program to refer to that zone. When a workstation is opened (in either SGS_OPEN or SGS_OPNWK), a base zone is created which occupies the whole display surface. This base zone has a world coordinate extent such that the square (0,0) to (1,1) fills it in at least one coordinate. A similar default coordinate system is set up whenever a zone is created.

One important use of the zone facility is to enable the allocation of plotting resources to be separated from the plotting itself. Thus the user might decide that the three graphs he is about to plot should, on one occasion, go to three regions of his VDU screen, and on another occasion to two regions of his screen and to a pen plotter respectively, by using zones the plotting program can operate as if the three plots were always on separate workstations, and switch freely between them during plotting. Activation and deactivation of workstations is handled automatically by SGS, as well as control of the various windows and viewports.

Another occasion on which SGS zones can be useful is when it is convenient to operate in several world coordinate systems within one graph. For example, a program might create one zone for plotting axes and annotation, and create one or more smaller zones within that zone for plotting data in world coordinates.

There is always a current zone, within which plotting occurs. Zones are created in terms of the current zone, with no restriction on the number of levels deep. Overlapping zones are permissible, but a new zone must lie entirely within the current one. There is a maximum number of zones that can exist at any one time, and a routine is available for dispensing with a zone once it is no longer required. There is no hierarchy of zones; once a zone has been created within the current zone and then made current, the parent zone can be released.

3.1 Zone creation

In all the create zone routines the new zone is selected, so that further plotting is to the new zone. The IZONID argument is the zone identifier supplied by SGS. ISTAT is the status return, which should be zero. The world coordinate system that the new zone is born with is such that (0,0) is at the bottom left hand corner, and (1,1) is on the top or right edge (or both). Thus the top right corner has one coordinate unity and the other unity or more.

A zone can be created within a nominated region of the current zone by means of:

      CALL SGS_ZONE (X1, X2, Y1, Y2, IZONID, ISTAT)

X1, X2, Y1, Y2 are the bounds of the new zone, in the world coordinate system of the current zone.

A zone of nominated shape can be fitted into the current zone as follows:

      CALL SGS_ZSHAP (AR, POS, IZQNID, ISTAT)

AR is the aspect ratio x/y. Thus a normal TV raster has an AR of about 1.3. The new zone has this aspect ratio, and fills the parent zone in at least one dimension. POS is a character string specifying the position of the new zone within the parent zone. The first character is 'B'* 'C' or 'T', to position the new zone at the bottom of the parent zone, centred vertically, or at the top. The second character is 'L', 'C' or 'R', for left, centre or right respectively.

For a zone of nominated absolute size:

      CALL SGS_ZSIZE (XM, YM, POS, IZONID, ISTAT)

XM, YM are the dimensions of the new zone in metres. POS is as for SGS_ZSHAP.

Once a zone has been created (by SGS_OPEN. SGS_OPNWK or one of the above routines), it can be given a suitable coordinate system as follows:

      CALL SGS_SW (X1,X2, Y1, Y2, ISTAT)

X1, X2, Y1, Y2 are the bounds of the current zone in the new world coordinate system.

3.2 Zone selection and release

To start plotting on a new zone:

      CALL SGS_SELZ(IZONID, ISTAT)

Plotting is suspended on the current zone and the new zone, specified by the zone identifier IZONID, is made the current one. Subsequent plotting goes to the new zone. The selection may imply a change of workstation, this is handled by SGS.

There is only a limited amount of workspace within SGS for storing zone attributes, and it is best to release a zone once it is no longer required:

      CALL SGS_RELZ (IZONID)

Attempts to release the current zone or the base zone for a workstation are simply ignored.

3.3 Inquiries

The zone identifier for the current zone is available via:

      CALL SGS_ICURZ (IZONID) 

To find out the size of the current zone:

      CALL SGS_IZONE (X1, X2, Y1, Y2, XM, YM)

X1, X2, Y1, Y2 are the world coordinate bounds. XM, YM are the dimensions in metres.

To optimise plotting efficiency it is sometimes necessary for a program to find out what the plotting resolution is. The inquiry:

      CALL SGS_IDUN (DXW, DYW)

returns the plotting resolution of the current zone, in world coordinates, in x and y separately.

The workstation identifier for the current zone may be required if GKS calls are to be employed. It is available by means of:

      CALL SGS_ICURW (IWKID)

4. PLOTTING LINES

4.1 Polylines

Many graphics packages have line drawing routines based on a current position concept. A single straight line is drawn either by calling first a set current position routine then calling a draw line from current position to new position routine, or by calling a general move routine twice with a pen up/down argument suitably set each time. The GKS line drawing primitive, on the other hand, does not use a current position but instead allows a series of connected straight lines, called a polyline, to be plotted as one item. The call is:

      CALL GKS_POLYL(LENGTH, XARRAY, YARRAY)

where LENGTH is the size of the 1-dimensional arrays XARRAY and YARRAY, which contain the X and Y coodinates of the vertices of the polyline, in world coordinates. Thus the following code would plot a 3:4:5 triangle:

      ..
      REAL XA(4), YA(4)
      ..
      DATA XA/0.0,3.0,0.0,0.0/
      DATA YA/0.0,0.0,4.0,0.0/
      ..
      CALL GKS_POLYL(4, XA, YA)
      ..

However, there are times when this method may be inconvenient and an approach based on drawing single lines is more appropriate. In these cases, the SGS routines BPOLY, APOLY and OPOLY may be preferred. The BPOLY routine is used to begin a polyline:

      CALL SGS_BPOLY(X,Y)

where X,Y are the starting coordinates for the polyline. The polyline is then built up by calls to APOLY, each of which appends a single line from the current end of the polyline to the new X,Y:

      CALL SGS_APOLY(X,Y)

Finally/ when the polyline is complete, it can be output using:

      CALL SGS_OPOLY

The triangle plotted in the example given earlier can be produced with the following code:

      CALL SGS_BPQLY(0.0, 0.0)
      CALL SGS_APOLY(3.0, 0.0) 
      CALL SGS_APOLY(0.0, 4.0)
      CALL SGS_APOLY(0.0. 0.0)
      CALL SGS_OPOLY

In most cases the call to OPOLY may be omitted; any polyline awaiting output is automatically plotted if a new polyline is begun (via BPOLY or LINE) or at various other critical places within SGS.

It is, however, good practice to issue OPOLY if there is any uncertainty. For example, at the end of a general purpose subroutine is a good place, as the subroutine might be called in a case where keyboard interaction occurs before any subsequent line-drawing takes place. Redundant calls to OPOLY cause no problems.

      SUBROUTINE CROSS(X1, X2, Y1, Y2) 
      REAL X1,X2,Y1,Y2
      CALL SGS_BPOLY(X1, Y1) 
      CALL SGS_APOLY(X2, Y2)
*  CAN OMIT CALL TO OPOLY HERE  * 
      CALL SGS_BPOLY(X1 Y2) 
      CALL SGS_APOLY(X2, Y1) 
      CALL SGS_OPOLY 
      END

At any time, the current end coordinates of the polyline being built can be obtained by:

      CALL SGS_IPLXY(X, Y)

(Only a limited amount of space is reserved for building the polyline; however, when this space is filled the polyline is automatically plotted and a new one begun starting from the last point given. Thus polylines of arbitrary length may be plotted via the SGS routines. Only if dotted lines are in use will the joins show. )

When the polyline to be drawn is merely a single line, it may be most convenient to use the SGS routine LINE, which opens a new polyline consisting of a single line:

      CALL SGS_LINE(X1, Y1, X2, Y2)

The polyline begins at (X1, Y1) and ends at (X2, Y2). Note that output of the polyline is not forced, so the LINE routine can be used to begin a polyline of any length.

Notes:

  1. All of the SGS calls which affect the coordinate transformation, change pen, etc, automatically arrange for any pending polyline to be plotted before the change occurs.
  2. Improperly begun polylines (where no call to BPOLY or to LINE has been made) are nevertheless plotted. The starting point is either the end of the previous polyline or - immediately upon opening or after calling one of the routines which affect the coordinate transformation - the first X, Y to be appended to the new polyline. This property of SGS should not be exploited.

4.2 Plotting rectangular boxes

Rectangular boxes, with sides parallel to the axes, can be plotted by means of the SGS routine BOX:

      CALL SGS_BOX(X1, X2, Y1, Y2) 

The arguments are the x and y extents of the box.

4.3 Plotting arcs and circles

The SGS package includes facilities for outputting both complete circles and arcs of circles:

      CALL SGS_CIRCL(X, Y, R)
      CALL SGS_ARC(X, Y, R,THETA1, THETA2)

The arc or circle is centred on X, Y and has radius R. The start and finish angles of the arc are THETA1 and THETA2 repectively, they are expressed in radians and have the conventional zero point and direction (e.g. an arc from 0 to PI/2 would begin at [X+R,Y] and end at [X, Y+R]).

5. PLOTTING TEXT

There are a number of SGS routines for creating and plotting strings of characters. The most general, low level routines will be described first, although in many instances it will be more convenient to use the higher level routines TX, TXI and TXR, which allow single strings and formatted numbers to be plotted and which will be described later.

A text string can be plotted by means of the SGS routines BTEXT, ATEXT and OTEXT. BTEXT begins a new string:

      CALL SGS_BTEXT(X,Y)

where X,Y is the position of the string (more about that shortly). ATEXT appends a new field onto the string:

      CALL SGS_ATEXT(STRING) 

and OTEXT outputs a completed string:

      CALL SGS_OTEXT

The call to OTEXT can usually be omitted; any existing string is output automatically when BTEXT or CLOSE are called (and and at various other critical places within SGS).

(n.b. The maximum length of string that can be plotted is set by an internal workspace. Unreasonably long strings will suffer truncation to this maximum.)

There are several very useful higher level append routines.

The SGS routine ATXL appends a field to the text string after stripping any trailing blanks; thus if:

      INITAL='S MCN ' 

the calls:

      CALL SGS_ATXL(INITAL) 
and
      CALL SGS_ATEXT(INITAL(:5))

produce identical results.

The SGS routine ATXB, in contrast, appends a right justified field to the text string, but replaces any leading blanks with a specified number of blanks. Thus, if:

      NUM='      -0.035'
the calls
      CALL_SGS_ATXB(NUM,1)
and
      CALL SGS_ATEXT(NUM(4:))

produce identical results.

Routines are provided for conveniently plotting numbers; ATXI formats and appends an integer, and ATXR does the same for a real.

Integers may be plotted by. means of:

      CALL SGS_ATXI(I,NFI)

where I is the number and NFI controls the formatting. If the number is to be left justified (for example within a message), an NFI value equal to the number of leading spaces should be specified. For example:

      CALL SGS_ATEXT('THERE WERE')
      CALL SGS_ATXI (25, 1 )
      CALL SGS_ATEXT(' SAMPLES')

would produce the string 'THERE WERE 25 SAMPLES'. If, on the other hand, right alignment is required (if a scale were to be marked on the left of a vertical axis, for example, an NFI value of minus the required field width should be specified.

Similarly, real numbers can be plotted with the SGS routine ATXR:

      CALL SGS_ATXR(R, NFI, NDP)

where R is the number and NFI is as for the ATXI routine. NDP is the number of decimal places to be plotted. -1 (or any other negative value) causes only the integer part of the number to appear; if 0 is specified the decimal point appears as well; positive values result in the specified number of decimal places being plotted.

(n.b. Both ATXI and ATXR are limited in the width of fields they can handler and only sensible values should be used.)

Details of the text string under construction can be inquired through the SGS routine ITXB:

      CALL SGS_ITXB (X. Y. N, DX, DY)

For the current zone, the ITXB routine returns the reference position (X,Y), the number of characters in the string (N) and the string extent (DX, DY). The string extent is such that if a new string is begun with reference position X+DX,Y+DY, it will append correctly to the current one, as long as the text attributes remain unchanged in between. The string extent works in this way if the default string alignment parameters are used (these are altered by SGS_STXJ - see below).

When the string to be output has already been formatted, or where a single number is to be plotted, it is convenient to use the SGS routines TX, TXI and TXR:

      CALL SGS_TX(X, Y, STRING) 
      CALL SGS_TXI(X,Y, I, NFI) 
      CALL SGS_TXR(X, Y, R, NFI, NDP)

In each case X,Y is the position of the string. STRING is the character string to be output, I and NFI are the integer to be formatted and the format indicator (exactly as for the ATXI routine); R, NFI and NDP are the real number to be formatted, the format indicator, and the number of decimal places (likewise exactly as for the ATXR routine).

These routines merely open a new text string and append the requested field to it; immediate output is not implied and more fields can be appended if desired.

Notes:

  1. All of the routines which affect the coordinate transformation automatically arrange for any pending text string to be output before the change occurs. The same applies to changes in the SGS pen selection.
  2. If a text string is improperly begun without a call (explicit or implicit) to BTEXT, nothing is ever plotted for that string.

6. TEXT ATTRIBUTES

The manner in which the text is plotted is controlled by a set of attributes, the most important of which are size, orientation and alignment. In addition, control over precision, font, aspect ratio and spacing is possible.

The size is specified by means of the SGS routine SHTX:

      CALL SGS_SHTX(HT)

The argument HT is the height of the character box, in world coordinates (for upright text reading left to right). n.b. If the plotting scale (i.e. world units per mm) is altered, by calling SW for example, the character height will stay the same in world units and hence will change in mm. So if a given character height in mm is to be maintained across changes of the world coordinate system it will be necessary to call SHTX after each such change.

The orientation is specified by means of the SGS routine SUPTX:

      CALL SGS_SUPTX(XU, YU)

where XU,YU is a vector specifying the up direction. The standard orientation is (0.0,1.0), for text on its side reading upwards an up vector of (-1.0,0.0) could be used, and so on. Only the vector, not its magnitude, is significant.

The disposition of the plotted string with respect to the reference x, y specified in the BTEXT call may be controlled using the SGS routine STXJ:

      CALL SGS_STXJ(TXJ)

TXJ is a character string of length 2. The first character of TXJ is B, C, or T, and specifies whether the reference position is to lie on the bottom, centre, or top horizontal of the string. The second character is L, C, or R, and specified whether the reference position is to lie on the left, centre, or right vertical of the string. Thus a TXJ of BL (the default) will cause all strings to be plotted with the given X,Y at the bottom left corner. If CC is specified, all strings will be plotted centred on the given positions. (Notes: (1) The STXJ routine may be called at any time before the string is actually plotted and applies to all strings from then on. (2) The directions bottom, left, etc., refer to the string seen in its standard orientation.)

The SGS routine SPREC allows the text precision to be specified:

      CALL SGS_SPREC(NPR) 

A precision value of NPR=2 (the default) indicates that no avoidable discrepancy between the characters as defined by the font and as they appear on the display device is tolerable; in effect, software generated characters will be plotted which look the same on all devices. A precision value of 0 allows the use of hardware characters, a compromise between speed and appearance (the latter depending to some extent on how much trouble the user program goes to in order to find out the true extent of plotted strings).

Different fonts may be selected by means of the SGS routine SFONT:

      CALL SGS_SFONT(NF)

where NF is the font number. The default font is ordinary letters and numbers.

Control of the aspect ratio of the character box is available via the SGS routine SARTX:

      CALL SGS_SARTX(AR)

AR is the aspect ratio (width/height).

The SGS routine SSPTX allows the spacing between characters to be changed:

      CALL SGS_SSPTX(SP)

SP is the distance between one character box and the next as a fraction of the width of the box.

The SGS routine IMTX allows all the above text attributes (as well as the marker height) to be inquired:

      CALL SGS_IMTX(HM, NF, NPR, HT, AR, XU, YU, SP, TXJ)

7. MARKERS

A set of centred symbols, called markers, is supported. The symbol to be plotted is selected via a number called the marker type; the following set of markers is currently available:

type     symbol
 1         .
 2         +
 3         *
 4        square or O shape
 5         x

To plot a single marker, use:

      CALL SGS_MARK(X, Y, MTYPE) 

where X and Y are now single values.

Markers may be plotted at intervals along a polyline by means of the SgS routine MARKL:

      CALL SGS_MARKL(MTYPE)

which plots the specified symbol at the current end of the polyline being built via APOLY. For example, the following code will plot a triangle with a star marker at corner A, an open symbol at corner B, and an X at corner C:

      CALL SGS_BPOLY(XA, YA) 
      CALL SGS_MARKL(3) 
      CALL SGS_APOLY(XB, YB) 
      CALL SGS_MARKL(4) 
      CALL SGS_APOLY(XC, YC) 
      CALL SGS MARKL(5) 
      CALL SGS_APOLY(XA, YA) 
      CALL SGS_OPOLY

The marker height can be specified by the call:

      CALL SGS_SHMK(HM)

where HM is the height (=width) of the symbol.

The current marker size HM (as well as all the text attributes) can be found via the SGS routine IMTX, which is described under text attributes.

8. INPUT

SGS provides two ways in which a program can interact with the person running it; a graphics cursor (locator in GKS terminology) which the user can move around the screen with for example a joystick or trackerball and whose position in world coordinates can be read by the program, and a choice device in which the user selects one of a number of alternatives usually by pressing, a button on a control box or a key on a keyboard. The most familiar form of interaction is where the cursor is displayed and the program waits for the user to move it to the desired position and press one of the choice keys. The cursor position (a position in world coordinates) and the choice selected (a positive integer) are then returned to the program.

This type of interaction is achieved by:

      CALL SGS_REQCU(X, Y, N)

If this routine is called repeatedly the cursor will reappear at the position that it was left at by the previous call. The cursor's position can be explicitly set by:

      CALL SGS_SETCU(X, Y)

provided that the hardware allows the position of the cursor to be controlled by the computer. Not all devices have cursors, eg. the Versatec, and so a program can find out if the workstation of the current SGS zone has a cursor (all SGS input routines operate on the currently selected SGS zone) with:

      CALL SGS_ICUAV(AVAIL)

where AVAIL is set to the logical value .TRUE, or .FALSE.. The cursor can also be used in a mode (sample mode) in which the cursor can be moved around by the user but the position is read by the program without waiting for the use to press a choice key. This mode of operation has to be explicitly enabled with:

      CALL SGS_ENSCU 

the cursor position can then be sampled with:

      CALL SGS_SAMCU(X, Y) 

typically in a loop. Sample mode is disabled with:

      CALL SGS_DISCU

It is sometimes desirable to use this mode without the cursor being visible, its position being indicated in some other way such as continuously drawing a line to the cursor position from its position when last sampled. In order to allow this the cursor can be made invisible by:

      CALL SGS_CUVIS(.FALSE.) 

and made visible again with:

      CALL SGS_CUVIS(.TRUE.)

The cursor will of course only actually appear if sample mode is enabled or when REGCU is called. Some hardware may not support the setting of the cursor visibility or the elegant operation of sample mode.

The choice device, which can be invoked either in conjunction with the cursor or on its own, can be one of two devices. By default it is a choice device associated with the graphics workstation such as the trackerball buttons on an ARGS or the numeric keys on a graphics terminal and is characterised by having a small number of choices (eg. only 4 on an ARGS). SGS provides an alternative device which is the keyboard of the terminal from which the program is being run. This has the advantage of being always available (except in a batch job!) and of having a much larger number of choices. However, since it is potentially a different device from the graphics device two separate read operations are required to get the choice and the cursor information and on a very busy system or over a network these operations may be separated by an appreciable length of time.

The choice device you wish to use is selected by:

      CALL SGS_SELCH(NCHDEV)

where NCHDEV is 1 for the normal GKS device and 2 for the command terminal keyboard. The number of choices on a choice device can be inquired with:

      CALL SGS_INCHO(NCHDEV, N)

If the choice device does not exist N will be returned as zero. The mapping of the keyboard keys onto the integers returned by SGS_REGCH is controlled by:

      CALL SGS_DEFCH(CHOSTR)

where CHOSTR is a character string specifying which keys are to be considered to be valid choices. If the first character in the string is pressed an integer 1 will be returned, if the second a 2 will be returned, and so on. If the key is not included in the string a zero will be returned. There is no restriction on which characters can be specified but upper and lower case characters are not distinguished and you are advised to only use the FORTRAN character set (A-Z 0-9 =+*'.(),.:$ and blank) as other characters cannot be guaranteed to be present on a terminal. For this reason, if the number of choices on device 2 is inquired 49 is returned.

A typical use of this facility might be a program which plots a star field and then asks the user to identify each object on the plot as either a star a galaxy or a plate defect by positioning the cursor on each object in turn and pressing the S G or D keys to indicate the nature of the object or the "." key to terminate the sequence. The interactive part of this program might be

*    Select terminal keyboard as choice device
      CALL SGS_SELCH(2)
*   Define valid keys
      CALL SGS_DEFCH('SGD. ') 
100   CALL REGCU(X, Y, N)
      GO TO (200,300,400,500) N
*  Not a valid choice (N is 0) try again 
      GO TO 100
*   A Star 
200   ...
      GO TO 100
*   A Galaxy 
300
      GO TO 100
*   A Defect 
400   ...
      GO TO 100
*  No more objects .. 
500   CONTINUE

It is a Starlink recommendation that you use the "." character to terminate a sequence of operations such as this.

9. LINKING AND RUNNING SGS

Your program can be linked using a logical name:

      LINK objmodule.@SGSLINK

which loads both SGS and GKS, or the linking can quote the SGS library explicitly, in which case GKS must be quoted too:

      LINK objmodule,LIBDIR: SGS/LIB,GKSOPT/OPT

There are no special requirements for running SGS other than those needed by GKS. The GKS workstation description table will be accessed automatically through the logical name GKSWDT. For full details see the latest version of SUN/11.

APPENDIX A: REFERENCE SECTION

The routines are described in alphabetical order.

* * * * * * * Append new line to POLYline * * * * * * *
SUBROUTINE SGS_APOLY (X, Y)
Description
A new line, whose end-point is (X,Y), is added to an existing buffered polyline. It is possible that a partial polyline mill be output automatically because of finite buffer space (which however will be large). SGS will, in this case, record that the polyline has to be continued but the join might not be perfect in the case of dotted and dashed line-styles.
Arguments (given)
REAL X,Y
The end point of the line.
GKS Effect
If the current polyline buffer becomes full, then the polyline so far is sent to GKS. The specified point is added to the polyline buffer.

* * * * * * * draw ARC of a circle * * * * * * *
SUBROUTINE SGS_ARC (X, Y, R, THETA1, THETA2)
Description
Draws an arc of a circle, centre (X,Y), radius R, starting at angle THETA1 and finishing at angle THETA2. Direction is anti-clockwise.
Arguments (given)
REAL X, Y
Centre of complete circle in world coordinates.
REAL R
Radius of complete circle in world coordinates.
REAL THETA1, THETA2
Start and finish angles of the arc in radians. Angle increases anti-clockwise and 0 is at (X+R,Y),
GKS Effect
Routine starts a new polyline (equivalent of BPOLY). Routine adds lines to the polyline, approximating the arc. Finally, the polyline is sent to GKS. The line length is chosen to correspond to the addressability of the finest active workstation (inquiry is made of GKS to determine this).

* * * * * * * Append a field to the TEXT buffer * * * * * * *
SUBROUTINE SGS_ATEXT (STRING)
Description
This routine appends to the SGS buffered text the entire specified CHARACTER expression (all spaces included). If the buffer would overflow, excess characters are lost.
Arguments (given)
CHARACTER*(*) STRING
Text string to be appended entirely.
GKS Effect
None.

* * * * * * * Append to TeXt with Blanks * * * * * * *
SUBROUTINE SGS_ATXB (STRING, NSPACE)
Description
This routine appends to the SGS buffered NSPACE spaces and secondly the specified text string, firstly CHARACTER expression with all its leading spaces removed. If the buffer would overflow, excess characters are lost.
Arguments (given)
CHARACTER*(*) STRING
Text string to be appended.
INTEGER NSPACE
The exact number of spaces that are to be put in front of the first non-space character appended to the buffer.
GKS Effect
None.

* * * * * * * Append to TeXt an Integer * * * * * * *
SUBROUTINE SGS_ATXI (I, NFI)
Description
Converts an integer to a character string, which is a field, using NFI as an indication of field width. resulting field to the SGS buffered string.
Arguments (given)
INTEGER I
Integer to be converted to characters.
INTEGER NFI
Indicates what is to be done with the integer. If NFI>=0, NFI spaces are appended to the SGS buffered string, followed by the characters representing the number. If NFI<0, the characters representing the number are put right-justified into a field which is minus NFI characters wide. If the field width is not sufficient, leading characters are lost.
GKS Effect
None.

* * * * * * * Append to TeXt Left justified * * * * * * *
SUBROUTINE SGS_ATXL (STRING)
Description
Appends to the SGS buffered string the specified CHARACTER expression with trailing spaces removed. If the buffer would overflow, excess characters are lost.
Arguments (given)
CHARACTER*(*) STRING
Text string to be appended.
GKS Effect
None.

* * * * * * * Append to TeXt A Real number * * * * * * *
SUBROUTINE SGS_ATXR (R, NFI, NDP)
Description
Converts a real number to a character string, using NDP to determine the number of decimal spaces. Places the string in a field, using NFI as an indication of field1 width. Appends the field to the SCS buffered string.
Arguments (given)
REAL R
Real number to be converted to characters.
INTEGER NFI
Similarly to routine ATXI, this parameter indicates how the converted real number is to be put in the field.
INTEGER NDP
Indicates the number of digits after the decimal point. If NDP>0, then NDP digits are included. If NDP<0, only the integer part appears. If NDP=0. only the integer part and the decimal point appears.
GKS Effect
None.

* * * * * * * Draw a BOX * * * * * * *
SUBROUTINE SGS_BOX (X1, X2, Y1, Y2)
Description
Draws a rectangular box with sides parallel to the axes.
Arguments (given)
REAL X1, X2, Y1, Y2
Extent of box in world coordinates
GKS Effect
A polyline is drawn (via SGS_BPOLY and SGS_APOLY).

* * * * * * * Begin POLYline * * * * * * *
SUBROUTINE SGS_BPOLY (X, Y)
Description
By a call to this routine, the programmer indicates that a new chain of lines (could be only one line) is to begin at the specified point. Further end points are added by SGS_APOLY. Any existing buffered polyline is output first.
Arguments (given)
REAL X, Y
Starting x and y coordinates for polyline.
GKS Effect
Any existing buffered polyline is output first by calling the GKS polyline routine. Then the starting position of the new polyline is saved.

* * * * * * * Begin a new TEXT string * * * * * * *
SUBROUTINE SGS_BTEXT (X, Y)
Description
Flushes the SSS buffered string if one exists and sets up a new one with zero characters. The reference point is recorded.
Arguments (given)
REAL X, Y
Reference point in world coordinates. This is used when the buffer is flushed.
GKS Effect
None.

* * * * * * * draw CIRCLe * * * * * * *
SUBROUTINE SGS_CIRCL (X, Y, R)
Description
Draws a complete circle, centre (X,Y), radius R.
Arguments (given)
REAL X, Y
Centre of circle in world coordinates.
REAL R
Radius of circle in world coordinates.
GKS Effect
Similar to ARC routine except that complete circle is drawn.

* * * * * * * CLOSE graphics * * * * * * *
SUBROUTINE SGS_CLOSE
Description
Puts out the SGS text, and polyline buffers. Closes SKS.
GKS Effect
All pending output dispatched (via SGS_FLUSH). All active workstations are deactivated. All open workstations are closed. SGS is closed.

* * * * * * * set CUrsor Visibility * * * * * * *
SUBROUTINE SGS_CUVIS (VIS)
Description
Sets the visibility of the cursor on the current SGS workstation.
Arguments (given)
LOGICAL VIS
The visibility of the cursor.
GKS Effect
The echo switch for locator device 1 is set.

* * * * * * * DEFine valid CHoice keys * * * * * * *
SUBROUTINE SGS_DEFCH (CHOSTR)
Description
This routine defines the valid keys for choice input from the command terminal keyboard (SGS choice device type 2).
Arguments (given)
CHARACTER CHOSTR
A character expression of up to 49 characters which defines the keys that are valid for choice input. The order of the characters determines the number returned when a key is pressed. The first key in the string will return 1, the second 2, etc. If a key which has not been defined is pressed a 0 is returned.
GKS Effect
None.

* * * * * * * Disable Sample CUrsor * * * * * * *
SUBROUTINE SGS_DISCU
Description
Sample mode is disabled for the cursor.
GKS Effect
Sample mode is disabled for locator device 1 on the current SGS workstation.

* * * * * * * ENable Sample CUrsor * * * * * * *
SUBROUTINE SGS_ENSCU
Description
Sample mode is enabled for the cursor.
GKS Effect
Sample mode is enabled for locator device 1 on the current SGS workstation.

* * * * * * * FLUSH buffers * * * * * * *
SUBROUTINE SGS_FLUSH
Description
Flushes all buffers.
GKS Effect
Flushes the SGS text and line buffers before calling SGS_UPDTE for all active workstations to flush the GKS buffers.

* * * * * * * Inquire CUrsor Availability * * * * * * *
SUBROUTINE SGS_ICUAV (AVAIL)
Description
AVAIL is set to TRUE if a cursor is available on the current SGS device and to FALSE otherwise.
Arguments (given)
LOGICAL AVAIL
The LOGICAL value .TRUE, or .FALSE., depending on the availability of a cursor.
GKS Effect
Inquires only.

* * * * * * * Inquire CURrent Workstation * * * * * * *
SUBROUTINE SGS_ICURW (IWKID)
Description
Returns workstation ID for current zone.
Arguments (returned)
INTEGER IWKID
The workstation ID for the SGS zone last selected.
GKS Effect
None.

* * * * * * * Inquire CURrent Zone * * * * * * *
SUBROUTINE SGS_ICURZ (IZONID)
Description
Returns ID of current SGS zone.
Arguments (returned)
INTEGER IZONID
Identifier of last selected SGS zone.
GKS Effect
None.

* * * * * * * Inquire Device UNits * * * * * * *
SUBROUTINE SGS_IDUN (DXW,DYW)
Description
The purpose is to obtain the length of device units in each of x and y for the current SGS zone.
Arguments (returned)
REAL DXW, DYW
Size of a raster unit in world coordinates in each of the x and y directions.
GKS Effect
Only inquiries are made of GKS.

* * * * * * * Inquire Marker and TeXt attributes * * * * * * *
SUBROUTINE SGS_IMTX (HM, NF, NPR, HT, AR, XU, YU, SP, TXJ)
Description
Returns the values of all the SGS marker and text attributes.
Arguments (returned)
REAL HM
Marker height
INTEGER NF, NPR
Font number and text precision.
REAL HT, AR, XU, YU, SP
Character height, aspect ratio, text orientation direction cosines (XU and YU) and text spacing.
CHARACTER*2 TXJ
Text alignment coding
GKS Effect
None.

* * * * * * * Inquire Number of CHOices * * * * * * *
SUBROUTINE SGS_INCHO (NCHHDEV, N)
Description
This routine allows the number of choices available on the currently selected workstation to be inquired.
Arguments (given)
INTEGER NCHOIC
The SGS choice device number. 1 is the GKS choice device number 1, 2 is the command terminal.
Arguments (returned)
The number of choices available on the selected device. If no such device exists, zero will be returned.
INTEGER N
GKS Effect
Inquires only.

* * * * * * * Inquire Pen Number * * * * * * *
SUBROUTINE SGS_IPEN (NPEN)
Description
Returns current SGS pen number.
Arguments (returned)
INTEGER NPEN
The current SGS pen number as presented via SGS_SPEN.
GKS Effect
None.

* * * * * * * Inquire PolyLine X and Y * * * * * * *
SUBROUTINE SGS_IPLXY (X, Y)
Description
The routine returns the coordinates of the last line added to the polyline buffer if there is one.
Arguments (returned)
REAL X,Y
X and Y of the last line added to the polyline buffer, if there is such a line. If not, X and Y are unchanged.
GKS Effect
None.

* * * * * * * Inquire TeXt Buffer * * * * * * *
SUBROUTINE SGS_ITXB (X, Y, N, DX, DY)
Description
Returns state of SGS buffered string.
Arguments (returned)
REAL X, Y
Reference position of SGS buffered string.
INTEGER N
Number of characters in buffered string.
REAL DX, DY
The extent of the current buffered string (expressed as a displacement from its starting point).
GKS Effect
Inquiry is made of GKS to determine the extent.

* * * * * * * Inquire ZONE attributes * * * * * * *
SUBROUTINE SGS_IZONE (X1, X2, Y1, Y2, XM, YM)
Description
Returns bounds and size of current SGS zone.
Arguments (returned)
REAL X1, X2, Y1, Y2
Bounds of current zone.
REAL XM, YM
Size of zone in metres.
GKS Effect
The workstation transformation for the workstation of the current SGS zone is inquired via GKS_IWKT.

* * * * * * * begin polyline with single LINE * * * * * * *
SUBROUTINE SGS_LINE (X1, Y1, X2, Y2)
Description
This routine starts a new polyline with the specified line. If subsequent lines are added, the first 2 points will be (XI,YI and (X2,Y2)
Arguments (given)
REAL X1, Y1
Coordinates of the first point on the polyline.
REAL X2, Y2
End point of the line.
GKS Effect
The effect is the same as CALL SGS_BPOLY(X1,Y1) followed by CALL SGS_APOLY (X2.Y2).

* * * * * * * draw MARKer * * * * * * *
SUBROUTINE SGS_MARK (X, Y. MTYPE)
Description
A single marker is drawn, centred on the given position (X,Y).
Arguments (given)
REAL X. Y
Coordinates of the marker.
INTEGER MTYPE
Marker type. The correspondence between marker types and marker shapes is shown in the chapter on markers.
GKS Effect
A marker is output using the GKS polymarker routine GKS_POLYM. No SGS buffers are affected.

* * * * * * * draw MARKer at end of polyLine * * * * * * *
SUBROUTINE SGS_MARKL (MTYPE)
Description
If there is an SGS buffered polyline, it is output, a marker is output at its end position and a new buffered polyline is begun.
Arguments (given)
INTEGER MTYPE
Marker type. The correspondence between marker types and marker shapes is shown in the chapter on markers.
GKS Effect
Current buffered polyline is output via GKS: a marker is output at the end position using the GKS polymarker routine GKS_POLYM: a new SGS buffered polyline is begun.

* * * * * * * OPEN graphics * * * * * * *
SUBROUTINE SGS_OPEN (WKSTN, IZONID, ISTAT)
Description
This routine is intended to be used at the beginning of graphics and performs all GKS calls necessary to get the specified workstation open and active. It also sets defaults for various attributes and should therefore be used if other SGS routines are called.
Arguments (given)
CHARACTER*(*) WKSTN
Workstation name: a character string which translates ultimately into GKS workstation sequence number and connection identifier. See SGP/26 for full details of formats supported; simplest is the two numbers as decimals separated by a comma.
Arguments (returned)
INTEGER IZONID
Zone identifier for the base SGS zone on this workstation - a number allocated by SGS.
INTEGER ISTAT
If workstation is opened OK, then this value is zero.
GKS Effect
If GKS is already open, it is first closed. The routine then opens GKS. It opens the specified workstation and activates it. Maximum deferral is requested. An SGS zone filling the display surface is set up.

* * * * * * * OPeN WorKstation * * * * * * *
SUBROUTINE SGS_OPNWK (WKSTN, IZONID, ISTAT)
Description
This routine opens an additional workstation, and sets up the base SGS zone, which is then selected.
Arguments (given)
CHARACTER*(*) WKSTN
Workstation type/connection identifier pair (see SGS_OPEN).
Arguments (returned)
INTEGER IZONID
Zone identifier - number allocated by SGS.
INTEGER ISTAT
If workstation is opened OK, then this value is 0.
GKS Effect
The specified workstation is opened. The workstation viewport is set to cover the full display surface; the the base zone is set up and is then selected via SGS_SELZ. A text table is set up with an entry for each supported combination of GKS font and precision.

* * * * * * * Output buffered POLYline * * * * * * *
SUBROUTINE SGS_OPOLY
Description
Outputs buffered polyline. SGS_OPQLY is automatically invoked, at appropriate times, by other routines and only rarely requires calling directly.
GKS Effect
The buffered polyline is sent to GKS.

* * * * * * * Output buffered TEXT * * * * * * *
SUBROUTINE SGS_OTEXT
Description
This routine outputs existing SGS buffered text. The point stored by SGS_BTEXT is used as the reference point. Current text attributes are used, including the SGS text alignment. SGS_OTEXT is automatically invoked, at appropriate times, by other routines and rarely needs to be called directly.
GKS Effect
GKS inquiries are used to determine the string extent/ for the workstation of the current SGS zone: in early versions, this may be idealised and may ignore the approximations due to hardware text. Using the reference point and the text alignment, a starting point is calculated. The text string is then delivered to GKS as an INTEGER array.

* * * * * * * RELease Zone * * * * * * *
SUBROUTINE SGS_RELZ (IZONID)
Description
The specified SGS zone is offered for release.
Arguments (given)
INTEGER IZONID
The identifier for the SGS zone which the program no longer requires.
GKS Effect
None.

* * * * * * * A * * * * * * *
SUBROUTINE SGS_REGCH (N)
Description
This routine waits for the user to press a key on the current SGS choice device and returns the number of the key selected. When choice device 2 is being used the number is the position in the define keys string passed to DEFCHO. If the key is not included in the string 0 is returned.
Arguments (returned)
INTEGER N
The number of the key pressed.
GKS Effect
All buffered output is plotted and for device 1 GKS REQUEST CHOICE is called.

* * * * * * * REQuest CUrsor position * * * * * * *
SUBROUTINE SGS_REQCU (X, Y, N)
Description
The system waits for the user to press a key on the current SGS choice device and then returns the position of the cursor and the number of the choice key.
Arguments (returned)
REAL X, Y
The cursor position in world coordinates.
INTEGER N
The number of the key pressed.
GKS Effect
None.

* * * * * * * SAMple CUrsor * * * * * * *
SUBROUTINE SGS_SAMCU (X, Y)
Description
The cursor position is returned without waiting for the user to press any key.
Arguments (returned)
REAL X, Y
The cursor position in world coordinates.
GKS Effect
All output buffers are plotted and locator device 1 is sampled on the current SGS workstation.

* * * * * * * Set Aspect Ratio of TeXt * * * * * * *
SUBROUTINE SGS_SARTX (AR)
Description
Sets aspect ratio of text. A usual figure is between 1/1.3 and 1/1.5. Default is 2/3.
Arguments (given)
REAL AR
Aspect ratio.
GKS Effect
Outputs any SGS buffered text, sets SGS aspect ratio and resets all GKS text attributes to follow current SGS settings.

* * * * * * * SELect CHoice device * * * * * * *
SUBROUTINE SGS_SELCH (NCHDEV)
Description
This routine selects the current SGS choice device.
Arguments (given)
INTEGER NCHDEV
The SGS choice device to be used for subsequent input. 1 is the GKS choice device number 1, 2 is the command terminal.
GKS Effect
None.

* * * * * * * SELect Zone * * * * * * *
SUBROUTINE SGS_SELZ(IZONID, ISTAT)
Description
The nominated SGS zone is selected.
Arguments (given)
INTEGER IZONID
The zone identifier supplied by SGS when the zone was set up.
INTEGER ISTAT
If the zone is selected successfully, then this value is 0.
GKS Effect
If the new zone is on a different workstation from the current zone, the current workstation is deactivated and the new one activated. The new window/viewport is set up.

* * * * * * * SET CUrsor position * * * * * * *
SUBROUTINE SGS_SETCU (X, Y)
Description
Sets the cursor to the specified position provided that the hardware is capable of this. If the cursor is not visible it will appear at the requested position when it next becomes visible. If the requested position is outside the workstation window no action is taken.
Arguments (given)
REAL X, Y
The desired cursor position in world coordinates.
GKS Effect
Set Locator called.

* * * * * * * Set FONT of text * * * * * * *
SUBROUTINE SGS_SFONT (NF)
Description
Sets font number.
Arguments (given)
INTEGER NF
Font number. Currently this is normally 1 and the default is 1. Font 4 (a Greek font) is available at precision 2.
GKS Effect
Outputs any SGS buffered text, sets SGS font number and selects the GKS text number most appropriate to the SGS text font and precision.

* * * * * * * Set Height of MarKers * * * * * * *
SUBROUTINE SGS_SHMK (HM)
Description
Sets marker height. Default is 0.02.
Arguments (given)
REAL HM
Marker height in world coordinates. Note that if the coordinate system changes, the displayed size will alter. The program would then have to supply a new value if the display size is to remain the same.
GKS Effect
Sets SGS marker height and sets GKS marker size accordingly. Visual effect depends in hardware and the device-dependent software and actual marker size might not be changeable.

* * * * * * * Set Height of TeXt * * * * * * *
SUBROUTINE SGS_SHTX (HT)
Description
Sets character height. Default is 0.02.
Arguments (given)
REAL HT
Character height in world coordinates. (If the coordinate system changes, then the displayed size will alter. The program would then have to supply a new value to maintain the same display size).
GKS Effect
Outputs any SGS buffered text, sets SGS character height and sets GKS text attributes from SGS settings.

* * * * * * * Select PEN * * * * * * *
SUBROUTINE SGS_SPEN (NPEN)
Description
Selects SGS pen. Any polyline or text string is flushed first. The initial pen is number 1.
Arguments (given)
INTEGER NPEN
Required SGS pen number.
GKS Effect
The GKS pen number is set to the SGS pen number given. All available workstation are assumed to support at least 4 predefined pens, giving readily distinguishable lines.

* * * * * * * Set PRECision of text * * * * * * *
SUBROUTINE SGS_SPREC (NPR)
Description
Sets text precision. This indicates the fidelity with which the text attributes are followed by GKS. Precision 2 (the S6S default) is the most accurate and is normally achieved by a software font. The GKS text number most appropriate to the SGS text font and precision is selected.
Arguments (given)
INTEGER NPR
Text precision.
GKS Effect
Outputs any SGS buffered text. Sets SGS precision number. On all open workstations, sets text representation accordingly.

* * * * * * * Set SPacing of TeXt * * * * * * *
SUBROUTINE SGS_SSPTX (SP)
Description
Sets text spacing. Default is 0.29.
Arguments (given)
REAL SP
Spacing between the end of one character and the start of the next. Spacing in SGS is expressed as a fraction of the width of the character box.
GKS Effect
Outputs any SGS buffered text. Sets SGS spacing value (note that the spacing value is different from GKS 6.2). Sets GKS text attributes from the SGS settings.

* * * * * * * Set TeXt Justification * * * * * * *
SUBROUTINE SGS_STXJ (TXJ)
Description
This routine sets the alignment options that are subsequently used by SGS_DTEXT and by implicit and explicit flushes of the SGS text buffer.
Arguments (given)
CHARACTER*2 TXJ
A 2 letter option string. The 1st letter is the vertical alignment: B(OTTOM), C(ENTRE) or T(OP). The 2nd is the horizontal alignment: L(EFT), C(ENTRE) or R(IGHT). In either case, space implies no change. The default is 'BL'. The alignment refers, to where in the character string the nominated X, Y lies; thus a code of 'BL' would place the nominated X,Y at the bottom left of the string. The terms 'top', 'left' etc refer to the character string as seen in its normal orientation, rather than as actually displaced.
GKS Effect
Outputs SGS buffered text. Causes the SGS text routines to make inquiries of GKS in order to calculate a revised starting position for text output.

* * * * * * * Set UP vector of TeXtA * * * * * * *
SUBROUTINE SGS_SUPTX (XU,YU)
Description
Specifies character orientation in terms of a- vector. Default is (0.0,1.0)
Arguments (given)
REAL XU, YU
(XU,YU) is a vector specifying the up direction of subsequent text. This is the direction of the vertical axis of each character. The standard orientation would be (0,1). Only the direction of the vector, not its magnitude is significant.
GKS Effect
Outputs any SGS buffered text. Sets SGS orientation vector. Sets GKS text attributes from SGS settings.

* * * * * * * Set Window * * * * * * *
SUBROUTINE SGS_SW (X1, X2, Y1, Y2, ISTAT)
Description
Routine sets the bounds of plotting in world coordinates.
Arguments (given)
REAL X1, X2
Left and right bounds respectively in X.
REAL Y1, Y2
Bottom and top bounds respectively in Y.
INTEGER ISTAT
Status
GKS Effect
Sets the window bounds according to the parameters provided. Note that the arguments are in a different order to those in the GKS 6.2 Set Window routine. This is because SGS refers to the bounds (or limits) in each axis, in here GKS 6.2 refers to the corner points. GKS 7.0 uses bounds so the SGS concept will be more compatible with subsequent implementations of GKS.

* * * * * * * begin a new TeXt string with a string * * * * * * *
SUBROUTINE SGS_TX (X, Y, STRING)
Description
Starts a new SGS buffered text string with the specified text.
Arguments (given)
REAL X, Y
Reference point for new SGS buffered string.
CHARACTER*(*) STRING
Text string to be put into emptied text buffer.
GKS Effect
A new SCS buffered string is begun: equivalent to SGS_BTEXT(X,Y); the specified string is appended to it: equivalent to SGS_ATEXT(STRING).

* * * * * * * begin new TeXt with Integer * * * * * * *
SUBROUTINE SGS_TXI (X, Y, I, NFI)
Description
Starts a new SGS buffered text string with text derived from the specified integer.
Arguments (given)
REAL X, Y
Reference point of new SGS buffered string.
INTEGER I
Integer to be converted to characters.
INTEGER NFI
Indication of field width: similar to SGS_ATXI.
GKS Effect
A new SCS buffered string is begun: equivalent to SGS_BPOLY(X, Y). The converted integer is appended to it: equivalent to SGS_ATXI(I,NFI).

* * * * * * * begin new TeXt with Real * * * * * * *
SUBROUTINE SGS_TXR (X, Y, R, NFI, NDP)
Description
Starts a new SCS buffered string with text derived from the specified real number.
Arguments (given)
REAL X, Y
Reference point of new SGS buffered string.
REAL R
Real number to be converted to characters.
INTEGER NFI, NDP
Conversion parameters, similar to SGS_ATXR.
GKS Effect
A new SGS buffered string is begun: equivalent to SGS_APOLY(X, Y). The converted real number is appended: equivalent to SGS_ATXR(R,NFI,NDP)

* * * * * * * Create a ZONE * * * * * * *
SUBROUTINE SGS_ZONE (X1, X2, Y1, Y2, IZONID, ISTAT)
Description
A new SGS zone is created, occupying the given bounds within the world coordinate system of the current zone. It is then selected.
Arguments (given)
REAL X1, X2, Y1, Y2
The extent of the new zone in the world coordinates of the old zone.
Arguments (returned)
INTEGER IZONID
The zone identifier for the new zone - supplied by SGS.
INTEGER ISTAT
Status.
GKS Effect
A new GKS window/viewport is set up.

* * * * * * * Create a Zone of given SHAPe * * * * * * *
SUBROUTINE SGS_ZSHAP (AR, POS, IZONID, ISTAT)
Description
An SGS zone of the specified shape (aspect ratio) is created within the current zone and is then selected.
Arguments (given)
REAL XM, YM
The absolute size of the new zone in metres.
CHARACTER*2 POS
As for SGS_ZSHAP.
Arguments (returned)
INTEGER IZONID
The zone identifier for the new zone - supplied by SGS.
INTEGER ISTAT
Status.
GKS Effect
A new GKS window/viewport is set up.

* * * * * * * Create a Zone of given SIZe * * * * * * *
SUBROUTINE SGS_ZSIZE (XM, YM, POS, IZONID, ISTAT)
Description
An SCS zone of the specified absolute size is created within the current zone and is then selected.
Arguments (given)
GKS Effect
A new GKS window/viewport is set up.

APPENDIX B: COORDINATE SYSTEMS IN SGS AND GKS

In the discussion that follows, (i) all the coordinate systems mentioned will be 2-D and rectangular, (il) official GKS terms mill be given in capitals when they are being defined, and (iii) only rather ordinary cases are described. It should be read in conjunction with the diagram below.

The WORKSTATION is the complete graphics station, consisting of at least a display device and perhaps some input devices as well. An example of a workstation is a VDU with keyboard and joystick; the VDU is the display device in this case. The region of a display device on which images can be displayed is called the DISPLAY SURFACE; for the example of the VDU the display surface is the addressable area of the screen.

Moving now to the other end of the user-workstation chain, WORLD COORDINATES are those in which the user (i. e. the programmer) wishes to work. The units may be natural for the information being plotted (seconds of right ascension and arc seconds of declination for example) but equally often will simply be convenient units for planning the picture.

The window is mapped onto the display surface by means of a sequence of two independently controllable transformations. Each of the two transformations proceeds from a 'window' to a 'viewport'.

The first transformation, called the NORMALISATION TRANSFORMATION, starts with user's region of interest in world coordinates which is called simply the WINDOW. This maps onto an intermediate system, called NORMALISED DEVICE COORDINATES (NDC); the NDC space consists of a square region whose bottom left and top right corners are respectively (0,0) and (1,1). The region within NDC space onto which the world coordinate window maps is called the VIEWPORT.

The second transformation is called the WORKSTATION TRANSFORMATION. For each workstation, there is a region in NDC space called the WORKSTATION WINDOW, and this maps onto part or all of a region of the display surface called the WORKSTATION VIEWPORT.

The NDC space is an idealised model of the different plotting devices; in particular, the things plotted in NDC space appear on the various devices without change of shape - a circle in NDC space will appear circular on all display devices, for example. Because of this conservation of aspect ratio, the workstation window may not map onto the whole of the workstation viewport, although this will commonly be contrived.

The normalisation transformation allows the window to be positioned on the display surface without needing to refer to any device units, and the workstation transformation allows different workstations to be treated separately.

At any time there can be only one window, NDC space and viewport, but there may be multiple display devices, each with its own workstation window and workstation viewport.

GKS Coordinate Systems

GKS Coordinate Systems
Full Size Image

APPENDIX C: SGS EXAMPLE

This appendix consists of a complete program using SGS. This and another (longer) program are available on disc in the files LIBDIR:SGSX1.FOR and SGSX2.FOR.

      PROGRAM SGSX1
*     --------------
*      S G S X 1
*     --------------
*   USES SGS PACKAGE TO DRAW BOX WITH 'STARLINK' WRITTEN IN IT

      CHARACTER*20 WKSTN
*  GET WORKSTATION TYPE AND NUMBER 
      PRINT *, 'WORKSTATION?' 
      READ (*, '(A)') WKSTN
*  OPEN
      CALL SGS_OPEN(WKSTN,IZONID, J)
*  DECLARE A SQUARE ZONE
      CALL SGS_ZSHAP(1.0,'O',IZ,J)
*  BOX
      CALL SGS_BOX(0.1, 0.9, 0.4, 0.6)
*  MESSAGE
      CALL SGS_SHTX(0.1) 
      CALL SGS_STXJ('CC') 
      CALL SGS_BTEXT(0.5, 0.5) 
      CALL SGS_ATEXT (' STARLINK')
*  WRAP UP
      CALL SGS_CLOSE
END