$a dcpi=12; line = 75; left=2; dcpi=12; invert=0; dhold=0
$B15
$T4$  $ $ $  THE $B
$T4$ $   E D W I N $B
$T4$ USER'S$  GUIDE $b
$T4(Fourth Edition)
$B20
$a left=10
$l0
     EDWIN is a set of graphics programs developed in the
Edinburgh University Computer Science Department.    This
document  describes  how the procedures provided by EDWIN
may be used to produce two dimensional line drawings.
    The subsequent editions of this guide reflect changes
made to EDWIN as a result of user feedback.  This edition
of the user's guide refers to version 4 of EDWIN.
$a left=2
$B2
$T4 J. Gordon Hughes $B
$T4 $ $  $  $  $  $  December 1981
$N
$L1UMC
CONTENTS
$A PAGENO=1
$B
$T %Section $T8 %Page
$B
$T Contents $t8 $  1$b
$T A historical and logical overview of EDWIN.  $T8 $  2$B
$T User's guide to the EDWIN  procedures. $B0
$t2 A) Initialisation and termination routines$T8 $  5 $B0
$t2 B) Primitive output routines $t8 $  6 $b0
$t2 C) Control routines $T8 $  8 $b0
$t2 D) Attribute handling routines $t8 $ 11 $b0
$T2 E) Miscellaneous procedures $t8 $ 13 $b
$t The structure of the device drivers. $t8 $ 14 $b
$t The Calcomp device driver. $t8 $ 15 $b
$t The Charles driver. $t8 $ 17 $b
$t The Cursor Addressable Terminal drivers. $t8 $ 19 $b
$t The H P model 2648 terminal driver. $t8 $ 21 $b
$t The H P model 7221 plotter driver. $t8 $ 22 $b
$t The Printronix printer driver. $t8 $ 24 $b
$t The Tektronix device driver. $t8 $ 25 $b
$t The VT15 device driver. $t8 $ 27 $b
$t A set of geometric utility routines. $t8 $ 29 $b
$t A transformation stack. $t8 $ 31 $b
$t Acessing EDWIN  $t8 $ 33 $b0
$t2 A) Under VMS on the VAX 11/780  $b0
$t2 B) Under EMAS on the ICL 2900 range  $b0
$t2 C) Under MOUSES on the Perkin-Elmer machines  $b0
$t2 D) Under RSX-11/M on the PDP-11 range $b0
$t2 E) Under ISYS on the Interdata series 70  $b0
$t2 F) Under the IMP 15 system on the PDP-15s  $b
$t Cross calling of EDWIN from other languages. $t8 $ 35 $b
$t Use of the VIEWPDF program. $T8 $ 37 $B
$t Use of the PDFDEC program. $t8 $ 37 $b
$t Appendices $b0
$t2 A) EDWIN error messages $T8 $ 38 $B0
$t2 B) Listing of the normal EDWIN procedure specs $t8 $ 39 $b0
$t2 C) The EDWIN character set $t8 $ 40 $b0
$t2 D) Some example programs $t8 $ 41 $b0
$t2 E) The structure of the EDWIN PDF $t8 $ 49 $b0
$t2 F) Acknowledgements $t8 $ 51 $b0
$t2 G) References $T8 $ 52
$N
$B2 
$L1UM
A historical and logical overview of EDWIN
$a just=1
$p 'EDWIN' is a graphics package consisting of
set of procedures which provide basic facilities for producing
two dimensional line drawings. The major design aims when writing EDWIN
were :
$b a) The package should be portable;
$b0 b) The package should be small; $b0
c) The package should be independent of the graphics terminal being used.
$p Before EDWIN was written there existed a number of local graphics packages,
mostly based on a Tektronix package called the MacPherson Package [1].
These packages had been implemented on a wide range of machines, but in each
case by a different person, who added new procedures and consequently more
incompatibilities. The importance of the first design aim is that a user should
have an identical interface on each machine, and this has been achieved in
EDWIN.
At the time of the first release of EDWIN the following machines were required
to support it: $b
$t a) DEC PDP-15  $t4  (18 bit machines) [2]$b0
$t b) Interdata series 70 $t4  (16 bit machines) [3]$b0
$t c) ICL system 4-75 $t4  (32 bit machines) [4,5]$b0
$t d) ICL 2900 $t4 (32 bit machines) [6] $b
All of these systems were running the operating systems described in the
references mentioned above.   During the
first year of use EDWIN was also implemented on a VAX-11/780 running the VMS 
operating system [7].  It has since been implemented on Perkin-Elmer models
7/32 and 3220 under MOUSES [8], and the PDP-11 series of computers under RSX-11/M.
$p All of the above mentioned systems support the IMP language [9,10], and 
for this reason the IMP language was used to write EDWIN. All the
IMP compiler implementations are similar, but there are a number of minor
 differences, and 
consequently EDWIN is written using a subset of the IMP language. Because of
this, EDWIN could be translated into another Algol-like language fairly easily. 
Although all the above machines have different word lengths this does not 
pose a problem as 
EDWIN does not assume that it has a larger word length than 16 bits. Users
can however make use of any 'world space' which the machine will allow, with
the knowledge that if they use one greater than _+$ 32 K, then their 
programs are no longer portable.
$p Another machine-dependent feature is the length of name which is significant
when matching external procedures. Of the original systems, EMAS on the ICL
system 4 processors has the lowest limit (8 characters) and all the procedure
names were chosen to be distinct in eight characters.
   On the DECsystem-10 and PDP-11s running RSX-11/M,
 external names are only matched to six characters.
The IMP77 %include statement should be used to declare the EDWIN procedures
with the system provided file of procedure specs,
 as the names have been made distinct at 6 characters by the %alias
mechanism. Any user requiring to mount EDWIN under RSX-11/M or on the
DECsystem-10 should consult J$. Gordon Hughes to get a suitable version released.

$v10
$b$p The second design aim was to make EDWIN small.
This requirement arises because on the PDP-15 there is a limit of 8K words
on the size of an IMP program, and on the Interdata 70's 
and PDP-11's this limit is 64K bytes.
There is no significant limit on the 32 bit machines. One of the things
which had made previous packages non-standard was the addition of 'frills'
on the larger machines.  The philosophy taken by EDWIN is to allow the user
to make full use of the graphics capabilities of the devices that are being
driven, but not to provide facilities which users can easily provide
themselves (such as the provision of menus).
$b$p The reason for the third design aim is that in the past, local graphics
packages have been written for specific devices, and a new set of procedures 
had to be written for each new device which became available, frequently 
having the same facilities, but with incompatible procedures. A superior approach
is used in GINO [11] and suggested by the ACM in their SIGGraph proposals [12],
to have device specific code localised, forming a 'device driver', which
is interfaced to the machine and device independent 'core' of the graphics
package. The following diagram shows how EDWIN may be thought of in relation
to a user's program -
$b
$a UND=0
$l20
                                                             ______________
                                                            |              |
                                                            |   Charles    |
                                                       ---->|   Driver     |
                                                       |    |______________|
                                                       |     ______________
    _______________            ___________________     |    |              |
   |               |          |                   |-----    |  Tektronix   |
   |   U S E R     |--------->|                   |         |    Driver    |
   |               | procedure|                   |-------->|______________|
   | P R O G R A M |  calls   |   E  D  W  I  N   |          ______________
   |               |--------->|                   |-------->|              |
   |               |--------->|                   |         |   Plotter    |
   |_______________|          |___________________|-----    |   Driver     |
                                                       |    |______________|
   (User shielded from                                 |
    specific device                                    ---->    to other 
    idiosyncrasies)                                          device drivers




$a UND='_'

$b$p On the large virtual machines all the device drivers can be included in
the version of EDWIN with little overhead, but on the smaller machines the
version of EDWIN is normally pruned to include only a small number of
device drivers.
Device  drivers now exist for $b
$a indent=1
$l0i
a) Tektronix 4000 series storage tubes  [13,14,15,16]
b) A range of Calcomp plotters [1]
c) VT15 vector display processor [17]
d) Perkin-Elmer 550 terminals (Bantams) [18]
e) Hewlett Packard 7221 flat bed plotter [19]
f) 'CHARLES' colour graphics terminal [20] 
g) Visual 200 terminals [21] 
h) Hewlett Packard 2648 terminal [22] 
i) Printronix printers [23] 
$a indent=0
$n
$p
The facilities provided by EDWIN have been developed from ideas in the
existing MacPherson package, with the use of names and other ideas from the
ACM SIGGRAPH proposals.  Because of the requirement to run EDWIN on the local
mini-computers it was not possible to provide the ACM's segmented data 
structure,
although this would have been desirable. EDWIN has provided a low level 
graphics package which is machine and device independent. If the user 
wishes to disregard the device independence, virtual coordinate space, ability
to produce software characters, and checking of parameters, it would be 
possible
to use the EDWIN device drivers as a 0th level graphics package, or they could
be used as drivers for a more complex graphics system.
EDWIN has been used in research projects (eg. the ESDL suite [24] and a
system to plot Integrated Circuit descriptions [25]), and in undergraduate
teaching and projects [26].
$b The rest of this guide describes:
$b$p i) The user facilities -
$b
Drawing pictures with EDWIN is a matter of writing a program which incorporates
the procedure calls which are descibed in this section.
$b$p ii) The device drivers -
$b
This section describes the device specific features of the devices which EDWIN
can be used to draw pictures on.  It should be noted that users should very
rarely require to call the device drivers directly as the purpose of EDWIN is
to provide a user with a device independant interface.
$b$p iii) Some useful utilities -
$b
This section describes a set of geometric drawing routines, and a transformation
stack which users may find useful.  Utilities for drawing and analysing stored
picture descriptions are also described.
$b$p iv) Appendices which cover -
$b
The EDWIN error messages $b0
The standard procedures provided $b0
The EDWIN character set $b0
A selection of example programs $b0
A definition of the stored picture format $b0
Acknowledgements and references
$n
$l1mu
Users Guide to the EDWIN procedures
$b
A) Initialisation and Termination routines:
$b
%routine INITIALISE FOR (%integer DEVICE TYPE)
$p This is normally always the first EDWIN routine to be called. It initialises
EDWIN and selects the device driver to be used.
If the device driver selected is not available or if an unidentified device
is specified, EDWIN signals error 0 (see appendix A).

$p The following DEVICE TYPES are valid :- $b0
$b0$t 0 $t4 : The 'null' device
$b0$t 15 $t4 : VT15
$b0$t 120 $t4 : Soroc IQ 120 terminal
$b0$t 300 $t4 : Printronix printers
$b0$t 550 $t4 : Perkin Elmer 550 terminal (Bantam)
$b0$t 200 $t4 : Visual 200 terminal (VT52 compatable)
$b0$t 69 ('E'), 101 ('e') $t4 : Hazeltine Esprit terminal
$b0$t 564, 565, 663, 963 $t4  : E.R.C.C. Calcomp plotters
$b0$t 2648 $t4 : Hewlett Packard terminal
$b0$t 7221, 7220 $t4 : Hewlett Packard plotters
$b0$t 4002, 4010, 4012, 4014 $t4 : Tektronix storage tubes
$b0$t 67 ('C'), 99 ('c') $t4 : CHARLES driver
$b0$t 76 ('L'), 108 ('l')   $t4 : Line printers
$p Further details of these device drivers may be found in the sections
following the description  of the EDWIN procedures.
$b3
%routine TERMINATE EDWIN
$p This %must always be the last EDWIN routine to be called. It ensures
that any pending output is forced out, and the device is left in
its normal state. $b Examples of what is meant by 'normal' are - $b
$ta) Tektronix terminals are set to alpha-numeric mode $b0
$tb) Roll plotters have all the paper used moved past the pen $b0
$tc) The VT15 processor is stopped $b0
$td) The HP plotter pen is put away

$n
$b
B) Primitive output routines  :
 $p The following routines may be used to generate line drawings. The 
parameters refer to virtual coordinates (ie. any number in the
range -32K to +32K). If storing of the picture is enabled, the procedure
calls are noted and the picture may be redrawn by utilities 
described later. In all cases the vectors are clipped to the
current WINDOW setting, and projected to the current VIEWPORT. This
is described in more detail in section C. Lines are drawn at the
current line style and colour settings if the device has them available.
Changing these is described in section D.
$b3 
%routine MOVE ABS (%integer X,Y)
$p This routine moves the current position to the point (X$,Y).
$b2 %routine MOVE REL (%integer DX,DY)
$p This changes the current position  (say (CX,CY)) to the point
(CX+DX, CY+DY). If the specified point lies outside the current window, then
the current screen position remains unaltered.
$b2 %routine LINE ABS (%integer X,Y)
$p This routine causes a line to be drawn from the current position to the
point (X,Y), updating the current position to the point (X,Y).

