              The Draw library

%DWARCC

 CALL DWARCC(XYC,RADIUS,TH1,TH2,IERR)

 Purpose: draws an arc of a circle (unclosed)

 Parameters:

  XYC    - REAL array dimension 2 containg the x and y of the circle centre
                in user coordinates

  RADIUS - REAL radius of circle in user coordinates

  TH1    - REAL angle (radians) from the x-axis of the beginning of the arc

  TH2    - REAL angle (radians) from the x-axis of the end of the arc

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                 -13: TH2 not greater than TH1, or arc more than 2pi

 Comments: it is best to keep the angles within the range -2pi to +2pi.
           use DWCOLF to set the fill colour (the arc can be filled even
                                         though it is not a closed curve)
           use DWCOLL to set the colour
           use DWSTYL to set the thickness
           use DWDASH to make a dash/dot arc
 
%DWBGRP

 CALL DWBGRP(IERR)

 Purpose: starts a group of objects

 Parameter:

  IERR   - INTEGER returned error number
                   0: group started OK
                   2: file not initialised  (no action taken)
                  -4: can't write any more to file (disc full?)
                  -7: four nested groups already (no action taken)

%DWCIRC

 CALL DWCIRC(XYC,RADIUS,IERR)

 Purpose: draws a circle

 Parameters:

  XYC    - REAL array dimension 2 containg the x and y of the circle centre
                in user coordinates

  RADIUS - REAL radius of circle in user coordinates

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)

 Comments: use DWCOLF to set the fill colour (or no fill)
           use DWCOLL to set the outline colour
           use DWLWID to set the outline thickness
           use DWDASH to make a dash/dot outline

%DWCOLF

 CALL DWCOLF(IRED,IGREEN,IBLUE)

 Purpose: sets the fill colour for a polyline or curve

 Parameters:

  IRED   - INTEGER amount of red (0 to 255)
                   or -1 if no filling required (default)

  IGREEN - INTEGER amount of green (0 to 255)
                   not needed if IRED=-1

  IBLUE  - INTEGER amount of blue (0 to 255)
                   not needed if IRED=-1

 Errors: if the value given is outside the range 0 to 255 it will be set to
         0 or 255. IRED=-1 is a special case.

%DWCOLL

 CALL DWCOLL(IRED,IGREEN,IBLUE)

 Purpose: sets the line colour for a polyline or curve

 Parameters:

  IRED   - INTEGER amount of red (0 to 255) default 0
                   or -1 if no outline required

  IGREEN - INTEGER amount of green (0 to 255) default 0
                   not needed if IRED=-1

  IBLUE  - INTEGER amount of blue (0 to 255) default 0
                   not needed if IRED=-1

 Errors: if the value given is outside the range 0 to 255 it will be set to
         0 or 255. IRED=-1 is a special case.

%DWCURV

 CALL DWCURV(XY,N,CLOSE,IERR)

 Purpose: draws a curve through a set of points

 Parameters:

  XY     - REAL array dimension (2,N) with the X and Y values of the points
                on the curve in user coordinates.

  N      - INTEGER number of points defined on the curve

  CLOSE  - LOGICAL defines whether to close the curve
                   .TRUE. joins the last point back to the first
                   .FALSE. joins the N points with N-1 lines

  IERR   - INTEGER returned error
                   0: path drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                  -6: N less than 2
                 -14: adjacent identical points

 Comments: calculates Bezier points to interpolate between the given
           coordinates. These points must also lie inside the user area.
           use DWCOLF to set the fill colour
               DWCOLL to set the line colour
               DWLWID to set the line width
               DWSTYL to set the line style
               DWDASH to make a dash/dot line

%DWDASH

 CALL DWDASH(NPART,IP1,IP2,IP3,  etc)

 Purpose: to set up a dashed line pattern for a polyline or curve

 Parameters:

  NPART  - INTEGER number of parts defined (see following)
                   0 for a continuous line (default)
                   maximum of 8

  IP1    - INTEGER length of first solid part (in OS units)

  IP2    - INTEGER length of next clear part

  IP3    - INTEGER length of next solid part

    etc.

 Comments: this routine expects as many arguments as you define in NPART

