






                     _N_e_w _M_O_D_U_L_A_2 _g_r_a_p_h_i_c_s _l_i_b_r_a_r_y _f_o_r _V_L_S_I






                                  Graham Toal


                                   13/12/1984




















































    VLSIC Design Aids Group     Graphics library                      Page 1


    _1.  _D_e_s_i_g_n _a_i_m_s

         This graphics package was designed with three aims in mind:

    (1)  To cater for 21/2D graphics - i.e. VLSI layouts

    (2)  To be portable between hardware configurations, including those
         with local graphics and those with the graphic output device on a
         serial line

    (3)  To be portable between low resolution raster devices, high
         resolution raster devices, and even line-drawing devices, such as
         plotters.

         How these aims were achieved will be described below.








































    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 2


    _2.  _P_r_o_g_r_a_m_m_e_r_s _I_n_t_e_r_f_a_c_e

    _2._1.  _M_o_d_u_l_a_2 _c_a_l_l_s

         The current interface is described in /_p_r_j/_l_i_b/_G_r_a_p_h_i_c_s._d_e_f, with
    device driver modules in /_p_r_j/_l_i_b/_B_B_C._d_e_f, /_p_r_j/_l_i_b/_H_P._d_e_f and
    /_p_r_j/_l_i_b/_N_S_1_6_K._d_e_f.
















































    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 3


    _2._2.  _C_o_n_f_i_g_u_r_a_t_i_o_n _f_i_l_e_s

         /prj/lib/Graphics.ini contains a list of logical colour to CMOS
    layer names.


    _3.  _I_m_p_l_e_m_e_n_t_a_t_i_o_n

         Refer to VLSI CAD document no. ### (Care & Maintenance of Graphics
    Packages)


    _4.  _E_x_a_m_p_l_e_s

    _4._1.  _s_e_t_t_i_n_g _u_p _t_h_e _e_n_v_i_r_o_n_m_e_n_t

         A minimal set of commands has been designed that will allow a
    single program to run on all devices; each device has its individual
    points, however, so to get full benefit from your hardware it is
    sometimes necessary to issue device-dependent commands.


    _4._1._1.  _F_i_n_d_I_n_p_u_t, _F_i_n_d_O_u_t_p_u_t, _F_i_n_d_I_n_O_u_t

         This graphics package supports the notion of STREAMs.  Multiple
    streams may exist concurrently; many streams may be owned by one process
    or many processes may own some streams each.  Each stream is a logical
    connection to a physical device: the connection is made when the stream
    is opened by FindXXX. It may happen (say in a windowed system) that two
    streams are connected to the same physical device.  All these notions
    are supported by this system.

         There is a generic Graphics.FindInput ("device") which looks in a
    table of device names and calls a device-specific FindInput from the
    appropriate device driver. The device-specific versions may have extra
    parameters; for instance the BBC version of FindInput has four integers
    to describe the viewport to be used on the screen.  Similarly, the HP
    version has an extra string parameter which allows the plotter output to
    be sent to a file, instead of being sent directly to the plotter itself.
    NOTE: The generic interface is not yet implemented, BUT WILL BE shortly.


    _4._1._1._1.  _B_B_C._F_i_n_d???

         FindInOut (not yet implemented) opens a bi-directional stream to
    the viewport given in the parameter list. Mouse picks will only be
    returned if they take place within this window. This is intended to
    offer some level of possible extension when or if we go multi-process.

         FindInput returns a _n_o_n-_e_c_h_o_e_d, _s_i_n_g_l_e _c_h_a_r_a_c_t_e_r _k_e_y_b_o_a_r_d input
    stream if possible.




    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 4


         FindOutput is the standard call to open a window on the BBC
    display.  Due to the lack of resolution, multiple windows are not
    recommended (and indeed not yet supported) so the default of 0,0 to
    1279,1023 is recommended.


    _4._1._1._2.  _H_P._F_i_n_d???

         FindOutput is the only call supported: it is policy that plotters
    must be drivable off-line, so interactive requests to read paper size,
    or digitise are _n_o_t allowed.


    _4._1._2.  _U_p_d_a_t_e & _D_e_l_e_t_e

         Update forces all pending output to be sent to the file/device.
    Delete calls Update and then renders the stream unusable for further
    graphics. (Data structures built by the stream implementation may be
    deleted at this point, so DO NOT use a loop consisting of
    'FindOutput ... Delete' when you mean 'Surface ... Update'.


    _4._1._3.  _S_u_r_f_a_c_e

         A call to Surface tells the graphics package how big your world
    co-ordinate space is.  It also has an implicit call to what some
    graphics packages call 'Newframe'.


    _4._1._4.  _C_o_m_m_a_n_d

         Command is an escape mechanism which allows arbitrary command lines
    to be sent directly to a device driver.  It is intended that all a
    program should supply is a simple loop of the form:

        LOOP
           Readline (CommandString);
           IF String.EqualCC ("", CommandString) THEN EXIT END;
           Result := Graphics.Command(CommandString)
        END

    This interface is used for such things as setting the paper size on a
    plotter, or generating a new stipple pattern for the BBC graphics.  A
    full list is given later.


    _4._1._4._1.  _B_B_C '_C_o_m_m_a_n_d'_s

        debug tables
        debug on
        debug off
        view



    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 5


    _4._1._4._2.  _P_l_o_t_t_e_r '_C_o_m_m_a_n_d'_s

        debug on
        debug off
        debug tables
        debug params
        view
        paper A0
        paper A1
        paper A2
        paper A3                ( default paper size )
        paper A4
        scale integer     ( default = 1000 )
                   ( scale 1000 means 1 mm per micron, 2000 is 2mm per micron )
        device hp7220c
        device hp                ( default hardware )
        device hp7585b
        device bighp
        xonxoff
        to plotfile       ( default /dev/hp )   *** To be implemented
                          ( this call MUST be issued BEFORE calling Surface )



    _4._1._5.  _r_e_l_a_t_e_d _U_n_i_x _c_o_m_m_a_n_d_s

         Both the plotters on acorn-vax are connected with 3-wire RS232
    lines, and use Xon/Xoff protocol. The command to put the plotter in the
    correct state to deal with this protocol must be sent _b_e_f_o_r_e any
    graphics data is sent to the plotter.  This can be done either by the
    program issuing 'Command("xonxoff")' or by the system management sending
    a file containing the correct commands to the plotter at system start-up
    time.  It would be preferable if both could be set to RTS/CTS
    handshaking and have 5-wire lines.  See also the unix manual on stty and
    cat.


    _4._2.  _d_r_a_w_i_n_g _c_o_m_m_a_n_d_s

         Before you can draw anything useful, you have to select a colour in
    which to draw: however, the method of choosing a colour depends on
    whether you are drawing unconnected lines, or coherent areas. We
    therefore describe the differences between these two concepts before we
    introduce colours.


    _4._2._1.  _s_i_m_p_l_e _l_i_n_e_s

         Line drawing in this package is unexceptional. Commands LineTo and
    MoveTo are supplied which do the obvious things.  See also 'selecting
    colours'.




    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 6


    _4._2._1._1.  _c_l_i_p_p_i_n_g _l_i_n_e_s

         Currently, lines are clipped by the hardware.  This was an
    engineering decision made through expediency: all the hardware we have
    can clip - so there seemed little reason in either duplicating effort or
    wasting CPU. If there is any demand, this decision can be reversed
    relatively easily.


    _4._2._2.  _c_o_h_e_r_e_n_t _p_o_l_y_g_o_n_s

         This graphics package supports the concept of POLYGON as defined in
    VLSI CAD Group internal document no. ###.  The call 'DrawPolygon'
    outputs the polygon in the current window to the nominated device.  The
    representation of the polygon depends on the hardware.  Device
    independent representations are provided by the 'Colour' interface for
    CMOS VLSI layers, and for the major colours red, green & blue.  The
    representation will be area-filled if possible, or unless explicitly
    overridden by a 'Colour' call such as 'HP.Colour("blue hatched")'


    _4._2._2._1.  _c_l_i_p_p_i_n_g _p_o_l_y_g_o_n_s

         Polygons are clipped by AND-ing them against a clip-window of the
    size defined by Surface.


    _4._3.  _s_e_l_e_c_t_i_n_g _c_o_l_o_u_r_s

         There are two stages to drawing something in colour: first you must
    get a handle for the colour you want, like this
                         Red := Graphics.Colour ("red")
    and then you should apply the colour to the graphics stream as:

        Graphics.SetLineColour (BBCDevice, Red)
        or
        Graphics.SetAreaColour (BBCDevice, Red)

    The colour selected for line-drawing is independent of that selected for
    area-fill.


    _4._4.  _C_u_r_s_o_r _e_n_q_u_i_r_y/_m_o_u_s_e _s_u_p_p_o_r_t

         In order to meet some degree of device independence, we have
    adopted the 'virtual keyboard' approach to cursor hits.  The
    'ReadCursor' routine returns a string parameter which describes the
    selection made.  In the case of a mouse, it could encode the buttons
    pressed to make the selection (Chord-presses will be de-bounced by the
    graphics hardware or the package - the programmer should never see
    multiple presses for one function.) It is possible that an icon menu
    system may be written, allowing specific items to be chosen from a menu:
    these will be returned by name in this field. A tektronix-like device


    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 7


    will return the value of the key pressed to enter the cross-hair cursor,
    and the BBC micro - when operating in 'Snapper-key' mode - will simulate
    the strings returned by each of the mouse buttons for a choice of
    'enter' keys (probably RETURN, ESCAPE and SPACE).  Whenever possible the
    device intelligence is used to the utmost:  a notion of 'Cursor style'
    is supported, which allows most of the functions which would normally be
    done by the controlling program to be executed locally: Rectangular
    boxes may be stretched interactively, for example, by

        StretchBox := Cursor ("box xr,yt"); (* use top-right corner as
                                               movable part of cursor *)
        ReadCursor (BBCdevice, FixedXL, FixedYB, InitialXR, InitialYT,
                               FinalXR, FinalYT, PickString)
                                      (* first 4 integers are where initial
                                         box is drawn - Final?? is where
                                         the top-right corner ends up. *)
                                      (* PickString is a text-string
                                         describing the buttons pressed.
                                         See ??? for details of PickString *)



    _4._4._1.  _I_c_o_n _d_r_a_g_g_i_n_g

         The representation of a point cursor is not fixed to the
    traditional cross.  Users may supply a raster representation of the
    cursor they wish to use. Clever use of this feature will give the effect
    of an iconic system.


    _4._4._2.  _B_o_x _d_r_a_g_g_i_n_g

         In VLSI, it is sometimes necessary to re-position objects, such as
    cells in a composition editor.  When dragging these objects (cheaply
    implemented as bounding box rectangles - the applications package
    implementer must redraw any contents when the new position is know) The
    size & initial position of the box to be dragged are given to the
    ReadCursor call.


    _4._4._3.  _B_o_x _s_t_r_e_t_c_h_i_n_g

         See example above.


    _4._4._4.  _L_i_n_e _s_t_r_e_t_c_h_i_n_g

         Sometimes it is necessary to draw the outline of a shape other than
    a simple rectangle. Drawing rubber-band lines allows this by offering a
    fixed end and a free end which can be manipulated by a mouse etc.  For
    VLSI work, it is probably preferable to limit the degrees of freedom
    such a line may have to one or more of the major axes, and the diagonals
    X=Y & X=-Y.  The package does not enforce such a restriction if it is


    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 8


    not explicitly asked for.


    _4._4._4._1.  _9_0 _s_n_a_p _a_n_g_l_e_s

        Cursor ("line x")
        or
        Cursor ("line x y")



    _4._4._4._2.  _4_5 _s_n_a_p _a_n_g_l_e_s

        Cursor ("line / \")



    _4._4._4._3.  _a_r_b_i_t_r_a_r_y _r_u_b_b_e_r-_b_a_n_d_i_n_g

        Cursor ("line")



    _4._5.  _d_e_v_i_c_e_s _a_v_a_i_l_a_b_l_e

    _4._5._1.  _B_B_C _m_i_c_r_o

         The BBC Micro running the VLSI CAD Group terminal emulator (see
    VLSI CAD Group internal document no. ### (Graphics Terminal Emulator
    interface)) offers two modes of interactive graphics. The most common is
    the mode whereby colour graphics may be drawn in medium resolution, four
    colours.  The lack of colour is compensated for by dithering: the effect
    is reasonably acceptable for pictures without too much detail.  The
    other mode supported is higher resolution black and white.  The choice
    is made in the call to BBC.FindOutput.


    _4._5._1._1.  _N_S_3_2_0_1_6 _t_e_r_m_i_n_a_l

         A temporary implementation conforming primarily to the above and
    not intended for permanent use has been carried out on the NS32016
    second processor.  This is expected to disappear when we get either Unix
    workstations or Hi-res graphics hardware.  Knowing the nature of life,
    however, it may well become our standard graphics interface.


    _4._5._2.  _H_i-_r_e_s _g_r_a_p_h_i_c_s

        _W_a_t_c_h _t_h_i_s _s_p_a_c_e.






    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                      Page 9


    _4._5._3.  _P_l_o_t_t_e_r_s

         We currently support Hewlett-Packard Graphics Language on any HP
    plotter.  We could also support the Unix PLOT filters with little extra
    effort if there arose a sudden need for portable plot files.  The large
    and small plotters differ only in paper size, and the ability to turn
    the plotter off-line at the end of a plot.  (by
    Graphics.Command("view")) Plot files as generated by the graphics
    package normally contain _o_n_l_y drawing protocol. There are no device
    commands (scaling, origin manipulation, Xon/Xoff vs. hardware handshake
    etc.) in the plotfile.  The protocol for the above commands can be
    generated explicitly if desired by the 'Command' interface;
    alternatively it can be placed in a file and sent to the plotter before
    running the applications package, or it can be sent to the plotter by
    the system manager at system start-up time.


    _4._5._3._1.  _l_a_r_g_e _p_l_o_t_t_e_r (_A_0)

         The large plotter is referred to most easily by the alias 'bighp',
    as is the default unix output file for this device, /dev/bighp.


    _4._5._3._2.  _s_m_a_l_l _p_l_o_t_t_e_r (_A_3)

         As above, but known as 'hp'.


    _4._6.  _V_L_S_I _L_a_y_e_r _n_a_m_e_s

         A pre-defined selection of layer names has been added to the
    graphics package as a set of aliases for the colours which they
    represent.  There is more portability in describing metal as
    'Colour("metal")' than as 'Colour("blue")' because if we change the
    representation of metal (some people prefer it to be yellow) it can be
    done without changing the applications package. (It may even be done
    without changing the graphics package if we sort out the notion of
    initialisation files at some point)


    _4._7.  _s_e_l_e_c_t_i_n_g _c_o_l_o_u_r_s

         There is an important point to be clarified here:  Colours (as
    mentioned earlier) may be either line colours or area-fill colours.
    NOTICE, though, that an area-fill colour may in fact be an outline.
    This will probably cause some confusion at first, so I'll try a few
    examples.

         First, assume we are drawing an area of metal, in blue, which is
    covering a poly wire (in green). We wish the metal to be drawn on top,
    but we also want to see where the wire is below.  If we had appropriate
    hardware, we could draw each layer on a separate plane, and allow the
    colour map in the device to accentuate the overlap.  As we cannot


    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                     Page 10


    (unfortunately) assume such hardware, we resort to the simple trick of
    drawing the outline of the layer which is below after we have drawn the
    layer which is on top.

        Green := Colour(S,"green");             (* Default style - area-fill *)
        Metal := Colour(S,"blue");              (* on the BBC, outline on HP.*)
        PolyOutline := Colour(S,"red outline"); (* - explicitly want outline *)
        SetAreaColour(S,Green); DrawPolygon (...);
        SetAreaColour(S,Metal); DrawPolygon (...);
        SetAreaColour(S,PolyOutline); DrawPolygon (...);

    Note that at no time did we 'SetLineColour'.  If we now wish to draw a
    pointer to something in our data structure, (a port for example) we do
    so as follows:

        SetLineColour(Green);(* this picks up the line-drawing component of *)
                             (* the COLOUR-token, 'green'.                  *)
        MoveTo (S,100,100); LineTo (S,200,100);
        LineTo (S,170,125); MoveTo (S,170,75);
        LineTo (S,200,100); Update (S);

    The significant point to note now, is that another call to 'DrawPolygon'
    will output the polygon in the colour last selected by 'SetAreaColour'.

         Another feature of the colour, as previewed above, is that you may
    append a style keyword after the colour name in the call to 'Colour'.
    If the keyword is recognised, the appropriate feature will be encoded in
    the colour token.  If it is not recognised, the default style for the
    device will be used.  The styles recognised by the BBC micro are:

        ""   (area-fill)
        "areafill"
        "outline"

    and by the HP plotter:

        ""   (outline)            *** Note: none of the below yet implemented
        "outline"
        "outline"
        "outline"
        "hatch1"
        "hatch2"

    ******* CHANGE: add info about "linestyle_colour drawstyle": examples:
    "dotted_red outline", "dotdash-metal hatch1"


    _4._7._1.  _B_B_C _m_i_c_r_o _c_o_l_o_u_r_s

         A full list of bbc micro colours can be found in file
    /prj/lib/Graphics.ini.  At the time of writing, these are

        line colours:


    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                     Page 11


           "black" 0
           "red"   1
           "green" 2
           "blue"  3
           "default" 1

    and

        area colours:
           "red green"    "red, black, black, green"
           "grey"         "green, red, blue, green"
           "dark green"   "green, black, black, green"
           "purple"       "red, blue, blue, red"
           "dark purple"  "black, red, blue, black"
           "light blue"   "green, blue, blue, green"
           "gold"         "green, red, red, green"
           "dark blue"    "blue, blue, blue, black"
           "hatched blue" "black, blue, blue, green"
           "solid black"  "black, black, black, black"
           "dark red"     "red, black, black, red"
           "solid red"    "red, red, red, red"
           "solid blue"   "blue, blue, blue, blue"
           "solid green"  "green, green, green, green"



    _4._7._2.  _H_i-_r_e_s _g_r_a_p_h_i_c_s _c_o_l_o_u_r_s

         See above.


    _4._7._3.  _p_l_o_t_t_e_r _p_e_n _c_o_l_o_u_r_s

         The pen colours are dependent on the carousel fitted. The default
    colour/slot assignment is

        pen colours:
           "black"     1
           "red"       2
           "green"     3
           "blue"      4
           "brown"     5
           "turquoise" 6
           "gold"      7
           "violet"    8
           "default"   1



    _5.  _T_e_x_t _a_n_d _a_n_n_o_t_a_t_i_o_n

         There are two ways of placing text offered by this package.  The
    first is the traditional 'place this string at these co-ordinates', the


    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                     Page 12


    second is 'place the following text in this area'.  The second can place
    the text according to sophisticated algorithms, in various orientations,
    depending on implementation and hardware support.  A 'Text style' can
    enforce use of italics, character sets etc. if the user explicitly
    wishes to use device-specific features.  No text styles are as yet
    supported on any of our devices.


    _6.  _E_n_q_u_i_r_y _f_u_n_c_t_i_o_n_s

         There are NO enquiry functions supported in this package: instead,
    a generic information record is exported which contains a mirrored copy
    of the important variables used by each device-driver implementation
    module.  This information is _n_o_t the master copy - and it is up to the
    implementer of each device-driver to ensure that these variables are
    kept up to date.  _C_H_A_N_G_I_N_G _T_H_E_S_E _V_A_R_I_A_B_L_E_S _W_I_L_L _H_A_V_E _N_O _E_F_F_E_C_T
    _W_H_A_T_S_O_E_V_E_R.


    _7.  _D_e_b_u_g_g_i_n_g _y_o_u_r _p_r_o_g_r_a_m_s

                            Graphics.Command ("debug on")

    will cause a file "graphics.debug" to be created in your current
    directory.  The file is not created if debugging is not used.  The debug
    output from Graphics consists mainly of a trace of the procedures
    executed.  Note that this output can, if desired, be edited to produce a
    modula2 source consisting of simple drawing commands.  When creating
    colour tables for a new device, or amending the current ones, the
    command ("debug tables") may be useful.
    Reminder to author - check that debug stream is not re-written on a new
    call to Find???.























    Working paper                                         DRAFT: DO NOT CITE







    VLSIC Design Aids Group     Graphics library                     Page 13


    Design aims .......................................................    1
    Programmers Interface .............................................    2
    Modula2 calls .....................................................    2
    Configuration files ...............................................    3
    Implementation ....................................................    3
    Examples ..........................................................    3
    setting up the environment ........................................    3
    FindInput, FindOutput, FindInOut ..................................    3
    BBC.Find???  ......................................................    3
    HP.Find???  .......................................................    4
    Update & Delete ...................................................    4
    Surface ...........................................................    4
    Command ...........................................................    4
    BBC 'Command's ....................................................    4
    Plotter 'Command's ................................................    5
    related Unix commands .............................................    5
    drawing commands ..................................................    5
    simple lines ......................................................    5
    clipping lines ....................................................    6
    coherent polygons .................................................    6
    clipping polygons .................................................    6
    selecting colours .................................................    6
    Cursor enquiry/mouse support ......................................    6
    Icon dragging .....................................................    7
    Box dragging ......................................................    7
    Box stretching ....................................................    7
    Line stretching ...................................................    7
    90 snap angles ....................................................    8
    45 snap angles ....................................................    8
    arbitrary rubber-banding ..........................................    8
    devices available .................................................    8
    BBC micro .........................................................    8
    NS32016 terminal ..................................................    8
    Hi-res graphics ...................................................    8
    Plotters ..........................................................    9
    large plotter (A0) ................................................    9
    small plotter (A3) ................................................    9
    VLSI Layer names ..................................................    9
    selecting colours .................................................    9
    BBC micro colours .................................................   10
    Hi-res graphics colours ...........................................   11
    plotter pen colours ...............................................   11
    Text and annotation ...............................................   11
    Enquiry functions .................................................   12
    Debugging your programs ...........................................   12










    Working paper                                         DRAFT: DO NOT CITE