$b3 %routine LINE REL (%integer DX,DY)
$p This routine draws a line to (CX+DX, CY+DY), where (CX,CY) is
the current position, and updates the current position appropriately.
$b3
%routine MARKER ABS (%integer N,X,Y)$b0
%routine MARKER REL (%integer N,X,Y)
$p These routines provide a set of symbols which can be drawn after an
implicit call on MOVE ABS or MOVE REL, depending on which routine is
used. At present eleven are available; N identifies which symbol is to be drawn

.
$b
$t$ 0$t2 Point$t6 ( $. ) $b0
$t$ 1$t2 Octagon $t6 ( O )$B0
$t$ 2 $t2 Square $t6 ( [] )$b0
$t$ 3$t2 Triangle $t6 ( A ) $b0
$t$ 4$t2 Transformation point $t6 ( X ) $b0
$t$ 5$t2 Flag point $t6 ( one with six ) $b0
$t$ 6 $t2 Visual Centroid $t6 ( + ) $b0
$t$ 7$t2 Right pointing arrow $b0
$t$ 8$t2 Left pointing arrow $b0
$t$ 9$t2 Upward pointing arrow $b0
$t 10 $t2 Downward pointing arrow $n

$p The following routines may be used to output text on graphics 
terminals.
The character drawing instructions are  recorded if the picture is
being stored. Although on some terminals (eg. Tektronix, Cursor Addressable 
terminals and the HP 2648 terminal) users can
mix output produced by the standard I/O routines with output from EDWIN, this 
practice is not encouraged as problems can arise in the synchronisation of
the two outputs. If this must be done the routine UPDATE can be used
to ensure that any pending graphics output is forced out.
$p By default the characters are drawn in a 12 (X) by 20 (Y) box in virtual 
coordinates. EDWIN supports two types of character.  The first of these
are 'hardware' characters, which are generated by the device, and are
usually of fixed size and orientation. The second type, 'software'
characters, may be scaled and rotated by routines described later. Software
characters are generated as sequences of lines and moves by EDWIN.
The routine SET CHAR QUALITY (page 12) selects the font in which text is to
be drawn.

$b3%routine CHARACTER (%integer CH)
$p This causes the character CH to be drawn at the current position 
and the current position is advanced by the character width.
The routine call is ignored if CH is a character of quality one and is
outside of the range of ISO characters whose codes lie in the range 32 to 127.
$b3 %routine TEXT (%string (255) ST)
$p This routine causes sequence of characters making up ST to be output.
$b3$p Users should note that most systems provide procedures for converting
integers and reals to strings and vice versa.  Because the names vary between
systems, users are referred to the appropriate system library manuals.
$b3
$p PDP-15 users should refer to the section describing the PDP-15
implementation of EDWIN for details of restrictions placed on the
character handling routines on the PDP-15.
$n
C) Control Routines :
$p The following routines may be used to control the drawing of the picture.
$b2%routine NEWFRAME
$p This causes a blank surface to be found for the graphics output  to be
displayed on. In the case of Tektronix, VT15 and Video terminals
this results in the screen being cleared, and in the case of roll plotters
the paper is fed to the start of a new plot. The fact that a new frame has 
been taken is recorded if the picture is being stored.
$b2 %routine UPDATE
$p This routine causes any output buffers to be flushed, so that
after  a call of UPDATE the picture is 
guaranteed to
be up to date. The routine needs to be used if graphics output is to be
mixed with other output to the same device. In the case of a Tektronix, UPDATE
results in the terminal being left in alpha-numeric mode.
$b2 %routine STORE ON (%integer STREAM)
$p This causes calls of drawing routines to be recorded
on output stream STREAM. 
This representation of the picture, often called the Pseudo Display File or 
PDF, can then be re-read, or used  as
input to other EDWIN utility programs described later.
The storing of the picture does not alter the currently selected output stream.
$b2 %routine STORE OFF
$p This disables the recording of graphics instructions, and is the default.
$b2 %routine VIEW ON (%integer STREAM)
$p This causes the graphics output to go to the stream specified. By default
this is stream number one if the device is not a terminal, and stream zero for
terminals. For terminals the graphics output usually reaches the terminal
through a different mechanism than the standard I/O  routines
and trying to view on another stream will have no effect. The default
is for viewing to be enabled.
$b2 %routine VIEW OFF
$P This disables viewing. Calling any of the routines described
in section B will have no visible effect, but the routine calls will
be stored if storing is enabled.
$n$b2
%routine WINDOW (%integer XL, XR, YB, YT)
$P The picture is built up in a coordinate system which is known as
the VIRTUAL SPACE (sometimes called the "WORLD SPACE"). Within this 
space there is an area
known as a WINDOW, and  this area is mapped to the user-selected area
of the graphics device called the VIEWPORT (see below).
The routine WINDOW defines the size of the window in the virtual space.
The parameters are the lower and upper X value, and the lower 
and upper Y values respectively, the default values being (0, 1023, 0, 1023).
If a lower window bound exceeds an upper window bound the two parameters are
swapped by EDWIN; thus it is not possible to invert the picture by swapping
the window limits.
The limits of the virtual space are dependent on the machine, but
the virtual space must not exceed %+ 32K square if the user program 
and PDF are to
be portable. In any particular implementation the maximum size of the
virtual  space is equal to the largest integer which the machine can hold.
The following diagram shows the arrangement for windowing - $b
$n
%routine VIEWPORT (%integer XL, XR, YB, YT)
$P The picture is drawn 
within an area in the output device's coordinate space
 which is known as the VIEWPORT.
This routine may be used to alter the size of
the viewport (the parameters have the same significance as for the
routine WINDOW) and they have default values which are device dependent
but have been chosen so that if the viewport is unaltered an 'average' size
of picture results. For graphics terminals this is the complete screen,
and for plotters the default viewport is typically 15$ cm square.
The descriptions of the individual device drivers give details of the possible
and default settings of the viewport.
$P The package automatically maps the currently specified window
onto the current viewport and clips the drawing appropriately.
$p If the coordinates of the viewport are set greater than the maximum
viewport possible on the device, then the largest viewport settings 
possible are used.
If the upper X or Y bound is greater than the corresponding lower bound then
the bounds are reversed, and the effect is the same as calling VIEWPORT with
the parameters in the opposite order.
$p With the Tektronix 4014, the users can either have 1024 unit resolution
or enhanced 4096 unit resolution. If a viewport with a maximum X value of
greater than 1023 is given then the 4014 will be driven in enhanced graphics 
mode, until it is re-initialised by a call of INITIALISE FOR.
$b3
%routine ASPECT RATIOING (%integer STATE)
$p If the parameter is 0 then the automatic adjustment of
window bounds to keep the picture with the correct aspect ratio is
suppressed. A value of 1 (the default) for the parameter causes the window 
bounds to be enlarged to maintain the correct aspect ratio for the picture.
When the routine ASPECT RATIOING or VIEWPORT is called the current window 
is altered to reflect the current aspect ratio.
$p
When aspect ratioing is enabled; if a square is drawn in the virtual co-ordinate
space then a square will be seen on the screen.
If aspect ratioing is disabled and
if the terminal does not have a aspect ratio of unity then the square which
has been drawn in the virtual co-ordinate space will appear as a rectangle
on the screen.  When aspect ratioing is enabled, EDWIN checks the aspect 
ratio that
a picture will have on the screen, and extends the window in either the X or Y
direction to give correct aspect ratio on the screen.

$n
$b D) Routines for changing Attribute settings :
$p The following routines are used to set values of attributes, which
remain set until they are changed again. Any parameter given
outside the specified parameter range causes the default to be used.
The information about the attribute change is recorded if the picture is
being stored.
If the device being used cannot support the attribute 
change then it is ignored, but the attribute change is still recorded
if storing was enabled.
$b3 %routine SET COLOUR (%integer COLOUR)
$p This allows the colour being used for drawing to be changed.  For most 
devices colour changes are carried out automatically, but on some plotters
(eg. the Calcomp 564) this must be done manually by stopping plotting,
removing the current pen, and inserting in the new one. It is
consequently good practice to draw all the output required in one
colour before changing the pen. The following parameters are valid - $b
$t2 1 = Black (default) $b0
$t2 2 = Blue $b0
$t2 3 = Green $b0
$t2 4 = Red $b
$p The driver for the ERCC Calcomp plotter and the CHARLES terminal allow
a wider range of parameters. Details of these codes can be found in the 
sections describing the device drivers.
$b3 %routine SET LINE STYLE (%integer STYLE)
$p This routine allows the user to make use of the different
line styles which are available on the Tektronix 4014, plotters, and VT15. 
The driver for Cursor Addressable Terminals uses this routine 
to choose the symbol which is used to generate lines on the terminal, 
(see the section on the Cursor Addressable Terminal driver).
$b The following parameters are significant - $b
$t 0 = Normal Lines (default)
$b0$t 1 = Dotted lines
$b0$t 2 = Chain Lines (on 4014 and HP plotter; otherwise normal lines)
$b0$t 3 = Short Dashed lines
$b0$t 4 = Long dashed lines

$b3 %routine SET INTENSITY (%integer BRIGHTNESS)
$p The only device currently driven by EDWIN which has variable intensity is
the VT15. BRIGHTNESS should be a number in the range zero to seven, with
seven being the brightest. An intensity of 5 is the default, 0 and 1 are
effectively invisible, and 7 is brightest.

$n
$b3 %routine SET CHAR SIZE (%integer SIZE)
$p This routine may be used to change the size of the characters to be 
drawn by CHARACTER and TEXT. The size should be a positive integer,
representing the size of the character in the X direction. The default
size is 12 units wide (which corresponds to 20 units high).
If hardware characters are being used then the nearest size of
character available is used, but in most cases only size 12 is available.
In general nothing about low quality text should be relied on when moving
programs to run on other devices.  Details of hardware characters available
 on devices can be found by referring to the sections describing the device
 drivers. If software characters are used then
any size is possible, but choosing factors or multiples of 12 avoids
rounding errors in text strings which may otherwise arise.
$b3 %routine SET CHAR ROT (%integer DEGREES)
$p If software characters are being used, DEGREES gives a
clockwise rotation of the appropriate amount.
DEGREES is currently rounded to a multiple of 90 degrees. 
The default value for DEGREES is 0.
$b3 %routine SET CHAR QUALITY (%integer QUALITY)
$p If QUALITY=0 (the default) then hardware characters
(that is characters which are generated by the device hardware, or by local
device driving software)
are used, otherwise the EDWIN software characters set is used.
Hardware characters are frequently provided in only a small number of
sizes, and with limited or no rotation possible.
$b3 %routine SET CHAR FONT (%integer FONT)
$p If the device being used has alternative character fonts, then this
sets the character font which is used for subsequent hardware characters.
(There is only one software character font available at present).
$b3 %routine SET CHAR SLANT (%integer DEGREES)
$p If the character set which is currently being used can have a slant
specifed, this routine can be used to set it.    Currently the only two 
devices which this applies to is the Calcomp and Hewlett Packard plotters.
In the case of the HP plotters, DEGREES may be any number in the range 
-90 to 90, but the Calcomp plotters have only one alternate slant angle
which is 15 degrees forward.

$n
F) Miscellaneous procedures:
$b %routine INQUIRE POSITION (%integer %name X, Y)
$p This routine sets X and Y equal to the X and Y coordinates of the 
current virtual position.
$b2 %routine INQUIRE WINDOW (%integer %name XL, XR, YB, YT)
$p This routine sets the parameters to the current window bounds.
The parameters are lower X, upper X, lower Y, upper Y, respectivly.
$b2 %routine INQUIRE VIEWPORT (%integer %name XL, XR, YB, YT)
$p This routine sets the parameters to the current viewport bounds.
The order of the parameters is the same as for INQUIRE WINDOW.
$b2 %routine MAP TO DEVICE COORDS (%integer %name X, Y)
$p This routine can be used to ask EDWIN to transform the point specified
from the world space to the device space, using the appropriate transformation
for the current window and viewport settings.
The coordinates have no clipping performed on them.
$b2 %routine MAP TO VIRTUAL COORDS (%integer %name X, Y)
$p This routine performs the inverse operation to the routine above. If 
converts the coordinates X and Y to the equivalent coordinates in the
world space. The coordinates have no clipping performed on them.
$b4
%routine CURSOR (%integer %name STATUS, X, Y)
$p Many devices have a means of allowing the user to point at the screen,
for example the cursor on a Tektronix tube or the BIT PAD on the CHARLES
terminal.  This routine can be used to allow a limited form of interaction
with EDWIN.  The contents of STATUS vary between devices; for example it
contains the character hit to leave cursor mode on a Tektronix, the value
of the buttons on the VT15, or the pen status on the HP plotter. The 
parameters X and Y are set to the pointer's X and Y coordinates. If the device
has no cursor then EDWIN error 8 is signalled when the routine is called.
  Users are referred to the 