%DWDONE

  CALL DWDONE(KEEP)

 Purpose: to close the draw file 

 Parameter:

  KEEP   - LOGICAL, equivalent to the STATUS= in Fortran CLOSE
                  =.TRUE. to KEEP
                  =.FALSE. to DELETE

  Errors: nothing happens if the file is not open

%DWEGRP

  CALL DWEGRP(IERR)

 Purpose: ends a group of objects

 Parameter:

  IERR   - INTEGER returned error number
                   0: group ended OK
                  -8: no group started (no action taken)
                   2: file not initialised

 Comment: open groups will be closed by DWDONE if DWEGRP is not called.

%DWELIP

 CALL DWELIP(XYC,A,B,THETA,IERR)

 Purpose: draws an ellipse

 Parameters:

  XYC    - REAL array dimension 2 containg the x and y of the ellipse centre
                in user coordinates

  A,B    - REAL lengths of the major and minor axes in user coordinates

  THETA  - REAL angle (radians) of the major axis to the x-direction

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)

 Comments: use DWCOLF to set the fill colour (or no fill)
               DWCOLL to set the outline colour
               DWLWID to set the outline thickness
               DWDASH to make a dash/dot line

%DWFONT

  CALL DWFONT(FONTNM,IHFONT)

 Purpose: to register a font name for text output

 Parameters:

  FONTNM - CHARACTER full font name (e.g. 'Homerton.Bold.Oblique')

  IHFONT - INTEGER returned font handle or error number
                  1,2,3 etc. = good font handles
                   0: draw file not initialised
                  -2: font not found
                  -9: no more room to store font names
                 -10: too late to register fonts (see comments)

 Comments: 1) a returned font handle must be passed to DWTXFS in order to
              write text in the font.
           2) all fonts must be registered with DWFONT before using them in
              DWTXFS and before drawing anything.
           3) if you inadvertently pass a negative font handle to DWTXFS it
              will use the system font.

%DWINIT

  CALL DWINIT(FILENM,PAGESZ,XL,YL,XH,YH,IERR)

 Purpose: opens a Draw file, sets up the coordinate system and initialises
          colours and line styles to default values.

 Parameters:

  FILENM - CHARACTER file name for the draw file

  PAGESZ - CHARACTER*3 page size between A5L and A0P
                      (P for portrait, L for Landscape

  XL,YL  - REAL coordinates of bottom left corner of user defined area

  XH,YH  - REAL coordinates of top right corner of user defined area

  IERR   - INTEGER returned error code:
                   0: draw file initialised OK
                   1: can not open file
                   3: unrecognised page size
                   4: user dimensions do not define a positive area
                  -4: unable to write header (disc full?)

 Comments: Your area, defined by (XL,YL) to (XH,YH), is fitted into the page
           with (XL,YL) at the bottom left corner, and scaled so that it
           just fits onto the page. Try to make the aspect ratio of your
           area match that of the page as far as is possible.

%DWJPEG

 CALL DWJPEG(JPEG,LJPEG,XY,IERR)

 Purpose: inserts JPEG image

 Parameters:

   JPEG  - ARRAY containing the JPEG image

  LJPEG  - INTEGER length of JPEG in bytes

     XY  - REAL array of 2 words giving the bottom left corner for image

   IERR  - INTEGER returned error code
                 0: image transferred OK
                -1: image outside frame (not transferred)
                >0: JPEG is illegal

 Comments: 1) use FLLOAD to load JPEG into an array and FLSIZE to find
              its size.
           2) JPEG images can not be plotted with Draw in RISC-OS < 3.5

%DWJPSZ

 CALL DWJPSZ(JPEG,LJPEG,XY,IERR)

 Purpose: finds the size of a JPEG image in user coordinates

 Parameters:

   JPEG  - ARRAY containing the JPEG image

  LJPEG  - INTEGER length of JPEG in bytes

     XY  - REAL array of 2 words returned with the (x,y) size of the image
           in User Coordinates

   IERR  - INTEGER returned error code
                 0: image transferred OK
                -1: image outside frame (not transferred)
                -4: can't write any more to file (disc full?)
                >0: JPEG is illegal

 Comments: 1) use FLLOAD to load JPEG into an array and FLSIZE to find
              its size.
           2) JPEG images can not be plotted with Draw in RISC-OS < 3.5

%DWLWID

 CALL DWLWID(IWID)

 Purpose: sets the line width for a path

 Parameter:

  IWID   - INTEGER line width in OS units*256 from 0 (thinnest) to 
                   &FF00 (thickest) default 0

 Errors: none (IWID is limited to the allowed range) 

