GKS and GKS-3D Primer

Version April 1990

ASD Group -- Program Library Section

Computing and Networks Division

CERN Geneva, Switzerland

Preface

This primer introduces the graphics concepts which should be understood in order to write a simple GKS program. It is not supposed to be a complete text book on GKS, many of which exist already, and deliberately omits some of the more abstruse details. For a complete treatment of the subject the reader is referred to the GKS ISO Standard, or one of the texts listed in the bibliography. For details about a particular implementation, such as a list of available text fonts, etc., the appropriate Reference Manual must be consulted. A separate guide is available to describe the graphics facilities available at CERN.

The document in its present form has been put together by D.R. Myers, with much help from I. Mclaren, J. Moebes, and I. Seis. Thanks are also due to a group of 'volunteers' who proof-read various draft versions. It is based on a short introduction to GKS by J. Bettels and J. Tweed which was included in a previous DD manual. The source text was marked-up in SGML, and the figures were inserted directly from a GKS metafile.

What is GKS

The Graphical Kernel System (GKS) is a document produced by the International Standards Organization (ISO) which defines a common interface to interactive computer graphics for application programs. GKS has been designed by a group of experts representing the national standards institutions of most major industrialized countries. The full standard provides functional specifications for some 200 subroutines which perform graphics input and output in a device independent way. Application programs can thus move freely between different graphics devices and different host computers. For the first time graphics programs have become genuinely portable.

However, one should point out that GKS itself is not portable. Individual GKS implementations will vary substantially as they have to support different graphics devices on different computers. Moreover, GKS is a kernel system, and thus does not include an arbitrary collection of functions to produce histograms or contour plots, etc. Such facilities are regarded as applications which sit on top of the basic graphics package and, at CERN, they are provided by the Graphical Extensions to the NAG Library, or the HPLOT package.

In order to allow particular applications to choose a graphics package with the appropriate capability, GKS has been defined to have different levels. The level structure has two dimensions, one for output (0, 1, or 2) and one for input (a, b, or c). Higher levels include the capabilities of lower levels. In the United States, ANSI has defined also a level 'm', for very simple applications, which sits below output level '0'. Most implementations provide all output (level '2') and intermediate input (level 'b'). The reason input level 'c' is not usually supported is that it requires asynchronous input facilities not found in all operating systems.

The GKS functions have been defined independently from a specific programming language, and bindings to individual languages are subject to separate standards efforts which have been undertaken for all the major languages. See for the FORTRAN binding.

The Graphical Kernel System for two dimensional graphics was adopted as an ISO standard in 1985, and since that date work has been in progress to define a three dimensional super-set which was accepted as an International Standard during 1988. The FORTRAN binding to GKS-3D has also been published as a Draft International Standard.

The GKS functions are separated into those which pass values to GKS for control, setting or output, and those which inquire about status information. There are 8 distinct classes:

1. Control functions         5. Transformations
2. Output Attributes         6. Input functions
3. Output Primitives         7. Metafile functions
4. Segment functions         8. Inquiry functions

Throughout this document many values are specified using GKS Enumerated Types. The symbolic names for these all begin with 'G' and are enclosed in single quotes within the text. (But do not include the quotes in FORTRAN calls!) They have been coded into an Include File, called ENUM.INC, which is listed in Appendix .

Major Differences to Earlier Graphics Interfaces

In some respects GKS is a major departure from earlier software interfaces to graphics display systems, and several new concepts have been introduced. The following is a brief list of the new features, which will be more fully described within the body of the document.

GKS has no concept of a current point. This idea dates from when most graphics devices were pen plotters, in which case the current point corresponded clearly to the position of the pen. However, it would be less obvious where one would define the current point when drawing a filled polygon on a raster display. Thus, all GKS primitives which require a starting point specify that point in the function call.
In most cases earlier software interfaces could only control a single device at a time, and if some means was provided to 'capture' the graphics output for storage, then this was handled in a special way. GKS simplifies this situation considerably by defining Workstations, which correspond to 'virtual devices'. GKS maps each workstation onto a real piece of hardware, but to the application programmer they are all handled in the same way, and several workstations can be active simultaneously. There is a workstation which writes the output it receives onto a Metafile for storage and/or transmission over a network and this, also, is handled just like any other workstation.
GKS incorporates the concept of a Logical Device to control input. There are six classes of Logical Input Devices, and these are mapped onto the actual physical devices in use, without the application programmer having to write special code if, for example, (s)he is using a mouse instead of a tablet. This helps to make application code much more portable. The following logical devices are of particular interest:
1. The Logical Locator Device, which returns the locator position in the user's coordinate system, not that of the physical device.
2. The Logical Pick Device, which tells the application at which object the user is pointing, without having to provide the code to work it out.
3. The Logical Choice Device, which allows the user to choose one option out of a set.
GKS provides a mechanism to group the graphics output commands into Segments, where they may be stored for later use. Thus, an image stored in a segment could be made invisible and then visible again without the application having to re-draw it. Information sent to a workstation to produce an image which is not stored is called non-retained data.
Finally, GKS provides a whole host of functions allowing the application to inquire at run-time the state and/or capabilities of a workstation or the implementation of GKS itself. This is a very important feature for allowing code to be written in a portable way, and still to make the best possible use of the environment in which it is running.

Workstations

workstation

Definition

GKS defines the concept of an abstract graphical workstation which provide the logical interface through which the application program controls the physical devices. A workstation can have one display surface and/or a collection of logical input devices. Thus, a particular interactive workstation may belong to one of three classes: Output-Only, Input-Only, or Input-Output. (There are a further two classes of workstation: Metafile-Input and Metafile-Output.) GKS allows several workstations to be open simultaneously, for example, one for an interactive graphics terminal and one for a metafile or hardcopy device. The actual maximum number of simultaneously open workstations is installation dependent; in the GTS-GRAL implementation it is set to 15.

GKS allows the appearance of output primitives to vary between workstations in order to take advantage of their differing capabilities. However, it is possible to inquire at run-time what the actual capabilities are, and to design one's code appropriately. The inquiry functions are too numerous to list in this Primer, and the reader is referred to one of the texts in the bibliography.

Opening and Closing GKS

Before any workstation is opened or activated, GKS itself must be opened. This must be the first call in any GKS program as it performs the initialization. The last call should be to close (exit from) GKS.

CALL GOPKS(ERRFIL, BUF) ....... CALL GCLKS ERRFIL defines the FORTRAN logical unit number to which all error messages will be sent. BUF is the amount of memory space to be used. (This parameter is ignored by the GKSGRAL and GKSGRAL-3D implementations.)

Opening and Closing a Workstation

Each workstation is identified in the application program by a unique number, the workstation identifier. This number is used in routines which communicate with the device, i.e. when output is to be sent to it, or when it is to be cleared, etc. In order to establish a connection between the application program and a workstation, the workstation has to be opened. When the workstation is closed, the connection is released, segments stored in Workstation Dependent Segment Storage are lost, and no further interactions are possible. The calls to open and close a workstation are:

CALL GOPWK(WKID, CONID, WTYPE) and CALL GCLWK(WKID)

The workstation identifier WKID is a positive integer which the application chooses, and is typically a number like 1,2,3... The integer CONID is the Connection Identifier which connects the workstation to an I/O channel. It is usually a FORTRAN logical unit number, but depends on the workstation and the host computer being used. Thus, the value of conid must be obtained from the workstation-dependent documentation.

The Workstation Type (WTYPE) is an integer which specifies which type of workstation should be opened, e.g. a Tektronix 4014 or a Versatec plotter. Workstation Types are implementation dependent. See GKSGKS-3D at CERN for a list of workstation identifiers in use at CERN.

Activating and Deactivating a Workstation

When primitives and attributes are output they are sent to all open and active workstations. When a workstation is deactivated no further output is sent to it. At the end of the application program all open workstations must be deactivated and closed before GKS itself can be closed. To activate or deactivate the workstation the calls are:

CALL GACWK(WKID) CALL GDAWK(WKID) Note that Input-Only and Metafile-Input workstations may not be activated.

Clearing the Workstation

The application has control over clearing the display surface at any time by calling:

CALL GCLRWK(WKID, COFL) The integer COFL controls the way in which the update happens. If COFL is set to 'GALWAY' (see note at bottom of page 1), then the workstation is cleared even if there was no previous output. If COFL is set to 'GCONDI', then the drawing surface is cleared only if there has been previous output. Clearing the workstation deletes all WDSS segments stored on that workstation (segments are described in Chapter ), and on a hardcopy device the paper is advanced. For metafile interpretation by the CERN utilities this function is used to indicate 'end of picture'.

Note that the workstation is cleared automatically when it is opened. Some implementations also clear the workstation when it is closed, but this is not mandated in the standard.

Deferral States

GKS allows the programmer to defer sending output to a workstation by calling the function Set Deferral State. For example, it might be more efficient to send primitives in batches, rather than one at a time. Thus, 'As Soon As Possible' often may not be as fast as possible! For most users of GKS the default values should be acceptable (but note that these are device-dependent). The call is:

CALL GSDS(WKID, DEFMOD, REGMOD)

The second argument, DEFMOD, controls when output should be sent to the workstation specified by WKID, and can take the following values:

'GASAP': send output As Soon As Possible
'GBNIG': send output Before Next Interaction Globally. This makes sure that the workstation is up-to-date before the next input action on any open workstation
'GBNIL': send output Before Next Interaction Locally. This makes sure that the workstation is up-to-date before the next input action on the workstation specified in the call
'GASTI': At Some TIme allows GKS to choose some opportune moment to bring the workstation up-to-date

The third argument, REGMOD, controls what should happen on those workstations which require the image on the display to be regenerated in some circumstances. For example, to delete a segment on a direct view storage tube display, such as a TEKTRONIX 4014, would require the screen to be cleared and then the remaining contents re-drawn. This is called implicit regeneration. REGMOD can take the following values:

'GSUPPD': Re-drawing is suppressed until an update is forced by calling the Update Workstation function, GUWK, or by re-drawing all the segments with GRSGWK.
'GALLOW': Immediate re-drawing is allowed.

Updating the Workstation

Because of the deferral mode set, not all the output may yet have been sent to the display. The routine

CALL GUWK(WKID, REGFL) is provided to bring the contents of the workstation WKID up-to-date. The argument REGFL can take the values 'GPOSTP' or 'GPERFO'. If 'GPOSTP' is specified, then all deferred actions are performed at some time. If 'GPERFO' is specified, then all deferred actions are performed, the workstation transformation is updated, the display surface is cleared, and all segments are re-drawn as necessary. If an implicit regeneration of the image has to be performed then non-retained data (primitives not stored in segments) will be lost.

Note that a call to GUWK will not necessarily clear the workstation and re-draw all segments from scratch. However, this can be achieved by calling the function GRSGWK (see section ).

Sending Messages/Prompts

In order to display messages and prompts on the display surface the following routine is provided:

CALL GMSG(WKID, STR) WKID specifies on which workstation the text string STR should appear. Where and how the message is written out is both implementation and workstation-dependent.

The Drawing Primitives

primitives

Drawing primitives are the basic elements of graphics output, such as lines, text etc. GKS supports the six output primitives which are described below: polyline, polymarker, fill area, text, cell array, and the generalised drawing primitive. Each primitive has a corresponding set of attributes e.g. line type, colour index, character height, etc. The appearance of an individual primitive is governed by the attributes in force at the time when the primitive is passed to GKS, and attribute setting will be described in the following chapter. A number of example programs may be found in Appendix which illustrate the use of the following features. Examples of some GKS Primitives The Polyline, Polymarker, and Fill Area primitives are specified by an array of points which may not be arbitrarily large, and the maximum size of this array is implementation-dependent. The GKSGRAL implementation at CERN restricts the number points in a Fill Area to 300. However, calls to Polyline or Polymarker can handle more points than this by internally sub-dividing the array.

Polyline

This draws line segments between two or more points using the currently set attributes for line style, polyline colour index and line width scale factor. The call is:

CALL GPL(N, PXA, PYA) where N is the number of points, and PXA(N), PYA(N) are real arrays containing the X and Y values of the points in the application program's own coordinate system (called the World Coordinates System).

Polymarker

This marks a sequence of points with the marker symbol selected by the currently set attributes for polymarker colour index, marker type and marker size scale factor. The marker size to which the scale factor is applied is workstation-dependent. The call is:

CALL GPM(N, PXA, PYA) where N, PXA and PYA have the same meanings as for GPL.

Text

text

Text is displayed using the current attribute settings for text colour index, text font and precision, character-up vector, text alignment, character expansion factor, character spacing, text path and character height. The call is:

CALL GTX(PX, PY, STR) where PX and PY are real numbers which define in World Coordinates the starting position of the text string STR.

Fill Area

Fill Area draws an area which is specified by a polygon. The interior of the polygon can be either not filled (hollow), filled with a solid colour, or filled with various patterns. The fill area style and colour is specified by the current setting of the fill area colour index, fill area style and fill area style index attributes. The call is:

CALL GFA(N, PXA, PYA) where N, PXA, PYA have the same meaning as for GPL and GPM. If the first and last points are different, they are joined by a line.

Cell Array

The Cell Array is an array of rectangular cells with individual colours. It serves for passing raster images to GKS. Note that in general, colour values within the Cell Array do not correspond to picture elements (pixels) on a hardware display, and that all primitives, including Cell Arrays, are subject to the usual GKS transformations. The call is:

CALL GCA(PX,PY,QX,QY,DIMX,DIMY,ISC,ISR,DX,DY,COLIA) Neither the Cell Array primitive nor the function call arguments will be described in detail in this Primer, and the reader is referred to the GKSGRAL manual, or one of the texts in the bibliography, for more information.

Generalised Drawing Primitive

Although at present GKS defines only six types of graphics primitives, the standard allows for these to be augmented within particular implementations by using Generalised Drawing Primitives (GDPs). Thus, the Generalised Drawing Primitive may be thought of as a 'standard way to be non-standard', and in fact a mechanism exists for implementors of GKS to register GDPs with the International Standards Organization group responsible for GKS. The intention is that these registered GDPs will be incorporated as new primitives within future revisions of the standard. However, note that the use of GDPs may make programs non-portable to other GKS implementations. On the other hand, they do permit the GKS driver to make use of special hardware features, circle drawing for example, if these features are available.

GKSGRAL supports 6 GDPs:

Circle
Circular Arc
Ellipse
Elliptical Arc
Bezier Curve defined by Bezier Polygon
Cubic Curve defined by Interpolation Points

The call is: CALL GGDP(N, PXA, PYA, PRIMID, IDR, DATREC) See the GKSGRAL Manual for more details.

The Output Attributes

attributes

Before actually outputting any primitives, the application will want to specify the exact way in which the drawing appears on the display surface. This rendering process is controlled by output attributes. Output primitives have geometric and non-geometric attributes. Geometric attributes, such as the character height, affect the size and shape of a primitive, whereas non-geometric attributes are qualities such as colour, line style, etc.

Output attributes affect the appearance or rendering of primitives at the moment when the primitives are sent to GKS, and attributes are said to be bound to primitives at this time. Thus, modification of an attribute has no effect on primitives which have been output already. GKS attributes are said to be modal in character because, after setting an attribute, GKS is in a mode in which the value of that attribute will be bound to all primitives of the appropriate type which follow. Setting a different value for the attribute would then change the mode.

Attribute Bundles

There are two ways of specifying attributes, Bundled and Individually. Attributes may be set individually by calling the appropriate routines one at a time. As an example, for a polyline one could set the line style, the line width, and the colour by calling the routines GSLN, GSLWSC, and GPLCI, before calling GPL to output the polyline. Setting attributes individually will ensure that the primitives to which they are bound appear the same on all workstations, assuming that the workstations have sufficient capability. However, if attributes are set using bundles, then the results will be workstation-dependent.

Bundled attributes are assigned by selecting a bundle index for a particular type of primitive using the routines given in section . The bundle index points to an entry in the appropriate workstation bundle table. Hence, each workstation has a bundle table for every primitive type, and each entry in a bundle table contains a pre-defined set of attributes for that particular primitive. For example, the first entry in the polyline bundle table may contain the attributes dotted and red, the second may contain solid, double thickness and blue, etc. Note that attribute bundles do not contain geometric attributes. Beginners are advised to ignore attribute bundles and to set each attribute individually. However, read the next section on Aspect Source Flags before trying out a program.

As an example of why one might make use of attribute bundles, consider an application which sometimes uses a colour terminal and sometimes a monochrome one. By drawing polylines with, say, bundle table index 5, the actual appearance of the polylines will depend on the contents of polyline bundle 5 on the two workstations. Thus, the application can arrange to distinguish the polylines by using a particular colour on the colour terminal, and a particular dash pattern on the monochrome terminal, without making changes to the body of the code which draws the primitives.

By using attribute bundles to specify attributes, and assuming that the primitives have been stored in segments (segments are described in Chapter ), the application can also change the appearance of primitives after they have been output to a workstation by re-defining the contents of the bundle table. This effect can not be achieved if the attributes are set individually without deleting and re-drawing the primitives.

Aspect Source Flags

To control whether a primitive attribute should be set individually, or using a bundle table index, each primitive has a set of attributes called the Aspect Source Flags (ASFs); one flag for each primitive attribute. If the ASF for a particular attribute is set to 'GBUNDL', then the primitive will be bound to the attributes in the bundle table entry pointed to by the bundle index currently in force. If the ASF for a particular attribute is set to 'GINDIV', then the primitive will be bound to the current individual attribute values for that type of primitive.