sections describing the device drivers for further details of this routine.
$b2 %routine D CURSOR (%integer %name STATUS, X, Y)
$p This routine is similar to the routine CURSOR, except that the
coordinates are returned in device units, and are not scaled.  The value of
STATUS is the same as for CURSOR.
$n
$l1mu
The structure of the EDWIN device drivers.
$p All the graphics output from EDWIN goes into a module called the "device
driver". This can take two forms, either it is a specific device driver, in
the case of machines which have a limited version of EDWIN, or it is just a
switch which selects the true device driver, after the switch has been 
initialised. All the device drivers have the following format -
$b
%routine DRIVE DEV (%integer COM, X, Y)
$p This rigid format makes it easy to produce new device drivers, and it is
also easy to configure versions of EDWIN which reflect the devices available.
The above named routine may be assumed to be present in any version of EDWIN
which supports multiple devices, otherwise the device driver is one of the
routines which are described in the following sections.
$p COM is the command code which instructs the device driver which operation
is to be performed, and the parameters X and Y give further information for
some of the codes.  Codes 1 to 9 are defined for all device drivers, but other
codes are accepted by specific device drivers to allow users to make use of
device dependent features.
These additional codes are described in the descriptions of the device drivers.


$b
The following is the significance of the general codes -
$b
%Code $t $  X $T2 $  Y $t3 %Description $b
$  0  $t TYPE $t2 $  - $t3 Initialise the driver for TYPE. $b0
$  1  $t $  - $t2 $  - $t3 Terminate $b0
$  2  $t $  - $t2 $  - $t3 Update $b0
$  3  $t $  - $t2 $  - $t3 Newframe $b0
$  4  $t $  X $t2 $  Y $t3 Move Abs to (X,Y) $b0
$  5  $t $  X $t2 $  Y $t3 Line Abs to (X,Y) $b0
$  6  $t CHAR $T2 $  - $t3 Output character CHAR $b0
$  7  $t WHICH $t2 $ VAL $t3 Change attribute WHICH to VAL $b0
$  8  $t $ XL $t2 $ YB $t3 Set lower device window bounds $b0
$  9  $t $ XR $t2 $ YT $t3 Set upper device window bounds $b
$p Note that calls to a device driver are ignored if another device has been
selected, or if viewing is disabled. This means that calls such as SET COLOUR 
MAP to the CHARLES device driver are ignored if the current device is not
CHARLES.
$b$p In the versions of EDWIN on the multi-user systems VAX, MOUSES, and 
EMAS, the following routines are present to perform graphics input and output.
$b0
$t2%routine TTPUT (%integer SYM)$b0
$t2%routine FLUSH OUTPUT$b0
$t2%integer %fn TTREAD $b0
$t2%integer %fn TTGET $p
The routine TTPUT places its parameter into an internal
buffer, which is flushed when it gets full, or explicitly by the use
of the routine FLUSH OUTPUT. The output is automatically forced out
when the routines UPDATE or TERMINATE EDWIN are called.  The function TTREAD
returns the next character on the console stream. TTGET is the same as
TTREAD except the character is not echoed.
$n
$l1mu
The Calcomp device driver
$p The Calcomp device driver produces pictures on a range of Calcomp drum
plotters. These plotters are now all driven by means of calls to
the Graphpack plotter routines provided by the E$. R$. C$. C.,
but a version which directly drives a model 563 plotter also exists.
 The use of
Graphpack allows all the plotters to have a range of line styles and 
characters, even though the plotters themselves cannot support these.
$p Graphpack, and consequently EDWIN, can be used to drive the models 564,
565, 663,  and 963 plotters, but the use of the model 963 (device $.GP23 on EMAS)
is recommended. The Calcomp device driver currently exists on the VAX and
EMAS implementations of EDWIN. In the case of EMAS, the process username and
current delivery information appear at the start of the plot, and the plotter 
output goes to the plotter automatically.
In the case of VAX the process username and a delivery message is appended to
the start of the plot. If the VAX user has the logical name "NETFS$$DELIVER"
 defined,
then this is used as the delivery information, otherwise it is set to
"E.R.C.C. Front Door".
The logical name NETFS$$DELIVER may be set by the command - $b
$t2 $$ DEFINE NETFS$$DELIVER "Level 3 of the J.C.M.B.
$b
On VAX the plotter driver produces the output
for the plotter in the file "T.GP", which must be explicitly sent to a
plotter by the NETFS command, as shown in the following example - $b
$t2 $$ NETFS $b0
$t2 >> device 2972 $b0
$t2 >> fire t.gp $b0
$t2 >> stop
$p
Users are referred to chapter 3 of the ERCC Graphics Manual [1] for specific
details of the plotters mentioned above, and also how the specific models
are addressed on the ERCC network. The plotters all have a default viewport
of 0 to 1500 in both the X and Y directions. Y is the distance across the
paper, and X is the distance along the paper, so that the maximum Y coordinate
of the viewport is dictated by the width of the plotter being used, and the
maximum X coordinate of the viewport is almost infinite.  
The default viewport is set
to be 15 cm, so if a plot of size 30 cm is required, the viewport bounds 
should be set to (0,3000,0,3000).
$b
$p If the user wishes to send the plotter output to explicit files, then the
routine call $  VIEW ON (n) $  should be given before the call to
INITIALISE FOR where 'n' is the stream which is to be used for the plotter file.
In the case of VAX and EMAS, the stream should be set up by the routine call
$b$t2 OPEN OUTPUT (21, "MYPLOTFILE")$b
The routine OPEN OUTPUT (%integer STREAM, %string (255) FILE) requires to be
explicitly declared on EMAS.
$n
$b$p
The device driver is present as $b
%routine C963 (%integer COM, X, Y)
$p which has the same parameters as the general device driver described on 
page 14.
$b
$p The plotters have multiple colour facilities. In the case of student users
only black may be used (any attempt to draw other colours will still result in
black).
Other users can make use of the four colours mentioned
in the description of the SET COLOUR routine. There are also facilities for
doing liquid ink drawing, for which permission from the ERCC is required. 
Users are referred to the ERCC graphics manual for details of how to get
in touch with the appropriate ERCC personnel, and also for the range of valid
pen numbers for SET COLOUR. 
$p The plotters provide
4 line styles: these are the ones mentioned in the routine SET LINE STYLE, 
with the exception of the 'chain lines'. 
$p If 'hardware' characters are used,
these are the characters from the ERCC Graphpack, while 'software' characters
are the standard EDWIN software character set.
This means that hardware characters on the plotter may be set to any size.
$n
$l1mu
The CHARLES driver
$p This device driver controls the 'CHARLES' terminals, based on a design
by Charles Minter at Caltech.
The terminals consist of a small PDP-11 (eg. PDP-11/03), which
controls a colour display, and also talks to a console.
$p Once the Charles station has been switched on, the PDP-11 runs a small
program in ROM which allows the terminal to talk to the selected host computer.
The PDP-11 must then be loaded with the software to interpret the protocol
sent by the device driver. The information about switching on the terminal,
and loading the PDP-11 software from VAX, EMAS and the DEC-system 10, is
contained in a black folder beside the terminal.
$p
The display is a 512 x 512 x 4 bit raster scan display, where the 4 bits
assigned to each point determine which of 16 user programmable colour registers
are to be used. This gives a range of 16 colours, which can be selected by
the SET COLOUR routine. Colours 1 to 4 are defined to be the standard 
EDWIN colours, and colour 0 is defined as black (the background). The 
default colour is 1, which is white. The remaining colours are undefined.
Users can set their own colour map
registers by the routine SET$ COLOUR$ MAP described below.
The Charles station includes a 'Bit pad',
an analogue device which can be used by
the PDP-11 to control a tracking cross. The position of the cross
 can be accessed by the EDWIN
routine CURSOR. The status returned by the cursor contains the value of the
buttons on the bit pad.
$p
The Charles terminal can either be in console mode, where it acts like
a normal terminal, or in drawing mode. EDWIN automatically sets the terminal
to the correct mode;  if users wish to enter console mode to interact with
a graphics program which is running, the routine UPDATE must be called.
$p
When the Charles terminal is in drawing mode, the PDP-11 may be in one of
five states.
The first of these is 'text mode', which is automatically selected by
the routines CHARACTER and TEXT and terminated by an attempt to enter
another mode.
The second mode is 'line mode', where the terminal performs like a standard
line drawing terminal, and this is the default mode for any graphics output
done by EDWIN.  The other modes are 'dot mode', 'polygon mode', and
'box mode', the
first of which causes lines to be converted into a 'point' primitive. Thus
points may be drawn over the screen by just a sequence of calls to LINE ABS
or LINE REL.  The next mode is polygon mode. Once in polygon mode, ie.
the first call to LINE after either polygon mode has just been set, or the
last polygon terminated, this is used to start a polygon. Then any sequence
of moves or lines are treated as defining the vertices of a polygon. The
polygon is automatically shaded by Charles when a call to END MODE is given.
The other mode is used to draw boxes on Charles. 
Each two calls to LINE are taken to describe the upper and lower
corners of a box, which the Charles terminal will draw, and shade.
 Although these low level features are present, users are recommended
to use the  routines to generate polygons and boxes which are described in
the section following the device driver descriptions.
These save
the user knowing about the Charles driving modes, and also clip the
shapes to the current screen window.

$n
$l1m
Routines specific to the Charles driver
$b2
%routine CHAS (%integer COM, X, Y)
$p This is the Charles device driver. It accepts all the standard device
driver commands, and also commands 10 and 11.
$b
Command 10 is 'mode change', and is used to select the appropriate mode.
The parameter X chooses the mode to be used until the mode is next changed.
Mode 0 is text mode, 
mode 1 is line 
drawing mode (the default), mode 2 is point mode, mode 3 is polygon
mode, and mode 4 is box mode.
Users are encouraged to use the routines S BOX and POLYGON described
above rather than altering modes themselves.
$b
Command 11 is used to set the colour replacement mode.
When part of the picture is drawn on the Charles terminal the user can
choose 3 modes of colour replacement by the use of this command. The
required mode of replacement is specified by the X parameter. Mode 0 is
'replace' mode, where the colour currently selected is used regardless
of which colour is currently at the point. Mode 0 is the default. Mode
1 causes the currently selected colour number, to be ANDed with the
colour number which is currently at the point, and the resulting colour
number is used as the colour which the point is to be. Mode 2 is similar
to mode 1, but the colour numbers are ORed together. 
$b2
%routine END MODE
$p This routine is used to end the currently selected mode. 
This routine is not required by users unless they wish to change
the Charles driving modes themselves.
$b2
%routine SET COLOUR MAP (%integer REG, RED, BLUE, GREEN)
$p This sets one of the 16 colour registers, given by the value of
REG, (0 to 15), to be the colour given by the appropriate
proportions of the three primary colours. Each colour should be
specified with a value in the range of 0 to 15.
$b2
%routine C BIT PAD POS (%integer %name X, Y)
$P This routine returns the current position of the BIT PAD cursor in X and
Y.  These are in device units, ie. in the range 0 to 511, which can be
mapped to the current virtual coordinates by the routine MAP$ TO$ VIRTUAL$ COORDS
$b3
%routine C CURSOR (%integer %name STATE, X, Y)
$p This routine waits for the next button change to occur on the BIT PAD, and 
the parameter STATE is set to the current value of the buttons,
and the parameters X and Y are set to the current device position.
$n
$l1mu
The Cursor Addressable Terminal drivers
$p The main driver for Cursor Addressable Terminals was written for terminals
made by Visual Technology Inc. called Visual 200s. These terminals are DEC
VT52 compatible.  In addition the driver has been extended to drive a number
of other Cursor Addressable Terminals such as the Perkin-Elmer 550 terminal
and the Soroc IQ120 terminal.  All these terminals have the drawback of having
very poor resolution for general purpose graphics. However, this has to be 
traded off with the very high availability of these terminals.
The default and maximum settings of viewport are 0 to 79 in the X direction,
and 0 to 23 in the Y direction.
$p If low quality text is used with the Cursor Addressable Terminal driver,
then the normal terminal text is used.  Software characters are available, but
rapidly fill the screen.  Users must use the routine UPDATE if they wish to mix
program interaction with drawing.  The only other attribute which is available
is line style.  Style 0 is the 'best' graphics approximation to lines that the
terminal can provide, for example the Visual 200 graphics primitives allow 
line segments from the centre to the four boundaries of each character position,
and the Perkin-Elmer terminals have a 'splodge' character.  If the other line
styles are selected then the lines are drawn by the characters '-', '#', '+',
'*' (for styles 1 to 4) respectively.  Any other style selected causes an asterix
to be used, which is also the default character used if the device has no
graphics character set.  In the case of the Visual 200 the routine SET CHAR FONT
may be used to select the alternate character set, but this has no effect on
other terminals. (The alternative character set is used if a non-zero setting
of the character font is specified).
All other attribute setting commands are ignored.
$p Since the driver is concerned with manipulating points on a character grid
it can be used for any hard copy terminal or line printer.  In this case the
characters are stored in the character map of the screen and sent to the terminal
when the EDWIN routine UPDATE is called.  The default viewport for line printers
is 0 to 131 in X and 0 to 63 in Y.
$p The following table summarises the devices which can be driven by this driver
and the number which should be given to select them at initialisation. $b2
$l0
   Device                No. for INIT        Default/Max Viewport    Cursor?
   Visual 200                200             0 - 79    x   0 - 23      Yes
   VT52                       52             0 - 79    x   0 - 23      Yes
   Perkin-Elmer 550          550             0 - 79    x   0 - 23      Yes
   Soroc IQ 120              120             0 - 79    x   0 - 23      Yes
   Hazeltine Esprit          'E'  (69)       0 - 79    x   0 - 23      Yes
   General video/h.copy      'V'  (86)       0 - 79    x   0 - 23       No
   Line printer              'L'  (76)       0 - 131   x   0 - 63       No