%DWPOLY

 CALL DWPOLY(XY,N,CLOSE,IERR)

 Purpose: draws a polyline or closed polygon

 Parameters:

  XY     - REAL array dimension (2,N) with the X and Y values of the points
                forming the polyline in user coordinates.

  N      - INTEGER number of points in the polyline

  CLOSE  - LOGICAL defines whether to close the polyline into a polygon
                   .TRUE. joins the last point back to the first
                   .FALSE. joins the N points with N-1 lines

  IERR   - INTEGER returned error
                   0: path drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                  -6: N less than 2

 Comments: use DWCOLF to set the fill colour
               DWCOLL to set the line colour
               DWLWID to set the line width
               DWSTYL to set the line style
               DWDASH to make a dash/dot line

%DWSECT

 CALL DWSECT(XYC,RADIUS,TH1,TH2,IERR)

 Purpose: draws a sector of a circle, (an arc closed with a chord).

 Parameters:

  XYC    - REAL array dimension 2 containg the x and y of the circle centre
                in user coordinates

  RADIUS - REAL radius of circle in user coordinates

  TH1    - REAL angle (radians) from the x-axis of the beginning of the arc

  TH2    - REAL angle (radians) from the x-axis of the end of the arc

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                 -13: TH2 not greater than TH1, or arc more than 2pi

 Comments: it is best to keep the angles within the range -2pi to +2pi.
           use DWCOLF to set the fill colour (or no fill)
           use DWCOLL to set the outline colour
           use DWLWID to set the outline thickness
           use DWDASH to make a dash/dot outline

%DWSEGC

 CALL DWSEGC(XYC,RADIUS,TH1,TH2,IERR)

 Purpose: draws a segment of a circle, (closed by joining the ends of
          the arc to the centre).

 Parameters:

  XYC    - REAL array dimension 2 containg the x and y of the circle centre
                in user coordinates

  RADIUS - REAL radius of circle in user coordinates

  TH1    - REAL angle (radians) from the x-axis of the beginning of the arc

  TH2    - REAL angle (radians) from the x-axis of the end of the arc

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                 -13: TH2 not greater than TH1, or arc more than 2pi

 Comments: it is best to keep the angles within the range -2pi to +2pi.
           use DWCOLF to set the fill colour (or no fill)
           use DWCOLL to set the outline colour
           use DWLWID to set the outline thickness
           use DWDASH to make a dash/dot outline

%DWSPRT

 CALL DWSPRT(IAREA,SPNAME,XY,IERR)

 Purpose: inserts a sprite into the draw file

 Parameters:

  IAREA  - INTEGER array: sprite area containing the sprite
                   or = 0 for system sprite
                      =-1 for wimp sprite

  SPNAME - CHARACTER sprite name of the sprite to insert

  XY     - REAL array dimension 2 containg the x and y of the bottom left
                of the sprite in user coordinates

  IERR   - INTEGER returned error number
                   0: circle drawn OK
                   2: draw file not opened by DWINIT
                  -1: path outside user area defined by DWINIT
                  -4: can't write any more to file (disc full?)
                 -15: can't find sprite in sprite area



%DWSTYL

 CALL DWSTYL(JOIN,IECAP,IBCAP,IWRULE,ITCWID,ITCLEN)

 Purpose: sets the line style for a path

 Parameters:

  JOIN   - INTEGER defines how lines are joined
                   0: mitred joins
                   1: round joins
                   2: bevelled joins (default)

  IECAP  - INTEGER defines line end cap style
                   0: butt caps (default)
                   1: round caps
                   2: projecting square caps
                   3: triangular caps (see ITCWID, ITCLEN below)

  IBCAP  - INTEGER defines line beginning cap style 
                   definitions as for IECAP

  IWRULE - INTEGER winding rule defining the inside/outside of a path
                   0: non-zero
                   1: even-odd (default)

  ITCWID - INTEGER triangle cap half-width in range 0 to 255
                   measured in 1/16 of the line width (default 16)

  ITCLEN - INTEGER triangle cap length in range 0 to 255
                   measured in 1/16 of the line width (default 32)

  Comments: 1) if the value given is bigger than the allowed range, the
               default value is used
            2) if a negative value is given for a parameter, then it is
               ignored, and no later parameters are used, neither need they
               be specified in the calling sequence. E.g.
                      CALL DWSTYL(0,-1) 
               just sets the joins to be mitred.