Unfortunately, the committee which designed GKS could not agree on whether the default setting for the ASFs should be bundled or individual. Thus, American implementations, such as PLOT10/GKS, tend to default the ASFs to set attributes individually, whilst European implementations, such as GKSGRAL, tend to default ASFs to bundled attributes. In order to be safe, users of GKS are advised to set their own default values for the ASFs as soon as they open GKS. This can be done by calling:

CALL GSASF(ASFLST) where ASFLST is an array of 13 integers, one for each attribute, which must be set to 'GBUNDL' or 'GINDIV'. The bundle table index for each attribute is given in parentheses in the attribute list below. An example program which calls GSASF may be found in Appendix .

Defining Attribute Bundles

It is possible to define the entries in the bundle tables by calling one of the following routines:

Set polyline representation:

GSPLR(WKID, PLI, LN, LWSC, PLCI)

Set polymarker representation

GSPMR(WKID, PMI, MK, MKSC, PMCI)

Set text representation

GSTXR(WKID, TXI, TXF, TXP, CHXP, CHSP, TXCI)

Set fill area representation

GSFAR(WKID, FAI, FAIS, FASI, FACI)

Set pattern representation

GSPAR(WKID, PAI, DIMX, DIMY, NCS, NRS, DX, DY, PACI) As arguments, each routine requires the workstation identifier (WKID) and bundle index (PLI, etc.) to be set, plus a value for each of the non-geometric attributes for that particular primitive, and which are listed below. Details of GSPAR will not be given in this Primer; see the GKSGRAL manual or one of the references in the bibliography for more information.

The List of GKS Attributes

Individual Attributes

POLYLINE

LN
(integer) the polyline line style (ASF 1). Set by GSLN(LN).
LWSC
(real) the line width scale factor (ASF 2). Set by GSLWSC(LWSC).
PLCI
(integer) the polyline colour index (ASF 3). Set by GSPLCI(PLCI).
POLYMARKER

MK
(integer) the polymarker type (ASF 4). Set by GSMK(MK).
MKSC
(real) the marker size scale factor (ASF 5). Set by GSMKSC(MKSC).
PMCI
(integer) the polymarker colour index (ASF 6). Set by GSPMCI(PMCI).
TEXT

TXF
(integer) the text font (ASF 7). Set by GSTXFP(TXF, TXP).
TXP
(enumerated) the text precision (ASF 7). Set by GSTXFP(TXF, TXP).
CHXP
(real) the character expansion factor (ASF 8). Set by GSCHXP(CHXP).
CHSP
(real) the character spacing (ASF 9). Set by GSCHSP(CHSP).
TXCI
(integer) the text colour index (ASF 10). Set by GSTXCI(TXCI).
CHUP
(real) the character up vector. Set by GSCHUP(CHUX, CHUY).
TXAL
(enumerated) the text alignment. Set by GSTXAL(TXALH, TXALV).
TXP
(enumerated) the text path. Set by GSTXP(TXP).
CHH
(real) the character height. Set by GSCHH(CHH).
FILL AREA

FAIS
(enumerated) the fill area interior style (ASF 11). Set by GSFAIS(FAIS).
FASI
(integer) the fill area style index (ASF 12). Set by GSFASI(FASI).
FACI
(integer) the fill area colour index (ASF 13). Set by GSFACI(FACI).
PATTERN

PA
(real) the pattern size. Set by GSPA(PASZX, PASZY).
PARF
(real) the pattern reference point. Set by GSPARF(RFX, RFY).

Bundled Attributes

POLYLINE

PLI
(integer) the polyline bundle index. Set by GSPLI(PLI).
POLYMARKER

PMI
(integer) the polymarker bundle index. Set by GSPMI(PMI).
TEXT

TXI
(integer) the text bundle index. Set by GSTXI(TXI).
FILL AREA

FAI
(integer) the fill area bundle index. Set by GSFAI(FAI).

Specifying Line Styles For Polylines

It is possible to draw polylines solid, dashed, dotted or dashed-dotted ('GLSOLI', 'GLDASH', 'GLDOT', 'GLDASD'). For example:

CALL GSLN(GLDASH) - sets the line style to dashed The different line styles available are shown in . GKS line styles .pa

It is also possible to specify a scale factor which modifies the nominal width of lines on the workstation. For example:

CALL GSLWSC(2.0) should double the nominal line width. Note, however, that this (Real) parameter is implementation-dependent, and may be ignored by terminal drivers as it is both difficult and expensive to emulate in software if the device does not support the feature in hardware.

Specifying Marker Types for Polymarkers

The five GKS Marker types, point, plus, asterisk, circle and cross ('GPOINT', 'GPLUS', 'GAST', 'GOMARK', 'GXMARK'), are demonstrated in . For example:

CALL GSMK(GPOINT) - sets the marker type to point GKS marker types

Markers may be scaled in size by calling GSMKSC. For example:

CALL GSMKSC(3.5) will scale the following markers by 3.5 times. The implementation of this function is workstation-dependent. In particular, markers drawn on terminals by hardware may only exist in certain fixed sizes.

Specifying Fill Areas

Many applications need shaded or coloured areas as well as lines and points. GKS allows one to draw such an area by specifying an array of points representing a closed polygon. If the last point in the array is not the same as the first, these two will be joined. The interior style of the area can be set to one of the four values hollow, solid, pattern, and hatch, which are demonstrated in ('GHOLLO', 'GSOLID', 'GPATTR', 'GHATCH'). Examples for setting fill area interior style are:

CALL GSFAIS(GHOLLO) or CALL GSFAIS(GSOLID)

For interior style hollow the boundary polygon only is drawn as a solid line. For style solid the interior is completely filled with a uniform colour, as specified by the fill area colour index set by calling GSFACI. Workstations for devices which support area filling of polygons by hardware should normally make use of this feature. However, this is not always possible, as some monochrome terminals do not use the correct algorithm to perform the area fill.

For interior styles hatch and pattern, the particular hatch algorithm or pattern used may be chosen by specifying a fill area style index. This represents a second level of selection on the way the area is filled, and the index points into either a hatch or pattern table stored at the workstation. Thus, hatches and patterns are workstation-dependent. The fill area style index is set by calling:

CALL GSFASI(FASI) where FASI is an integer value. To find out the effect of setting a particular index, it is necessary to consult the workstation documentation.

The GKS standard provides calls to modify patterns by setting the pattern reference point (GSPARF) and pattern size (GSPA). The pattern representation attribute bundle is set using GSPAR. The GKSGRAL package also allows the possibility to define one's own hatch styles by calling the routine GUSHTR, although this is not a standard GKS feature. None of these routines will be described further in this Primer, and the reader is referred to the texts in the bibliography for more information. GKS fill area styles

Specifying Text

Text is the most complex of the GKS primitives because there are so many different variations. The text attributes are described below. Note that only the non-geometric attributes may be set in the text bundle table. (HINT: For FORTRAN programmers, it is possible to use the Internal Write construct to convert numeric variables to character strings for output as text primitives, see section ).

Font and Precision

The text font is specified by an integer font number, and fonts are workstation-dependent. Any text font which is not supported on a given workstation is defaulted to 1. This text font is a simple, roman type font produced by stroking out each character using line segments. To find out which fonts are provided by a particular implementation one should consult the relevant reference manual.

The text precision attribute determines how closely the chosen font has to obey the specifications of the other text attributes. The choices for text precision are: string, char and stroke ('GSTRP', 'GCHARP', 'GSTRKP'). In string precision the text string should be placed as close as possible to the position specified by the primitive call. None of the other text attributes need be taken into account except the approximate size specified by character height. Thus, if string precision is specified, the implementation is usually free to make use of hardware characters which can be drawn much faster than generating the fonts in software. If char precision together with a workstation-provided font is chosen, GKS will try a workstation dependent approximation. In stroke precision GKS has to follow precisely the attribute specifications, and always defaults to font 1 if the requested font does not exist. Note that an implementation of GKS may provide stroke precision text on a particular workstation even if the application specified only a lower precision. Both the text font and the text precision are set by the same routine:

CALL GSTXFP(FONT, PREC) Text fonts, precisions and up vectors

Expansion Factor

character

The character expansion factor, a real number, causes each character to appear 'fatter' or 'thinner' than normal. The default value is 1.0. The height of the character is not affected, nor is the space between the characters.

CALL GSCHXP(CHXP)

Spacing

The character spacing attribute defines the amount of extra blank space to be inserted between adjacent characters of a text string. This is a real number defined as a fraction of the character height. The default value is 0.0. A positive character spacing spreads the letters out, a negative one makes the letters overlap.

CALL GSCHSP(CHSP)

Character-Up-Vector

The char-up vector defines the orientation of the text. The text is written from left to right along a line perpendicular to the char-up vector, which is specified by its X and Y components (two real numbers):

CALL GSCHUP(CHUX, CHUY) The effect of choosing different combinations of text font, text precision and character-up-vector is shown in .

Alignment

text

The text string as a whole is positioned relative to the point specified in the GTX primitive call according to the current setting of the text alignment attribute. The call to GSTXAL has two parameters for horizontal and vertical alignment.