$n$b2$l1m
Routines specific to the Cursor Addressable Terminal Drivers
$b2
%routine CATS (%integer COM, X, Y) $b0
$p This is the two terminal driver that is described above.  The commands 
are the same as for the standard device driver described previously.
$b3
%routine V CURSOR (%integer %name STATUS, X, Y) $b0
$p If the terminal is a true cursor addressable terminal then the programmer
can call
the routine CURSOR which then allows the user to move the current position 
marker about the screen. This is usually done by means of cursor control keys
with the exception of the Perkin-Elmer terminal and Hazeltine Esrit
where the following keys have
to be used - $b
$t BACK SPACE = cursor left $t5 TAB = cursor right $b0
$t LINE FEED = cursor down $t5 DEL = cursor up
$b
Cursor mode is terminated by pressing any non-control character. The ISO value
of this character is returned in the variable STATUS, and the current screen
point is returned in the parameters X any Y.
$p
The CURSOR routines are NOT available on the EMAS implementation of EDWIN.
$n
$l1mu
The H P terminal driver
$p The Hewlett-Packard terminal driver drives the HP model 2648A raster-scan
graphics terminal.  This terminal can be used as a standard terminal connected
to a computer in a similar manner to Tektronix terminals, but it also has an
array of points which can allow diagrams to be drawn.  The array of screen 
points is 720 in X by 360 in Y, which gives the default, and maximum, setting
of Viewport to be 0 to 719 in X, and 0 to 359 in Y.
$p The terminal has two character sets.  The first of these is used when the
terminal is in normal text conversation with the host machine, and the other
set, which has a range of 8 sizes between 4 and 53 screen units, is generated
by the routine CHARACTER.  The terminal has a hardware zoom facility which can
be used on the picture and the second of the character sets described above.
The routine UPDATE should be used to force the terminal to use the lower
quality character set.  The terminal character set may be changed to italics
by the use of the EDWIN routine SET CHAR FONT with a non-zero parameter.
$p The range of line styles which are described in the documentation of the 
routine SET LINE STYLE are all supported.  Line styles, character size
and font are the only attributes described in section D which are supported by
the terminal.
$p The terminal has a tracking cross which may be invoked by the EDWIN routine
CURSOR. This may be moved about the screen by means of four cursor control
keys.  Any keyboard character may be used to terminate cursor mode, and the
ascii value of the character which is typed is returned as the 'status' when 
cursor mode is terminated.

$b2
Routines specific to the HP 2648A terminal driver -
$b
%routine HP 2648A (%integer COM, X, Y)
$p This is the device driver, which only accepts the standard device driver
commands which have been described previously.
$b3
%routine H CURSOR (%integer %name STATUS, X, Y)
$p This evokes the terminals tracking cross, and returns the key which was used
to terminate cursor mode in STATUS, and the current device coordinates of the
tracking cross in X and Y.
$n
$l1mu
The H P plotter driver
$p The Hewlett-Packard plotter driver drives the HP model 7221 flat bed
plotter. This takes sheets of paper up to size A3. The plotter has a
terminal connected to it, and the plotter sits between the computer being
used and the terminal in 'transparent mode', ie. the plotter has no 
noticeable effect on the use of the terminal. Under program control
the plotter may be placed in 'plotting mode', and all output sent to the
plotter is interpreted as graphics protocol.
$p The following is the procedure for using the plotter: Switch on the 
plotter at the switch on the front of the plotter, and switch on the
terminal. The plotter will be in transparent mode, which allows the user
to log on to the system which they wish to use. Before drawing any
pictures it is recommended that users disable messages from being sent by
other users or operators, as these give rise to random lines over plots!
Users are referred to the system documentation of the system that they are
using for details of how this is done. Paper is loaded by pressing the
'CHART LOAD' button, then laying the paper flat on the bed of the plotter,
and pressing the 'CHART HOLD' button.
The paper is held down electrostatically.
No other buttons on the front need to be used when using EDWIN to drive the
plotter. If the EDWIN routine NEWFRAME is called, the string "Enter new 
sheet of paper, type YES to continue", appears followed by  the prompt
"ready?". The user must type YES or Y to continue, after adding a new
sheet of paper. If a user wishes to escape from a program which is 
plotting, they must press the BREAK key on the terminal, followed
by the appropriate key to attract the computer's attention.
$p
The HP plotter has 4 pens which are chosen by the EDWIN routine SET
COLOUR, and are picked up by the plotter automatically. The 
plotter has 6 built-in character sets. The primary character set (set 0) is
used by default, but the others may be nominated
the routine SET CHAR FONT, with the values 0 to 5 selecting the set required.
Users are referred to the plotter manual for a full description of all the 
character sets.   The EDWIN driver also produces
5 line styles on the plotter, as described for the routine SET LINE STYLE.
$p
The default values for the viewport are 0 to 11200 in the X direction and 
0 to 8000 in the Y direction, which is the size of A4 paper. The maximum
viewport is 0 to 16000 in the X direction, and 0 to 14000 in the
Y direction. One device unit is 0.0025 cm.
The following calls to viewport set the paper size to be A4 and A3 respectivly
- $b
$t VIEWPORT (0, 28 * 400, 0, 20 * 400); $  ! For A4 $ (28 cm x 20 cm) $b0
$t VIEWPORT (0, 40 * 400, 0, 28 * 400); $  ! For A3 $ (40 cm x 28 cm) $b0
$p
The EDWIN routine CURSOR is available on the HP plotter, and its use is
described in the documentation for the routine P CURSOR on the next page.
$p
If users require to use the terminal attached to the plotter for any
input or output during the drawing of a picture, the routine UPDATE must
be called to ensure that the plotter is set to transparent mode.
$n$b3$l1m
Routines specific to the HP Plotter driver
$b2
%routine P7221 (%integer COM, X, Y)
$p This routine is the plotter driver. The commands accepted are the
same as the general device driver discussed previously.
$b3
%routine HP AC ARC (%integer RAD, IA, FA)
$p This routine draws an anti-clockwise arc of radius RAD, from an
initial angle of IA to a final angle FA
(both angles specified in degrees) centered on the current point.
$b3
%routine HP C ARC (%integer RAD, IA, FA)
$p This routine is the same as the routine HP AC ARC, except that a
clockwise arc is used.
$b3
%routine HP CIRCLE (%integer RAD)
$p A circle of radius RAD is drawn centred on the current position.
Note that RAD should be specified in device co-ordinates.
$b3
%routine HP SPEED (%integer SPEED)
$p This routine sets the speed at which the plotter draws lines. The default
is that it draws lines at 36 cm/s, the fastest speed: but this may be reduced
if the pens are old. A speed of 10 cm/s is recommended for the plotting of
overhead projection slides.
$b3
%routine P CURSOR (%integer %name STATE, X, Y)
$p Once this routine is called, the pen assembly can be moved about
by the buttons on the front of the plotter surrounding the ENTER button.
When the pen has been positioned in the desired place, the ENTER
button is pressed, and the plotter sends the current state, which
consists of whether the pen is up or down, followed by which pen
is selected: (UPDOWN*16!PEN).
UPDOWN is 0 if the pen is up, and 1 if the pen is down. PEN
refers to the current slot which is empty, which is 5 minus the current EDWIN
colour number. The X and Y coordinates are returned in device coordinates.
$n
$l1mu
The Printronix printer driver
$p The Printronix printer driver is designed to produce pictures on matrix
line printers which are made by Printronix.  Such printers can be accessed
from the VAX, Mouses, and EMAS systems.  In normal mode the printer prints a
page of 64 rows by 132 characters on a page, but when placed in matrix mode
the printer treats the page as an array of 780 x 780 points.  If the 
printer is being used by EDWIN, the picture is entered into a bit map of the
page as it is drawn, and this is sent to the printer when NEW FRAME or
TERMINATE$ EDWIN is called when the dot matrix is not all empty.
$p When the Printronix driver is initialised the output is sent to stream one
if the user has not previously called VIEW ON with the stream that he wishes
to use.  After the graphics program has completed, the user should send the
file produced to the printer in the following way -$b
a) Mouses
$b$t COPY <file> / LP: $b
b) EMAS
$b$t LIST <file> , .LP??$t4 where ?? can currently be 15, 41 or 78 $b
c) VAX
$b$t i) $  PRINT <file> $b0
$t ii) $ Send the file to an ERCC printer with the command NETFS.
$b2
$p Users should note that the routine VIEWPORT must be used if the printer
that they are using is fitted with paper of width 132, which is the default
assumed by the EDWIN driver.
$p The driver is present as  $b
%routine P300 (%integer COM, X, Y)
$p which only accepts the standard device driver commands.  The picture is
only drawn in black, and there are no alternate line styles available.
If characters are used these are all drawn as characters of quality 1 owing
to difficulties in mixing the printer's character set with arbitrary pictures.
$n
$l1mu
The Tektronix device driver
$p The Tektronix device driver is designed to drive the Tektronix 4000 series
storage tubes, and also drives ADM3A terminals when they are fitted with the
Tektronix graphics option card. The Tektronix terminals are 'storage tubes',
which 
means that once a picture has been drawn, any changes to the picture can only
be shown by completely erasing the screen, and drawing the altered picture.
$p The terminals operate in two distinct modes. The first of these is 'Graph
mode', where the screen is addresed as an array of 1023 x 1023 points (of 
which only the points whose Y coordinates are in the range 0 to 779 are 
visible).
The Tektronix hardware allows the beam to be positioned at a specific point, 
and then allows vectors to be drawn to other points. The other mode is 
'alpha-numeric mode', in which the Tektronix simulates a normal terminal.
In this mode the user must explicitly clear the screen periodically by the use
of the ERASE and HOME keys for 4002s, SHIFT and CLEAR keys for the ADM3A,
and PAGE or PAGE RESET for the other models.
It is also necessary to clear the screen when a Tektronix is first switched on.
EDWIN automatically ensures that the terminal
is in the correct mode for the function that it is to perform, but the routine
UPDATE may be used to force the terminal into alpha-numeric mode.
$p If the display is not altered for a while, the Tektronix reduces the
intensity of the display to avoid damage to the screen. The normal intensity 
is restored by pressing the VIEW key on the 4002 or any key (eg. the SHIFT key)

on the later models.