%DWSZXY

 CALL DWSZXY(STRING,XYS,IERR)

 Purpose: finds the size of the circumscribed box round some text

 Parameters:


  STRING - CHARACTER string for investigation

  XYS    - REAL (dimension 2,2) returned coordinates of the 
                bottom-left and top-right of the circumscribed box
                relative to the bottom left of the first letter.
                Descenders will make XYS(1,2) less than zero; 
                XYS(1,1) may be either side of zero depending on the first
                letter and the font.

  IERR   - INTEGER returned  error number
                   0: box found OK
                   2: drawfile not initialised
                  -2: can't find font (should never happen)

 Comments: change font and size with DWTXFS

%DWTEXT

 CALL DWTEXT(XY1,STRING,XYRECT,IERR)

 Purpose: writes text in current font, size and colour

 Parameters:

  XY1    - REAL (dimension 2), coordinates of bottom left start of text

  STRING - CHARACTER string to be printed

  XYRECT - REAL (dimension 2,4) returned coordinates of the circumscribed
                rectangle, starting from the bottom left and going
                clockwise.

  IERR   - INTEGER returned  error number
                   0: written OK
                   2: drawfile not initialised
                  -1: string does not fit in user area
                  -2: can't find font (should never happen)
                  -4: can't write any more to file (disc full?)

 Comments: change font and size with DWTXFS
           change colour with DWTXFC and DWTXBC

%DWTXBC

 CALL DWTXBC(IRED,IGREEN,IBLUE)

 Purpose: sets the anti-alias background colour for DWTEXT

 Parameters:

  IRED   - INTEGER amount of red (0 to 255) default 255

  IGREEN - INTEGER amount of green (0 to 255) default 255

  IBLUE  - INTEGER amount of blue (0 to 255) default 255

 Errors: if the value given is outside the range 0 to 255 it will be set to
         0 or 255.

%DWTXFC

 CALL DWTXFC(IRED,IGREEN,IBLUE)

 Purpose: sets the text colour for DWTEXT

 Parameters:

  IRED   - INTEGER amount of red (0 to 255) default 0

  IGREEN - INTEGER amount of green (0 to 255) default 0

  IBLUE  - INTEGER amount of blue (0 to 255) default 0

 Errors: if the value given is outside the range 0 to 255 it will be set to
         0 or 255.

%DWTXFS

  CALL DWTXFS(IFONT,IXSIZ,IYSIZ,IERR)

 Purpose: sets up font information for next line of text

 Parameters:

  IFONT  - INTEGER font handle as defined by DWFONT
                   (default 0 : system font)

  IXSIZ  - INTEGER nominal x size in points (6 to 144) (default 10)

  IYSIZ  - INTEGER nominal y size in points (6 to 144) (default 10)

  IERR   - INTEGER returned error number
                   0: OK
                   2: draw file not initialised
                  -4: can't write any more to file (disc full?)
                 -11: unknown font handle
                 -12: point size outside allowed range
           
 Comments: 1) an unknown font (IERR=-11) defaults to the system font
           2) point sizes outside the allowed range cause both IXSIZ and
              IYSIZ to be set to the default.

%DWTXTA

 CALL DWTXTA(XY1,ANGLE,STRING,XYRECT,IERR)

 Purpose: writes text in current font, size and colour at any angle

 Parameters:

  XY1    - REAL (dimension 2), coordinates of bottom beginning of
                the first letter

  ANGLE  - REAL angle from the x-axis to draw the text (radians)

  STRING - CHARACTER string to be printed

  XYRECT - REAL (dimension 2,4) returned coordinates of the circumscribed
                rectangle, starting from the corner near XY1 and going
                clockwise. N.B. this rectangle is aligned with the text,
                not with the screen axes.

  IERR   - INTEGER returned  error number
                   0: written OK
                   2: drawfile not initialised
                  -1: string does not fit in user area
                  -2: can't find font (should never happen)
                  -4: can't write any more to file (disc full?)

 Comments: use DWTEXT to draw normal text, it is much more efficient.
           change font and size with DWTXFS
           change colour with DWTXFC and DWTXBC
