                                            THE

                                         E D W I N

                                       USER'S  GUIDE

                                      (Fourth Edition)

                   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.

                                      J.  Gordon Hughes

                                                 December 1981

                                       CONTENTS

              Section                                                 Page

              Contents                                                  1

              A historical and logical overview of EDWIN.               2

              User's guide to the EDWIN procedures.
                      A) Initialisation and termination routines        5
                      B) Primitive output routines                      6
                      C) Control routines                               8
                      D) Attribute handling routines                   11
                      E) Miscellaneous procedures                      13

              The structure of the device drivers.                     14

              The Calcomp device driver.                               15

              The Charles driver.                                      17

              The Cursor Addressable Terminal drivers.                 19

              The H P model 2648 terminal driver.                      21

              The H P model 7221 plotter driver.                       22

              The Printronix printer driver.                           24

              The Tektronix device driver.                             25

              The VT15 device driver.                                  27

              A set of geometric utility routines.                     29

              A transformation stack.                                  31

              Acessing EDWIN                                           33
                      A) Under VMS on the VAX 11/780
                      B) Under EMAS on the ICL 2900 range
                      C) Under MOUSES on the Perkin-Elmer machines
                      D) Under RSX-11/M on the PDP-11 range
                      E) Under ISYS on the Interdata series 70
                      F) Under the IMP 15 system on the PDP-15s

              Cross calling of EDWIN from other languages.             35

              Use of the VIEWPDF program.                              37

              Use of the PDFDEC program.                               37

              Appendices
                      A) EDWIN error messages                          38
                      B) Listing of the normal EDWIN procedure specs   39
                      C) The EDWIN character set                       40
                      D) Some example programs                         41
                      E) The structure of the EDWIN PDF                49
                      F) Acknowledgements                              51
                      G) References                                    52

                      A historical and logical overview of EDWIN

         '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 :

      a) The package should be portable;
      b) The package should be small;
      c) The package should be independent of the graphics terminal being used.

         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:

              a) DEC PDP-15           (18 bit machines) [2]
              b) Interdata series 70  (16 bit machines) [3]
              c) ICL system 4-75      (32 bit machines) [4,5]
              d) ICL 2900             (32 bit machines) [6]

      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.

         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.

         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.

         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).

         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 -

                                                                   ______________
                                                                  |              |
                                                                  |   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

         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

              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]

         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].

      The rest of this guide describes:

         i) The user facilities -

      Drawing  pictures  with  EDWIN  is  a  matter  of  writing  a program which
      incorporates the procedure calls which are descibed in this section.

         ii) The device drivers -

      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.

         iii) Some useful utilities -

      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.

         iv) Appendices which cover -

      The EDWIN error messages
      The standard procedures provided
      The EDWIN character set
      A selection of example programs
      A definition of the stored picture format
      Acknowledgements and references

                          Users Guide to the EDWIN procedures

      A) Initialisation and Termination routines:

      routine INITIALISE FOR (integer DEVICE TYPE)

         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).

         The following DEVICE TYPES are valid :-
              0                       : The 'null' device
              15                      : VT15
              120                     : Soroc IQ 120 terminal
              300                     : Printronix printers
              550                     : Perkin Elmer 550 terminal (Bantam)
              200                     : Visual 200 terminal (VT52 compatable)
              69 ('E'), 101 ('e')     : Hazeltine Esprit terminal
              564, 565, 663, 963      : E.R.C.C.  Calcomp plotters
              2648                    : Hewlett Packard terminal
              7221, 7220              : Hewlett Packard plotters
              4002, 4010, 4012, 4014  : Tektronix storage tubes
              67 ('C'), 99 ('c')      : CHARLES driver
              76 ('L'), 108 ('l')     : Line printers

         Further  details  of  these  device drivers may be found in the sections
      following the description of the EDWIN procedures.

      routine TERMINATE EDWIN

         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.

      Examples of what is meant by 'normal' are -

              a) Tektronix terminals are set to alpha-numeric mode
              b) Roll plotters have all the paper used moved past the pen
              c) The VT15 processor is stopped
              d) The HP plotter pen is put away

      B) Primitive output routines :

         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.

      routine MOVE ABS (integer X,Y)

         This routine moves the current position to the point (X,Y).

      routine MOVE REL (integer DX,DY)

         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.

      routine LINE ABS (integer X,Y)

         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).

      routine LINE REL (integer DX,DY)

         This routine draws a line  to  (CX+DX,  CY+DY),  where  (CX,CY)  is  the
      current position, and updates the current position appropriately.

      routine MARKER ABS (integer N,X,Y)
      routine MARKER REL (integer N,X,Y)

         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 .

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

         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.

         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.

      routine CHARACTER (integer CH)

         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.

      routine TEXT (string (255) ST)

         This routine causes sequence of characters making up ST to be output.

         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.

         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.

      C) Control Routines :

         The following routines may  be  used  to  control  the  drawing  of  the
      picture.

      routine NEWFRAME

         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.

      routine UPDATE

         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.

      routine STORE ON (integer STREAM)

         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.

      routine STORE OFF

         This disables  the  recording  of  graphics  instructions,  and  is  the
      default.

      routine VIEW ON (integer STREAM)

         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.

      routine VIEW OFF

         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.

      routine WINDOW (integer XL, XR, YB, YT)

         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 -

      routine VIEWPORT (integer XL, XR, YB, YT)

         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.

         The  package  automatically maps the currently specified window onto the
      current viewport and clips the drawing appropriately.

         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.

         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.

      routine ASPECT RATIOING (integer STATE)

         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.

         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.

      D) Routines for changing Attribute settings :

         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.

      routine SET COLOUR (integer COLOUR)

         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 -

                      1 = Black (default)
                      2 = Blue
                      3 = Green
                      4 = Red

         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.

      routine SET LINE STYLE (integer STYLE)

         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).

      The following parameters are significant -

              0 = Normal Lines (default)
              1 = Dotted lines
              2 = Chain Lines (on 4014 and HP plotter; otherwise normal lines)
              3 = Short Dashed lines
              4 = Long dashed lines

      routine SET INTENSITY (integer BRIGHTNESS)

         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.

      routine SET CHAR SIZE (integer SIZE)

         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.

      routine SET CHAR ROT (integer DEGREES)

         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.

      routine SET CHAR QUALITY (integer QUALITY)

         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.

      routine SET CHAR FONT (integer FONT)

         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).

      routine SET CHAR SLANT (integer DEGREES)

         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.

      F) Miscellaneous procedures:

      routine INQUIRE POSITION (integer name X, Y)

         This  routine  sets  X  and  Y  equal  to the X and Y coordinates of the
      current virtual position.

      routine INQUIRE WINDOW (integer name XL, XR, YB, YT)

         This routine sets the parameters to  the  current  window  bounds.   The
      parameters are lower X, upper X, lower Y, upper Y, respectivly.

      routine INQUIRE VIEWPORT (integer name XL, XR, YB, YT)

         This  routine  sets the parameters to the current viewport bounds.   The
      order of the parameters is the same as for INQUIRE WINDOW.

      routine MAP TO DEVICE COORDS (integer name X, Y)

         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.

      routine MAP TO VIRTUAL COORDS (integer name X, Y)

         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.

      routine CURSOR (integer name STATUS, X, Y)

         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.

      routine D CURSOR (integer name STATUS, X, Y)

         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.

                      The structure of the EDWIN device drivers.

         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 -

      routine DRIVE DEV (integer COM, X, Y)

         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.

         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.

      The following is the significance of the general codes -

      Code      X       Y     Description

        0     TYPE      -     Initialise the driver for TYPE.
        1       -       -     Terminate
        2       -       -     Update
        3       -       -     Newframe
        4       X       Y     Move Abs to (X,Y)
        5       X       Y     Line Abs to (X,Y)
        6     CHAR      -     Output character CHAR
        7     WHICH    VAL    Change attribute WHICH to VAL
        8      XL      YB     Set lower device window bounds
        9      XR      YT     Set upper device window bounds

         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.

         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.
                      routine TTPUT (integer SYM)
                      routine FLUSH OUTPUT
                      integer fn TTREAD
                      integer fn TTGET

         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.

                               The Calcomp device driver

         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.

         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 -

                      $ DEFINE NETFS$DELIVER "Level 3 of the J.C.M.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 -

                      $ NETFS
                      >> device 2972
                      >> fire t.gp
                      >> stop

         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).

         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

                      OPEN OUTPUT (21, "MYPLOTFILE")

      The  routine OPEN OUTPUT (integer STREAM, string (255) FILE) requires to be
      explicitly declared on EMAS.

         The device driver is present as

      routine C963 (integer COM, X, Y)

         which has the same parameters as the general device driver described  on
      page 14.

         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.

         The plotters provide 4 line styles: these are the ones mentioned in  the
      routine SET LINE STYLE, with the exception of the 'chain lines'.

         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.

                                  The CHARLES driver

         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.

         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.

         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.

         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.

         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.

                        Routines specific to the Charles driver

      routine CHAS (integer COM, X, Y)

         This is the Charles device driver.   It accepts all the standard  device
      driver commands, and also commands 10 and 11.

      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.

      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.

      routine END MODE

         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.

      routine SET COLOUR MAP (integer REG, RED, BLUE, GREEN)

         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.

      routine C BIT PAD POS (integer name X, Y)

         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

      routine C CURSOR (integer name STATE, X, Y)

         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.

                        The Cursor Addressable Terminal drivers

         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.

         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.

         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.

         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.

         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

             Routines specific to the Cursor Addressable Terminal Drivers

      routine CATS (integer COM, X, Y)

         This  is the two terminal driver that is described above.   The commands
      are the same as for the standard device driver described previously.

      routine V CURSOR (integer name STATUS, X, Y)

         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 -

              BACK SPACE = cursor left        TAB = cursor right
              LINE FEED = cursor down         DEL = cursor up

      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.

         The  CURSOR  routines  are  NOT  available on the EMAS implementation of
      EDWIN.

                                The H P terminal driver

         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.

         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.

         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.

         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.

      Routines specific to the HP 2648A terminal driver -

      routine HP 2648A (integer COM, X, Y)

         This is the device driver, which only accepts the standard device driver
      commands which have been described previously.

      routine H CURSOR (integer name STATUS, X, Y)

         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.

                                The H P plotter driver

         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.

         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.

         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.

         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 -

              VIEWPORT (0, 28 * 400, 0, 20 * 400);   !  For A4  (28 cm x 20 cm)
              VIEWPORT (0, 40 * 400, 0, 28 * 400);   !  For A3  (40 cm x 28 cm)

         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.

         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.

                      Routines specific to the HP Plotter driver

      routine P7221 (integer COM, X, Y)

         This routine is the plotter driver.   The commands accepted are the same
      as the general device driver discussed previously.

      routine HP AC ARC (integer RAD, IA, FA)

         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.

      routine HP C ARC (integer RAD, IA, FA)

         This routine is the same as  the  routine  HP  AC  ARC,  except  that  a
      clockwise arc is used.

      routine HP CIRCLE (integer RAD)

         A  circle of radius RAD is drawn centred on the current position.   Note
      that RAD should be specified in device co-ordinates.

      routine HP SPEED (integer SPEED)

         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.

      routine P CURSOR (integer name STATE, X, Y)

         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.

                             The Printronix printer driver

         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.

         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 -

      a) Mouses

              COPY <file> / LP:

      b) EMAS

              LIST <file> , .LP??     where ?? can currently be 15, 41 or 78

      c) VAX

              i)   PRINT <file>
              ii)  Send the file to an ERCC printer with the command NETFS.

         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.

         The driver is present as

      routine P300 (integer COM, X, Y)

         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.

                              The Tektronix device driver

         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.

         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.

         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.

         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.

                       Routines specific to the Tektronix driver

      routine T4000 (integer COM, X, Y)

         This routine is the Tektronix device driver.   The  parameters  are  the
      same as those of the general device driver described on page 14.

      routine T CURSOR (integer name CHAR, X, Y)

         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.

         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.

         The details of each model are: -

      4002

         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.

      4006

         These  terminals are upper case only, with no adjustable attributes, and
      have no cursor.

      4010

         These terminals are identical to the model 4006 except that they have  a
      cursor, which is controlled by means of thumb wheels.

      4012

         These  terminals are identical to the 4010, with the addition of a lower
      case character set.

      4014

         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.

      ADM 3A  (made by Lear Siegler inc.)

         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.

                                The VT15 device driver

         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.

         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.

         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.

                         Routines specific to the VT15 driver

      routine VT15 (integer COM, X, Y)

         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.

              STOP VT - VT15 (12, 1, 0)
              START VT - VT15 (12, 2, 0)

         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.

              ENABLE PEN - VT15 (12, 3, 0)
              DISABLE PEN - VT15 (12, 4, 0)

         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.

              ENABLE BLINK - VT15 (12, 5, 0)
              DISABLE BLINK - VT15 (12, 6, 0)

         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.

      routine V CURSOR (integer name STATE, X, Y)

         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.

      routine TRACK (integer name X , Y)

         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.

              TRACK (X, Y) until X<20 and 10<=Y<=100

      integer fn VT BUTTONS

         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.

         Users of the VT15 who wish to have 'moving' pictures are referred to the
      device specific package, 'SOGGY' [27].

                          A set of geometric utility routines

         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.

         All the routines assume the following record format has been declared -

      record format POINTF (integer X, Y)

         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.

      routine POLYGON (integer NUM ELE, record (POINTF) array name PTS)

         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.

      routine S BOX (record (POINTF) name L, U)

         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.

      routine BOX (integer L, W, record (POINTF) name C, D)

         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.

      routine FLASH (record (POINTF) name C, integer D)

         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.

      routine SET FLASH POINTS (integer SIDES)

         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.

      routine WIRE (integer W, N, record (POINTF) array name PTS)

         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.

                                A transformation stack

         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,

              a) Routines for creating transformation matrices
              b) Routines for manipulating the transformation stack

      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 -
                                       ( 0 1 2 )
                                       ( 3 4 5 )
                                       ( 6 7 8 )

      a) Routines to create transformation matrices -

      routine M TRANSLATE (integer X, Y, real array name TX)

         This routine sets the array TX  to  be  the  transformation  which  will
      translate a point (a, b) to a point (a', b') such that -

                              a' = a + x
                              b' = b + y

      routine M MX (real array name TX)

         This  routine sets the array TX to be the transformation which mirrors a
      point in the X axis. eg.
                              a' = - a
                              b' = b

      routine M MY (real array name TX)

         This routine sets the array TX to be the transformation which mirrors  a
      point in the Y axis. eg.
                              a' = a
                              b' = - b

      routine M ROTATE (integer X, Y, real array name TX)

         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).

                              a' = (X/Z) * a + (-Y/Z) * b
                              b' = (Y/Z) * a + (X/Z) * b

      b) Routines to manipulate the transformation stack

      routine INIT TRANS

         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).

      routine PUSH TRANS (real array name TX)

         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.

      routine POP TRANS (real array name TX)

         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.

      routine INQUIRE TRANSFORM (real array name TX)

         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.

      routine TRANSFORM POINT (record (POINTF) name P, NP)

         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

              NP_X = A(0) * X + A(3) * Y + A(6)
              NP_Y = A(1) * X + A(4) * Y + A(7)

      routine TRANSFORM VECTOR (record (POINTF) name V, NV)

         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.

                                    Accessing EDWIN

      a) Under VMS on the VAX-11/780

              Users should add the command GRAPHSETUP in their LOGIN.COM  files
              to set up the aliasses described in this guide.

              The file $EDWIN:.INC contains the routine specs (see appendix B).

              Graphics programs should be linked by the commands -

                      LINK PROG,$EDWIN/OPT
              or      SLINK PROG,$EDWIN/OPT   for IMP with streams

              The VAX version of EDWIN contains device drivers -

                C963   CATS   CHAS   HP2648   P300   P7221   T4000

       b) Under EMAS on the ICL 2900 range

              The file CONLIB.EDWIN_INC contains the routine specs.

              The EDWIN library is made available by executing the command

                      OPTION SEARCHDIR=CONLIB.EDWINDIR

              The EMAS version of EDWIN contains device drivers -

                C963   CATS   CHAS   HP2648   P300   P7221   T4000

                 While  initialising, EDWIN automatically sets graphics mode if
              a terminal is being used.

       c) Under MOUSES on the Perkin-Elmer machines.

              The file EDWIN:EDWIN.INC contains the routine specs.

              EDWIN is made available by the command -

                      LIB EDWIN:EDWIN

              The MOUSES version of EDWIN contains device drivers -

                CATS   P300   T4000

       d) Under RSX-11/M on PDP-11s

              The file LB:[1,1]EDWIN.INC contains the routine specs.

              The library is automatically searched by the task builder, so  no
              special action is necessary for linking.

              The RSX-11/M version of EDWIN contains device drivers -

                HP2648   CATS   T4000

       e) Under ISYS on the Interdata series 70

              The file EDWIN.EDWIN:INC contains the routine specs.

              Graphics programs should be linked by the command -

                      LINK program,EDWIN.EDWINLIB

              This version currently only supports a CATs driver.

       f) Under the IMP15 system on PDP-15s

              Graphics programs should be compiled with the command -

                      C .EDWIN+prog/obj,map

              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.

                 The  command  .VTSAT  is  used  to run the satellite software,
              allowing the VT15s to be used from VAX.

                 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

                      R <stream1>,<stream2>,.CHAR PDF/any outputs

                       Cross calling EDWIN from other languages

          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.

       a) Fortran

          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 -

                       Fortran name    IMP name

                       INIT FOR        INITIALISE FOR
                       MOVE A          MOVE ABS
                       MOVE R          MOVE REL
                       LINE A          LINE ABS
                       LINE R          LINE REL
                       MARK A          MARKER ABS
                       MARK R          MARKER REL
                       CHAR            CHARACTER
                       STR ON          STORE ON
                       V ON            VIEW ON
                       ASPECT RAT      ASPECT RATIOING
                       F WINDOW        WINDOW
                       F VIEW PORT     VIEW PORT

          All the attribute routines described in section D have the  word  SET
       replaced by the letter S. (eg.  SET COLOUR becomes S COLOUR).

          All  other  device  specific routines which are not directly callable
       from Fortran have the routine name prefixed by the letter 'F'.

          Note that the versions of Fortran on VAX,  MOUSES  and  EMAS  do  not
       impose a limit of 6 characters in names.

       b) Pascal

       In  general  the  IMP  routine  specification is converted to the Pascal
       procedure spec as shown by the following example.

               external routine spec INITIALISE FOR (integer DEV)
       becomes
               procedure INITIALISEFOR (DEV : integer ); extern;

          The files '$EDWIN:.PAS', 'CONLIB.EDWINPAS' 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.

          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

                       %include '$EDWIN:.PAS'

       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.

          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 -

         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.

                              Use of the VIEWPDF program

          This utility can be used to view pictures which have been  dumped  by
       the storing feature of EDWIN.  The form of the command is -

                       VIEWPDF picture/outfile

       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.

          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.

          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.

       Notes -

       a) Each picture is self defined, and  any  number  of  pictures  can  be
       joined together in one file.

       b)  This  provides a useful method of plotting pictures, without wasting
       plotter paper and time on unwanted plots.

       Accessing the VIEWPDF program on the different implementations -

               VIEWPDF pic/file        under VMS
               VIEWPDF pic/.LP15       under EMAS
               EDWIN:VIEWPDF pic/file  under MOUSES
               EDWIN.VIEWPDF pic       under ISYS
               .VIEW pic               on the PDP-15/40

                              Use of the PDFDEC program

          This utility can be used to decode a PDF into a HEX dump and  an  IMP
       program.  The form of the command is

               PDFDEC  pdf/decode

       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.

                          Appendix A : EDWIN error messages

          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.

       Error number Description:

         0             Device driver initialisation fails.

         1             No room left in VT15 display file.

         2             Internal error in the device driver.

         5             Attempting to review a corrupt PDF.

         6             Trying to change an undefined attribute.

         7             Internal error in the geometric routines.

         8             There is no CURSOR on currently selected device.

         9             Transformation stack not intialised.

        10             Transformation stack underflow, ie. too many POPs.

        11             Transformation stack overflow.

          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.

          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.

       string (63) function EDWIN ERROR (integer NUM)

               Appendix B : Listing of the normal EDWIN procedure specs

       !  EDWIN routine specs added.
       end of list
       !
       !  Routines for initialisation and termination
       external routine spec INITIALISE FOR (integer DEVICE TYPE)
       external routine spec TERMINATE EDWIN
       !
       !  Output primitives
       external routine spec MOVE ABS (integer X,Y)
       external routine spec MOVE REL (integer DX,DY)
       external routine spec LINE ABS (integer X,Y)
       external routine spec LINE REL (integer DX,DY)
       external routine spec MARKER ABS (integer N,X,Y)
       external routine spec MARKER REL (integer N,DX,DY)
       external routine spec CHARACTER (integer SYM)
       external routine spec TEXT (string (255) ST)
       !
       !  Control
       external routine spec NEW FRAME
       external routine spec UPDATE
       external routine spec CLIP ON
       external routine spec CLIP OFF
       external routine spec STORE ON (integer STREAM)
       external routine spec STORE OFF
       external routine spec VIEW ON (integer STREAM)
       external routine spec VIEW OFF
       external routine spec ASPECT RATIOING (integer MODE)
       external routine spec WINDOW (integer XL, XR, YB, YT)
       external routine spec VIEWPORT (integer XL, XR, YB, YT)
       !
       !  Attributes
       external routine spec SET COLOUR (integer COLOUR)
       external routine spec SET LINE STYLE (integer STYLE)
       external routine spec SET INTENSITY (integer BRIGHTNESS)
       external routine spec SET CHAR SIZE (integer SIZE)
       external routine spec SET CHAR ROT (integer ROT)
       external routine spec SET CHAR QUALITY (integer WHICH)
       external routine spec SET CHAR FONT (integer WHICH)
       external routine spec SET CHAR SLANT (integer ANGLE)
       !
       !  Miscellaneous routines
       external routine spec REVIEW
       external routine spec INQUIRE POSITION (integer name X,Y)
       external routine spec INQUIRE WINDOW (integer name XL,XR,YB,YT)
       external routine spec INQUIRE VIEWPORT (integer name XL,XR,YB,YT)
       external routine spec MAP TO DEVICE COORDS (integer name X,Y)
       external routine spec MAP TO VIRTUAL COORDS (integer name X,Y)
       external routine spec CURSOR (integer name STATE,X,Y)
       external string (31) fn spec DEVICE NAME
       external string (63) fn spec EDWIN ERROR (integer N)
       external integer fn spec DEFAULT DEVICE
       external routine spec DRIVE DEV (integer COM, X, Y)
       !
       list
       end of file

                    Appendix C : The EDWIN software character set

                          Appendix D : Some Example programs

          Note  that the IMP %include statement causes 3 lines to appear in the
       listing which are NOT part of the source file.

                 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

                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

          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

                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)

             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)

       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

           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

                      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

                     Appendix E : The Structure of the EDWIN PDF

          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 -

       routine REVIEW

       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.

                             Drawing Instruction Formats

          These are of two types :

       1) Normal Form-

          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.

                       eg.    | 0 0 0 code |   | X value |   | Y value |

       2) Short Form -

          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.

                       eg.     | 0 0 1 code |   | X value , Y value|

          The codes for the drawing instructions are -

                       0   -   Line Abs
                       1   -   Move Abs
                       2   -   Marker Abs
                       3   -   Line Rel
                       4   -   Move Rel
                       5   -   Marker Rel

          The  top byte of the first number is used to specify marker selection
       for codes 2 and 5.

                              Other Instruction Formats

       Window

          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.

         eg.   | 0 0 0 8 |   | XL |   | XR |   | 0 0 0 8 |   | YB |   | YT |

       Characters

          This requires one integer.  The code dumped is -

                               | 0 , char val , 9 |

          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.

       Change of attribute value.

          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 :-

                       | 0 value A | => Colour Change
                       | 1 value A | => Line Type Change
                       | 2 value A | => Char Size Change
                       | 3 value A | => Char Orientation Change
                       | 4 value A | => Char Quality Change
                       | 5 value A | => Char Font Change
                       | 6 value A | => Intensity Change
                       | F value A | => Aspect ratioing

       Newframe and End

          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.

                            Appendix F : Acknowledgements

          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

                               Irene Buchanan
                               Alan Gray
                               Lee Smith
                               Jeff Tansley
                               Rainer Thonnes
                               Ian Young

          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.

          Special thanks to Nick Rothwell,  whose  interactive  design  program
       (which uses EDWIN) was used to design the cover picture.

                               Appendix G : References

          [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

          [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