$p Some models in the range of Tektronix terminals support a cross-hair cursor
which users can use to interact with their program. The cursor appears when
the
EDWIN routine CURSOR is called, and the user can then move the cursor around 
the screen by means of a joystick or thumb wheels (depending on the type of
Tektronix being used). When the user hits a key on the terminal the cursor
disappears and the routine CURSOR returns the ISO value of the key struck in
STATUS and the 
virtual coordinates of the cursor in the parameters X and Y.
A control character should not be used to terminate cursor mode, as this can
cause problems with some operating systems.
$b3$l1m
Routines specific to the Tektronix driver
$b3
%routine T4000 (%integer COM, X, Y)
$p This routine is the Tektronix device driver.  The parameters are the same 
as those of the general device driver described on page 14.
$b3
%routine T CURSOR (%integer %name CHAR, X, Y)
$p This routine has the same effect as the general EDWIN CURSOR routine, but
the coordinates of X and Y are returned in device coordinates, rather than 
virtual coordinates.
The parameter CHAR is set to the ISO value of the key struck to terminate
cursor mode.
$n$p
The maximum size of VIEWPORT is 0 to 1023 in both the X and Y directions,
and this is also the default. Note that only Y coordinates in the range 0 to
779 are visible. In the case of the model 4014 the default viewport is also
0 to 1023 in both the X and Y directions which maps onto the whole screen,
but if the terminal is being driven in enhanced mode, the maximum size of
viewport becomes 0 to 4095 in X and Y, of which Y coordinates in the range
0 to 3209 are visible.
Enhanced mode is automaticaly entered if a Tektronix 4014 has an upper viewport
bound of more than 1023 set.
$b$p The details of each model are: -
$b2
4002 $p
These have upper and lower case, and two hardware character sizes of 12 and
24 units respectively. The cursor is controlled by an external joy stick if
one is provided.
$b2
4006 $p 
These terminals are upper case only, with no adjustable attributes, and have
no cursor.
$b2
4010 $p
These terminals are identical to the model 4006 except that
they have a cursor, which is controlled by means of thumb wheels.
$b2
4012 $p
These terminals are identical to the 4010, with the addition of a lower
case character set.
$b2
4014 $p
These terminals have upper and lower case, 5 line styles, 4 character sizes of
14, 12.75, 8.5, 7.5 screen units. The largest of these is selected when the
terminal is switched on, and the character size desired can be selected by
entering local mode, and typing ESCAPE followed by '8', '9', ':',
or ';' to set 
the respective sizes mentioned above. When EDWIN initialises for a 4014 the
12.75 character size is selected, which means that drawings will have a 
similar
size of character to that which they would have if they were running on other 
models in
the range, and TERMINATE EDWIN resets to the smallest size,
as this is what most
users prefer. The enhanced resolution available on the model 4014 has been 
mentioned previously.
$b2 
ADM 3A $t (made by Lear Siegler inc.) $p
This terminal is similar to a 4006, 4010 or 4012 depending on whether it
has been fitted with a lower case option. They have no cursor. Any of the
model numbers mentioned may be used to initialise this terminal.
$n
$l1mu
The VT15 device driver
$p This device driver controls the VT15 graphics processor which is a PDP-15 
option. This processor controls VT04 displays, which are line drawing 
refresh displays. The picture is continually being redrawn by the VT15 
processor, while the PDP-15 runs a program which interacts with the VT15.
$p The VT15 driver can be used in two ways. The first of these is to write a
program for the PDP-15 which uses EDWIN. This approach is not recommended, as
the user is likely to run into problems with the amount of store available
for his program, and has also to work with a subset of the IMP language.
The other approach is to give the command $.VTSAT on the PDP-15, and then the
PDP-15 can be used as a satellite from VAX. The device type 15 should be given
to initialise for the VT15 device driver.
$p The VT04 terminals have 0 to 1023 points in both the X and Y directions, 
and this is the default and maximum view of the viewport. They have a set of
seven intensities, of which 5 is the default. There are four line styles, 
the standard EDWIN set with the exception of 'chain lines'. Although there
is a limited hardware character set EDWIN does not make use of it, as 
it has no lower case, and the characters are of very low quality. All
characters are thus drawn as EDWIN software characters.
The VT15 driver provides a simulated cursor on the VT04 by displaying a
tracking cross, and the user can use the light pen to indicate points on
the screen.
The routine CURSOR returns control to the user program with the current
X and Y coordinates in the parameters X and Y, after 30
seconds with no initial light pen hit, or 5 seconds since the last
light pen hit.
The STATUS value which the cursor returns is the binary value of the 
six buttons on the VT04 terminal.

$b3 $l1m
Routines specific to the VT15 driver

$b2
%routine VT15 (%integer COM, X, Y)
$p This is the VT15 device driver,
which accepts the instructions which were mentioned for the
general device driver, and also a set of instructions
having command code 12, which allow the full use of the VT15
hardware facilities. The X coordinate defines which function 
is desired, and the Y parameter is ignored.
$b
$tSTOP VT    - VT15 (12, 1, 0)$b0
$tSTART VT   - VT15 (12, 2, 0) $p
These routines can be used to explicitly stop, and start the 
VT15 processor. An example of their use is when
the user wants to draw all of a picture, and then have it appear
on the VT04 terminal suddenly, without a slow buildup. In this
case they would call STOP VT after initialising, then draw
the picture and finaly call START VT.
$n
$b2
$t ENABLE PEN    -  VT15 (12, 3, 0) $b0
$t DISABLE PEN   -  VT15 (12, 4, 0) $p
These routines determine whether any lines drawn are sensitive
to the light pen. The default is that lines
will not be noticed by the light pen.
$b2
$t ENABLE BLINK   - VT15 (12, 5, 0) $b0
$t DISABLE BLINK  - VT15 (12, 6, 0) $p
The VT15 has a hardware blink feature, which may be enabled,
and disabled by the above calls to VT15. The default is for
the blinking to be disabled. If blinking is enabled, all lines
drawn afterwards will blink. If the blinking is to be stopped,
the picture will have to be cleared and redrawn by the use of NEWFRAME.
$b3
%routine V CURSOR (%integer %name STATE, X, Y)
$p
This routine is similar to the EDWIN CURSOR routine for the
VT15, except that the X and Y values are returned in device
coordinates. The integer STATE contains the logical OR of the sets of
six buttons on each VT04 console. If the
parameters to this routine are assigned, then the tracking cross appears
at this point on the screen.
$b3
%routine TRACK (%integer %name X , Y)
$p This routine may be used to display the tracking cross, but to return
after the first light pen hit, or a 30 second time out.
 It can consequently be used to interact with programs
in a more immediate way than the routine CURSOR. The  coordinates 
X and Y are returned in device coordinates. An example of the use
of TRACK would be in a program which was only interested in a light pen
hit which was within a certain area. $b
$t TRACK (X, Y) %until X<20 %and 10<=Y<=100 $b2
%integer %fn VT BUTTONS
$p This function returns the value of the six buttons on the
front of the VT04 display. Note that it is the logical OR of buttons
on all displays.
Bits are set to 1 if the button light is on, and the most significant bit
(32) is the left hand button.
$b2
$p Users of the VT15 who wish to have 'moving' pictures are referred
to the device specific package, 'SOGGY' [27].

$n
$l1mu
A set of geometric utility routines
$b$p
The routines described
in this section provide the user with a standard set of routines
for drawing geometric shapes on any of the EDWIN devices.  It must be emphasised
that there is nothing 'magic' about these routines, and that any user could
write them. Also although this set of routines is described in the
EDWIN users guide, it is not strictly part of EDWIN, and cannot be assumed to
be present in every EDWIN library.  In particular, it is not possible to 
provide the routines in this section on machines which cannot perform 
floating point arithmetic.
All the routines in this section are designed to generate closed shapes, and
on devices such as CHARLES, these closed shapes are automaticaly shaded.
On devices which have no automatic shading only the outline of the resulting
shape is drawn.
All the routines clip the resulting polygon, if clipping is enabled.
The routines make as much use of device specific features as possible, (eg.
using hardware circles on the HP plotter) while retaining the device 
independence of the picture.
$p All the routines assume the following record format has been declared -
$b %record %format POINTF (%integer X, Y)
$p Owing to that fact that the routines in this section are not strictly part
of the EDWIN package, the following routines must be explicitly declared.
$b2
%routine POLYGON (%integer NUM ELE, %record (POINTF) %array %name PTS)
$p This routine draws an arbitary polygon, on the current device. The
polgon is assumed to be defined by the set of points PTS(1) to PTS(NUM$ ELE).
The polygon need not be closed.
VAX Pascal users should see the section on cross-calling for details of how
to access this routine.
The polygon is clipped to the current window by default. 
Clipping entails a significant expenditure of CPU time, so that if
all the polygons to be drawn are known to be inside the current window, and 
there
are a large number to draw, then the routine CLIP OFF may be called to suppress
clipping.  Clipping is enabled again by calling the routine CLIP ON.
$b2
%routine S BOX (%record (POINTF) %name L, U)
$p This routine draws a Simple BOX, ie. one which is orthogonal to the axes.
This can often be done faster and more simply than for the general box drawing
routine which is described below.  L and U are assumed to represent the lower
left and upper right corners of the box, but they are swapped if they have been
specified in the wrong order.
$b2
%routine BOX (%integer L, W, %record (POINTF) %name C, D)
$p This routine draws an arbitary box, with length L, width W and centre C,
with D representing a direction vector.  The box is rotated so that side L lies
in the direction given by the direction vector.  
A direction vector of (1,3) would result in the box having an anti-clockwise
rotation of 60 degrees applied about its centre before it is drawn.
The box is converted to a polygon for clipping and drawing.
$n
%routine FLASH (%record (POINTF) %name C, %integer D)
$p This routine draws a round circle with diameter D centered at the point C.
If the device does not have a hardware circle primitive, then the number of
sides used can be set by the following routine. The default number of sides is
8.
$b2
%routine SET FLASH POINTS (%integer SIDES)
$p This routine decides how many sides a flash should be drawn with if the
flash has to be converted to a polygon.  The default number of sides is 8, and
this is the minimum number of sides which may be set. The maximum number of
sides is 100, and any attempt to try to use more sides results in 100 being
used.  The user must choose SIDES to give as round a circle as
possible, but a large choice of SIDES results in longer plot times.
This routine is also used to enable an alternative drawing mode of the routine
WIRE, which is described below.
$b2
%routine WIRE (%integer W, N, %record (POINTF) %array %name PTS)
$p The array PTS is assumed to define a 'wire' from PTS(1) to PTS(N). The strict
definition of a wire is the area which is covered by moving a circle of width
W along the set of points defined by the array PTS. This results in the
wire having a rounded ends, and rounded corners. As this would be 
time$ consuming
to plot, the default mode of drawing wires is to extend the wire at the ends
and convert the wire to a polygon, and draw it.  If a user wishes to use the
strict definition of WIRE he can set the number of flash points by the
routine SET FLASH POINTS, and then wires are drawn as a series of boxes, with
round flashes superimposed at the junctions.
VAX Pascal users should see the section on cross calling of Pascal and IMP for
details of how to access this routine.
$n
$l1mu
A transformation stack
$p The following routines may be used to provide a graphics program with
a transformation stack for a two dimensional coordinate system.  The routines
come under two headings, $b
$t a) Routines for creating transformation matrices $b0
$t b) Routines for manipulating the transformation stack $b
The transformation stack routines are only available on versions of EDWIN 
which are running on machines with floating point arithmetic, and any routines
which are used from this section require explicit declarations.
The routines in this section may not be cross called from most other langages,
but users are referred to the system library manuals of the machine which they
are using if they wish to check.
The transformation matrices which these routines work on are described in more
detail in Newman and Sproull [28].
All the arrays for the following routines are addressed from 0 to 8, and these
are assumed to represent matrices of the following format - $b0$l3m
( 0 1 2 )
( 3 4 5 )
( 6 7 8 )

