This part of the manual describes each of the basic routines available in the SMOG graphics system. The routines are 'basic' in that they usually correspond closely to facilities available in hardware on one or more graphical devices. Since SMOG sits below higher level routines, described in part D, which cater for commonly used applications such as graph drawing and contour display, the user may wish to turn to part D instead (chapter D1).
The SMOG graphics system is designed to produce broadly equivalent results on a number of different devices. The devices currently supported include the Xerox 8700 laser printer of the FR80 replacement programme, Tektronix 4000 series storage tube displays and Sigma 56xx raster displays. Each of these devices has different capabilities: details may be found in chapter H2. There is a variety of ways of initializing and controlling a device: these are described in chapter B2. Chapter B3 deals with how the user can specify his own coordinate system on part or all of the output device.
The basic routines for drawing are described in chapters B4 to B7. B4 deals with line drawing, including relative and absolute single lines and families of lines. B5 deals with text output while B6 deals with general controls on the output produced. B7 deals with curve drawing in the sense of using any hardware curve drawing facilities and also basic 3-D line and curve drawing, since the package has facilities for the basic perspective projection.
Since the routines described in this Part are the basic building blocks for graphical output, the examples in the text tend to be very short, with an environment assumed around the calls. Since this could lead to a situation where the user knew which routines to call, but not the order in which to call them or the rest of the program needed, each chapter describing routines ends with a complete program which demonstrates a fair cross section of the facilities described in that chapter.
All job control language, user terminal commands and other information specific to the different computer systems has been eliminated (as far as possible) from the body of this part and will be found in Part F. Chapter B8 details the error messages and codes produced by the system, together with an indication of what the user may have done wrong and how to correct the error.
Note: References to the FR80 indicate only the code produced as a result of calling the relevant routines in SMOG, not the device itself which is no longer in service. Output from the code generators is routed to the Xerox 8700 laser printer and processed according to the option required (for example HCS for hardcopy single frame on an A4 sheet).
This chapter deals with a variety of essential functions. Section B2.2 deals with the way of specifying the device or devices on which graphical output is to be produced. It also deals with the routines that allow output on one or more devices to be suspended and resumed, allowing selective output to different devices. Finally it deals with how to terminate graphics output, to one or all devices.
The RAL Graphics System allows graphical output to more than one device simultaneously. The devices may be of the same type or different. The user may choose to produce all output on all devices, or on just a selection of them, or on none. Each device is logically in one of four states: .
Routines are provided to start, suspend, resume and stop output on single devices, all devices of one type or all devices.
Each device is identified by a stream number. The interpretation of this stream number depends on the operating system: on the central IBM complex it is associated with a DDname of the form 'GRAPHnnn'. For details of the association between stream number and system object see the appropriate chapter in Part F.
On all systems a default stream is defined and routines are provided to start, suspend, resume and stop output on this stream without specifying a stream number.
Each device is driven by orders in a particular 'order code'. The order codes for different devices are usually different. Each 'code' is identified by a name (eg 'TK4010' for a Tektronix 4010 terminal). A list of the names is given in table B2.2 below. A single code generator may be used to produce the output for one or more graphics streams at the same time, saving both storage and CPU time. For instance, if the user has requested 4010 output to disk and a terminal and hard copy output to the Xerox 8700, with the HCS option, two code generators will be running (hard copy and 4010) and three streams will be active.
In some cases the operating system can provide the graphics system with the information required to identify which code generator is appropriate for a given device or stream. This can happen when for instance the device is a terminal of a known type. In other cases, for instance a disk file, the user may have to indicate the device code required. There are two routines, FRDEV and GRDEV, which will return a number that indicates the type of device to which a graphics stream is connected; by calling
CALL FRDEV (i)
or
CALL GRDEV (i,j)
the variable 'i' will be set to a value in the range 1 - 8 as shown by variable 'jcode' in table B2.3. For GRDEV, the 'j' parameter specifies the stream number; for FRDEV, the default stream is assumed.
A variety of routines may have to be called before any initialization routine is called. This requirement is specified in the individual descriptions of the commands. All other routines will produce an error message and be ignored if called before any initialization routine. Similarly it is incorrect to suspend, resume or halt output on a stream that has not been initialized.
There are two routines provided for initialization of the graphics stream, FRSPEC and a series of routines starting with the letters FR for initializing output for the FR80 replacement devices (eg the Xerox 8700).
This routine provides the simplest way of initializing the graphics system. It opens the default graphics stream. The stream used is dependent on the operating system (see Part F). The routine is only supported on those computers where the operating system can provide exact information about the code required for particular devices: this includes the RAL central IBM complex. The default graphics stream may be used in conjunction with explicitly referenced graphics streams, but only routine FRSPEC manipulates the default graphics stream alone - routines SUSPGR, RESTGR, CLOSGR, ENDSPR and FREND all deal with all graphics streams, including the default stream.
As with all the initialization routines, this routine should only be called once, although multiple calls will only produce a warning and be ignored.
The default code assumed for each type of stream on the central IBM batch system is given in table B2.1 below.
Stream connection Code generated SYSOUT=(G,,HCS) FR80 replacement, HCS option SYSOUT=(G,,HCM) FR80 replacement, HCM option SYSOUT=(G,,MFCH) FR80 replacement, MFCH option
These routines allow the user to nominate a particular device for the output on the default graphics stream. They are provided for compatibility with previous SMOG implementations since it is normal, certainly in batch, to select the output device by the special forms queue (see Fl). If the device is also selected by any means outside the program, both routes should give the same device.
There are two routines available to initialize a particular graphics stream, GRSPEC and INITCG. The first initializes for an assumed default code generator, the second for a code generator specified by the user.
This routine initializes graphics stream 'n': as noted before, the association between graphics stream numbers and system objects depends on the operating system - for batch at RAL, graphics stream 'n' connects to DDcard 'GRAPHnnn'. Thus the call
CALL GRSPEC(4)
will start graphics output on stream 4, generating the default code assumed for the type of device connected to the stream. For the list of default codes chosen, see table B2.1 above.
This routine initializes the graphics system for output on graphics stream 'n' and selects the code which is to be produced on that stream. The variable 'code' must be one of the following text strings:
code code produced FRMFCH Xerox hardcopy many up frames FRHCS Xerox hardcopy single frame FRHCM Xerox hardcopy many up frames TK4010 Tektronix 4010 display TK4002 Tektronix 4002A display TK4006 Tektronix 4006 display TK4012 Tektronix 4012/4013 displays TK4014 Tektronix 4014/4015 displays SG5600 Sigma 5600 display SG5670 Sigma 5670 display SG5671 Sigma 5671 display SG5674 Sigma 5674 display SG5664 Sigma 5664 display CC81 Calcomp 81 plotter
For example, the call
CALL INITCG (4,'FRHCS')
will initialize graphics stream 4 for output of FR80 code to the Xerox 8700 printer, with option RCS. Any externally specified device, such as HCS or HCM, should be the same as that set up internally.
Errors will be reported if the string provided does not match one of those in the above list. The graphics stream will not be opened in this case.
This routine allows the user to control all possible forms of initialization for the graphics stream through one routine. It will be found useful when the user is dynamically choosing the stream to be used or writing utility programs. The effect of the routine is to initialize stream 'n' according to the two integer parameters 'icode' and 'jcode'. The stream number may be a positive integer, indicating a particular graphics stream, or 0, indicating the default graphics stream. The 'icode' and 'jcode' parameters may take a range of values as indicated in table B2.3 below, or 'icode' may be negative, in which case the default code for the device connected to the selected stream is used (see table B2.1). The possible values for 'icode' and 'jcode' are given in table B2.3.
icode jcode code generator selected 0 7 Xerox 8700 hardcopy single and manyup frames 1 0 Tektronix 4010 1 1 Tektronix 4006 1 2 Tektronix 4012 1 3 Tektronix 4013 2 - Tektronix 4002A 3 0 Tektronix 4014 3 1 Tektronix 4015 3 2 Tektronix 4016 12 0 Sigma 5600 12 1 Sigma 5671 12 2 Sigma 5674 12 3 Sigma 5664 12 4 Sigma 5684 12 5 Sigma 5471 12 6 Sigma 5474 13 0 Calcomp 81 pen plotter
Although each graphics stream has to be initialized separately, one or more streams may be suspended by a single routine call. Suspended graphics streams remain in exactly the state (current plotting position and so on) they are in when they are suspended. Output continues to be produced on all other streams that are active.
This routine suspends all graphics output; it would normally be used to prevent any graphics output being produced despite the fact that the program is issuing calls to the graphics system, or before calling a 'resume' routine (see B2.2.4) for one or more streams. By this means just one or more streams may be activated.
This routine suspends all streams that are receiving code from the code generator indicated by 'code': the list of possible values of this parameter were given above in table B2.2.
Thus a convenient way of suspending all online output while continuing to produce FR80 code is -
CALL SUSPCG ('TK40l0')
This routine suspends output of graphics code on the stream indicated by the parameter 'n'; all other streams will be unaffected.
This routine, which has the same parameter list as RGINIT, may be used to control a single stream (if 'n' is a positive integer), all streams producing output from a particular code generator ('n' set to zero, 'icode' and 'jcode' indicating the code generator) or all streams (all parameters negative).
Although each graphics stream has to be initialized separately, one or more streams may be resumed by a single routine call. Resumed graphics streams will restart in exactly the state (current plotting position and so on) they were in when they are suspended.
This routine resumes all graphics output.
This routine resumes output all streams that are receiving code from the code generator indicated by 'code': the list of possible values of this parameter were given above in table B2.2.
Thus a convenient way of resuming all Tektronix 4010 output would be -
CALL RESTCG ('TK4010')
This routine resumes output of graphics code on the stream indicated by the parameter 'n'; all other streams will be unaffected. This may be used in conjunction with SUSPGR to enable output to be directed to a single stream at a time.
For example the sequence
CALL SUSPGR
CALL RESTST (8)
will stop graphics output on all stream except graphics stream 8.
This routine, which has the same parameter list as RGINIT, may be used to control a single stream (if 'n' is a positive integer), all streams producing output from a particular code generator ('n' set to zero, 'icode' and 'jcode' indicating the code generator) or all streams (all parameters negative).
These routines close down the default graphics stream. They are identical in effect. All output to the device is output if buffered for any reason. Any closedown sequence such as the production of the trailer frames on microfilm output, is performed on the device and finally the stream is closed down. Usually subsequent graphics output is impossible but for some devices more graphics operations are possible if the device is initialized again.
There are two routines for closing down selected streams, one for a single stream and one for all streams receiving output from one code generator.
This routine closes down graphics stream 'n'. No other streams are affected.
This routine closes down all graphics streams connected to the code generator indicated by parameter 'code': for a list of the possible values for 'code' see table B2.2.
Two routines allow all graphics output to be closed down - the second also allows full control of the graphics system by means of a single routine which may be useful for people writing utility programs.
This routine closes down all graphics streams. When only one stream has been opened, it is equivalent to FREND.
Section B3.2 describes how to select a plotting area. As explained in A1 there is a variety of ways in which this may be done, depending on whether the area is to be a particular shape, a particular physical size or is to be positioned on the medium in a specific way.
Section B3.3 deals with how a user coordinate system may be set up. This is done by providing two coordinate pairs to map onto the current plotting area. In the SMOG system there was some overlap between the functions of selecting a plotting area and defining a coordinate system: the SMOG routines involved are described in section B3.4. Section B3.5 describes the routines that allow the user to inquire about values set or assigned by selecting a coordinate system.
As was discussed in A1, it is often convenient to use less than the whole addressable area of the device or devices available and also more convenient to work in 'user coordinates', ie the coordinate system natural to the statement of the problem. This introduction discusses the facilities provided and the remaining sub-sections deal with routines that implement the facilities.
Graphics devices fall into two categories:
There is another way in which devices differ: for some, like display screens, the output can only be viewed one way round. For others, the output may be rotated by the viewer.
A user of the graphics system has a picture or series of pictures that he wants drawn. In some cases the size of the output may be known exactly, for instance text output might require the output to be exactly A4 size. A different problem may require the picture as large as possible on any device used, but square.
All these different requirements and constraints need a comprehensive system of routines to allow the user to specify what he wants clearly and concisely. In the original package the operations of
were allowed to overlap, causing confusion. While there is still complete support for the SMOG routines, a selection of new routines have been added which should make the user's task easier.
This routine specifies that the plotting area will be the maximum area visible on the device; on a terminal this is limited by the edge of the screen.
The following routines in this section are applicable to FR80 devices, but are retained here for completeness. They may or may not produce the desired effect on the FR80 replacement devices.
This routine specifies that the plotting area will be such that consecutive frames of output are abutted on the output medium. On terminals and devices that cannot support abutment the effect is the same as APER.
This routine selects the maximum area available on a device that has an aspect ratio the same as cine film. This is very close to the shape of most terminals, so normally has the same effect as APER or ABUT.
These routines have the effect specified above, except that the orientation with which the frame is located on an FR80 frame is rotated by 90 degrees clockwise.
Each of the above routines selected a plotting area on the output device. The user also has to specify the coordinate system that is associated with the plotting area. This may be done by a variety of routines. In this section, the routines that just set the coordinate system are dealt with. Section B3.4 deals with those that also change the plotting area.
These routines allow the user to specify whether the coordinate values used in subsequent calls are in his coordinate system (v=l.0 and the default) or the device's coordinate system (v=0.0). It is unusual to use device coordinates because they vary widely from device to device, making programs harder to develop.
These routines request that the addressable corners of the device have the coordinates (x1,y1) and (x2,y2) associated with them. Note that the addressable corners of the device are often not visible (especially not on a Tektronix display).
These routines request that the currently selected plotting area has the coordinates (x1,y1) and (x2,y2) associated with its corners. Note that although this ensures that all output produced is visible, the shape of the visible area varies from one device to another. Because the plotting area is not necessarily square, output may be 'squashed' or 'stretched'; for instance the sequence
CALL CINE
CALL LIMITV (-2.0 , -2.0 , +2.0 , +2.0)
CALL CIRCLA (0.0 , 0.0 , 1.5 , 0.0 , 0.0)
will produce an ellipse, not a circle, because the plotting area has an aspect ratio of 1.33 but the user coordinate system does not.
In many cases the user would like to have an area of a given aspect ratio and his own coordinate system applied to it. There are two pairs of routines in SMOG that allow this.
These routines select the maximum size area of aspect ratio 'sx/sy' that is within the current plotting area, set the plotting area to this and then applies the user coordinate system (x1,y1):(x2,y2) to this new plotting area. The new plotting area is permanently smaller than its predecessor and subsequent calls to LIMITS reduce it further. This reduction continues until the user calls APER, ABUT, CINE or a comic equivalent.
These routines set 'rx' of the user's units in the X-direction to be equivalent to 'ry' of the user's units in the Y-direction. This will normally necessitate a change of shape of the plotting area in a similar manner to that caused by LIMITS. As with LIMITS, the new plotting area is smaller than the old one.
Whereas LIMITS sets the aspect ratio for the whole new plotting area to be 'sx/sy', LIMITR sets the ratio of the sizes of the sides of a square in user coordinates to be 'rx/ry'.
For both LIMITS and LIMITR a call of the form
CALL LIMITx (A , B , A+D , B+D , 1.0, 1.0 )
will produce identical results and give the user a coordinate frame which is the largest square available on the output device.
The user often wants to tailor the size and/or location of his output rather exactly to a variety of devices. To assist him in this, a selection of routines are available.
This returns the device coordinates that describe the corner positions of the rectangle selected as the plotting area.
This returns the user coordinates that describe the corner positions of the rectangle selected as the plotting area.
The basic line-drawing command consists in the specification of a starting address on the raster of the output medium and then the instruction to draw a straight line segment from the cell with this address to the cell having a specified finishing address. In the SMOG system the issuing of a starting address causes nothing to be drawn, the instruction is output to the device and a current plotting position pointer - (XP,YP) for brevity in this text - is reset. The device awaits the completion of the command which can be the line segment instruction as above or the plotting of a "Point" or other graphic character as part of the picture.
All the following routines use coordinates that are usually specified in the user's own coordinate system; this will normally have been set by a LIMITx routine (see section A3.4). If the user has selected REGION 0 however, the values specified (whether as integer arguments or real) are taken as absolute raster coordinates on the output device(s).
Since the introduction of the IMPACT system below SMOG, windowing has been available on all output from line drawing routines. This has to be selected by the user with routine WINDON (see section A4.2) since no window is set by default. In the following discussion, solid lines are assumed in the descriptions.
Changes the current plotting position to be (X,Y); no plotting takes place. For JSETXY, the new position is (IX,IY).
Draws the line segment from the current plotting position to (X,Y) and then sets the current plotting position to be (X,Y): a straight line is drawn from the current drawing position to a specified end-point. A sequence of calls to this subroutine can thus be used to draw the approximation to a smooth, continuous curve:
CALL SETXY(Pl,P2)
DO 10 J = 1,N
10 CALL TOXY(Ql(J), Q2(J))
Draws the line segment from (X1,Y1) to (X2,Y2) using the above two instructions and sets the current plotting position to (X2,Y2).
For the above routines, there are many occasions when vertical and horizontal lines are being drawn and so either the Y or X value is not being changed. In these cases, the following routines can on some devices produce improved code and will in most cases also reduce the amount of space used for parameter lists in the user's program.
Sets the X component of the current plotting position component to 'x'. The Y component is not changed and no drawing takes place.
Sets the Y component of the current plotting position to 'y'. The X component is not changed and no drawing takes place.
Draws a line from the current position to a new current position in which the X component has been changed to 'x'.
Draws a line from the current position to a new current position in which the Y component has been changed to 'y'.
Example SMOG interpretation
CALL FRSPEC Select output device
CALL LIMIT(-3.2,-1.1.3.2,1.1) Set scales to whole area
A=3.1416
B=0.02*A
CALL SETXY(A,0.0) (XP,YP) = (3.146,0.0)
DO 10 I=1,100 draw...
CALL TOXY(A,SIN(A))
A=A-B
10 CONTINUE ... curve
CALL ADVFLM new frame
CALL FREND end graphics
Parameters are in terms of the user coordinate system dy default.
CALL FRSPEC and CALL FREND are necessary to initialize the graphics system and to ensure that all graphics output produced by the package is sent to the graphics device.
The above subroutines all map the user's coordinate specifications to unique cells in the raster on the output medium. The cells are, as it were, directly addressed from the currently selected region. The next set of subroutines allows relative displacements from the current plotting position (XP,YP) and can be thought of as indirectly addressing the raster. The subroutine identifiers have the mnemonic "DX", "DY", "DXY" included to indicate their incremental nature. They find their greatest use to be in the definition of Files of picture information (see section B6.5). These instructions, stored as command-sets in files, allow particular structures to be defined once only but used many times, often at different positions on the output medium:
Changes the current position so that the X-position is changed by 'dx'.
Changes the current position so that the Y-position is changed by 'dy'.
Changes the current position so that the X-position is changed by 'dx' and the Y-position by 'dy'.
Draws the line segment from the current (XP,YP) to a new position (XP+DX,YP) and resets the current position to (XP+DX,YP).
Draws the line segment from the current (XP,YP) to a new position (XP,YP+DY) and resets the current position to (XP,YP+DY).
Draws the line segment from the current position (XP,YP) to a new position (XP+DX,YP+DY), resetting the current position to (XP+DX,YP+DY).
Since these subroutines have incremental effect the user should be aware of the possibility of plotting out of the visible area - often for no immediately apparent reason!
Example:
SUBROUTINE CIRCLE(RAD)
C DRAW A CIRCLE, RADIUS "RAD" ABOUT
C THE CURRENT PLOTTING POSITION(XP,YP) C
TH=0.0
PH=0.0
DTH=0.031416
CALL UPDX(RAD)
DO 10 I=1,200
TH=TH+DTH
DX=RAD*(COS(TH)-COS(PH))
DY=RAD*(SIN(TH)-SIN(PH))
CALL TODXY(DX,DY)
10 CONTINUE
CALL UPDX(-RAD)
RETURN
END
This will draw a circle of any diameter at any point in the selected region.
The scaling currently being applied to the selected region will apply to this set of commands whenever they are obeyed.
Plotting outside the visible area can easily occur using this subroutine leading to missing segments in the picture.
The current plotting position is left unchanged.
These routines will draw a line from (x1,y1) to (x2,y2)i; the current position is then changed to (x2,y2). This routine calls SETXY and TOXY, which should therefore be called explicitly if a known sequence of lines is to be drawn, for instance, to draw through all (xi,yi), the user should use a routine as below:
SUBROUTINE DRLINE (X,Y,N)
REAL X(N),Y(N)
IF (N .LE. 1)
RETURN
CALL SETXY(X(1),Y(1))
DO 10 J=2,N 10
10 CALL TOXY(X(J),Y(J))
RETURN
END
One criticism levelled at previous versions of SMOG was the lack of any windowing facilities. These facilities are now available because IMPACT provides windowing for all line drawing actions. If windowing is not turned on then the routines will behave as described; if windowing is requested, any lines or parts of lines outside the window will be suppressed.
This allows the user to turn windowing on and its four arguments define the limits of the window. It will turn windowing on and define the window to be the area bounded by the rectangle with bottom left hand corner (X1,Y1) and top right hand corner (X2,Y2).
This allows the user to turn the windowing off. Subsequent calls to any windowing line drawing routine will have the same effect as a call to its non-windowing counterpart.
When considering windowing a line must be considered to have two parts: that which lies within the window (the visible part) and that which lies outside the window (the invisible part). In the following description the term 'current point' refers to the point which the windowing routines consider to be the current point and is not necessarily the same point which the output device considers to be the current point. For this reason the user should ensure that the first plotting order generated after turning windowing on or off is an absolute 'set point' instruction in both X and Y.
In a previous release of SMOG, windowed and dashed lines were not available by calling SETXY etc.. but by calling WSETXY. In case users still have programs that call these W..... routines, the following routines are provided, which are identical to their counterparts without a 'W':
Routines WSETXY, WSETX, WSETY
WUPDXY, WUPDX WUPDY
WTODXY, WTODX, WTODY
WTOXY, WTOX, WTOY
Previously when users mixed W..... and non-W..... calls, only the W..... calls were windowed; now all line drawing calls are windowed after WINDON has been called. To obtain the same effect as before, users should surround the calls for which windowing should not be done by VSTACK and VRESET (see B6.6):
C Windowing in effect
C
CALL VSTACK
CALL WINDOF
C
C The current window limits are now stacked and windowing
C has been turned off
CALL SETXY (...)
CALL TOXY (...)
C
C To turn windowing back on, just call VRESET
C
CALL VRESET
C
C Windowing is now back on
Some high level routines, eg contouring, have their own facilities for drawing dotted and dashed lines. Users may however need this facility on lines they are drawing themselves. There is a variety of methods open to the user, providing compatibility with a set of routines previously released for SMOG and some new routines.
This routine causes all subsequent vectors to be drawn with dashed strokes. The pattern produced is:
ON1 visible OFF1 invisible ON2 visible OFF2 invisible, and so on
All lengths are specified in terms of X-axis units. The pattern is continuous for multiple routines that request vector output.
This routine resets the mode in which vectors are produced so that all lines are produced as continuous visible lines.
This routine causes lines to be drawn as a sequence of points separated by a distance of 'space'. The units in which 'space' is measured is the X-axis scale.
This routine resets the mode in which vectors are produced to be continuous lines.
This routine sets the length of the dash and the gap between the dashes to 'dotlen' units in the current region's X-units.
This routine is used if a more sophisticated dashed/dotted pattern is required. The pattern is made up of repeated sets of ON1, OFF1, ON2, OFF2; the ON values are visible and the OFF values are invisible. If ON1 and ON2 are both zero then a plotting point is produced with alternate gaps OFF1 and OFF2.
These routines draw a single line from (xl,y1) to (x2,y2) according to the specified dot/dash pattern, as set by DOTINT or DOTSET.
These routines plot a line specified by the 'n' points in the 'xarray' and 'yarray' arrays according to the current dot/dash pattern set by DOTINT or DOTSET. The routine remembers how far it has progressed along each line segment and can thus be used for plotting curves.
These routines now all use the facilities in the IMPACT graphics system for dotted and dashed lines and there are no restrictions on the length of any arrays.
These routines draw the two lines (Xl,Yl) to (X2,Y2) and (X3,Y3) to (X4,Y4) and draws N-l lines between these two. The N-l lines are such as to partition the space between the two lines into N equal areas. The lines are of the form:
(Xl+a(X3-Xl),Yl+a(Y3-Yl)) to (X2+a(X4-X2),Y2+a(Y4-Y2))
where a is in the range [0,1].
The two lines can be in any direction and may intersect. For example, if (X1,Y1) = (X3,Y3), a fan of lines is produced. Of course, spacing between lines will not be constant along their length and so a coloured fan would vary in brightness. This routine does not update the current point; its value is the same on exit as it was on entry.
These routines are relative versions of the VECFAM/JVECFM routines described above. The first point is assumed to be the current point (XP,YP) and the other points are all defined to this one. This routine draws the two lines (XP,YP) to (XP+DX1,YP+DY1) and (XP+DX2,YP+DY2) to (XP+DX3,YP+DY3) and N-l lines in between.
This routine does not update the current point; its value is the same on exit as it was on entry.
The routines VECFAM and VECFAR should be used wherever possible to shade solid areas.
Two other routines use the vector family to draw a graticule over a rectangular area define by two parallel lines:
Draws the two extreme line segments: l1 from (Xl,Yl) to (Xl,Y2) and l2 from (X2,Yl) to (X2,Y2). The rectangular region defined by l1 and l2 is then partitioned by N-l lines equally spaced and parallel to the Y-axis in the selected region. A grating or graticule is thus produced.
Draws N+l lines as above, but in this case, the lines are parallel to the X -axis in the selected region.
Each draws an arrow head (V) at the current plotting position the size of which is given by DX,DY. AROWHR draws a horizontal arrow (left if DX is positive, right if DX is negative). AROWVR draws a vertical arrow (up if DY is positive, down if DY is negative).
Draw rectangles. BOXA uses VEC orders and constructs the rectangle so that the bottom left-hand corner is (X1,Y1) and the top right-hand corner is (X2,Y2), leaving the current plotting position at (X1,Y1). BOXR uses relative orders and, starting from the current position, constructs the rectangle with sides DX,DY.
It is often useful to represent numerical information in the form of characters distributed over the visible area. The characters are usually chosen from the most easily represented font for a given device, the criteria being:
In these instances the character is not an element in a text-string as such. Consequently, for the above purposes, the concept, "current plotting position" is still relevant and the following character plotting subroutines will print one character so that its lower left-hand corner, or that of its defining, or exscribed, rectangle is at the point (XP,YP), the current plotting position.
Plots the character with the code number 'I' with its lower left-hand corner at (XP,YP).
Plots the one-element string "S" located at the current position as set by SETXY or an equivalent routine.
The following commands are equivalent:
CALL HPLOTS ('S')
LOGICAL*l I
DATA I/'S'/
CALL HPLOTS(I)
SMOG supports commands to type, as opposed to draw, and although no distinct "Current typing position" pointer is maintained by the system, it is helpful to refer to a purely notional pointer (XT,YT) when we are considering the printing of text with no drawing commands interspersed.
Prints "N" characters from core location "string", starting at (XT,YT) on the output medium. If the last call was to a plotting subroutine then (XT,YT)=(XP,YP) ie in this case the text is printed from the current plotting position. Here "N" is the number of characters to be printed at this call and "string" is one of the following:
DATA LCH/4HARCH/
DATA JCH/14HEXISTENTIALISM/
where JCH is a previously dimensioned array.The pointer (XY,YT) is reset to the end of the last character and, if further text output commands follow, concatenation of the two strings occurs. Any plotting command will take (XP,YP) as its starting point, lines will be plotted as though the text were not there and (XT,YT) will be the most recent value of (XP,YP) when printing or typing is resumed. For example:
DIMENSION ITEXT(20)
READ(1,10)(ITEXT(I),I=1,18)
10 FORMAT(18A4)
with a data file on channel 1 beginning:
IN THE 'SIXTIES SURELY NO SERIOUS PHILOSOPHY STUDENT COULD HAVE FAILED T O HAVE BEEN AMUSED WHEN READING THE REVOLTING MESSES OF ORTEGA Y GA
will load the array ITEXT(I). Subsequently the instructions:
CALL HTEXT(2,'NO BIAS PLEASE - WE ARE FROM MARS')"
CALL HTEXT(26,ITEXT(12))
will cause:
NO STUDENT COULD HAVE FAILED
to be printed upon the output medium, starting at the point (XP,YP) if these happen to be an isolated pair of printing instructions. However, if printing has occurred immediately before this then the output string will be appended ie. it will start at (XT,YT).
Precisely the same effect can be obtained by any of the following examples:
CALL HTEXT(28,'NO STUDENT COULD HAVE FAILED')"
CALL HTEXT(28,28HNO STUDENT COULD HAVE FAILED)"
CALL HTEXT(28,'NO STUDENT COULD HAVE FAILED AT ALL')"
CALL HTEXT(28,35HNO STUDENT COULD HAVE FAILED AT ALL)"
In each case resetting of the notional pointer (XT,YT) takes place in anticipation of more text but the calling of a plotting routine will reset (XP,yp) and destroy (XT,YT).
The following two subroutines are for the "Typing" (ie printing as opposed to plotting) of single characters:
This prints SMOG character number "I" at (XT,YT) and resets (XT,YT) by one character space in anticipation of more text.
This prints the single-element string "S" at (XT,YT) and resets (XT,YT) in the same way as HTYPE. In each case the lower left-hand vertex of the exscribed rectangle defines the "Position" of the character.
It is often necessary to print, as a text string, a number stored in core in machine coded form. This is not a trivial operation since the process involves decoding and re-encoding before the number can be included in the printing instruction. The "Typing" of a number is performed by the following two subroutines:
Prints the number "X" as a character string starting from (XT,YT). The form in which the number is to be represented is indicated by the values "A" and "B", their interpretation being as follows:
A=0.0: E-FORMAT, field width B+7
B=0.0: I-FORMAT, field width A+1
A#0.0, B#0.0: F-FORMAT, field width A+B+2
A places and sign before and
B places after the point.
Prints the INTEGER "N" as a character string of field width l+1.
In both these cases it is the number field that is left justified to the point (XT,YT).
The SMOG system allows control of character font, size, spacing, orientation etc whenever the selected main device has the facility to implement the user's choice. (The limitations of the lineprinter, for example, as a graphic output device are that character font, orientation, spacing and size are fixed.) Format control is effected by the following subroutines:
Sets the height of the defining (exscribed) rectangle to be "Y" units in the selected region. The setting Y=0.0 causes the height to be defined by the current setting of the character spacing (set by CHSP - see below).
A more practical method of setting character size is with routine CHSIZE see below.
Defines the spacing between the character base-lines in successive lines to be "DY" units in the selected region.
Defines character spacing to be "X" units in the current Region. Note the effects of the following two subroutines:
Interprets all subsequent character spacing instructions (whether they be from within the SMOG system or from the user) as being: "The distance between the left-hand sides of the exscribed rectangles of adjacent characters", ie the usual typewriter spacing and selects mono-spacing for any subsequent text output. This is the default option.
Interprets all subsequent character spacing instructions as being: "The distance between adjacent sides of the characters' exscribed rectangles" and selects proportional spacing for any subsequent text output.
This sets character height to be "Y" units in the current region and then sets the character and line spacing to "standard" values, based upon this height, so as to provide an aesthetically pleasing format with economy. Calls to the subroutines MONO and PROP remain effective when this subroutine
Issues "n" linefeed instructions, resetting the typing position (XT,YT) to (XP,YT N*DY) where "DY" is set by the last call to LNSP or CHSIZE. The user may thus set a block of type left-justified to a margin defined by an initial call to SETX(AMARG) followed by his text output.
Resets typing position to: "Top line, left margin, new page" and uses the routine ADVFLM (B6.3). The effect is, of course, dependent upon which SMOG device has been initialised since the left-hand margin is different for each device. See also B6.2 for other device controls.
This routine sets a translation table such that character 's' will be regarded as a backspace character. It is reacted to in much the same way as NLCHAR, as described below.
The single-character string "S" is interpreted as the instruction to issue a linefeed (see Note) and carriage return to XP on the selected device. "8" can be any character in the SMOG character set or any character from the reassigned set that the user may have assembled in the text table (see Section B6.5). Since this character must be included in the input text-string, the user must be careful to count it when setting up FORTRAN READ instructions etc. The interpretation of "S" as "Linefeed" continues until either:
Note: Displacement is as set by CALL LNSP(DY) or CALL CHSIZE(Y).
The effect of not having defined a newline character differs according to the SMOG device selected. For example, the Tektronix 4010 display issues its own linefeed if text output reaches a right-hand margin. Example:
Call NLCHAR( 'T' )
CALL HTEXT( 24, 'THEN TRY TO, SEE METALLIC HYDRIDES' )
CALL NLCHAR( 'A' )
CALL HTEXT(20,29HL-A. . WET AN' COLD AN' SMOG)
will cause:
HEN RY O, SEE ME ALL- . . WET N' COLD
to be printed.
In the FR80 this subroutine defined a rotation of "R" units of pi/4 to be applied to each character that is subsequently printed. R is rounded and assigned to a type INTEGER variable in the range (D,7). R = 0.0 is the default setting. The rotation is anticlockwise with respect to a "Normally" orientated character and is not related to the last call to CHOCT(R). Proportional spacing does not work if an odd multiple of pi/4 is selected.
The SMOG Character codes are, in fact, the local "Host-machine" "'internal character code representations. From the FR80 character table in H3 it is evident that the two-digit hexadecimal coding for characters allows the printing of upper and lower case letters and many Special characters. It is possible to reassign the Host-machine codes so that, in a particular program, the user may print characters from this extended set. He is still restricted in respect of the total number of characters available to him at anyone time. The recoding is achieved by constructing a Look-UP table locally in the SMOG COMMON BLOCK named "'TEXTAB. At initialisation the table is loaded with the FR80 codes for the lineprinter characters, each being indexed by the Host-machine's code for that character. The character codes for the selected device are loaded into an array in the COMMON BLOCK TEXTAB, (see Section B6.5) and may or may not be modified by the user. Note: a user defined character set may not give the desired result on *the FR80 replacement devices.
This subroutine will cause the printing of the "Plotting-point" (a small circular dot) at the current plotting position (XP,YP). The character will be centred upon (XP,YP). Since this routine generates a low level FR80 control word no reallocation of an entry in the text-table in TEXTAB is required (see B6.5).
Note: The plotting of single characters in the above contexts leaves the current plotting position (XP,YP) unchanged.
This chapter deals with various routines that change the appearance of output produced by SMOG. The most obvious of these is colour, which is dealt with in section B6.1. This is obviously only available on devices that have some colour capability; calls to routines that change colour are ignored on other devices.
The user will want to be able to produce several different pictures: routines for advancing to a new frame (or clearing the screen on a terminal) are described in section B6.2.
Section B6.3 deals with routines that, on some devices, have particular device dependent effects, such as setting the title on a microfiche and requesting that pictures are produced with multiple user frames on a single device frame. Section B6.4 covers enquiry facilities.
This routine defines the colour, intensity and number of hits for all lines and characters drawn until its next call or a call to an equivalent colour or intensity select routine. The colour numbers, col/icol, available depend on the device being used, but for a colour terminal will range from 1 to 8 for the colours: cyan, yellow, green, magenta, blue, red, black and white.
The value of HITS should be 1.0 and XINT should be 256.0 for terminals.
Selects a new page on the output medium. On all devices other than MFCH and HCM the output is advanced one frame. On MFCH the output is moved to a new page position. On HCM a new subframe is selected. The Appendices provide fuller details of the effects of this subroutine since it presents a fresh visible area on the output medium.
Selects a new fiche if the microfiche camera is being used. On other devices is has the same effect as ADVFLM.
Before the initialisation of certain SMOG devices the user may call subroutines which, in some sense, control the output to the medium for that device. There are two such subroutines:
This should be called before initialisation for hardcopy by the instruction CALL FRHCM (Section A3.5) if the user requires other than four sub-frames (I=2,J=2) per hardcopy frame, which is the system default setting. Calling MANYUP(I,J) before calling FRHCM will result in the division of each approximately A4 frame into "I" sub-frames across and "J" sub-frames down.
This will cause "n" of the characters from the string "string" to be printed at the head of each fiche as a title. A call to this subroutine only has effect when followed, subsequently, by a call to initialise the Microfiche camera. Most of the variations in interpretation of "N" and "STR" are as described in B5.2 for subroutine HTEXT(n,string). The occurrence in "STR" of "$L" will cause "Carriage return, linefeed". Only one such occurrence is permitted per fiche.
These controls only have any effect when graphical output is being produced online at a terminal.
These routines control which of three actions are taken when the end of a frame is sent to a screen. The actions are as follows:
This routine allows the user to specify whether the bell is rung at the end of a frame or not. By default the bell is rung, since the default end-of-frame handling is for a null prompt to be displayed and some indication of the end of frame should be perceptible. If 'n' is 1, a bell is rung: if 'n' is 0, no bell is rung.
This routine ensures that all graphics output so far requested is sent to the terminal and that the terminal is in a suitable state for interaction. It should therefore be called before any input is requested from the terminal. Because it causes incomplete buffers to the sent to the terminal, it should not be used when not required as it will reduce the data rate to the terminal.
This routine returns in 'x' and 'y' the distance between raster points on the output device in terms of the user's current coordinate system. This can be useful when determining how densely lines should be spaced for a block effect.
This routine returns the current values for the colour ('ic') and hits ('ih'). It is useful if the writer of a package is going to change these values and wants to reset them to the user's previous values before returning control to the user.
This routine is provided as a means of preserving the current dot/dash and window mode. The values are put onto a stack that is 4 deep.
This routines takes the most recently stacked dot/dash and window status and sets this up as the current status. The values must have been stacked by VSTACK.
ARCA, ARCB take the circle's centre to be (X,Y) and draw an arc from THST to THFI using VEC orders. ARCR, ARCS start the arc at the current plotting position and use Relative orders (ie the centre of the circle is assumed to be (XP-RAD*COS(THST),YP~RAD*SIN(THST)). In ARCA, ARCR, each line segment of the arc is less than D in length. In ARCB, ARCS, Q equal line segments are used. If P=0.0, all lines are drawn, otherwise only every other line is visible, giving a dotted arc. The end-point of the arc will be the current plotting position on exit.
Possible errors are the same as for the circle drawing routine (see below).
CIRCLA, CIRCLB select (XX,YY) as centre and use VEC orders. CIRCLR,CIRCLS select the current plotting position as centre and use relative orders. The centre will be the current plotting position on exit. CIRCLA, CIRCLR construct the circle so that each line segment is less than D in length. CIRCLB,CIRCLS construct the circle from Q lines of equal length. If P=0.0, all lines are drawn, otherwise only every other line is visible, giving a dotted circle.
The following errors are possible:
RAD<0.0 ABS (RAD) taken, or 1.0 if RAD=0.0 D<0.001*RAD D=0.l*RAD Q<l.0 ABS (Q) taken, or 8.0 if Q=0.0
Draw an ellipse whose major and minor axes (parallel to X,Y axes) are A, B respectively. ELLPSA, ELLPSB select (XX,YY) as centre and use VEC orders. ELLPSR,ELLPSS select the current position as centre and use relative orders. The centre will be the current plotting position on exit. ELLPSA,ELLPSR construct the ellipse so that each line segment has X,Y increments less than DX,DY. ELLPSB,ELLPSS construct the ellipse from Q lines, subtending equal angles at the centre. If P=0.0, all lines are drawn, otherwise only every other line is visible.
Possible errors are:
A,B<0.0 Absolute value taken, or 1 if zero DX<0.001*A DX=0.l*A DY<0.001*B DY=0.l*B Q<0.0 Absolute value taken, or 8 if zero
The following routines provide a projection onto the output medium (the "View Plane") of a set of triples (X.,Y.,Z.) which could, for example, be points on the surface f(X,Y,Z)=0. The projection is in perspective from the point of view of the viewer, situated "D" units along a normal to the view plane.
The boundary to the visible area in the view plane is set as in Section 3 and similar scaling applies.
Defines the location of the viewer (XV,YV,ZV) and the distance, D, from the viewer to the view plane in the direction of the origin. D may be negative. The viewer always looks towards the view plane and anything 'behind' him will be hidden. There is no 'hidden line removal' in the object itself. The view plane may cut the object being viewed.
This sets the intensity level of all lines between the viewer and the plane to XI, and the intensity level of all lines on the other side of the view plane to XO. It is thus possible to obscure one or other of the sections by setting the appropriate intensity to zero.
These two routines allow the user to change the current (3-D) position, SETXYZ being to an absolute position, UPDXYZ to a relative one.
These routines all provide facilities which are all obvious extensions of the 2D routines. 2D routines may be mixed with 3D routines, but the 3D routines will always reset the 2D current plotting position (XP,YP).
Characters can be drawn by this routine which plots the one element character string 'S' at the current 3D position. The character is always drawn in the plane of the screen at the currently selected character size (5.3.6). 3D rotation and expansion have no effect on the actual character but may change its position.
3D expansion is performed by this routine, where EX, EY and EZ are the expansion factors for the X,vY and Z directions.
Rotation about a general axis is performed by two routines: ROTAXZ defines the axis of rotation and ROTANZ defines the angle (in radians).
The order of expansion/rotation is determined by this routine where the parameter has the following effect:
This routine will project a cube drawn from the current 3-D point with sides parallel to the respective axes, lengths DX,DY,DZ.
Example:
C***ROTATION OF CUBE
CALL FRSPEC
CALL LIMIT(-3.0,-3.0,3.0,3.0)
CALL ZVIEW(0.0,0.0,20.0,25.0)
CALL ROTAXZ(0.0,0.0,0.0,0.0,1.0,0.0)
TH = 0.0
STP = 0.31415926
DO 10 I = 1,6
CALL ROTANZ(TH)
CALL SETXYZ(-1.0,-1.0,-1.0)
CALL CUBER(3.0,3.0,3.0)
CALL ADVFLM
10 TH = TH + STP
CALL FREND
STOP
END