CALL GSTXAL(TXALH, TXALV). The horizontal alignment is either normal, left edge, centre, or the right edge of the text string ('GAHNOR', 'GALEFT', 'GACENT', 'GARITE'). The vertical alignment is either normal, top, cap line, half, base line, or bottom (GAVNOR', 'GATOP', 'GACAP', 'GAHALF', 'GABASE', 'GABOTT'). The alignment attribute is illustrated in . The selection of normal for either horizontal or vertical alignment results in GKS choosing the most appropriate value depending on the current Text Path. Text alignment

Text Path

The text path describes the direction in which the text string is written. The possible values are Right, Left, Up and Down ('GRIGHT', 'GLEFT', 'GUP', ' GDOWN'). The default for the text path is perpendicular to the up vector (i.e. 'GRIGHT').

CALL GSTXP(TXP)

Height

The character height is set in World Coordinates by calling GSCHH. Increasing the height automatically causes a corresponding increase in the width of the character.

CALL GSCHH(CHH)

Note that the use of World Coordinates to specify the character height may cause problems if the normalization transformation chosen has a very large or very small range in Y. In this case it is possible that when using a metafile as an output workstation the number of digits required to specify the character height may be more than the range used to define real numbers within the metafile. If it would be inconvenient to modify the range of World Coordinate Y values, then another possible solution to the problem is to superimpose two viewports, one on top of the other. All characters may then be drawn on one of the viewports which has been defined using a more reasonable normalization transformation.

Specifying Colour

colour

Colour is specified separately for each primitive type by a colour index value.

Polyline: CALL GSPLCI(PLCI)
Polymarker: CALL GSPMCI(PMCI)
Text: CALL GSTXCI(TXCI)
Fill Area: CALL GSFACI(FACI)

The colour index, instead of defining a colour directly, points to an entry in a colour look-up table which is workstation-dependent. If the colour is an attribute of a primitive, then one can specify a colour index either as an individual attribute or as part of a bundle table. The size of the colour table is workstation-dependent, but the table always contains the entries 0 and 1. The background colour is 0, and the default foreground colour is 1. Each entry greater than 1 defines an additional foreground colour. If a colour index greater than the maximum is specified, then the default value 1 is taken, which ensures that a program written using colour will run on a monochrome device.

To set entries in the colour look-up table one must call the function Set Colour Representation (GSCR). It takes as parameters the workstation identifier, the colour index to be set, and a value (from 0 to 1.0) for each of the red, blue, and green intensities. The workstation then uses the closest available colour to that which has been requested.

CALL GSCR(WKID, INDEX, RED, GREEN, BLUE)

The highest possible value for the colour index (NCOLI) depends on the capabilities of the device and can be inquired using GQCF and specifying the workstation type:

CALL GQCF(WTYPE, ERRIND, NCOLI, COLA, NPCI) The parameter COLA ('GMONOC' or 'GCOLOR') indicates whether or not colour is available, and NPCI specifies the number of pre-defined colour indices.

The colour index can also be used if part of a previously drawn picture is to be erased. The part to be erased should be re-drawn in the background colour (index=0). All other attribute settings and transformations must be exactly as they where when the picture was produced initially. However, even in this case, the trick may not work if the primitive being erased overlays another primitive, and not just the background.

Colour may be part of a fill area pattern, in which case different parts of the pattern may be defined to be different colours. For the cell array primitive an array of colours is specified as part of the primitive itself.

Coordinates and Transformations

transformations

GKS defines three coordinate systems:

WORLD Coordinates (WC)
NORMALIZED DEVICE Coordinates (NDC)
DEVICE Coordinates (DC)

The application program specifies the coordinates of points in primitive calls using a cartesian coordinate system with whichever scale is the most convenient. This system is called the World Coordinate System. The WC range can go from negative to positive infinity along both axes, which gives the application an unlimited choice of coordinates. The definition of the WC space is independent of any graphics output device and can be different for each application as the requirements dictate.

All world coordinates are transformed by GKS to a 'virtual' device space, the Normalized Device Coordinate (NDC) space. The NDC space ranges from 0 to 1 in both x and y. This space is device independent and appears identical for all workstations in the system. A transformation from WC to NDC is called a Normalization Transformation. GKS allows more than one such transformation to be defined, and so an application may draw each part of a picture in its own WC system, and then map them into a single NDC space. See and .

The third coordinate system is that of the hardware device. GKS uses specific information about the graphics output device to transform normalized device coordinates into coordinates that the device itself understands. Usually the units in the device dependent space will be metres or raster units. The translation from NDC to DC is called the Workstation Transformation. normalization

Normalization Transformation

This transformation is specified by mapping a Window in the application's WC space to a Viewport in NDC space. Both the WC window and the NDC viewport are rectangles parallel to the x,y axes. They are specified by calls to Set WiNdow and Set ViewPort:

CALL GSWN (TNR, WXMIN, WXMAX, WYMIN, WYMAX) CALL GSVP (TNR, VXMIN, VXMAX, VYMIN, VYMAX) Because there may be several Normalization Transformations, the integer value TNR indicates to which one the call applies. The other values are real numbers defining the bottom left and top right corners of the two rectangles. The window is specified in the WC system, and the viewport in the NDC system. If the x and y sides of the window and the viewport do not have the same Aspect Ratio a distortion effect will take place. This may or may not be intentional!

As has been mentioned, it is possible to generate a complex picture with different world coordinates for different parts of the image, or to place several pictures on different areas of the screen. This is achieved by specifying multiple normalization transformations. Each transformation is assigned a transformation number (TNR) for which the range is 0 to some implementation-dependent maximum (usually about 20). Thus, the transformation corresponding to each number specifies a separate window-to-viewport mapping. If the viewports overlap then their contents will be superimposed.

The default transformation number is 0, for which the WC and NDC coordinate systems are the same. Transformation 0 may not be modified, and so its use is always equivalent to calling:

CALL GSWN (TNR, 0.0, 1.0, 0.0, 1.0) CALL GSVP (TNR, 0.0, 1.0, 0.0, 1.0)

The application specifies which normalization transformation is active at a given time by a call to GSELNT (SELect Normalization Transformation):

CALL GSELNT(TNR) All primitives created subsequently will be transformed according to this transformation until a different one is selected. Windows and Viewports

Workstation Transformation

The method of defining which portion of NDC space is to appear on a specific workstation is similar to the way a viewport is positioned in NDC space (the Normalization Transformation). The Workstation Transformation defines that part of NDC space which will be visible, and where it will appear on the display surface. It is set by calling the functions Set WorKstation WiNdow and Set WorKstation ViewPort:

CALL GSWKWN(WKID, WXMIN, WXMAX, WYMIN, WYMAX) CALL GSWKVP(WKID, VXMIN, VXMAX, VYMIN, VYMAX) Set Workstation Window specifies in NDC coordinates the area of the NDC space to be output to the device. Set Workstation Viewport specifies in Display Coordinates (DC) where on the device the window will appear. These functions may be called at any time. However, whether or not the effect is immediately visible is workstation-dependent. For example, if changing the workstation transformation requires an implicit image regeneration, then the timing of when it will take place is affected by the current deferral mode (see section ).

The aspect ratio for the workstation window and the workstation viewport must always be the same. If they are not, then the specified transformation is ignored, and the complete workstation window is displayed on the device in the correct aspect ratio. A rectangle is used with the bottom left corner set to the bottom left corner of the specified viewport, and which is as large as possible.

The default setting for the workstation transformation is to map the whole unit square of NDC onto the largest square possible for the workstation. For rectangular displays, this means that not all of the display surface is used. Conversely, if the workstation transformation is set so that all of a rectangular display is used, then either: (1) the normalization transformation can not preserve the aspect ratio, or: (2) not all of NDC space can be used.

To inquire the range of device coordinates corresponding to a particular workstation type, it is possible to call the function GQDSP (inQuire Display SPace). (Note: The 3D version is called GQDVOL.)

CALL GQDSP (WTYPE, ERRIND, DCUNIT, RX, RY, LX, LY) The routine returns the units in which the display surface is measured (DCUNIT), and also the maximum x and y values in each direction. Some devices, for example hardcopy plotters, are measured in metres (DCUNIT='GMETRE'), so the routine will return the actual size of the device. Other devices, for example graphics terminals, will be defined in raster or some other units (DCUNIT='GOTHU'). RX, RY are real device coordinates, and LX, LY are in integer raster units.

As an example of how to use this routine, below is a fragment of code which allows an application to draw on the whole of a rectangular display surface with a 'Landscape' aspect ratio (width > height). See also the example in Appendix .

C Inquire the Workstation Display Surface Size CALL gqdsp (wtype, errind, dcunit, rx, ry, lx, ly) C C Set the Workstation Window and Viewport (assume x > y) CALL gswkwn(wkid, 0.0, 1.0, 0.0, ry/rx) CALL gswkvp(wkid, 0.0, rx, 0.0, ry) C C Make sure Workstation Transformation is used CALL guwk (wkid, gperfo) C C Set Window and Viewport for Normalization Tfrm 'trn' CALL gswn (trn, xmn, xmx, ymn, ymx) CALL gsvp (trn, 0.0, 1.0, 0.0, ry/rx) C C Select this Normalization Tfrm for future primitives CALL gselnt(trn) Normalization and Workstation Transformations

Clipping

Clipping is the exclusion of those primitives, or parts of primitives, which lie outside a specified window or viewport. That is to say, if clipping to a particular window is enabled, then only those parts of primitives which lie within the boundaries of the window will be displayed. Both the normalization transformation viewport (in NDC space) and the workstation window can be used to clip a picture. Clipping at the boundary of the normalization transformation viewport (clipping rectangle) effects the image displayed on ALL workstations. However, clipping at the boundary of the workstation window only affects the image on the display surface belonging to that particular workstation. This is illustrated in Workstation Viewport 1 in .

The application can control whether clipping at the boundary of the clipping rectangle is enabled or not by calling the routine GSCLIP(VAL). This routine takes the value 'GNCLIP' (no clip) or 'GCLIP' (clip), and the default is to clip. Clipping at the workstation window may not be switched off.

Segments

segments

GKS provides a way to collect and store together the primitives that make up all or part of a picture. Such a collection of primitives is called a segment, has a unique name, and may be manipulated as a unit in various ways. Only one segment can be open at a time, and once a segment has been closed further output primitives cannot be added to it, nor can the primitives in it be modified.

Any non-retained data output whilst there is no open segment will be lost if the screen is cleared for some reason. There are several circumstances when this may be useful. For example, a message written on the screen may have only limited validity, or one may wish to output a very complicated image with too much data to be stored, or which needs only to be displayed once. However, much of the power of GKS comes from the ability to interactively modify the image without always having to regenerate the complete picture. To make use of this feature, primitives must be stored in segments.

Segment Storage

Every workstation in a GKS output level 1 or 2 implementation has associated with it a Workstation Dependent Segment Store (WDSS). At the time a segment is created, it is stored in the WDSS of all open and activated workstations. The WDSS may be physically located in the Graphics Terminal, in which case there can be a substantial improvement in performance. Of course, care must be taken not to exceed the available memory space.

In addition to WDSS, GKS output level 2 implementations have also a Workstation Independent Segment Store (WISS). WISS is a mechanism for storing segments in a workstation-independent way, and allows segments to be re-used and manipulated on different workstations at different times. WISS is treated like any another workstation, just like a terminal for example, and if it is open and activated when a segment is created, then that segment will be stored there as well as on the WDSSs of the other active workstations. For example, one might store an object in WISS at the same time as displaying it on a terminal. Then, at a later time, it would be possible to make a hardcopy of the object by extracting the segment(s) in which it was stored from the WISS and copying it (them) to a plotter. A transformation or segment deletion affects the segment wherever it is stored.

Before primitives are stored in WDSS or WISS they first undergo the normalization transformation currently in force. Also, when a segment is created, the current clipping rectangle together with the clipping flags, are stored in the segment, but clipping is not performed on the primitives when they are stored, but only when the contents of the segment are output to a device.

Segment Creation, Deletion, and Re-naming

To use GKS segmentation, first a segment must be created by calling:

CALL GCRSG(SGNA) where SGNA is an integer segment name. A segment called SGNA will be created on all active workstations, including WISS, and will remain open and store all primitives and attributes which are output until one calls: CALL GCLSG Only a single segment may be open at one time.

Segments may be renamed, or deleted on a particular workstation or all workstations by the following calls:

CALL GRENSG(SGNOLD, SGNNEW) CALL GDSGWK(WKID, SGNA) CALL GDSG(SGNA) Once a segment has been deleted the same segment name may be re-used. Note that the Clear Workstation function deletes all the segments stored in WDSS on that workstation.

The following fragment of code shows the use of segments. See also the example in Appendix .

--------- --------- CALL gcrsg(1) ! Create segment 1 CALL objone ! Draw an object CALL gclsg ! close segment CALL gcrsg(2) ! Create segment 2 CALL objtwo ! Draw an object CALL gclsg ! Close segment --------- --------- --------- CALL guwk(wkid, gperfo) ! Update Workstation --------- ---------

Segment Names

As indicated above, the FORTRAN binding requires segment names to be integers, and these may be restricted by an implementation to a particular range of values (1-32763 for GKSGRAL). However, because segment names are specified by integers does not imply that an implementation has to make available as many segments as there are names, and the maximum number of available segments is also an implementation-dependent feature which may be much smaller than the maximum legal name. (Thus, one can not assume that an implementation stores name N as the N'th element of an array.) GKS does not provide inquiry functions to obtain either of these maximum values, so one must consult the relevant documentation, for example GKS/GKS-3D at CERN.

The GKS standard provides a function, GQSGUS, to inQuire the set of SeGment names in USe. However, as it is difficult to work with variable length sets in FORTRAN, the FORTRAN binding has modified this function to allow only the inquiry of the name of one element of the set at a time:

CALL GQSGUS(N, ERRIND, NSG, SGNA) where

N: is the N'th segment in the set (an input parameter)
ERRIND: is an error number
NSG: is the total number of segments in use
SGNA: is the name of the N'th segment

Thus, in FORTRAN, it is necessary to call GQSGUS in a loop from 1 to NSG in order to obtain a list of all the segment names in use.

Note that the function:

CALL GQSGWK(WKID, N, ERRIND, NSG, SGNA) works in a similar way to GQSGUS but provides the list of segment names associated with workstation WKID.

Segment Association, Copying, and Insertion,

To view the contents of segments stored in WISS it is necessary to transfer them to a real device. This can be accomplished in three ways:

Association: Associate SeGment to WorKstation retrieves a segment stored in WISS and sends it to the designated workstation as if this workstation had been activated when the segment was first created. It is thus stored in the WDSS of the designated workstation. Nothing may be added to the segment. There must be no open segment when this function is called.
Copying: Copy SeGment to WorKstation transforms the contents of the designated WISS segment using the segment transformation (described below), and then sends the result to the workstation specified. The clipping volume of the copied segment is also sent to the workstation. Note that the copied segment itself is not transferred; its contents are just drawn on the output device without being stored in WDSS. Thus, there must be no open segment when this function is called.
Insertion: INsert SeGment transforms the contents of the designated WIS segment using both the transformation stored in the segment header and then the matrix provided in the call (MTX), before inserting the results into the output stream as if they had come directly from the application. Thus, the output of Insert Segment goes to all activated workstations, including the WISS, and will be stored in a segment if one is open. All clipping rectangles and indicators, etc. are ignored. The transformation matrix, MTX, may be produced using the routine GEVTM as described below.

The flow of graphics data between WISS, WDSS and the application is shown in . Data Flow for GKS

Segment Attributes

The appearance of segments depends on the following segment attributes:

segment transformation
visibility
highlighting
segment priority
detectability

Segment attributes may be modified after the segment has been closed, and the changes will become visible on all active workstations on which the segment has been stored. However, the timing of when these changes take place is workstation-dependent, and may also be affected by the deferral mode which is in force (see sections and ). This is because some workstations may require picture regeneration to produce the new attribute state on the display.

Segment Transformations

A segment transformation is a transformation of all the coordinates within a segment and is performed by a 2 x 3 matrix stored in the segment header. It maps from NDC to NDC. As an example of the use of segment transformations, consider a circuit design application which has symbols for transistors, capacitors, resistors, etc. Such an application would store each symbol in a separate segment, and then call INsert SeGement specifying a transformation matrix in order to duplicate a particular symbol at the positions and orientations required.

When a segment is created GKS sets a default null transformation which leaves the original coordinates unchanged. Before setting a transformation it is necessary to evaluate the transformation matrix by either using one's own algorithm, or by using the routines:

CALL GEVTM(X0, Y0, DX, DY, PHI, FX, FY, SW, MXOUT) and/or CALL GACTM(MXIN, X0, Y0, DX, DY, PHI, FX, FY, SW, MXOUT) GEVTM evaluates a matrix (MXOUT), whilst GACTM accumulates changes to an existing matrix (MXIN). Both routines require the definition of:

X0, Y0: (real) a fixed reference point about which 2D rotations take place.
DX, DY: (real) a translation (or shift) vector.
PHI: (real) an angle of rotation about X0, Y0.
FX, FY: (real) X and Y scale factors.
SW: (enumerated) a switch specifying whether the reference point and shift vector are given in World Coordinates or Normalized Device Coordinates ('GWC' or 'GNDC').

The transformation is composed in the order: scale, rotate, shift. In the case of GACTM, the matrix MXIN is pre-concatenated with that formed from the scale, rotate, and shift parameters, so MXOUT = SHIFT * ROTATE * SCALE * MXIN.

Once the transformation matrix has been evaluated, it may then be Set in the SeGmenT by calling the routine:

CALL GSSGT(SGNA, MTX) An example of using a segment transformation may be found in Appendix .

Visibility

Segment VISibility (GSVIS) determines whether or not the segment is displayed; the default is for the segment to be visible. The values are 'GINVIS' or 'GVISI'. As an example of its use, messages or icons could be created in segments which would normally be invisible, but which could be made visible at the appropriate time by the application program. The call is:

CALL GSVIS(SGNA, GVISI) Note that if a segment is invisible it is not detectable (cannot be picked), even if detectability is enabled. Also, even if a segment has visibility enabled, it may not actually be drawn if the deferral state is set to something other than 'GASAP' (see section ).

Highlighting

Many display systems have some means for highlighting graphical output, eg by making it brighter, or by causing it to blink. The implementation of this attribute is dependent on the device being used. Note that in order for a Segment to be HighLIghTed (GSHLIT), it must first be made visible. The default is not highlighted. The possible values are 'GNORML' or 'GHILIT'. The call is:

CALL GSHLIT(SGNA, GHILIT)

Priority

SeGment Priority, a real number in the range 0.0 to 1.0, enables the control of the order in which segments are re-drawn when the picture has been changed. It also controls the order in which segments are picked. If parts of segments overlap, then the segment with the highest priority will be picked first and displayed on top of all the others. If two segments with the same priority occupy the same area of the display surface, then the last one will be drawn on top. The default priority is 0.0. The call is:

CALL GSSGP(SGNA, PRIOR)

The number of segment priority levels available (NSGP) for a particular workstation, WTYPE, may be inquired using:

CALL GQSGP(WTYPE, ERRIND, NSGP)

Detectability

Segment DeTECtability controls which segments can be picked by the operator using a Logical Pick Device, and which ones cannot. Values are 'GUNDET' or 'GDETEC'. If a segment is detectable, it can be picked. The default setting is un-detectable. The call is:

CALL GSDTEC(SGNA, GDETEC) Note that if a segment is invisible it is not detectable (cannot be picked), even if detectability is enabled.

The Pick Identifier

It is possible to attach an integer Pick Identifier to primitives which are stored in segments using the routine:

CALL GSPKID(PCID) This inserts one or more Pick Identifiers (PCIDs) into a segment, and these are associated with the subsequent primitives. If one of these primitives is picked sometime later using a Logical Pick input device (see ), then one of the pieces of information returned to the application is its PCID.

As the application is free to choose the value of the Pick Identifier, this provides a second level of naming, and provides a mechanism to refer back to an application database. For example, if the identifiers 1 to 4 were attached to the four wheels of a car, then picking wheel number three would return the identifier '3' to the application program.

Segment Re-drawing

It is possible to force all segments within the WDSS on a particular workstation to be re-drawn by calling the routine Re-draw SeGments on WorKstation:

CALL GRSGWK(WKID)

The routine clears the screen, performs all deferred actions, and re-draws all segments. All non-retained data is lost. Possible reasons to re-draw all segments are:

if a segment had been over-written or deleted and it is desired to regenerate a clean image;
if one wishes to remove all non-retained data, system messages, etc;
if, on this workstation, image regeneration is required in order to display the effect of modifying a segment attribute, and implicit regeneration is switched off.

The action of this routine differs from that of Update WorKstation (GUWK), which may or may not re-draw segments which have not been changed.

Graphical Input

Logical Input Devices

input

GKS organizes data that can be input to an applications program into six types, each related to a Logical Input Device. The actual physical input devices are mapped onto these logical devices, which makes it possible for GKS to organize the different forms of data in a device-independent way, and thus helps to make the code more portable. A logical input device is identified by 3 items:

a workstation identifier
an input class
a device number

The six input classes and the logical input values they provide are:

LOCATOR

Returns a position (an x,y value) in World Coordinates and a Normalization Transformation number corresponding to that used to map back from Normalized Device Coordinates to World Coordinates. The NT used corresponds to that viewport with the highest Viewport Input Priority (set by calling GSVPIP). Warning: If there is no viewport input priority set then NT 0 is used as default, in which case the coordinates are returned in NDC. This may not be what is expected! CALL GSVPIP(TNR, RTNR, RELPRI)

TNR: Transformation Number
RTNR: Reference Transformation Number
RELPRI: One of the values 'GHIGHR' or 'GLOWER' defined in the Include File, ENUM.INC, which is listed in the Appendix .

STROKE

Returns a sequence of (x,y) points in World Coordinates and a Normalization Transformation as for the Locator.

VALUATOR

Returns a real value, for example, to control some sort of analogue device.

CHOICE

Returns a non-negative integer which represents a choice from a selection of several possibilities. This could be implemented as a menu, for example.

STRING

Returns a string of characters from the keyboard.

PICK

Returns a segment name and a pick identifier of an object pointed at by the user. Thus, the application does not have to use the locator to return a position, and then try to find out to which object the position corresponds.

Prompt/Echo Types and Triggers

A Prompt and an Echo type is defined for each logical input device. For example, enabling the pick device might prompt with a cursor of a particular shape which would track the tablet or mouse to constitute an echo. Acceptance of a trigger by the application, hitting a key, for example, causes feedback via an acknowledgment process. Thus, the picked object could be made to blink. Different prompt/echo types can be set when initializing the device. They are implementation and workstation-dependent, so see the relevant reference manual for details.

Input Modes

request input

Logical input devices can be operated in three modes: Request, Sample, and Event ('GREQU', 'GSAMPL', 'GEVENT'). In Request mode the application enables a device and then waits for the user to trigger input, perhaps by pushing a key. This is similar to issuing a FORTRAN READ. In Sample mode the application can measure the current value of the device, for example the locator position, without waiting for a trigger. Finally, in Event mode, the application can enable a set of several logical devices simultaneously. Output measures from devices which have been triggered will be placed in an Event Queue, from whence they can be extracted by the application.

Note that in GKS input level 'b' only Request mode input is available, and that it is not possible to request GKS input and issue a FORTRAN I/O operation at the same time. (However, although not required by the standard, the GKSGRAL level 'b' implementation provides Sample input for some devices.)

Request Input Functions

To request input one of the following calls needs to be made.

Locator

CALL GRQLC(WKID, LCDNR, STAT, TNR, PX, PY)

WKID: (I) Workstation identifier
LCDNR: (I) The number of the logical locator device (usually 1).
STAT: (O) Error status (integer)
TNR: (O) The Normalization Transformation number used to convert the input position to World Coordinates.
PX,PY: (O) The returned coordinates in WC.

String

CALL GRQST(WKID, STDNR, STAT, LOSTR, STR)

WKID: (I) Workstation identifier
STDNR: (I) The number of the logical string device (usually 1).
STAT: (O) Error status (integer)
LOSTR: (O) string length
STR: (O) The returned character string

Stroke

CALL GRQSK(WKID, STDNR, N, STAT, TNR, NPX, PX, PY)

WKID: (I) Workstation identifier
STDNR: (I) The number of the logical stroke device (usually 1).
N: (I) Maximum number of points (size of point arrays).
STAT: (O) Error status (integer)
TNR: (O) The Normalization Transformation number used to convert the input position to World Coordinates.
NPX: (O) Number of points returned.
PX,PY: (O) The returned coordinate arrays (WC).

Valuator

CALL GRQVL(WKID, VLDNR, STAT, VAL)

WKID: (I) Workstation identifier
VLDNR: (I) The number of the logical valuator device (usually 1).
STAT: (O) Error status (integer)
VAL: (O) The returned value (real number).

Choice

CALL GRQCH(WKID, CHDNR, STAT, CHNR)

WKID: (I) Workstation identifier
CHDNR: (I) The number of the logical choice device (usually 1).
STAT: (O) Error status (integer)
CHNR: (O) The returned choice number (integer).

Pick

CALL GRQPK(WKID, PCDNR, STAT, SGNA, PCID)

WKID: (I) Workstation identifier.
PCDNR: (I) The number of the logical pick device (usually 1).
STAT: (O) Error status (integer)
SGNA: (O) Picked segment name.
PCID: (O) Pick identifier (integer set by GSPKID).

Initializing Logical Input Devices

initializing logical input devices

For each of the input classes there is an initialization function which can change the values set as default by GKS for use in Request Mode (and which should be called after the mode has been set). The function calls are:

Initialize locator: CALL GINLC(...)
Initialize string: CALL GINST(...)
Initialize stroke: CALL GINSK(...)
Initialize valuator: CALL GINVL(...)
Initialize choice: CALL GINCH(...)
Initialize pick: CALL GINPK(...)

For all the input classes the echo area can be changed (i.e. the portion of the display surface where the prompt appears and which can accept input from the operator). For Locator and Stroke input the initialization function sets the initial normalization transformation and the initial locator position. The initialization functions also select the required prompt/echo type.

A detailed description of the initialization functions is outside the scope of this Primer, so those readers who wish to dig somewhat deeper should consult the reference manual for the GKS implementation being used. An example using GKSGRAL may be found in Appendix ).

Input Inquiry Functions

There are two types of inquiry functions for GKS input. The first is Inquire Device State, and the information is obtained by calling GQCHS, GQLCS, etc. The second is Inquire Default Device Data and the information is obtained by GQDVL, GQDST etc. There is also a function GQLI which can inquire the number of available logical input devices. A detailed description of these functions is outside the scope of this Primer, and so for more information the reader is referred to the GKSGRAL manual or one of the texts in the bibliography.

GKS Metafiles

metafiles

GKS provides metafiles for the storage of graphical information. Their principal uses are:

transporting graphical information between computer systems
transporting graphical information from one site to another (by magnetic tape for example)
device spooling, e.g. for a plotter

There is no official ISO standard for writing a GKS metafile. However, in Appendix E of the ISO GKS Functional Description document a metafile format is described, and its use is recommended. A GKS metafile created using this format is known as an Appendix E metafile. Unfortunately, not all implementations follow the Appendix E format, and so metafiles created by different GKS packages may be incompatible. In fact, even different examples of Appendix E metafiles may be incompatible due to variations in the file record lengths, etc. However, all GKS implementations available at CERN produce compatible Appendix E metafiles.

The Computer Graphics Metafile (CGM) standard is now finalised, and this will eventually become an alternative to the Appendix E format for the storage and transmission of complete pictures. However, as it does not support segmentation or 3D primitives it is not a complete replacement for the GKS metafile. ISO has several work items to produce extended versions of CGM, so these may be introduced at CERN in the longer term.

Writing a Metafile

A GKS metafile is produced by a standard GKS output-only workstation (see ). Hence the application must control it in the same way as a terminal or a plotter. Clearly, some of the workstation inquiry functions, such as Inquire Text Extent, can not be used because this knowledge depends on the device(s) ultimately chosen to interpret the file. The workstation must first be 'opened' (GOPWK), then 'activated' (GACWK), and all graphical information following these calls is recorded on the metafile as a series of items (listed in Appendix ) until a 'deactivate workstation' is encountered (GDAWK). Thus, a GKS metafile does not record a complete 'picture' so much as all the actions performed to make such a picture. If the application deletes segments and then draws different ones all this will be recorded on the metafile if it is active.

This last point has a number of ramifications. Because the metafile captures all the output generated whilst it is active, it could be used to record a dynamic sequence, like a cartoon, so long as it is re-interpreted onto a dynamic display system. However, if the object of the exercise is to interpret the metafile on a hardcopy device, it is not clear what the interpreter would be expected to do with, for example, a Delete Segment operation! Thus, for this kind of use, the metafile workstation should only be activated when a finished picture is ready to be output, perhaps by copying the image from WISS. A classic mistake is to leave the metafile workstation activated whilst one works interactively on a terminal, and then to crash when all the available disc space is used up.

To open an Appendix E metafile workstation the call is:

CALL GOPWK(WKID, CONID, WTYPE) where the parameter WTYPE specifies the metafile workstation which is defined in the documentation for the GKS implementation in use. At CERN, this parameter is defined in an include file (see the appendix to GKS/GKS-3D at CERN).

The metafile will be written to the logical unit number corresponding to the connection identifier (conid) in the GOPWK call. For example, using GKSGRAL on VAX/VMS the metafile can be written to a file which should be opened prior to the call to GOPWK. If there is no OPEN statement, the metafile will be written to FOR0XX.DAT, where XX is the specified conid. On VM/CMS, a conid of XX with no OPEN or FILEDEF statements would result in a metafile name 'FILE FTXXF001'. More precise information may be obtained from GKS/GKS-3D at CERN.

As a further point of interest, GKS provides the possibility to write private user items to a metafile using the routine GWITM. These can contain anything of interest to the application, and are ignored by GKS on interpretation. Note that the format of the records output by GWITM is implementation-dependent.

Shipping Metafiles

One of the fundamental uses of a GKS metafile is that it can be stored in a device independent manner and transferred to other hosts and other sites where it can be subsequently interpreted. GKSM metafiles at CERN are written in 80 character records with no 'control' characters, which makes transfers between host computers straightforward.

Interpreting Metafiles

To use the graphical information stored in the metafile this must be interpreted so that the original picture can be re-created on whatever device the application requests. GKS provides three functions in order to interpret metafiles:

GRDITM: read item from metafile
GGTITM: get item from metafile
GIITM: interpret item from metafile

These functions will not be described in detail here as for most users it should be sufficient to make use of the utility functions provided at CERN. The utilities allow a metafile to be interpreted either onto a terminal, or onto a (remote) plotting device. They are described in GKS/GKS-3D at CERN, or in the on-line help system. Note that as the Appendix E metafile has no items to explicitly define the start and end of a complete picture. Thus, when using a plotting device, the CERN convention is that separate pictures are implicitly generated by the item 'Clear Workstation'. At CERN there is a non-standard routine called GCNAME available which is used to output a character string to a metafile in order to name pictures which are later inserted into SGML documents such as this one. See GKS/GKS-3D at CERN for details.

GKS in Three Dimensions

GKS-3D Whilst in general the information in this Primer is independent of a particular GKS implementation, this is not entirely the case for GKS-3D. The reason is that the goal of the Primer is not simply to describe the functionality of GKS, but to explain in detail how it may be used via the FORTRAN language binding. However, as the binding has not yet been completely finalised for GKS-3D, this chapter explains its use in terms of a particular implementation, namely GKSGRAL-3D Version 2.0.

The text of the Draft International Standard for the GKS-3D FORTRAN binding was published at the end of 1988, with voting to finish by May, 1989. Discrepancies between the FORTRAN DIS and GKSGRAL-3D Version 2.0 are minor, and are mentioned at the appropriate places within the chapter. Only the setting of the viewing parameters and the aspect source flags are affected, and the text will be revised after the final voting on the standard is complete. The changes between VSN 1.1 and VSN 2.0 of GKSGRAL-3D are described in Appendix .

Introduction to GKS-3D

GKS-3D is a pure super-set of GKS designed to handle 3D graphics in a compatible way. That is to say, a 2D application written to the GKS standard is guaranteed to run in a GKS-3D environment without change. However, apart from the usual GKS functions, GKS-3D provides additional ones to handle 3D primitives, 3D input, and 3D viewing. As for GKS, the standard is in multiple parts with the language bindings separate from functional specification. See for the FORTRAN binding.

All primitives within GKS-3D are deemed to be three dimensional. Thus, although an application using GKS-3D may make only 2D function calls, all the 2D primitives will be turned immediately into the corresponding 3D versions inside the package by the addition of a Z coordinate. This has several noticeable effects:

2D function calls may be slightly slower than 3D ones (using the same GKS-3D package), as a 2D call will add a Z coordinate and then make the corresponding 3D function call.
2D applications running on GKS-3D will take more storage space in WDSS and WISS.
A 2D picture stored on a 3D metafile will require more space than on a 2D metafile. Also, quite clearly, such a picture could not be re-interpreted by reading the metafile into a GKS (2D) implementation.

The Drawing Primitives

With one addition, GKS-3D supports the same GKS primitive types as described in chapter . Four of the functions are called in a similar way to that for GKS-2D, but with the addition of a third coordinate:

Polyline 3D: CALL GPL3(N, PXA, PYA, PZA)
Polymarker 3D: CALL GPM3(N, PXA, PYA, PZA)
Fill Area 3D: CALL GFA3(N, PXA, PYA, PZA)
GDP 3D: CALL GGDP3(N, PXA, PYA, PZA, PRIMID, IDR, DATREC)

However, the 3D routines for Cell Array (GCA3) and Text (GTX3) have calling sequences which are substantially changed. GCA3 is not described here, and those brave enough to peruse the standards document will see why. Concerning GTX3, it should be emphasized that this function is only required if it is desired to place text on a surface which is not parallel to the X-Y plane, otherwise the 2D text function (GTX) is sufficient. For example, one would need to use GTX3 to write 'MIGROS' on the side of a truck drawn with some random orientation.

The function call for 3D Text is:

CALL GTX3(PX, PY, PZ, TDX, TDY, TDZ, STR) where the arguments are as follows:

PX, PY, PZ: Reference Point (start point of text string)
TDX/Y/Z(2): Two Text Direction vectors (three real arrays of length 2).
STR: The character string to be output.

For both GTX and GTX3 the character string, STR, is drawn in a plane. The difference is that in the 3D case this text plane can be oriented in space using two text direction vectors, U and V, specified by TDX(1), TDY(1), TDZ(1), and TDX(2), TDY(2), TDZ(2). The text is drawn in a plane perpendicular to the vector formed from taking the vector product U x V, and the origin of the local coordinate system in which the geometric text attributes are measured is defined by the reference point, P. The X axis of the local text coordinate system is parallel to the first direction vector, U, and the Y axis is perpendicular to this direction. Thus, the system reduces to the 2D case if U and V are defined as (1, 0, 0) and (0, 1, 0). An example program using 3D Text is given in Appendix .

The additional primitive, called Fill Area Set (or Fill Area Set 3), generates a set of polygonal areas which may be hollow or filled with a uniform colour, pattern, or hatch style. Thus, it allows the application to specify regions with holes, or disjoint regions which must be treated as a single entity. There are both 2D and 3D versions of Fill Area Set, and the 2D function will be added to the next revision of GKS. Unlike the Fill Area primitive, Fill Area Set and Fill Area Set 3 have separate attributes, described below, to control the edge style of the polygons. The calls are:

CALL GFAS(NPTR, PTR, PX, PY) CALL GFAS3(NPTR, PTR, PX, PY, PZ) where the arguments are as follows:

NPTR: (integer) Number of fill areas in set
PTR(NPTR): (integer) Array of pointers to starting elements of lists in PX(N), PY(N), PZ(N). Total number of coordinates is PTR(NPTR)-1.
XA/YA/ZA(*): (real) List of points for all fill areas of the set.

Thus, all the polygons are packed into the arrays, XA(N), YA(N), ZA(N), and the start point of each polygon is indicated by the pointers in the array PTR(NPTR).

Although they are specified in a 3D space, the primitives Text, Cell Array, Fill Area, and Fill Area Set are all coplanar. It is the responsibility of the application program to ensure that the coordinates supplied fulfil this condition. What happens if they are not coplanar is implementation-dependent!

The Output Attributes

As for the primitives, GKS-3D uses almost the same output attributes as GKS-2D (described in Chapter ), but with the three following additions:

Extra attributes are required for the new Fill Area Set primitive.
The View Index attribute. This is analogous to the Normalization Transformation index attribute, and specifies which viewing transformation is to be used to process the primitive.
The Hidden Line/Hidden Surface (HLHSR) attribute specifies which HLHSR algorithm should be used to process the primitive (if HLHSR is supported by the workstation).

The Fill Area Set primitive uses the same attributes as Fill Area to control the interior of the polygons (see section ), plus the following which allow independent control of the edges:

EDFLAG: the Fill Area Set edge flag (ASF 1). Set by GSEDFG(EDFLAG). EDFLAG may take the vales 'GON' or 'GOFF'.
EDTYPE: the Fill Area Set edge type (ASF 2). Set by GSEDT(EDTYPE). EDTYPE is an integer value which is workstation-dependent.
EDWSF: the Fill Area Set edge width scale factor (ASF 3). Set by GSEWSC(EDWSF). The value of EDWSF is a real number which modifies the width of the line used to draw the edge of the Fill Area Set.
EDCI: the Fill Area Set edge colour index (ASF 4). Set by GSEDCI(EDCI).

The numbers in brackets are, for the GTS-GRAL implementation, the indices into the integer array ASFLST(4) used to set the corresponding Attribute Source Flags by calling: CALL GASF3(ASFLST) However, the DIS FORTRAN binding uses GASF3 to set all the Attribute Source Flags in one go by defining the array ASFLST to be of length 17, where elements 1 to 13 correspond to the 2D case and the last four elements are those listed here.

Note that the Fill Area Set primitive is rendered using two independent sets of attributes, one for the interior, and one for the edge. This separate set of edge attributes also has its own attribute bundle, selected by calling GSEDI, plus a corresponding routine to Set the EDge Representation:

GSEDI(EDI) and GSEDR(WKID, EDI, EDFLAG, EDTYPE, EDWSF, EDCI)

Viewing in 3D

Setting up the Viewing Parameters is undoubtedly the most complicated part of any 3D graphics system. When primitives are output to a workstation they (conceptually) pass through a series of processes called the Viewing Pipeline before they finally reach the display surface. This pipeline is briefly described below in order that the reader is aware of the complete process (see ). The transformations will then be covered in more detail.

The primitives are transformed by the Normalization Transformation from World Coordinates (WC3) to Normalized Device Coordinates (NDC3), which are always in the range [0.0, 1.0]. This transformation is composed of a translation and change of scale, but no rotation. GKS-3D allows for the existence of many World Coordinates systems, and their corresponding Normalization Transformations are numbered from 0 upwards. Normalization Transformation 0 always corresponds to the identity matrix. Normalization in 3D is exactly analogous to the 2D case described in section .
Primitives which are stored in segments are also processed by the Segment Transformation before proceeding to the next stage. In the 3D case this requires a 3 x 4 matrix which is described below. The segment transformation maps NDC3 to NDC3, and includes scaling, rotation, and translation.
Having assembled the components in a unique NDC3 space, primitives may next be clipped to a box to remove extraneous information. This is called the Normalization Clip, and may be switched on or off using the Normalization Clip Flag.
The primitives are now 'viewed' from some arbitrary direction. The View Orientation Transformation performs a rotation only to take Normalized Device Coordinates to View Reference Coordinates (VRC3). The application is free to calculate the corresponding matrix itself, or to use a utility routine which is described below.
The View Mapping (Projection) Transformation next takes View Reference Coordinates to Normalized Projection Coordinates (NPC3) in order to provide parallel or perspective projection of the image. As for the View Orientation Transformation, the application is free to calculate the required matrix using its own algorithm, or to call a utility function. The GKS-3D Viewing Pipeline
At this point the View Clip takes place. It is positioned at this stage in the pipeline so that the clip box may be defined as a rectangular parallelepiped with its sides parallel to the axes of the NPC3 system, and thus the clipping algorithm is more efficient. The View Clip is controlled by three Clip Flags which allow clipping to be turned on or off separately for the front plane, back plane, and window.
Finally, the Workstation Transformation takes Normalized Projection Coordinates to Display Coordinates (DC3) in order to position the projected image in the device coordinate space. It preserves the aspect ratio, and includes a clipping operation which cannot be disabled. As their clip faces are parallel, the View Clip and Workstation Clip are usually combined internally for efficiency. DC3 coordinates may be in metres or raster units. The Workstation Window limits are [0,1]x[0,1]x[0,1].

A good implementation of the graphics pipeline will attempt to combine as many as possible of the stages in the pipeline using matrix concatenation in order to reduce the amount of computation necessary.

The Normalization Transformation

As in the 2D case, this is specified by a Window volume in World Coordinates, and a Viewport volume in Normalized Device Coordinates. The Normalization Clip is controlled as for GKS-2D (see section ). The calls are:

CALL GSW3(TNR, WN) CALL GSV3(TNR, VP) where WN and VP are real arrays of dimension 6 containing (XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX).

The View Orientation Transformation

The View Orientation Transformation algorithm provided by a utility function in the GKS-3D standard performs a rotation in three dimensions in order to take Normalized Device Coordinates to View Reference Coordinates (VRC3), where the axes are labeled U, V and N (see ). The definition of the UVN system requires the application to specify:

The View Reference Point (VRP), which is a point on or near the object to be viewed, and is the origin of the VRC3 system.
The View Plane Normal (VPN), which points from the View Reference Point towards the eye point. The VPN is the third axis of the VRC3 system, and the plane perpendicular to the View Plane Normal through the View Reference Point is called the View Reference Plane.
The View Up Vector (VUV), which defines the direction to be considered as 'UP' within the View Plane. It is the second axis of the VRC3 system. Clearly, the View Plane Normal and the View Up Vector must not be defined to be collinear.

Thus, in the View Reference system, the axis N is along the View Plane Normal, the axis V is the projection of the View Up Vector onto the View Reference Plane, and the axis U is constructed to form the third axis of a right-handed coordinate system. The default transformation sets the identity matrix. The limits of the VRC3 system are [0,1]x[0,1]x[0,1]. The GKS-3D View Reference System The View Reference Point, defined in World Coordinates, should be situated near the object to be viewed. The View Plane Normal is directed at the eye point.

The View Mapping (Projection) Transformation

The View Mapping (Projection) Transformation provided by a utility function in the GKS-3D standard takes View Reference Coordinates to Normalized Projection Coordinates (NPC3), and the projection may be either parallel or perspective (see ). The default View Mapping Transformation sets the identity matrix.

The transformation maps the View Volume in VRC3 space to a rectangular parallelepiped in Normalized Projection Coordinates. The horizontal and vertical boundaries of the View Volume are specified by the projectors drawn from the Projection Reference Point (the centre of projection) to the corners of the View Window, which is a rectangle parallel to the View Reference Plane, and with edges parallel to the U and V axes. The View Window cuts the N axis of the VRC3 system at the View Plane Distance (VPD) from the View Reference Point. The hither (front) and yon (back) boundaries of the View volume are specified by the Front Plane and the Back Plane, which are planes parallel to the View Reference Plane at distances from the View Reference Point called the Front Plane Distance (FPD) and the Back Plane Distance (BPD).

The rectangular parallelepiped in NPC3 to which the View Volume is mapped, called the Projection Viewport Limits, is specified by the two points (XMIN, YMIN, ZMIN) and (XMAX, YMAX, ZMAX). Although the View Mapping operation maps a volume to a volume, which is slightly different from the usual idea of projection onto a plane, a little thought should (hopefully) convince the reader that the effect is equivalent. Consider looking at the result along the N axis; the effect is that the contents of a truncated pyramid are distorted to map into a rectangular volume, and thus objects closer to the viewer will be magnified.

For parallel projection, the projectors are parallel to a line drawn from the Projection Reference Point to the centre of the View Window, and thus the PRP should be set in the middle of the View Window to produce an orthographic projection. In this case the actual Z value of the PRP is unimportant, so long as it is not identical to the View Plane Distance.

The View Clip takes place at the edges of the View Clipping Limits according to the setting of the clipping indicators. There are three of these: the x-y clipping indicator, the front clipping indicator, and the back clipping indicator. The default clipping limits are set to [0,1]x[0,1]x[0,1] and all clipping indicators set to clip on ('GCLIP'). It would normally be the case that the View Clipping Limits and the Projection Viewport Limits were set to the same values, but this is not a requirement. If not set to be co-incident, there is clearly the possibility for an application to clip away all of the image by mistake! The GKS-3D Projection System The figure shows the definition of the View Volume with Perspective Projection.

Setting the 3D View Representation

Having described the concepts, this section will attempt to explain how all these parameters are actually set. This is an area of the GKS-3D standard which was modified fairly late, and release 2.0 of GKSGRAL-3D still took place before the publication of the Draft International Standard for the FORTRAN binding .

As for the Normalization Transformation, there may be more than one Viewing Transformation (actually, combined Viewing and Projection Transformation plus Clip), and the different transformations are specified by a View Index. However, unlike the Normalization Transformation, which applies to all primitives no matter on which workstation they are displayed, the Viewing Transformation is workstation-dependent, and so the same VieW Index (VWI) may produce a different effect on each active display. The View Index is set using the routine:

CALL GSVWI(VWI) Following this call all primitives will be transformed according to the parameters specified by viewing attribute bundle VWI, assuming that the deferral mode set has allowed the workstation to be brought up-to-date. The default viewing attributes, corresponding to VWI = 0, define identity matrices for the View Orientation and View Mapping transformations, and place the clip limits at the boundary of NPC3 space.

As indicated, the attribute values contained in the viewing attribute bundle specified by VWI must be defined separately for each workstation using the call:

CALL GSVWR(WKID, VWI, VWM, PRM, VCLP, CLW, CLB, CLF)

WKID: Workstation Identifier
VWI: The View Index
VWM: The View Orientation Matrix (a 4 x 4 real array), which may be calculated by the function GEVVWM
PRM: The Projection (View Mapping) Matrix (a 4 x 4 real array), which may be calculated by the function GEVPJM
VCLP: The View Clipping Limits (XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX)
CLW: Clip Indicator for Window Clipping ('GNCLIP', 'GCLIP')
CLB: Clip Indicator for Back Plane Clipping ('GNCLIP', 'GCLIP')
CLF: Clip Indicator for Front Plane Clipping ('GNCLIP', 'GCLIP')

The utility functions provided to evaluate the matrices are EValuate VieW orientation Matrix and EValuate ProJection (View Mapping) Matrix:

CALL GEVVWM(VRPX, VRPY, VRPZ, VUPX, VUPY, VUPZ, VPNX, VPNY, VPNZ, CSW, ERR, VWM)

VRPX/Y/Z: The View Reference Point in NDC3 or WC3
VUPX/Y/Z: The View Up Vector in NDC3 or WC3
VPNX/Y/Z: The View Plane Normal in NDC3 or WC3
CSW: Switch specifying whether the vectors are given in World Coordinates or Normalized Device Coordinates ('GWC' or 'GNDC')
ERR: (out) Error indicator
VWM: (out) View Matrix (a 4 x 4 real array)

CALL GEVPJM(UMIN, UMAX, VMIN, VMAX, PRVP, PROTYP, PRPU, PRPV, PRPN, VPD, BPD, FPD, ERR, PRM)

U, V: (MIN,MAX) The limits of the View Window on the View Reference Plane measured relative to the View Reference Point. UMIN, VMIN is the bottom left corner, UMAX, VMAX is the top right corner.
PRVP: The Projection Viewport Limits (a 6 element real array containing XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX)
PROTYP: The Projection Type flag integer ('GPARL' or 'GPERS')
PRUP/V/N: The Projection Reference Point.
VPD: The View Plane Distance from the View Reference Point along the N axis. (Note that the View Reference Point does not have to be contained in the View Plane).
BPD, FPD: The Back and Front Plane Distances from the View Reference Point along the N axis. FPD must be greater than BPD.
ERR: (out) Error indicator
PRM: (out) Projection Matrix (a 4 x 4 real array)

The DIS FORTRAN binding of November 1988

The DIS FORTRAN binding of November 1988 has slight differences to the above. However, as all three routine names are different it should be possible to maintain both versions in the library during some transition period. The changes are as follows:

GSVWR becomes GSVWR3 with the same set of parameters.
GEVVWM becomes GEVOM3 (EValuate view Orientation Matrix). The values defining the View Up and View Plane Normal vectors have changed places.
GEVPJM becomes GEVMM3 (EValuate view Mapping Matrix). The values defining the window limits (UMIN, UMAX, VMIN, VMAX) have been placed in the array VWWLM(4), and the order of FPD and BPD has been swapped. As this order is now the reverse of that used for the equivalent PHIGS function, one of the two bindings certainly will have to be changed before final publication, and the document editor has been informed.

Workstation Transformation

This is specified by a Workstation Window volume in Normalized Projection Coordinates, and a Workstation Viewport volume in Device Coordinates. The Workstation Transformation always preserves the aspect ratio, and the default transformation will be used if the window or viewport volumes are not correctly set.

CALL GSWKW3(WKID, WKWN) CALL GSWKV3(WKID, WKVP) where WKWN and WKVP are real arrays of dimension 6 containing (XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX)

To inquire the range of device coordinates corresponding to a particular workstation type, it is possible to call the function GQDVOL (inQuire Display VOLume).

CALL GQDVOL (WTYPE, ERRIND, DCUNIT, RX, RY, RZ, LX, LY, LZ) The routine returns the units in which the display surface is measured (DCUNIT), and also the maximum x, y, and z values in each direction. Some devices, for example hardcopy plotters, are measured in metres (DCUNIT='GMETRE'), so the routine will return the actual size of the device. Other devices, for example graphics terminals, will be defined in raster or some other units (DCUNIT='GOTHU'). RX, RY, RZ are real device coordinates, and LX, LY, LZ are in integer raster units. The use of GQDVOL is analogous to the use of GQDSP, which is described in section .

But I don't see anything!

The first (and second and maybe third) time one tries out a 3D application, even after having checked the code very carefully, there may be nothing on the screen. The following is a list of possible pitfalls:

Is the View Reference Point really on or near the object to be viewed?
Is it defined in WC or NDC, and does this match the coordinate switch?
Is the View Plane Normal pointing the correct way? A classical bug is to look 180 degrees in the wrong direction. GKS-3D uses a Right-Handed system, so if the object to be viewed is at the origin, and is viewed along the Z axis, then one looks in the negative Z direction, but the VPN points in the positive Z direction (0.0, 0.0, 1.0). As only the direction and not the length of View Plane Normal vector matters, one can simply use the coordinates of the eye point to specify this vector, so long as the View Reference Point is placed at the origin.
Assuming one wants an orthographic projection, is the Projection Reference Point in the middle of the View Window?
Has the View Window (UMIN, VMIN), (UMAX, VMAX) really been set around the object?
Have the Front Plane and Back Plane distances been set correctly in front and behind the object?
Is the aspect ratio of the Normalization Viewport volume the same as that of View volume?
Are the Clipping Limits which define the projection parallelepiped correctly set within the NPC system limits? Do the Clipping Limits and Projection Viewport Limits match? It is always safer to start with clipping switched off!
Have the Workstation Window and Workstation Viewport been set to the same aspect ratio?

Segments

Segmentation operates in GKS-3D in the same way as for GKS, described in section , except that the segment transformation matrix is defined to be 3 x 4. (3 x 3 for scaling and rotation plus 3 x 1 for translation). Thus, the 2D utility routines which calculate a segment transformation matrix, GEVTM and GACTM, are modified as follows:

CALL GEVTM3(X0, Y0, Z0, DX, DY, DZ, ROTX, ROTY, ROTZ, FX, FY, FZ, SW, MXOUT) CALL GACTM3(MXIN, X0, Y0, Z0, DX, DY, DZ, ROTX, ROTY, ROTZ, FX, FY, FZ, SW, MXOUT) Similarly to the 2D case, GEVTM3 evaluates a matrix (MXOUT), whilst GACTM3 accumulates changes to an existing matrix (MXIN). Both routines require the definition of:

X0, Y0, Z0: (real) a fixed reference point about which 3D rotations take place.
DX, DY, DZ: (real) a translation (or shift) vector.
ROTX, Y, Z: (real) angles of rotation about the X, Y, and Z axes.
FX, FY, FZ: (real) X, Y, and Z scale factors.
SW: (enumerated) a switch specifying whether the reference point and shift vector are given in World Coordinates or Normalized Device Coordinates ('GWC' or 'GNDC').
MXOUT: (real) 3 x 4 output matrix composed in the order: scale, rotate, shift. In the case of GACTM, the matrix MXIN is pre-concatenated with that formed from the scale, rotate, and shift parameters, so MXOUT = SHIFT * ROTATE * SCALE * MXIN.

Once the transformation matrix has been evaluated, it may then be set in the segment by calling the routine:

CALL GSSGT3(SGNA, MTX) To INsert a SeGment into the output stream GINSG becomes: CALL GINSG3(SGNA, MTX)

Because GKS-3D is upwards compatible to GKS, one can still use the 2D versions of these routines. In this case, 2 x 3 matrices will be automatically filled-out to 3 x 4 by the suitable additions of 0s and 1s. GKS segment transformations are provided in order to orient the contents of segments with respect to the coordinate system in which their primitives were originally specified. In most cases it is extremely inefficient to modify the transformations in each segment in order to view a scene from a different direction. The viewing transformation should be used for this purpose

Graphical Input

As only the Locator and Stroke logical devices return coordinate values, only these two have 3D versions of the routines used for the three input modes. Thus, for request mode, the calls are:

CALL GRQLC3(WKID, LCDNR, STAT, TNR, VWI, PX, PY, PZ) and CALL GRQSK3(WKID, SKDNR, STAT, N, TNR, VWI, NP, PX, PY, PZ) Where, apart from the extra dimension, PZ, the only difference to the 2D calls is the addition of the View Index, VWI. (Note that as for TNR, VWI is an output parameter.) This corresponds to the index of the viewing attribute bundle used to convert the position(s) back from NPC3 coordinates to NDC3 coordinates. Of course, when using a physical 2D device, it is awkward for the user to provide the third coordinate for 3D input.

Although only Locator and Stroke have 3D functions to obtain input, all six logical devices have 3D versions of the initialization functions. For example, these allow the echo areas to be positioned in space, rather than in a plane. They will not be discussed further in this Primer.

GKS-3D Metafile

As for GKS, the GKS-3D standard has an Appendix E metafile. The logical format of the 2D and 3D Appendix E metafiles are the same. However, the contents are incompatible, as in one case points are represented by two values, and in the other by three values. The two types of metafile are clearly distinguishable by inspecting the metafile header record. In all other respects, the control and usage of the 2D and 3D metafiles are the same.

The Computer Graphics Metafile, CGM, will not initially have a 3D version. Therefore, if a CGM metafile driver is added to GKS-3D, the output could contain only a 2D projection. This would be sufficient to make a hardcopy, but only with the viewing parameters chosen when the metafile was created. At CERN, an additional output workstation is provided to produce a 2D metafile by carrying out the viewing and projection operations before outputting data to the file. This feature is useful for making hardcopies.

General Hints

System and Implementation Dependencies

As mentioned elsewhere in this document certain features of GKS and GKS-3D are system or implementation dependent. System dependencies are described in the manual appropriate for the implementation in use. The CERN-supported systems and devices are described in reference GKS/GKS-3D at CERN

The principle implementation dependencies to watch for are text fonts and fill area hatch styles, also described in GKS/GKS-3D at CERN, but it is also possible to have difficulties by inadvertently trying to exceed some maximum value, such as a table length. GKS has many inquiry function which may be used to discover the current and/or maximum value of various parameters, and it is not the intention of the Primer to describe all of them. However, one should take note of the following routines:

CALL GQWKM(ERRIND, MXOPWK, MXACWK, MXWKAS) CALL GQMNTN(ERRIND, MAXTNR) CALL GQLWK(WTYPE, ERRIND, MPLBTE, MPMBTE, MTXBTE, MFABTE, MPAI, MCOLI) or CALL GQLWK3(WTYPE, ERRIND, MPLBTE, MPMBTE, MTXBTE, MFABTE, MPAI, MEDBTE, MCOLI, MVTE) CALL GQSGP(WTYPE, ERRIND, NSGP) where the parameters are as follows:

WTYPE: workstation type (input parameter)
ERRIND: error number
MXOPWK: maximum number of simultaneously open workstations
MXACWK: maximum number of simultaneously active workstations
MXWKAS: maximum number of workstations associated with a segment
MAXTNR: maximum normalization transformation number
MPLBTE: maximum number of polyline bundle table entries
MPMBTE: maximum number of polymarker bundle table entries
MTXBTE: maximum number of text bundle table entries
MFABTE: maximum number of fill area bundle table entries
MPAI: maximum number of pattern indices
MEDBTE: maximum number of edge bundle table entries
MCOLI: maximum number of colour indices
MVTE: maximum number of view table entries
NSGP: maximum number of segment priorities

There is unfortunately no function provided to inquire the maximum available number of segments or the maximum available segment name so one must consult the relevant documentation, for example GKS/GKS-3D at CERN.

Integrating separately written modules of code.

As is the case when any independent software modules are combined into a single program, care must be taken that on entry a module saves the state of the current environment and sets up its own defaults. The original environment must then be restored on exiting from the module. This applies to saving and restoring registers when making a subroutine call no more than saving and restoring (parts of) the GKS State List and Workstation State Lists when entering a graphics module. For example, two modules of graphics code may use the same Normalization Transformation indices. If module B sets different windows and viewports than module A, then on re-using routines in A after calling module B the transformations will no longer produce the expected results.

GKS provides a mechanism to handle this situation in the form of a large set of inquiry functions. These enable a module of code to inquire at run time the values of those parameters it intends to modify in order that they may be correctly restored afterwards. In particular, functions exist to inquire attribute values and bundle table entries, values of the aspect source flags, and the normalization and viewing (for GKS-3D) transformations corresponding to a particular normalization or view index. As an example:

---- REAL WINDOW(4) REAL VIEWPT(4) ---- C Inquire current window and viewport for Transformation Number X C CALL GQNT(TNX, ERRIND, WINDOW, VIEWPT) CALL GSWN(TNX, WXMINA, WXMAXA, WYMINA, WYMAXA) ---- C Restore window which was modified for Transformation Number X C CALL GSWN(TNX, WINDOW(1), WINDOW(2), WINDOW(3), WINDOW(4)) ----

If several modules of code which are to be combined use GKS segments then clearly they must not both attempt to use the same segment names. Either one can agree before hand on the allocation of a range of names to each module, or else code can be written which assigns segment names at run time after checking that the values are not in use (see section ).

Using GKS-3D libraries for GKS (2D) applications

As GKS-3D is a super-set of GKS it is possible to run a GKS 2D application linked to a GKS-3D library. However, if a 2D code module is incorporated into a larger 3D program then the programmer must be aware that primitives will be bound to the current View Index as well as the current Normalization Transformation Index, possibly entailing 3D transformations plus view clipping. Thus, to be sure that the code within the 2D module will behave as if linked to a 2D library the View Index should be set to 0 (identity matrix) in the 3D code before calling the 2D module. This can not be done in the 2D module itself, as otherwise the linker would give an error when linking to GKS which does include the 3D function GSVWI.

Plotting numbers as text strings

For FORTRAN programmers it is possible to use the Internal Write construct to convert numeric variables to character strings for output as text primitives or via GMSG:

REAL rvar CHARACTER str*11 ---- C Set Variable rvar = v1 * v2 / v3 C Convert to a character string WRITE(str, '(''RVAR= '',F5.1)') rvar CALL GMSG(wkid, str) ----

GKS/GKS-3D Error Codes

The error codes defined in this section are of two types:

Those which are defined by GKS/GKS-3D.
Those which are implementation-dependent. These are between 900 and 2000.

STATES

1: GKS not in proper state: GKS shall be in the state GKCL
2: GKS not in proper state: GKS shall be in the state GKOP
3: GKS not in proper state: GKS shall be in the state WSAC
4: GKS not in proper state: GKS shall be in the state SGOP
5: GKS not in proper state: GKS shall be either in the state WSAC or in the state SGOP
6: GKS not in proper state: GKS shall be either in the state WSOP or in the state WSAC
7: GKS not in proper state: GKS shall be in one of the states WSOP, WSAC, or SGOP
8: GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP

WORKSTATIONS

20: Specified workstation identifier is invalid
21: Specified connection identifier is invalid
22: Specified workstation type is invalid
23: Specified workstation type does not exist
24: Specified workstation (wkid or [condi,wtype] pair) is open
25: Specified workstation is not open
26: Specified workstation cannot be opened
27: Workstation Independent Segment Storage is not open
28: Workstation Independent Segment Storage is already open
29: Specified workstation is active
30: Specified workstation is not active
31: Specified workstation is of category MO (Metafile Output)
32: Specified workstation is not of category MO (Metafile Output)
33: Specified workstation is of category MI (Metafile Input)
34: Specified workstation is not of category MI (Metafile Input)
35: Specified workstation is of category INPUT
36: Specified workstation is Workstation Independent Segment Storage
37: Specified workstation is not of category OUTIN
38: Specified workstation is neither of category INPUT nor of category OUTIN
39: Specified workstation is neither of category OUTPUT nor of category OUTIN
40: Specified workstation has no pixel store read-back capability
41: Specified workstation type is not able to generate the specified drawing primitive
42: Maximum number of simultaneously open workstations would be exceeded.
43: Maximum number of simultaneously active workstations would be exceeded.

2D TRANSFORMATIONS

50: Transformation number is invalid
51: Rectangle definition is invalid
52: Viewport is not within the Normalized Device Coordinate unit square
53: Workstation window is not within the Normalized Device Coordinate unit square
54: Workstation viewport is not within the display space

2D OUTPUT ATTRIBUTES

60: Polyline index is invalid
61: A representation for the specified polyline index has not been defined on this workstation
62: Line type is less than or equal to zero
63: Specified line type is not supported on this workstation
64: Polymarker index is invalid
65: A representation for the specified polymarker index has not been defined on this workstation
66: Marker type is less than or equal to zero
67: Specified marker type is not supported on this workstation
68: Text index is invalid
69: A representation for the specified text index has not been defined on this workstation
70: Text font is less than or equal to zero
71: Requested text font is not supported for the specified precision on this workstation
72: Character expansion factor is less than or equal to zero
73: Character height is less than or equal to zero
74: Length of character up vector is zero
75: Fill area index is invalid
76: A representation for the specified fill area index has not been defined on this workstation
77: Specified fill area interior style is not supported on this workstation
78: Style (pattern or hatch) index is less than or equal to zero
79: Specified pattern index is invalid
80: Specified hatch style is not supported on this workstation
81: Pattern size value is not positive
82: A representation for the specified pattern index has not been defined on this workstation
83: Interior style PATTERN is not supported on this workstation
84: Dimensions of colour array are invalid
85: Colour index is less than zero
86: Colour index is invalid
87: A representation for the specified colour index has not been defined on this workstation
88: Colour is outside range [0,1]
89: Pick identifier is invalid
90: Interior style PATTERN not supported by this workstation.
91: Dimensions of colour array invalid
92: Colour index less than zero
93: Colour index invalid
94: A representation for the specified colour index has not been specified on this workstation.
95: A representation for the specified colour index has not been pre-defined on this workstation.
96: Colour is outside range [0,1].
97: Pick identifier is invalid

2D OUTPUT PRIMITIVES

100: Number of points is invalid
101: Invalid code in string
102: Generalized drawing primitive identifier is invalid
103: Content of generalized drawing primitive data record is invalid
104: At least one active workstation is not able to generate the specified generalized drawing primitive
105: At least one active workstation is not able to generate the specified generalized drawing primitive under the current transformations and clipping rectangle.

SEGMENTS

120: Specified segment name is invalid
121: Specified segment name is already in use
122: Specified segment does not exist
123: Specified segment does not exist on specified workstation
124: Specified segment does not exist on workstation Independent Segment Storage
125: Specified segment is open
126: Segment priority is outside the range [0,1]
-127: (GTS-GRAL only) Number of segments exceeded, create failed.
-128: (GTS-GRAL only) Transformation matrix invalid

INPUT

140: Specified input device is not present on workstation
141: Input device is not in REQUEST mode
142: Input device is not in SAMPLE mode
143: EVENT and SAMPLE input are not available at this level of GKS
-143: (GTS-GRAL only) EVENT and SAMPLE input are not available for the specified workstation.
144: Specified prompt and echo type is not supported on this workstation
145: Echo area is outside display space
146: Contents of input data record are invalid
147: Input queue has overflowed
148: Input queue has not overflowed since GKS was opened or the last invocation of Inquire Input Queue Overflow
149: Input queue has overflowed, but associated workstation has been closed
150: No input value of the correct class is in the current event report
151: Timeout is invalid
152: Initial value is invalid
153: Length of initial string is greater than the implementation defined maximum
154: Length of initial string is greater than the buffer size

METAFILES

160: Item type is not allowed for user items
161: Item type is invalid
162: No item is left in GKS metafile input
163: Metafile item is invalid
164: Item type is not a valid GKS item
165: Content of item data record is invalid for the specified item type
166: Maximum item data record length is invalid
167: User item cannot be interpreted
168: Specified function not supported by this level of GKS-3D
-170: (GTS-GRAL only) Wrong CGM code during TEST OPEN
-171: (GTS-GRAL only) CGM not in state TEST OPEN during APPEND TEXT
-172: (GTS-GRAL only) Local text buffer too small

ESCAPE

180: Specified function is not supported
181: Specified escape function identification is invalid
182: Contents of escape data record are invalid

MISCELLANEOUS

200: Specified error file is invalid

SYSTEM

300: Specified function is not supported in this level of GKS
301: Storage overflow has occurred in GKS
302: Input/Output error has occurred whilst reading (eg font files)
303: Input/Output error has occurred whilst writing
304: Input/Output error has occurred whilst sending data to a workstation
305: Input/Output error has occurred whilst receiving data from a workstation
306: Input/Output error has occurred during program library management
307: Input/Output error has occurred whilst reading workstation description table
308: Arithmetic error has occurred

3D TRANSFORMATIONS

400: View up vector and view plane normal are collinear
401: View plane normal is null a vector
402: View up vector is a null vector
403: Projection viewport limits are not within NPC range
404: Projection reference point is between front and back clipping planes
405: Projection reference point is on the view plane
406: Box definition is invalid
407: Viewport is not within NDC unit cube
408: Specified view index is invalid
409: A representation for the specified view index has not been defined on this workstation.
410: A representation for the specified view index has not been pre-defined on this workstation.
411: Workstation window limits are not within the NPC unit cube
412: Back clipping plane is in front of front clipping plane

3D OUTPUT ATTRIBUTES

420: Edge index is invalid
421: A representation for the specified edge index index has not been defined on this workstation.
422: A representation for the specified edge index index has not been pre-defined on this workstation.
423: Edge type equal to zero
424: Specified edge type not supported by this workstation
425: Edge width scale factor less than zero
426: Pattern reference vectors are collinear
427: Specified HLHSR mode not supported on this workstation
428: Specified HLHSR identifier invalid
429: Specified HLHSR mode invalid

3D OUTPUT PRIMITIVES

430: The text direction vectors are collinear
431: List of points is invalid
432: At least one active workstation is not able to generate the specified generalized drawing primitive under the current transformations and clipping volume.

IMPLEMENTATION DEPENDENT

Device independent errors

-600: (GTS-GRAL only) Invalid values for cubic curve
900: Enumeration type out of range
901: Output parameter size insufficient
902: List member or set element not available (for inquiry routines)
903: Invalid data record - cannot be decoded; (Errors 900-903 may also appear as errors 500-503. Stay tuned.)
-920: (GTS-GRAL only) DSYS-error: keys outside range (MINKEY,MAXKEY)
-921: (GTS-GRAL only) DSYS-error: key (K1,K2) already present
-922: (GTS-GRAL only) DSYS-error: key (K1,K2) does not exist
-924: (GTS-GRAL only) DSYS-error: buffer size in GKDSGC too small, records truncated
-925: (GTS-GRAL only) DSYS-error: incorrect record size used (installation problem)
-927: (GTS-GRAL only) DSYS-error: whilst reading record from external file
-928: (GTS-GRAL only) DSYS-error: whilst writing record to external file
-929: (GTS-GRAL only) DSYS-error: whilst reading record from external file (Garbage file)
-930: (GTS-GRAL only) DSYS-error: whilst writing record to external file (Garbage file)
-950: (GTS-GRAL only) Missing font files
-1000: (GTS-GRAL only) Implementation Error

Device dependent errors

-7301: (GTS-GRAL only) UIS driver error in file WINDOW.DAT
-7302: (GTS-GRAL only) UIS driver error: not enough coordinates to open window
-7303: (GTS-GRAL only) UIS driver error: no logical unit is free

Typical 7xxx errors include the inability to open or read Font files, Apollo gks_characteristic files, etc. These are usually due to incorect installation. For example, files may be missing or have the wrong format, windows may have illegal sizes, etc.

Error codes specific to the FORTRAN language binding

2000: Enumeration type out of range; the integer passed as a GKS enumerated type is not within the range of valid values.
2001: Output parameter size insufficient; a FORTRAN array or string being passed as an output parameter is too small to contain the returned information.
2002: List element or member not available; for a non-empty list or set, a value less than zero or greater than the size of a list or set was passed as the requested list element or set member in an inquiry routine.
2003: Invalid data record; the data record cannot be decoded, or there was a problem encountered when the data record was created, making the result invalid.

RESERVED ERRORS

Unused error numbers less than 2000 are reserved for future standardization.

Error numbers 2000-3999 are reserved for language bindings.

Error numbers greater than 4000 are reserved for future registration.

Metafile Items

Note that whilst the structure of the 2D and 3D GKS Appendix E metafiles is the same, their contents are not inter-changeable. For example, item 11 corresponds to a polyline in both cases. However, in the 3D metafile each point in item 11 is represented by three coordinates, rather than by 2 coordinates in the 2D case.

GKS

The following is a list of the GKS Appendix E Metafile item numbers (2D).

General

0: End item (last item of every metafile)
1: Clear workstation
2: Re-draw all segments on workstation
3: Update workstation
4: Set deferral state
5: Message
6: Escape

Items for Output Attributes

11: Polyline
12: Polymarker
13: Text
14: Fill Area
15: Cell Array
16: Generalized Drawing Primitive

Items for Output Primitive Attributes

21: Polyline index
22: Line type
23: Line width scale factor
24: Polyline colour index
25: Polymarker index
26: Marker type
27: Marker size scale factor
28: Polymarker colour index
29: Text index
30: Text font and precision
31: Character expansion factor
32: Character spacing
33: Text colour index
34: Character vectors
35: Text path
36: Text alignment
37: Fill area index
38: Fill area interior style
39: Fill area style index
40: Fill area colour index
41: Pattern size
42: Pattern reference point
43: Aspect source flags
44: Pick identifier

Items for Workstation Attributes

51: Polyline representation
52: Polymarker representation
53: Text representation
54: Fill area representation
55: Pattern representation
56: Colour representation

Items for Transformation

61: Clipping area
62: Clipping indicator
71: Workstation window
72: Workstation viewport

Items for Segment Manipulation

81: Create segment
82: Close segment
83: Rename segment
84: Delete segment

Items for Segment Attributes

91: Set segment transformation
92: Set visibility
93: Set highlighting
94: Set segment priority
95: Set detectability

User Items

>100: User item (comments etc)

GKS-3D

The following is a list of the GKS-3D Appendix E Metafile item numbers.

General

0: End item (last item of every metafile)
1: Clear workstation
2: Re-draw all segments on workstation
3: Update workstation
4: Set deferral state
5: Message
6: Escape

Items for Output Attributes

11: Polyline 3
12: Polymarker 3
13: Text 3
14: Fill Area 3
15: Fill Area Set 3
16: Cell Array 3
17: Generalized Drawing Primitive 3

Items for Output Primitive Attributes

21: Polyline index
22: Line type
23: Line width scale factor
24: Polyline colour index
25: Polymarker index
26: Marker type
27: Marker size scale factor
28: Polymarker colour index
29: Text index
30: Text font and precision
31: Character expansion factor
32: Character spacing
33: Text colour index
34: Character vectors
35: Text path
36: Text alignment
37: Fill area index
38: Fill area interior style
39: Fill area style index
40: Fill area colour index
41: Set edge index
42: Set edge flag
43: Set edge type
44: Set edge width scale factor
45: Set edge colour index
46: Pattern size
47: Pattern reference point and vectors
48: Aspect source flags 3
49: Aspect source flags
50: Pick identifier

Items for Workstation Attributes

51: Polyline representation
52: Polymarker representation
53: Text representation
54: Fill area representation
55: Edge representation
56: Pattern representation
57: Colour representation

Items for Transformation

61: Clipping volume
62: Clipping indicator
63: View index
64: View representation 3
65: HLHSR identifier
66: HLHSR mode
71: Workstation window 3
72: Workstation viewport 3

Items for Segment Manipulation

81: Create segment
82: Close segment
83: Rename segment
84: Delete segment

Items for Segment Attributes

91: Set segment transformation 3
92: Set visibility
93: Set highlighting
94: Set segment priority
95: Set detectability

User Items

>100: User item (comments etc)

Changes between versions 1.1 and 2.0 of GKSGRAL-3D

This appendix is included for the reasons given in the note at the head of the chapter on GKS-3D. Most of the changes concern the way in which the viewing parameters are specified. This was changed in the functional standard in order to separate cleanly the setting of the viewing and projection matrices in the view representation from their evaluation. In addition, the conceptually different functions of the View Projection Limits and View Clipping Limits now are dis-entangled.

The committee responsible for the FORTRAN language binding has adopted, as a general rule, to pass in an array groups of more than 4 associated variables. The intention is to reduce to manageable proportions the number of arguments passed in subroutine calls. However, there is the unfortunate side effect that not all 3D equivalents of 2D functions have analogous argument lists. For example:

CALL GSWN(TNR, WXMIN, WXMAX, WYMAX, WYMAX) CALL GSW3(TNR, WN) where WN is an array containing (WXMIN, WXMAX, WYMAX, WYMAX, WZMAX, WZMAX)

Alphabetic list of changed functions

GEVVM: Name changed to GEVVWM with new parameter list. Vectors which were previously specified using arrays are now specified by individual components.
GFAS3: Parameter list changed.
GQDVO: Name changed to GQDVOL
GSVP3: Name changed to GSV3 with modified parameter list. The six coordinates specifying the viewport have been placed in an array.
GSVWR: The parameter list has been substantially changed. Those parameters used to specify the View Projection (mapping) Matrix have been placed in a new routine, GEVPJM.
GSWKV3: Modified parameter list. The six coordinates specifying the viewport have been placed in an array.
GSWKW3: Modified parameter list. The six coordinates specifying the window have been placed in an array.
GSWN3: Name changed to GSW3 with modified parameter list. The six coordinates specifying the window have been placed in an array.

Changes between versions 2.6 and 3.2 of GKSGRAL

In order to provide stability, the version of the GTS-GRAL GKS implementation distributed at CERN has been maintained at 2.6 since early 1988. However, in order to incorporate all the latest bug fixes, and also to take advantage of various improvements, it will be necessary eventually to install and distribute release 3.2. (The intermediate versions have been skipped.) This is a major update of GKSGRAL which unfortunately will require some minor coding changes for a few applications. The reason is that Version 2.6 had not incorporated a few last-minute corrections to the ISO Fortran binding, but Version 3.2 exactly follows the standard.

Apart from bug fixes, the principal modifications are as follows:

There are changes to the routines GIITM, GINSK, GPREC, GUREC in order to make them compatible with final version of the ISO Fortran binding.
The default value for the Aspect Source Flags has been changed from 'bundled' to 'individual'. A routine GXOPKS is available which keeps the default value for the Aspect Source Flags as 'bundled'. However, most applications at CERN user 'individual' attributes, and all the standard CERN example programs start by calling GSASF rather than accepting the default. Thus, this change is in fact in line with recommended CERN practice, as well as with many other implementations of GKS.
The source code has been re-written in Fortran 77, rather than for the FLECS pre-compiler. This makes it more readable, and also run faster on some machines.
The handling of segment storage is now implemented differently which provides improved performance. For VAX/VMS installations segment store is now held partially in dynamically allocated main memory and partially on disk. For other installations segment store is now held partially in statically allocated main memory and partially on disk.
Various new utilities have been added:

GUSPKA
set pick aperture
GUQBXB
inquire segment names
GUSHLC
set highlight colour
GUICGM
interpret CGM metafile
GUCTXW
connect text with workstation
These utilities are documented in the latest GKSGRAL manual available from GTS-GRAL, and they will be added to a future version of the manual available from CERN. However, users are warned that use of these features is non-standard.
Generalized Drawing Primitives using the Fill Area attribute are now available.
The internal link routine GKDDLK has been modified, but this will only affect those people adding new drivers to the library, and so need not be discussed further.

Changes to the Fortran Binding

Clearly, the most important point for users of GKSGRAL is the first one and, in order to minimize inconvenience, the old routines remain available with the names: GXIITM, GXINSK, GXPREC and GXUREC. However, it would be preferable to change application code to match the standard binding as follows:

GINSK

CALL GINSK(WKID, SKDNR, TNR, N, IPX, IPY, PET, XMIN, XMAX, YMIN, YMAX, BUFLEN, LDR, DATREC) In comparison with the old binding, the third parameter from last (INIPOS) has been removed and should be provided as the first integer in the data record constructed by GPREC. INIPOS is the position within the buffer at which points will be added or replaced.

GIITM

CALL GIITM(TYPE, IDRL, LDR, DATAREC) In comparison with the old binding the parameter LDR has been added. This is the dimension of the array DATREC of 80 character records, whilst IDRL is the number of characters in the data record array. CHARACTER*80 DATREC(LDR)

GPREC/GUREC

CALL GPREC(IL,IA,RL,RA,SL,LSTR,STR,MDL,ERRIND,DL,D) CALL GUREC(DL,D,MIL,MRL,MSL,ERRIND,IL,IA,RL,RA,SL,LSTR,STR) In comparison with the old binding the parameter SL has been added, and LSTR and STR have been turned into arrays of dimension SL. Thus, the string STR is now an array of SL character strings, and the string STR(n) contains LSTR(n) characters (1>=n>=SL). INTEGER LSTR(SL) CHARACTER*(*) STR(SL)

Example Programs

example programs

The programs which follow have been written in VAX FORTRAN-77 as it is easier to read. The VAX-specific features which would need to be changed in order for the programs to become standard FORTRAN-77 are:

Upper case only
In-line comments moved to new line with 'C' in column 1
Include statements replaced by the expanded code.

Machine-readable versions of these programs are available at CERN on all the supported systems. Details are available in GKS/GKS-3D at CERN.

Polylines and Fill Areas

This program demonstrates the use of polylines and fill area. The workstation chosen here is the Tektronix 4107 (or a compatible).

PROGRAM BOX INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' INTEGER errfil PARAMETER(errfil = 10) INTEGER wkid PARAMETER(wkid = 1) INTEGER conid PARAMETER(conid = 1) REAL pxa(5), pya(5) INTEGER asflst(1:13) DATA pxa /3.0,3.0,7.0,7.0,3.0/ DATA pya /2.0,8.0,8.0,2.0,2.0/ DATA asflst /13 * gindiv/ ! set all ASFs C CALL gopks(errfil, 0) ! open gks (BUFA not used) CALL gopwk(wkid, conid, T4107) ! open workstation CALL gsasf(asflst) ! set attributes individually CALL gacwk(wkid) ! activate workstation CALL gselnt(1) ! select normalization tran CALL gswn(1, 0.0,10.0,0.0,10.0) ! set window C CALL gsln(gldash) ! set line type CALL gsfais(ghatch) ! set fill area style CALL gpl(5, pxa, pya) ! draw polyline CALL gfa(5, pxa, pya) ! draw fill area C CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close GKS END

Viewports, Polymarkers, and Text

This program draws two ducks in different viewports on the same display surface (see ). As well as the polyline and fill area primitives, it also uses polymarkers and text. The position and size of the text are determined by setting the character up vector and the character height. The workstation selected in this example is the Hewlett Packard 7470A 2 pen plotter.

PROGRAM DUCK INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' INTEGER errfil, wkid PARAMETER(errfil = 10, wkid = 1) REAL pxa(44), pya(44) INTEGER asflst(1:13) DATA pxa/0.0,2.0,4.0,6.0,8.0,10.0,12.0,14.0, * 16.4,17.0,17.3,17.8,18.5,20.0,22.0,24.0, * 26.0,28.0,29.0,28.8,27.2,25.0,23.0,21.5, * 21.1,21.5,22.8,24.1,25.1,25.2,24.2,22.1, * 20.0,18.0,16.0,14.0,12.0,10.0,8.0,6.1, * 4.2,3.0,1.3,0.0/ DATA pya/8.8,7.6,7.1,7.4,8.0,8.9,9.6,9.9, * 9.4,9.7,12.0,14.0,16.1,17.0,17.0,16.0, * 13.9,13.1,13.2,12.3,11.5,11.5,11.5,11.2, * 10.5,9.0,8.0,7.0,5.1,3.6,1.9,1.1, * 0.9,0.7,0.8,1.0,1.0,1.2,1.8,2.1, * 2.9,4.1,6.0,8.8/ DATA asflst /13 * gindiv/ ! set all ASFs C CALL gopks(errfil, 0) ! open gks (BUFA not used) CALL gopwk(wkid, 6, H475L4) ! open workstation CALL gsasf(asflst) ! set attributes individually CALL gacwk(wkid) ! activate workstation C CALL gstxfp(1, gstrkp) ! set font 1, stroke precision CALL gschh(1.5) ! set char. height C C... Set Normalization Transformation C CALL gswn(1, 0.0,30.0,0.0, 30.0)! set window CALL gsvp(1, 0.0, 0.5, 0.0, 0.4)! set viewport in lower left CALL gselnt(1) C CALL gsln(glsoli) ! set solid line type CALL gpl(44, pxa, pya) ! polyline CALL gsfais(ghatch) ! set hatch fill area CALL gfa(44, pxa, pya) ! fill area CALL gschup(-1.0, 8.0) ! set char. up vector CALL gtx(8.0, 20.0, '"Quack"') ! text at position 8,20 C C... Re-Set Normalization Transformation C CALL gsvp(1, 0.5, 1.0, 0.4, 0.8)! move vpt to upper right CALL gsmk(gast) ! set asterisk marker type CALL gpm(44, pxa, pya) ! polymarker CALL gsfais(gsolid) ! set solid fill area CALL gfa(44, pxa, pya) ! fill area CALL gschup(0.5, 1.0) ! reset char. up vector CALL gtx(7.0, 20.0, '"Quack"') ! text at position 8,20 C CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close GKS END Output produced by example 'Ducks'

Text Fonts

This program demonstrates the setting of different text Fonts, precisions and character up vectors. String precision may ignore the character-up-vector. In Font 1, char precision is treated like stroke. Font -2 is implementation-dependent.

PROGRAM FONTS INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' INTEGER errfil PARAMETER(errfil = 6) INTEGER wkid PARAMETER(wkid = 1) INTEGER asflst(1:13) DATA asflst /13 * gindiv/ ! set all ASFs C CALL gopks(errfil, 0) ! open gks (BUFA not used) CALL gopwk(wkid, 6, T4107) ! open workstation CALL gsasf(asflst) ! set attributes individually CALL gacwk(wkid) ! activate workstation CALL gselnt(1) ! select norm transf. CALL gswn(1, 0.0,10.0,0.0,10.0) ! set window C CALL gschh(0.3) ! set character height CALL gstxfp(1, gstrp) ! set font 1, string precision CALL gtx(1.0, 1.5, 'Font 1 string prec') CALL gschup(1.0, 3.0) ! set character up vector CALL gstxfp(1, gcharp) ! font 1, char precision CALL gtx(5.0, 8.0, 'Font 1 char prec') CALL gschup(-1.0, 0.5) CALL gstxfp(1, gstrkp) ! font 1, stroke precision CALL gtx(2.0, 4.5, 'Font 1 stroke prec') CALL gstxfp(-2, gstrp) ! font -2, string precision CALL gtx(2.0, 3.0, 'Font -2 string prec') CALL gschup(0.5, -1.0) CALL gstxfp(-2, gcharp) ! font -2, char precision CALL gtx(7.0, 6.5, 'Font -2 char prec') CALL gschup(1.0, 0.0) CALL gstxfp(-2, gstrkp) ! font -2, stroke precision CALL gtx(8.0, 5.5, 'Font -2 stroke prec') CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close GKS END

Request Input

This program demonstrates REQUEST input for the Choice, Locator, Valuator and String input classes. It prompts for locator positions corresponding to the vertices of a polygon, and indicates them with markers. Request Choice is then used to find out the interior style for the fill area, and a title is requested for the picture. The character height of the title is selected using valuator input and is followed by another locator request so that the operator can position the text on the screen.

PROGRAM INP INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' C INTEGER errfil PARAMETER (errfil=6) INTEGER wktyp, wkid, conid PARAMETER (wkid = 1, conid = 1) INTEGER chcdev, locdev, strdev, valdev ! device numbers PARAMETER (chcdev = 1, locdev = 1, strdev = 1, valdev = 1) INTEGER tnr, i, status INTEGER lstr, nsides, fill REAL px(10), py(10) REAL chrht, sides INTEGER errind ! error flag CHARACTER*80 str INTEGER asflst(13) DATA asflst/13 * gindiv/! set all ASFs C C Open error log file, GKS and a Workstation C OPEN (unit=errfil, file='errors', status='unknown') wktyp = T4107 ! set workstation type CALL gopks(errfil, 0) ! open gks (bufa not used) CALL gopwk(wkid, conid, wktyp) ! open workstation CALL gacwk(wkid) ! activate workstation CALL gsasf(asflst) ! set attributes individually C C request locator positions C nsides = 6 ! Why not a hexagon? CALL gmsg(wkid, 'Point to 6 vertices') DO 30 i = 1, nsides CALL grqlc(wkid, locdev, status, tnr, px(i), py(i)) CALL gpm(1, px(i), py(i)) ! Plot positions 30 CONTINUE C C Request choice for fill area interior style C 50 CALL gmsg(wkid, 'Type 1-4: hollow,solid,pattern,hatch') CALL grqch(wkid, chcdev, status, fill) CALL gsfais(fill-1) ! Set fill area style CALL gfa(nsides, px, py) ! Draw fill area C C Request string for title of picture C CALL gmsg(wkid, 'Give the title of the picture') CALL grqst(wkid, strdev, status, lstr, str) C C Request valuator for CHARACTER height C CALL gmsg(wkid, 'Give CHARACTER height (0.01 to 0.1)') CALL grqvl(wkid, valdev, status, chrht) CALL gschh(chrht) C C Request locator for text position C CALL gmsg(wkid, 'Give text position') CALL grqlc(wkid, locdev, status, tnr, px(1), py(1)) CALL gstxfp(1, gstrkp) ! font 1, stroke precision CALL gtx(px(1), py(1), str(1:lstr)) CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close gks END

Input Initialization

This program is an extension of the last one. It starts by prompting for the number of sides for the polygon, and then continues as before. However, rather than just accept the default settings for the input devices it initializes them in a suitable way. As an example, the choice device is set-up to provide a menu, and the valuator has reasonable limiting values.

Note that initialization is implementation-dependent and may also be device-dependent. This example works for GKSGRAL. .cc 6

PROGRAM initst INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' C INTEGER errfil PARAMETER (errfil=6) INTEGER wktyp, wkid, conid PARAMETER (wkid = 1, conid = 1) INTEGER chcdev, locdev, strdev, valdev ! device numbers PARAMETER (chcdev = 1, locdev = 1, strdev = 1, valdev = 1) INTEGER tnr, pet, i, status, dcunit, lx, ly INTEGER lstr, nsides, fill, lfi(4) REAL px(10), py(10) REAL chrht, sides, rx, ry, inival PARAMETER (inival = 3.0) INTEGER errind ! error flag REAL dum(2) ! dummy array CHARACTER*40 filename CHARACTER*80 str(4) ! array used by GPREC CHARACTER*30 fi INTEGER asflst(13) DATA asflst/13 * gindiv/! set all ASFs C C Open error log file, GKS and a Workstation C OPEN (unit=errfil, file='errors', status='unknown') wktyp = T4107 ! set workstation type CALL gopks(errfil, 0) ! open gks (bufa not used) CALL gopwk(wkid, conid, wktyp) ! open workstation CALL gacwk(wkid) ! activate workstation CALL gsasf(asflst) ! set attributes individually CALL gqdsp(wktyp, status, dcunit, rx, ry, lx, ly) C C Request valuator for no of sides of polygon (3-10) C Initialize echo area and valuator upper and lower limits C CALL gmsg(wkid, 'Enter the number of sides for the polygon') pet = 1 ! define prompt/echo type lstr = 0 ! data record not used CALL ginvl(wkid, valdev, inival, pet, 0.0, rx, 0.0, ry/5, * 3.0, 10.0, lstr, str) CALL grqvl(wkid, valdev, status, sides) nsides = ifix(sides) C C request locator positions C CALL gmsg(wkid, 'point to vertices') CALL grqlc(wkid, locdev, status, tnr, px(1), py(1)) CALL gpm(1, px(1), py(1)) DO 30 i = 2,nsides C C Request locator for other positions C Initialize cursor to previous position C (for devices with this capability (eg not tek 4014)) C CALL ginlc (wkid,locdev,0,px(i-1),py(i-1),pet, * 0.,rx,0.,ry,lstr,str) CALL grqlc(wkid, locdev, status, tnr, px(i), py(i)) CALL gpm(1, px(i), py(i)) 30 CONTINUE C C Request choice for fill area interior style (0-3) C Use gprec to set up the DATA record used to initialize C the logical choice device with 4 menu strings. C C Note: C The call to GPREC does not conform to the final FORTRAN Binding. C fi(1:6) = 'hollow' lfi(1) = 6 fi(7:11) = 'solid' lfi(2) = 5 fi(12:18) = 'pattern' lfi(3) = 7 fi(19:23) = 'hatch' lfi(4) = 5 CALL gprec(4, lfi, 0, dum, 23, fi, 4, status, lstr, str) CALL ginch(wkid, chcdev, 1, 2, 3, 0.8*rx, rx, 0.5*ry, ry, * lstr, str) CALL grqch(wkid, chcdev, status, fill) CALL gsfais(fill-1) ! Set fill area style CALL gfa(nsides, px, py) ! Draw fill area C C Request string for title of picture C Initialize default string and echo area C CALL gmsg(wkid, 'Give the title of the picture') CALL ginst(wkid, strdev, 14, 'picture title', pet, * 0.0 ,rx ,0.0, 0.1*ry, 80, 1, 1, str) CALL grqst (wkid, strdev, status, lstr, str) C C Request valuator for CHARACTER height C Initialize valuator echo area plus value limits 1/100 to 1/10. C CALL gmsg(wkid, 'Give CHARACTER height (0.01 to 0.1)') CALL ginvl(wkid, valdev, 0.1, pet, 0.0, rx, 0.0, ry/5, * 0.01 ,0.1, 1, str) CALL grqvl(wkid, valdev, status, chrht) CALL gschh(chrht) C C Request locator for text position C CALL gmsg(wkid, 'Give text position') CALL grqlc(wkid, locdev, status, tnr, px(1), py(1)) CALL gstxfp(1, gstrkp) ! font 1, stroke precision CALL gtx(px(1), py(1), str(1)(1:lstr)) CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close gks END

GKS-3D Segments and Viewing

This example illustrates the use of segments, segment transformations, and 3D viewing. The program first sets up the Normalization Transformation to map the whole of the WC space onto the display surface, assuming that this is either a square or a landscape-oriented rectangle. The viewing parameters are set to look along the Z axis towards the origin. The program then draws a tetrahedron in a segment with a Text 3 character string along the front bottom edge, and in the plane of the front face. Next, it re-draws the same tetrahedron in another segment, which is positioned with a segment transformation.

Note that the second tetrahedron is first drawn with visibility off, so that when the transformation is set the un-drawing and re-drawing in the new orientation does not wipe out the first tetrahedron, which would have been exactly underneath. As an alternative, the segment transformation for the second segment could have been set before calling the routine to draw the tetrahedron.

Finally, the program modifies the View Plane Normal, so that the two tetrahedra may be seen from a different direction.

PROGRAM demo3d C C Version 2.0, 18.03.88 - New FORTRAN binding C INCLUDE 'GKS$GTSDEV' INCLUDE 'GKS$ENUM' C INTEGER errfil PARAMETER (errfil=10) INTEGER wktyp, wkid, conid PARAMETER (wkid = 1, conid = 1) INTEGER chcdev, locdev, strdev, valdev ! device numbers PARAMETER (chcdev = 1, locdev = 1, strdev = 1, valdev = 1) INTEGER errind REAL vrpx, vrpy, vrpz REAL vupx, vupy, vupz REAL vpnx, vpny, vpnz REAL prpu, prpv, prpn REAL vp(6), wn(6), wkvp(6),wkwn(6),prvp(6) REAL vpd, bpd, fpd REAL umin, umax, vmin, vmax INTEGER iclw, iclb, iclf INTEGER dcunit, lx, ly, lz REAL rx, ry, rz REAL sgmtx(3,4) REAL vwmtx(4,4) REAL prmtx(4,4) INTEGER tnr, vwi PARAMETER (tnr=1, vwi=1) CHARACTER*80 str INTEGER lstr INTEGER asflst(13) DATA asflst/13 * gindiv/! set all ASFs C C Set viewing parameters. Look along Z axis TOWARDS origin C DATA vrpx, vrpy, vrpz / 0.5, 0.5, 0.5 / DATA vupx, vupy, vupz / 0.0, 1.0, 0.0 / DATA vpnx, vpny, vpnz / 0.0, 0.0, 1.0 / DATA prpu, prpv, prpn / 0.0, 0.0, 1.0 / DATA prvp / 0.0, 1.0, 0.0, 1.0, 0.0, 1.0 / DATA umin, umax /-0.5, 0.5 / DATA vmin, vmax /-0.5, 0.5 / DATA bpd, fpd, vpd /-0.5, 0.5, 0.0 / C DATA vp / 0.0, 1.0, 0.0, 1.0, 0.0, 1.0 / DATA wn /-15.0, 15.0, -15.0, 15.0, -15.0, 15.0/ DATA wkwn / 0.0, 1.0, 0.0, 1.0, 0.0, 1.0 / DATA iclw / gnclip / DATA iclb, iclf / gnclip, gnclip / C C Open error log file, GKS and a Workstation C OPEN (unit=errfil, file='errors', status='unknown') C C request the workstation type on which the program is to be run C wktyp = T4014 ! set workstation type CALL gopks(errfil, 0) ! open gks (bufa not used) CALL gopwk(wkid, conid, wktyp) ! open workstation CALL gacwk(wkid) ! activate workstation CALL gsasf(asflst) ! set attributes individually CALL gsds(wkid, gasap, gperfo) ! As Soon As Possible + regen C C Set Workstation Window and Viewport to use whole display C and also the Normalization Transformation Window and Viewport. C If the window is not square the Aspect Ratio will be distorted. C CALL gqdvol(wktyp ,errind, dcunit, rx,ry,rz, lx,ly,lz) IF (rx .ge. ry) THEN wkwn(4) = ry/rx vp(4) = ry/rx ELSE wkwn(2) = rx/ry vp(2) = rx/ry ENDIF CALL gswkw3(wkid, wkwn) CALL gsv3(tnr, vp) wkvp(1) = 0.0 wkvp(2) = rx wkvp(3) = 0.0 wkvp(4) = ry wkvp(5) = 0.0 wkvp(6) = rz CALL gswkv3(wkid, wkvp) CALL gsw3 (tnr, wn) C CALL gselnt(tnr) ! Select Normalization Tfrm CALL gsvwi(vwi) ! Select Viewing Tfrm CALL gsclip(gnclip) ! Set clipping off C C Evaluate View Matrix & Projection Matrix (with parallel projection) C Set View Representation (use same projection viewport and clip limits). C CALL gevvwm(vrpx, vrpy, vrpz, vupx, vupy, vupz, * vpnx, vpny, vpnz, gndc, errind, vwmtx) IF (errind .ne. 0) THEN WRITE(6, *) 'Error in EValuate VieW Matrix ', errind GOTO 9999 ENDIF CALL gevpjm(umin, umax, vmin, vmax, prvp, gparl, * prpu, prpv, prpn, vpd, bpd, fpd, errind, prmtx) IF (errind .ne. 0) THEN WRITE(6, *) 'Error in EValuate ProJection Matrix ', errind GOTO 9999 ENDIF CALL gsvwr(wkid, vwi, vwmtx, prmtx, prvp, iclw, iclb, iclf) CALL guwk(wkid, gperfo) ! Update Workstation C C Create two 3D segments, one with a transformation C CALL gcrsg(1) ! Create segment 1 CALL tetra ! Draw a tetrahedron CALL gclsg ! close segment CALL gcrsg(2) ! Create segment 2 CALL gsvis(2, ginvis) ! Make it invisible CALL tetra ! Draw a tetrahedron CALL gclsg ! Close segment C CALL gevtm3(2.0, 3.0, 4.0, -6.0, 3.0, 0.5, * 0.0, 0.3, 0.7, 0.5, 0.5, 0.7, gwc, sgmtx) CALL gssgt3(2, sgmtx) ! Transform segment CALL gsvis (2, gvisi) ! and make it visible C C Give user a chance to see result, then transform view C CALL gmsg (wkid, 'Hit <return> to continue') CALL grqst(wkid, strdev, errind, lstr, str) C vpnx = 0.3 ! Change direction of vpny = 0.6 ! View Plane Normal vpnz = 1.0 CALL gevvwm(vrpx, vrpy, vrpz, vupx, vupy, vupz, * vpnx, vpny, vpnz, gndc, errind, vwmtx) IF (errind .ne. 0) THEN WRITE(6, *) 'Error in EValuate VieW Matrix ', errind GOTO 9999 ENDIF CALL gsvwr(wkid, vwi, vwmtx, prmtx, prvp, iclw, iclb, iclf) CALL guwk(wkid, gperfo) ! Update Workstation C C Give user a chance to see result, then exit C CALL gmsg(wkid, 'Hit <return> to continue') CALL grqst(wkid, strdev, errind, lstr, str) C 9999 CALL gdawk(wkid) ! deactivate workstation CALL gclwk(wkid) ! close workstation CALL gclks ! close gks END SUBROUTINE tetra C C Draw a tetrahedron with a 3D text string along one edge C INCLUDE 'GKS$ENUM' C REAL plax(6), play(6), plaz(6) REAL plbx(2), plby(2), plbz(2) REAL vx(2) , vy(2) , vz(2) DATA plax / 0.0, -5.7, 5.7, 0.0, 0.0, -5.7 / DATA play / -5.0, -5.0, -5.0, -5.0, 10.0, -5.0 / DATA plaz /-10.0, 5.0, 5.0,-10.0, 0.0, 5.0 / DATA plbx / 0.0, 5.7/ DATA plby / 10.0, -5.0 / DATA plbz / 0.0, 5.0 / C CALL gpl3(6, plax, play, plaz) CALL gpl3(2, plbx, plby, plbz) CALL gschh(1.5) ! Set character height vx(1) = plax(3) - plax(2) ! Text Direction Vector 1 vy(1) = play(3) - play(2) ! Text in front plane of vz(1) = plaz(3) - plaz(2) ! the tetrahedron vx(2) = plax(5) - plax(2) ! Text Direction Vector 2 vy(2) = play(5) - play(2) vz(2) = plaz(5) - plaz(2) CALL gschup(0.0, 1.0) ! Set character up vector CALL gstxfp(1, gstrkp) ! font 1, stroke precision CALL gtx3(-5.0, -5.0, 5.0, ! Write along bottom line * vx, vy, vz, 'Demo-3D') END

GKS Include Files

At CERN there are several machine-readable include files which should be used when specifying GKS enumerated types and workstations. The use of symbolic names greatly aids programming and, even more important, program debugging. See GKS/GKS-3D at CERN. to find out where these files are stored on the various CERN systems.

The include file GTSDEV.INC contains the symbolic names and codes for the various Workstation Types available for GKSGRAL. As it may change from time-to-time it is not reproduced here, and one should consult GKS/GKS-3D at CERN. or the machine-readable version.

The following is a listing of the file ENUM.INC, containing mnemonic FORTRAN names and their values for the GKS ENUMERATION types.

C C ENUM.INC C GKS and GKS-3D Enumeration Types C ISO/IEC 8651-1 and ISO/IEC DIS 8806-1 C (Last Update: 27-04-89) C C aspect source: bundled individual INTEGER GBUNDL, GINDIV PARAMETER (GBUNDL=0, GINDIV=1) C C clear control flag: conditionally, always INTEGER GCONDI, GALWAY PARAMETER (GCONDI=0, GALWAY=1) C C clipping disable and enable INTEGER GNCLIP, GCLIP PARAMETER (GNCLIP=0, GCLIP=1) C C colour available: monochrome, colour INTEGER GMONOC, GCOLOR PARAMETER (GMONOC=0, GCOLOR=1) C C coordinate switch: World Coordinates, Normalized Device Coordinates INTEGER GWC, GNDC PARAMETER (GWC=0, GNDC=1) C C deferral mode: ASAP, BNIG, BNIL, ASTI INTEGER GASAP, GBNIG, GBNIL, GASTI PARAMETER (GASAP=0, GBNIG=1, GBNIL=2, GASTI=3) C C detectability: undetectable, detectable INTEGER GUNDET, GDETEC PARAMETER (GUNDET=0, GDETEC=1) C C device coordinate units: meters, other INTEGER GMETRE, GOTHU PARAMETER (GMETRE=0, GOTHU=1) C C display surface: empty not-empty, empty INTEGER GNEMPT, GEMPTY PARAMETER (GNEMPT=0, GEMPTY=1) C C dynamic modification: IRG, IMM INTEGER GIRG, GIMM PARAMETER (GIRG=0, GIMM=1) C C echo switch: no-echo, echo INTEGER GNECHO, GECHO PARAMETER (GNECHO=0, GECHO=1) C C fill area interior style: hollow, solid, pattern, hatch INTEGER GHOLLO, GSOLID, GPATTR, GHATCH PARAMETER (GHOLLO=0, GSOLID=1, GPATTR=2, GHATCH=3) C C highlighting: normal, highlighted INTEGER GNORML, GHILIT PARAMETER (GNORML=0, GHILIT=1) C C input device status: none, ok, no-pick, no-choice INTEGER GNONE, GOK, GNPICK, GNCHOI PARAMETER (GNONE=0, GOK=1, GNPICK=2, GNCHOI=2) C C input class: none, locator, stroke, valuator, choice, pick, string INTEGER GNCLAS, GLOCAT, GSTROK, GVALUA, * GCHOIC, GPICK, GSTRIN PARAMETER (GNCLAS=0, GLOCAT=1, GSTROK=2, GVALUA=3, * GCHOIC=4, GPICK=5, GSTRIN=6) C C implicit regeneration: mode suppressed, allowed INTEGER GSUPPD, GALLOW PARAMETER (GSUPPD=0, GALLOW=1) C C level of GKS: L0a, L0b, L0c, L1a, L1b, L1c, L2a, L2b, L2c INTEGER GL0A, GL0B, GL0C, GL1A, GL1B, * GL1C, GL2A, GL2B, GL2C PARAMETER (GL0A=0, GL0B=1, GL0C=2, GL1A=3, GL1B=4, * GL1C=5, GL2A=6, GL2B=7, GL2C=8) C C new frame action necessary: no, yes INTEGER GNO, GYES PARAMETER (GNO=0, GYES=1) C C off/on switch for edge flag INTEGER GOFF, GON PARAMETER (GOFF=0, GON=1) C C operating mode: request, sample, event INTEGER GREQU, GSAMPL, GEVENT PARAMETER (GREQU=0, GSAMPL=1, GEVENT=2) C C operating state value: GKS closed, GKS open, Workstation open, C Workstation active, Segment open INTEGER GGKCL, GGKOP, GWSOP, GWSAC, * GSGOP PARAMETER (GGKCL=0, GGKOP=1, GWSOP=2, GWSAC=3, * GSGOP=4) C C presence of invalid values: absent, present INTEGER GABSNT, GPRSNT PARAMETER (GABSNT=0, GPRSNT=1) C C projection type for 3D: Parallel or Perspective INTEGER GPARL, GPERS PARAMETER (GPARL=0, GPERS=1) C C regeneration flag: postpone, perform INTEGER GPOSTP, GPERFO PARAMETER (GPOSTP=0, GPERFO=1) C C relative input priority: higher, lower INTEGER GHIGHR, GLOWER PARAMETER (GHIGHR=0, GLOWER=1) C C simultaneous events flag: no-more, more INTEGER GNMORE, GMORE PARAMETER (GNMORE=0, GMORE=1) C C text alignment: horizontal normal, left, center, right INTEGER GAHNOR, GALEFT, GACENT, GARITE PARAMETER (GAHNOR=0, GALEFT=1, GACENT=2, GARITE=3) C C text alignment: vertical normal, top, cap, half, base, bottom INTEGER GAVNOR, GATOP, GACAP, GAHALF, * GABASE, GABOTT PARAMETER (GAVNOR=0, GATOP=1, GACAP=2, GAHALF=3, * GABASE=4, GABOTT=5) C C text path: right, left, up, down INTEGER GRIGHT, GLEFT, GUP, GDOWN PARAMETER (GRIGHT=0, GLEFT=1, GUP=2, GDOWN=3) C C text precision: string, character, stroke INTEGER GSTRP, GCHARP, GSTRKP PARAMETER (GSTRP=0, GCHARP=1, GSTRKP=2) C C type of returned values: set, realized INTEGER GSET, GREALI PARAMETER (GSET=0, GREALI=1) C C update state: not-pending, pending INTEGER GNPEND, GPEND PARAMETER (GNPEND=0, GPEND=1) C C vector/raster/other: type vector, raster, other INTEGER GVECTR, GRASTR, GOTHWK PARAMETER (GVECTR=0, GRASTR=1, GOTHWK=2) C C visibility: invisible, visible INTEGER GINVIS, GVISI PARAMETER (GINVIS=0, GVISI=1) C C workstation category: Output, Input, Output+Input, Workstation C Independent Segment Storage, Metafile Output, Metafile Input INTEGER GOUTPT, GINPUT, GOUTIN, GWISS, * GMO, GMI PARAMETER (GOUTPT=0, GINPUT=1, GOUTIN=2, GWISS=3, * GMO=4, GMI=5) C C workstation state: inactive, active INTEGER GINACT, GACTIV PARAMETER (GINACT=0, GACTIV=1) C C list of GDP attributes: polyline, polymarker, text, fill area INTEGER GPLATT, GPMATT, GTXATT, GFAATT, * GEDATT PARAMETER (GPLATT=0, GPMATT=1, GTXATT=2, GFAATT=3, * GEDATT=4) C C line type: solid, dash, dot, dash-dot INTEGER GLSOLI, GLDASH, GLDOT, GLDASD PARAMETER (GLSOLI=1, GLDASH=2, GLDOT=3, GLDASD=4) C C marker type: '.', '+', '*', 'o', 'x' INTEGER GPOINT, GPLUS, GAST, GOMARK, * GXMARK PARAMETER (GPOINT=1, GPLUS=2, GAST=3, GOMARK=4, * GXMARK=5) C C For use in Inquiry Functions returning both Current & Requested Values INTEGER GCURVL, GRQSVL PARAMETER (GCURVL=0, GRQSVL=1) C

Bibliography and References

F.R.A Hopgood, D.A. Duce, J.R. Gallop and D.C. Sutcliffe, Introduction to the Graphics Kernel System * GKS *, Academic Press, London
This book is a well written introductory guide to the concepts of GKS. It contains a large number of program fragments as examples and the corresponding illustrations. It uses a fictive programming language which somewhat resembles FORTRAN. However, a GKS reference manual containing the exact FORTRAN statements is needed in addition.
G. Enderle, K. Kansy and G. Pfaff, Computer Graphics Programming, GKS - The Graphics Standard, Springer Verlag, Berlin
This book is intended for those who want to dig down deep into the internals of GKS. Its reading is a MUST for GKS implementors or writers of GKS workstation driver code.
D.R. Myers, A Background to Computer Graphics, CERN Yellow Report 83-07, Geneva, July, 1983.
This CERN Yellow report gives a brief overview of the major concepts and terminology of Computer Graphics for non-specialists.
J.D. Foley and A. van Dam, Fundamentals of Interactive Computer Graphics, Addison-Wesley, Reading, Mass., 1982.
Although requiring to be brought up-to-date, this book is perhaps still the best standard text on the field of Computer Graphics. It is complete, but nevertheless readable by interested beginners.
Donald Hearn and M. Pauline Baker, Computer Graphics, PRENTICE-HALL International, 1986.
This may be an easier book for beginners than the previous one. It is up-to-date, but not so thorough.
CN/ASD Group, GKS/GKS-3D at CERN, Geneva, 1991.
Minimal GKS Reference Manual, CERN Program Library Long Write-Up J550, May, 1987
GKSGRAL/GKSGRAL-3D Reference Manual, GTS-GRAL, Darmstadt (CERN Version: CERN/DD/US/102, February, 1987).
CN/ASD Group, NAG Graphics at CERN, CERN/DD/US/86-100, Geneva, September, 1986.
CN/ASD Group, HPLOT and HIGZ User Guide, CERN Program Library Long Writeups Q120 and Y251 (1994)
ISO, The Graphical Kernel System (GKS), International Standard ISO 7942, Geneva, 1985.
ISO, The Graphical Kernel System (GKS) language bindings-Part 1: FORTRAN, International Standard ISO/IEC 8651-1, Geneva, 1988.
ISO, Graphical Kernel System for Three Dimensions (GKS-3D) functional description, International Standard ISO/IEC 8805, Geneva, 1988.
ISO, The Graphical Kernel System for Three Dimensions (GKS-3D) language bindings-Part 1: FORTRAN, Draft International Standard ISO/IEC DIS 8806-1, Geneva, November 1988.
ISO, The Programmer's Hierarchical Interactive Graphics System Language Bindings--Part 1: FORTRAN, International Standard ISO/IEC 9593-1, Geneva, 1991.