$b
a) Routines to create transformation matrices -
$b2
%routine M TRANSLATE (%integer X, Y, %real %array %name TX)
$p This routine sets the array TX to be the transformation which will translate
a point (a,$ b) to a point (a',$ b') such that - $b
$t3 a' = a + x $b0
$t3 b' = b + y $b2
%routine M MX (%real %array %name TX)
$p This routine sets the array TX to be the transformation which mirrors a point
in the X axis.  eg. $b0
$t3 a' = - a $b0
$t3 b' = b $b2
%routine M MY (%real %array %name TX)
$p This routine sets the array TX to be the transformation which mirrors a point
in the Y axis.  eg. $b0
$t3 a' = a $b0
$t3 b' = - b $b2
%routine M ROTATE (%integer X, Y, %real %array %name TX)
$p This routine sets the array TX to be the transformation which is a rotation,
the value of which is specified by the direction vector (X,$ Y), and
Z = SQRT( X * X + Y * Y). $b
$t3 a' = (X/Z) * a + (-Y/Z) * b $b0
$t3 b' = (Y/Z) * a + (X/Z) * b $b2
b) Routines to manipulate the transformation stack
$b2
%routine INIT TRANS
$p This initialises the transformation stack module.  It is automatically 
called if there is an attempt to add a transformation to the stack when it has
not been initialised.  The base element of the stack is set to be a null 
transformation, (ie. the unit matrix).
$b2
%routine PUSH TRANS (%real %array %name TX)
$p This routine pushes the transformation TX onto the stack, by multiplying
the transformation with the transformation which was previously top of the
stack.  EDWIN error 10 is signalled if the stack overflows. The stack limit is 
currently set to be 25 matrices.
$b2
%routine POP TRANS (%real %array %name TX)
$p The transformation at the top of the stack is discarded, and the
one which is now at the top of the stack becomes the current transformation.
EDWIN error 9 is signalled if an attempt is made to pop a transformation before
the stack is initialised, and EDWIN error 11 is signalled if the user attempts
to pop more transformations than have been pushed.
$b2
%routine INQUIRE TRANSFORM (%real %array %name TX)
$p This routine sets TX to be the transformation at the top of the stack.
In this way a compound transformation can be stored and later restored by
pushing it onto the stack, (when the current transformation is unity)
to be used as the current transformation.
$b2
%routine TRANSFORM POINT (%record (POINTF) %name P, NP)
$p This routine transforms the point P to the point NP under the current
transformation.  Addressing the current transformation as array A,
the effect of this routine is  $b
$t NP$_X = A(0) * X + A(3) * Y + A(6) $b0
$t NP$_Y = A(1) * X + A(4) * Y + A(7)
$b2
%routine TRANSFORM VECTOR (%record (POINTF) %name V, NV)
$p This routine transforms the direction vector V to the vector NV under the 
current
transformation.  The effect is the same as for the routine TRANSFORM$ POINT,
except that the displacement in A(6) and A(7) is not added in.
$n
$l1mu
Accessing EDWIN
$b
a) Under VMS on the VAX-11/780 $b
$a left=10;line=65
Users should add the command GRAPHSETUP in their LOGIN.COM files
to set up the aliasses described in this guide.
$b
The file $$EDWIN:.INC contains the routine specs (see appendix B). $b
Graphics programs should be linked by the commands - $b
$t LINK PROG,$$EDWIN/OPT $b0
or$t SLINK PROG,$$EDWIN/OPT $  for IMP with streams$b
The VAX version of EDWIN contains device drivers - $b
$  C963 $  CATS $  CHAS $  HP2648 $  P300 $  P7221 $  T4000
$b3
$a left=3
b) Under EMAS on the ICL 2900 range $b
$a left=10
The file CONLIB.EDWIN$_INC contains the routine specs. $b
The EDWIN library is made available by executing the command $b
$t OPTION SEARCHDIR=CONLIB.EDWINDIR $b
The EMAS version of EDWIN contains device drivers - $b
$  C963 $  CATS $  CHAS $  HP2648 $  P300 $  P7221 $  T4000
$p While initialising, EDWIN automatically sets graphics mode if a terminal
is being used.
$b3
$a left=3
c) Under MOUSES on the Perkin-Elmer machines.
$a left=10
$b The file EDWIN:EDWIN.INC contains the routine specs. $b
EDWIN is made available by the command - $b
$T LIB EDWIN:EDWIN $b
The MOUSES version of EDWIN contains device drivers - $b
$  CATS $  P300 $  T4000
$n
$b3
$a left=3
d) Under RSX-11/M on PDP-11s $b
$aleft=10
The file LB:[1,1]EDWIN.INC contains the routine specs. $b
The library is automatically searched by the task builder,
so no special action is necessary for linking.
$b The RSX-11/M version of EDWIN contains device drivers -
$b $  HP2648 $  CATS $  T4000
$a left=3
$b3
e) Under ISYS on the Interdata series 70 $b
$a left=10
The file EDWIN.EDWIN:INC contains the routine specs. $b
Graphics programs should be linked by the command - $b
$t LINK program,EDWIN.EDWINLIB $b
This version currently only supports a CATs driver.
$b3
$a left=3
f) Under the IMP15 system on PDP-15s $b
$a left=10
Graphics programs should be compiled with the command  - $b
$t C $.EDWIN+prog/obj,map $b
where $.EDWIN contains the initial %begin, and EDWIN is added to the program
in source form. The limited PDP-15 library mechanism prevents the use of
external routines.  This version of EDWIN only contains a driver for the VT15s.

$p The command $.VTSAT is used to run the satellite software,
 allowing the VT15s

to be used from VAX.
$b$p There are  space problems in fitting EDWIN into the PDP-15 as there
is a limit of 8K on the program size. If the array describing
software characters is declared as
%own then this would count as 2000 words of code, but if it is 
just a normal array it does not count as code. For this reason on the
PDP-15 the routine SET CHAR PDF must be used, and this reads the software
character definitions into an internal array from the current input 
stream. For example if stream 3 was selected before SET CHAR PDF was 
called then the program would be run on the PDP-15 by the command$b
$t R <stream1>,<stream2>,$.CHAR PDF/any outputs
$b3
$a left=3
$a left=3
$a line=72
$n
$l1mu
Cross calling EDWIN from other languages
$p On machines such as VAX, MOUSES, and EMAS where there are a number of
compilers for different languages which conform to a standard format of 
object file, any of the compilers may be used to write graphics programs 
using the EDWIN library.  Users are referred to the system library manuals
of the system which they are using for the information which is applicable
to their machine, but some details of the use of EDWIN from Fortran and 
Pascal are given below.
$b2
a) Fortran
$p In Fortran all subroutines are defined to have reference-type parameters,
(ie. in IMP terms only %integer %name parameters can be used). To allow 
Fortran programs to access EDWIN a number of interface routines have been 
provided, with the same function as described elsewhere in this guide,
but with different names, and parameter passing modes.  Subroutines with 
no parameters, or only %name type parameters, may be called directly.
The following routines are provided - $b
$t2 Fortran name $t4 IMP name $b
$t2 INIT FOR $t4 INITIALISE FOR$b0
$t2 MOVE A $t4 MOVE ABS$b0
$t2 MOVE R $t4 MOVE REL$b0
$t2 LINE A $t4 LINE ABS$b0
$t2 LINE R $t4 LINE REL$b0
$t2 MARK A $t4 MARKER ABS$b0
$t2 MARK R $t4 MARKER REL$b0
$t2 CHAR $t4 CHARACTER$b0
$t2 STR ON $t4 STORE ON$b0
$t2 V ON $t4 VIEW ON$b0
$t2 ASPECT RAT $t4 ASPECT RATIOING$b0
$t2 F WINDOW $t4 WINDOW$b0
$t2 F VIEW PORT $t4 VIEW PORT$b0
$b
$p All the attribute routines described in section D have the word SET 
replaced by the letter S.   (eg. SET COLOUR becomes S COLOUR).
$p All other device specific routines which are not directly callable
from Fortran have the routine name prefixed by the letter 'F'.
$p Note that the versions of Fortran on VAX, MOUSES and EMAS do not impose
a limit of 6 characters in names.
$n
b) Pascal
$b2
In general the IMP routine specification is converted to the Pascal procedure
spec as shown by the following example. $b
$t %external %routine %spec INITIALISE FOR (%integer DEV) $b0
becomes$b0
$t%procedure INITIALISEFOR (DEV : %integer ); %extern;
$b
$p The files '$$EDWIN:.PAS', 'CONLIB.EDWIN_PAS' and 'EDWIN:EDWIN.PAS' on
VAX, EMAS and MOUSES respectivly contain a full set of the EDWIN procedure
declarations in the required Pascal format for the machine which they are
using.  Users can edit these files into their own Pascal programs.
$p In the case of VAX, external Pascal procedures have different parameter
passing formats from external IMP routines, but this is catered for in the
file $$EDWIN:.PAS.   On VAX the Pascal compiler allows the statement $b
$t2 $%include '$$EDWIN:.PAS'$b
and this should be used (with no ';') rather than users declaring their own
external procedures.   It should be placed after any declarations and before
the initial %begin.
Programs should be linked with $$EDWIN/OPT as described in the previous section.
$p VAX users are referred to the format of the file $$EDWIN:.PAS if they need
to declare any of the machine/device specific routines.  If the VAX user wishes
to use the routines WIRE or POLYGON, owing to the way that arrays are passed
between IMP and Pascal they should use the routines PASWIRE and PASPOLYGON
which convert the parameters to the appropriate IMP call. The following example
shows the calling of the procedure PASPOLYGON - $b

$a left=5
$l0
program skeleton (input, output)

type pointf = record
                 x, y : integer;
              end;

     pointa = array [0..10] of pointf;
     { note the user must choose the max size at compile time}

var  p : pointa;
     i : integer;

$%include '$$edwin:.pas'
procedure paspolygon ($%immed numpts : integer; var parray : pot);  extern;

begin
    initialisefor (ord('C'));  { Charles}
    newframe;
    { fill in points 1 to 10 of P, set I to be the number used}
    paspolygon (i, p);
    terminateedwin
end.

$a left=3

$n
$l1mu
Use of the VIEWPDF program
$p This utility can be
used to view pictures which have been dumped by the storing feature of EDWIN.
The form of the command is - $b
$t2 VIEWPDF picture/outfile$b
where 'picture' is a picture produced by the use of the EDWIN routine
"STORE ON", and 'outfile' is an optional file which is used for 
printronix output.
$p 
The program starts by prompting "Device type: ", (with the exception of the
PDP-15 version, which only draws on the VT15), and the number of a valid
EDWIN device should be given.
If the device is a plotter, the user is also prompted for the size of plot.
This should be a number of centimeters. If one number is given on the
line then a square viewport is set, otherwise the two numbers specify the
X and Y sizes of the plot respectivly.
$p
The program then interprets the instructions describing the picture, until
either an end of picture instruction (produced by TERMINATE EDWIN) or a 
NEWFRAME instruction
is encountered. The program then prompts "Another?", and if the response "N" or
"NO" is received, the program stops, otherwise the program continues hoping to
find another picture description on stream one. The program automatically stops
if the picture description runs out.
$b2
Notes -
$b
a) Each picture is self defined, and any number of pictures can be joined
together in one file.
$b
b) This provides a useful method of plotting pictures, without wasting plotter
paper and time on unwanted plots.
$b3
Accessing the VIEWPDF program on the different implementations -
$b
$t VIEWPDF pic/file $t4 under VMS $b0
$t VIEWPDF pic/.LP15 $t4 under EMAS $b0
$t EDWIN:VIEWPDF pic/file $t4 under MOUSES $b0
$t EDWIN.VIEWPDF pic $t4 under ISYS $b0
$t $.VIEW pic $t4 on the PDP-15/40
$b3$l1mu
Use of the PDFDEC program
$p This utility can be used to decode a PDF into a HEX dump and an IMP program.
The form of the command is  $B  $T  PDFDEC $ pdf/decode $B
where the program is called in the same manner as the VIEWPDF program described
above.  Although the program is mainly designed for the inspection of PDFs, a
number of users have found it useful for recreating programs to draw pictures.
The program terminates when the file ends, or if the PDF is found to be corrupt.
$n
$l1mu
Appendix A : EDWIN error messages
$p Errors with EDWIN are reported by the IMP77 signal mechanism. Event 14 is
signalled, with the sub event giving which of the following errors occurred.
These events may be trapped and then analysed by the IMP event trapping
mechanism.
$b2
%Error %number %Description: $b
$  0$t2 Device driver initialisation fails.$b
$  1$t2 No room left in VT15 display file. $b
$  2$t2 Internal error in the device driver. $b
$  5$t2 Attempting to review a corrupt PDF. $b
$  6$t2 Trying to change an undefined attribute. $b
$  7$t2 Internal error in the geometric routines. $b
$  8$t2 There is no CURSOR on currently selected device.$b
$  9$t2 Transformation stack not intialised.$b
$ 10$t2 Transformation stack underflow, ie. too many POPs.$b
$ 11$t2 Transformation stack overflow.$b3
$p In general EDWIN tries to avoid giving up. Examples of this are if a viewport outside the coordinate range is given, the largest one that the device 
supports is used, and any attempt to draw software 
control characters is ignored.
$p If a program wishes to find out what error is meant by a given number then
the following function returns a text description of what is meant for each
error. $b
%string (63) %function EDWIN ERROR (%integer NUM)
$n
$l2mu
Appendix B : Listing of the normal EDWIN procedure specs

   ! EDWIN routine specs added. $b0
   %end %of %list$b0
   !$b0
   ! Routines for initialisation and termination$b0
   %external %routine %spec INITIALISE FOR (%integer DEVICE TYPE)$b0
   %external %routine %spec TERMINATE EDWIN $b0
   !$b0
   ! Output primitives$b0
   %external %routine %spec MOVE ABS (%integer X,Y)$b0
   %external %routine %spec MOVE REL (%integer DX,DY)$b0
   %external %routine %spec LINE ABS (%integer X,Y)$b0
   %external %routine %spec LINE REL (%integer DX,DY)$b0
   %external %routine %spec MARKER ABS (%integer N,X,Y)$b0
   %external %routine %spec MARKER REL (%integer N,DX,DY)$b0
   %external %routine %spec CHARACTER (%integer SYM)$b0
   %external %routine %spec TEXT (%string (255) ST)$b0
   !$b0
   ! Control$b0
   %external %routine %spec NEW FRAME$b0
   %external %routine %spec UPDATE$b0
   %external %routine %spec CLIP ON$b0
   %external %routine %spec CLIP OFF$b0
   %external %routine %spec STORE ON (%integer STREAM)$b0
   %external %routine %spec STORE OFF$b0
   %external %routine %spec VIEW ON (%integer STREAM)$b0
   %external %routine %spec VIEW OFF$b0
   %external %routine %spec ASPECT RATIOING (%integer MODE)$b0
   %external %routine %spec WINDOW (%integer XL, XR, YB, YT)$b0
   %external %routine %spec VIEWPORT (%integer XL, XR, YB, YT)$b0
   !$b0
   ! Attributes$b0
   %external %routine %spec SET COLOUR (%integer COLOUR)$b0
   %external %routine %spec SET LINE STYLE (%integer STYLE)$b0
   %external %routine %spec SET INTENSITY  (%integer BRIGHTNESS)$b0
   %external %routine %spec SET CHAR SIZE (%integer SIZE)$b0
   %external %routine %spec SET CHAR ROT (%integer ROT)$b0
   %external %routine %spec SET CHAR QUALITY (%integer WHICH)$b0
   %external %routine %spec SET CHAR FONT (%integer WHICH)$b0
   %external %routine %spec SET CHAR SLANT (%integer ANGLE)$b0
   !$b0
   ! Miscellaneous routines$b0
   %external %routine %spec REVIEW$b0
   %external %routine %spec INQUIRE POSITION (%integer %name X,Y)$b0
   %external %routine %spec INQUIRE WINDOW (%integer %name XL,XR,YB,YT)$b0
   %external %routine %spec INQUIRE VIEWPORT (%integer %name XL,XR,YB,YT)$b0
   %external %routine %spec MAP TO DEVICE COORDS (%integer %name X,Y)$b0
   %external %routine %spec MAP TO VIRTUAL COORDS (%integer %name X,Y)$b0
   %external %routine %spec CURSOR (%integer %name STATE,X,Y)$b0
   %external %string (31) %fn %spec DEVICE NAME $b0
   %external %string (63) %fn %spec EDWIN ERROR (%integer N) $b0
   %external %integer %fn %spec DEFAULT DEVICE$b0
   %external %routine %spec DRIVE DEV (%integer COM, X, Y)$b0
   !$b0
   %list$b0
   %end %of %file$b0
$n
$l1mu
Appendix C : The EDWIN software character set
$n
$l1mu
Appendix D : Some Example programs
$p Note that the IMP $%include statement causes 3 lines to appear in the
listing which are NOT part of the source file.
$b2
$l0

          ERCC. Imp80 Compiler Release 1 Version 27 May 81

 255  765
   1      %include "CONLIB.EDWIN$_INC"
   2      ! EDWIN routine specs added.
   3      %end %of %list
  56      %end %of %file
  57      %external %routine %spec PROMPT (%string (15) S)
  58      %begin
  59      
  60      ! EDWIN test program 1
  61      ! This program tests the ability to draw lines and to read the cursor.
  62      ! The program reads four cursor locations, and then joins these by
  63      ! a mesh of lines.
  64      ! This is repeated until 'S' is the key hit in response to the cursor.
  65      
  66      %const %integer NUM = 10
  67      %integer I,CVAL,TYPE
  68      %integer %array X,Y (1:4)
  69      
  70      PROMPT ("Device Type:")
  71      READ (TYPE)
  72      INITIALISE FOR (TYPE)
  73      
  74      NEW FRAME;    ! This clears the screen
  75      
  76      %cycle
  77         %for I=1,1,4 %cycle
  78            ! This cycle reads the 4 points defining the two primary lines.
  79            CURSOR (CVAL, X(I) , Y(I))
  80            %exit %if CVAL = 'S' %or CVAL = 's'   ;! This stops the program.
  81            %if I&1=1 %then MOVE ABS(X(I),Y(I)) %else LINE ABS (X(I),Y(I))
  82         %repeat
  83       
  84         %exit %if CVAL = 'S' %or CVAL = 's'
  85      
  86         ! Now the points on these lines are joined up.
  87      
  88         %for I=0,1,NUM %cycle
  89            MOVEABS (X(1) + I*(X(2)-X(1))//NUM, Y(1) + I*(Y(2)-Y(1))//NUM)
  90            LINEABS (X(3) + I*(X(4)-X(3))//NUM, Y(3) + I*(Y(4)-Y(3))//NUM)
  91         %repeat
  92      %repeat
  93      
  94      TERMINATE EDWIN
  95      
  96      %end %of %program

    96 LINES ANALYSED IN   458 MSECS  -  SIZE=  2288

CODE   1096 BYTES      GLAP 376+ 0 BYTES      DIAG TABLES 104 BYTES
TOTAL  1576 BYTES

      80 STATEMENTS COMPILED IN  1047 MSECS
$n$l0
         Computer Science IMP-77 Compiler.  Version 4.17

    1  %include "EDWIN.EDWIN:INC"
    &  ! EDWIN routine specs added.
    &  %end %of %list
    &  %end %of %file
    2  %begin
    3  
    4     ! EDWIN test program 2
    5     ! This tests some of the attribute commands, for altering colour,
    6     ! line style, and character size.
    7     ! The picture is designed to show how windowing in EDWIN operates. 
    8     ! It is best run on a 4014 or VT15 to get the correct attributes set,
    9     ! because the other devices can't support the attributes.
   10  
   11     %const %integer BLACK = 1, BLUE = 2, RED = 4
   12     %const %integer NORMAL = 0, DOTTED = 1, SDASH = 3, LDASH = 4
   13     %integer TYPE
   14  
   15     %routine PRINT TEXT (%string (255) S, %integer X, Y)
   16        MOVE ABS (X,Y)
   17        TEXT (S)
   18     %end
   19  
   20     %routine JOIN (%integer X1, Y1, X2, Y2)
   21        MOVE ABS (X1,Y1)
   22        LINE ABS (X2,Y2)
   23     %end
   24   
   25     %routine RECT (%integer X, Y, H, V)
   26        MOVE ABS (X,Y)
   27        LINE REL (H,0); LINE REL (0,-V)
   28        LINE REL (-H,0); LINE REL (0,V)
   29     %end
   30  
   31     PROMPT ("Device Type:")
   32     READ (TYPE)
   33     INITIALISE FOR (TYPE)
   34  
   35     NEW FRAME
   36  
   37     STORE ON (2)
   38     ! A copy of the picture will be made on stream 2.
   39  
$n$b3$l0
   40     ! Now that everything is set up the picture can be drawn.
   41  
   42  
   43     RECT (0,1023,1023,1023)
   44  
   45     SET CHAR SIZE (14)
   46     SET LINE STYLE (LDASH)
   47     RECT (300,900,600,400)
   48     PRINT TEXT ("VIEW PLANE", 700, 920)
   49     
   50     SET CHAR SIZE (12)
   51     RECT (200,400,500,300)
   52     PRINT TEXT ("VIEW SURFACE", 720, 250)
   53  
   54     SET COLOUR (BLUE)
   55     SET LINE STYLE (SDASH)
   56     RECT (500,800,300,200)
   57     PRINT TEXT ("WINDOW", 620,810)
   58    
   59     RECT (300,350,200,200)
   60     SET CHAR SIZE (9)
   61     PRINT TEXT ("VIEW PORT", 350,170)
   62     
   63     SET LINE STYLE (DOTTED)
   64     SET COLOUR (RED)
   65     JOIN (500, 800, 300, 350)
   66     JOIN (800, 800, 500, 350)
   67     JOIN (500, 600, 300, 150)
   68     JOIN (800, 600, 500, 150)
   69  
   70     SET CHAR SIZE (7)
   71     PRINT TEXT ("VIEWING TRANSFORMATION", 720,450)
   72  
   73     TERMINATE EDWIN
   74  
   75  %end %of %program
? NORMAL unused
? BLACK unused

    90 Statements compiled
$n$l0

         Computer Science IMP77 Compiler.  Version 6.02

            Compiled on 10-JUN-1981 at 16:24:19

   Source file: $_DRA0:[GRAFIX.EDWIN]TEST3.IMP;1

   1  %include "$$EDWIN:.INC"
   &  ! EDWIN routine specs added.
   &  %end %of %list
   &  %end %of %file
   2  %begin
   3  
   4     ! EDWIN test program 3
   5     ! Program to check software characters,
   6     ! It checks both the size and rotation of the characters.
   7  
   8     %const %integer GOOD = 1
   9     %const %integer PDF STREAM = 1
  10     %integer I
  11  
  12     PROMPT ("Device: ")
  13     READ (I)
  14     INITIALISE FOR (I)
  15     NEW FRAME
  16  
  17     OPEN OUTPUT (PDF STREAM, "TEST3.PDF")
  18     STORE ON (PDF STREAM)
  19  
  20     SET CHAR QUALITY (GOOD)
  21  
  22     %for I = 0,1,3 %cycle
  23          MOVE ABS (511, 500)
  24          SET CHAR ROT (I*90)
  25          SET CHAR SIZE (12)
  26          TEXT ("CHAR at 12 OK")
  27          SET CHAR SIZE (24)
  28          TEXT ("CHAR at 24 OK")
  29     %repeat
  30  
  31  TERMINATE EDWIN
  32  
  33  %end %of %program

Code 292 bytes  Glap 88 bytes  Diags 138 bytes   Total size 518 bytes
    62 statements compiled in  3.10 seconds.  (1200 statements/minute)
$n$l0

      Computer Science VAX-11 IMP77 Compiler.  Version 8.01

            Compiled on 10-JUN-1981 at 16:24:26

   Source file: $_DRA0:[GRAFIX.EDWIN]TEST4.IMP;1

     1  %include "$$EDWIN:.INC"
 &   1  ! EDWIN routine specs added.
 &   2  %end %of %list
 &  55  %end %of %file
     2  %begin
     3     ! EDWIN test program 4
     4     ! Program to draw the EDWIN character set on a plotter to check for
     5     ! consistancy of letters, and also demonstrate the character set.
     6  
     7     %const %integer PDF STREAM = 2, GOOD = 1
     8     %integer I, X, Y
     9  
    10  PROMPT ("Device:")  ;  READ (I)  ;  INITIALISE FOR (I)
    11  
    12  NEW FRAME
    13  STORE ON (PDF STREAM)
    14  
    15  MOVE ABS (400, 20)  ;  ! Bottom right corner
    16  
    17  ! The boxes are now drawn to minimise moves.
    18  MOVE REL (-36, 0) %and LINE REL (-36, 0) %for I = 1, 1, 4
    19  LINE REL (0, 720)
    20  MOVE REL (36, 0) %and LINE REL (36, 0) %for I = 1, 1, 4
    21  %for I = 1, 1, 4 %cycle
    22     LINE REL (0, -720 )  ;  LINE REL (-36, 0)
    23     LINE REL (0, 720)  ;  LINE REL (-36, 0)
    24  %repeat
    25  %for I = 1, 1, 6 %cycle
    26     MOVE REL (0, -60)  ;  LINE REL (288, 0)
    27     MOVE REL (0, -60)  ;  LINE REL (-288, 0)
    28  %repeat
    29  
    30  X = 112  ;  Y = 697  ;  MOVE ABS (X, Y)  ;  I = 32
    31  
    32  SET CHAR SIZE (36)
    33  SET CHAR QUALITY (GOOD)
    34  
    35  %cycle; ! To draw the characters
    36     MARKER REL (4, 0, 0)
    37     CHARACTER (I)
    38     I = I + 1  ;  %exit %if I=127
    39     %if X = 364 %start; ! The end of a row
    40         MARKER REL (4, 0, 0)
    41         Y = Y - 60
    42         X = 112
    43     %finish %else X = X + 36
    44     MOVE ABS (X, Y)
    45  %repeat
    46  
    47  TERMINATE EDWIN
    48  %end %of %program
Code 732 bytes  Glap 48 bytes  Diags 232 bytes   Total size 1012 bytes
    85 statements compiled in  2.96 seconds.  (1722 statements/minute)
$n
$l0
Source file: test5     compiled on 10-JUN-81 at 19.04.00
Object file: TEST5.EXE

         Edinburgh IMP77 Compiler - Version 8.1

     1  %include "edwin:edwin.inc"
 &   1  ! EDWIN routine specs added.
 &   2  %end %of %list
 &  55  %end %of %file
     2  %begin
     3     ! EDWIN test program 5
     4     ! A demonstration program for the EDWIN CATs driver.
     5  
     6     %const %integer GOOD=1, LOW=0
     7     %integer SYM,TYPE
     8  
     9     %routine BOX (%integer XL,YL,XR,YR)
    10        MOVE ABS (XL,YL)
    11        LINE REL (0,YR-YL)
    12        LINE REL (XR-XL,0)
    13        LINE REL (0,-(YR-YL))
    14        LINE REL (-(XR-XL),0)
    15     %end
    16  
    17     %routine PAGE 1
    18        NEWFRAME
    19        MOVE ABS (12,21)
    20        TEXT ("This introduces a new version of")
    21        MOVE ABS (10,6)
    22        SET CHAR QUALITY (GOOD)
    23        TEXT ("EDWIN")
    24        MOVE ABS (41,4)
    25        SET CHAR QUALITY (LOW)
    26        TEXT ("for the ")
    27        TEXT ("Visual 200") %if TYPE=200
    28        TEXT ("Bantam 550") %if TYPE=550
    29        TEXT (" terminals")
    30        BOX (5,3,74,22)
    31        MOVE ABS (0,1)
    32        UPDATE
    33     %end
    34  
    35     %routine PAGE2
    36        %routine CROSS
    37           LINE REL (20,20)
    38           MOVE REL (-20,0)
    39           LINE REL (20,-20)
    40        %end
    41  
    42        NEW FRAME
    43        MOVE ABS (0,2)
    44        CROSS
    45        MOVE ABS (55,2)
    46        CROSS
    47        MOVE ABS (31,12)
    48        TEXT ("When things go wrong")
    49        MOVE ABS (32,10)
    50        TEXT ("Don't get cross!!")
    51        UPDATE
    52     %end $b3$l0
    53  
    54     Prompt ("Terminal type: ")
    55     Read (TYPE)
    56     Initialise for (TYPE)
    57     Aspect ratioing (0); ! Off
    58     Window (0, 79, 0, 23)
    59  
    60     Print string ("Enter line style required as a number between 0 and 4")
    61     Newline
    62     Prompt ("Number: ")
    63     Read (SYM) %until 0<=SYM<=7
    64     Set line style (SYM)
    65     Read symbol (SYM) %until SYM=NL
    66  
    67     Prompt ("Hit RETURN key")
    68  
    69     Page1
    70     Read symbol (SYM) %until SYM = NL
    71     Page2
    72  
    73     Terminate edwin
    74  %end %of %program
$n
$a und=0
$l0
               IMP77 Compiler for PDP-11

File: _DRA0:[GRAFIX.EDWIN]TEST6.IMP;1       16:24:54     10-JUN-1981

         Edinburgh IMP77 Compiler - Version 8.1a

     1  %include "$$edwin:.inc"
 &   1  ! EDWIN routine specs added.
 &   2  %end %of %list
 &  55  %end %of %file
     2  %begin
     3     ! EDWIN test program 6
     4     ! Acknowledgements to PSR and ADC for this program.
     5     ! Something to do with a fast video
     6  
     7     %own %string (40) %array pic(1:8) = 
     8+       "  ~\",
     9+       "    \   /~~~~~~~~~\",
    10+       "    /  /           ~\     /~\",
    11+       "   /  /              ~\   |  |",
    12+       "  (  /   ___           ~\_\  /_",
    13+       "  (  |      \                  \",
    14+       "   \_|       \___       |     o \",
    15+       "     \___________\_______\_______\"
    16     %byte %integer %name eye == charno(pic(7),31)
    17     %const %integer  open = 'o', closed = '*'
    18     %integer j, left
    19  
    20     prompt ("Terminal: ")
    21     read (j)
    22     initialise for (j)
    23     aspect ratioing (0)
    24     viewport(2,66,1,8)
    25     window(2,66,1,8)
    26     newframe
    27  
    28     left = 2
    29     %cycle
    30        moveabs(left,9-j) %and text(pic(j)) %for j = 1,1,8
    31        left = left + 2
    32        eye = open + closed - eye
    33     %repeat %until left = 74
    34  
    35     terminate edwin
    36  
    37  %end %of %program
$n
$A JUST=1; left=3; INVERT=0
$L1UM
Appendix E : The Structure of the EDWIN PDF
$p 
The EDWIN Pseudo Display File (PDF) consists of a number of coded graphics
instructions, one per line, which can be dumped into a file. These
instructions contain all the information to re-generate the picture. The file
can be redrawn by the use of - $b
%routine REVIEW $b
which reads the current input and uses it to redraw the picture which it
represents. This appendix describes the instruction formats of in the PDF.
$b3
$L1UM
Drawing Instruction Formats
$P
These are of two types : $b
1) Normal Form- $p
This consists of one integer for the code giving the instruction
type, this is stored in the first half byte, and the other three half
bytes are zero. The next integer contains the X co-ordinate which the
instruction uses, and the final integer contains the Y co-ordinate.
$B
$t2 eg. $ $ $ | 0 0 0 code | $  | X value | $  | Y value |  $b2
2) Short Form - $p
This consists of the code integer, with the instruction code having 
had 16 added to it, the X and Y co-ordinates are packed into two 
eight bit fields inside the second integer. This means that for any
drawing instruction where both co-ordinates are in the range -128 to 127,
the shorter form may be used. This is frequently the case.
$B
$t2 eg. $t3 | 0 0 1 code | $  | X value , Y value| $b
$p The codes for the drawing instructions are - $b
$t2 0 $  - $  Line Abs
$b0$t2 1 $  - $  Move Abs
$b0$t2 2 $  - $  Marker Abs
$b0$t2 3 $  - $  Line Rel 
$b0$t2 4 $  - $  Move Rel
$b0$t2 5 $  - $  Marker Rel
$p The top byte of the first number is used to specify marker selection for
codes 2 and 5.
$N
$L1UM
Other Instruction Formats
$B
$L1U
Window
$p If the EDWIN routine WINDOW is called, the parameters are stored in the
PDF in the following form. The window is automatically altered if the
PDF is being reviewed.$b
$  eg. $  | 0 0 0 8 | $  | XL | $  | XR | $  | 0 0 0 8 | $  | YB | $  | YT | $b2
$l1u
Characters
$p This requires one integer.
The code dumped is -  $b
$t3  | 0 , char val , 9 |$  $  
$p CHAR VAL is a byte, containing the ASCII value  of the character to be 
drawn, and this is drawn at the current settings of character size, rotation,
and quality as set by change attribute value commands.
$B2$L1U
Change of attribute value.
$P This has code 10. The centre two half bytes contain
the value of the attribute, and the top half byte is one of the 
following codes :- $b
$t2 | 0 value A | => Colour Change $b0
$t2 | 1 value A | => Line Type Change $b0
$t2 | 2 value A | => Char Size Change $b0
$t2 | 3 value A | => Char Orientation Change $b0
$t2 | 4 value A | => Char Quality Change $b0
$t2 | 5 value A | => Char Font Change $b0
$t2 | 6 value A | => Intensity Change $b0
$t2 | F value A | => Aspect ratioing
$b2$l1u
Newframe and End
$p These require one integer of value eleven or twelve respectively. If either 
are encountered when interpreting a PDF it causes control to return to the
point where the interpreting routine was called from.
$n
$l1mu
Appendix F : Acknowledgements
$p If everyone who had contributed to EDWIN was mentioned the list would go
on for pages. The people who contributed most to the design were $b
$t3 Irene Buchanan $b0
$t3 Alan Gray $b0
$t3 Lee Smith $b0
$t3 Jeff Tansley $b0
$t3 Rainer Thonnes $b0
$t3 Ian Young $b
$p
Most users of EDWIN have reported their criticisms, and suggestions for
enhancements, a number of which have appeared in the latest version.
Thanks go to them, and to the users who have helped to get rid of bugs.
The systems programmers of all the systems which EDWIN runs on have also 
provided valuable help in providing machine specific driving routines.
$p Special thanks to Nick Rothwell, whose interactive design program (which
uses EDWIN) was used to design the cover picture.
$n
$l1mu
Appendix G : References
$l0

   [1]  Edinburgh Regional Computing Centre
        E. R. C. C. Graphics Manual                                July 1979

   [2]  H. Dewar
        PDP-15 Users Guide
        E. U. C. S. D.                                                  1974

   [3]  P. McLellan
        LEGOS Users Guide
        E. U. C. S. D.  report  CSR-49-79                           Dec 1979

   [4]  H. Whitfield & A. S. Wight
        EMAS : The Edinburgh Multi-Acess System
        E. U. C. S. D. EMAS report 1                                    1977

   [5]  Edinburgh Regional Computer Centre
        EMAS Users Guide                                            Dec 1976

   [6]  Edinburgh Regional Computer Centre
        EMAS 2900 Users Guide                                       Jan 1980

   [7]  VAX-11 Software Handbook
        Digital Equipment Co.                                          1977

   [8]  P. S. Robertson & C. Whitfield
        MOUSES
        Moray House, Edinburgh                                     Mar 1980

   [9]  P. Stephens
        The IMP programming language
        E. U. C. S. D. EMAS report 6                                    1977

   [10] P. S. Robertson
        The IMP-77 language
        E. U. C. S. D.  report CSR-19-77                            May 1979

   [11] C. A. D Centre
        GINO-F User Manual                                          Dec 1978

   [12] A. C. M. SIGGRAPH proposals
        A. C. M.  Computer Graphics                                Fall 1977

   [13] Tektronix 4002 Programming manual
        Tektronix co.                                                   1969

   [14] Tektronix 4010 Users Manual
        Tektronix co.                                                   1971

   [15] Tektronix 4012 Users Manual
        Tektronix co.                                                   1971

   [16] Tektronix 4014 Computer Display Terminal Users Manual
        Tektronix co.                                                   1974

   [17] VT15 Graphics Processor
        Digital Equipment Co.   DEC-15-H2J2-D                          1970
$n$l0

   [18] Model-550 Users Guide
        Perkin-Elmer                                                Sep 1978

   [19] Hewlett Packard 7221A plotter operating and programming manual
        Hewlett Packard                                             Nov 1977

   [20] Charles R. Minter
        Two Prototypes of the Colour Graphics Display
        California Institute of Technology, internal report.            1978

   [21] Visual 200 Video Display terminal reference manual
        Visual Technonlgy Inc.                                          1980

   [22] Graphics Terminal reference manual 2648A
        Hewlett Packard                                             Mar 1978

   [23] Printronix 300 Applications Manual
        Printronix                                                  Nov 1977

   [24] L. D. Smith
        The Elementry Structural Description Language
        E. U. C. S. D. report CSR-53-80                             Jan 1980

   [25] W. Laing (ed.)
        V L S I  Design  Tools
        E. U. C. S. D.  report                                          1980

   [26] E. E. Barton & I. Buchanan
        The Polygon Package
        E. U. C. S. D.  report CSR-44-79                            Oct 1979

   [27] I. A. Young
        The 'SOGGY' users manual
        E. U. C. S. D. Internal file                                Jul 1980

   [28] W. M. Newman & R. F. Sproull
        Principles of Interactive Computer Graphics
        McGraw Hill                                                     1980
$e
