               The Graphics interface library
%GRARCC

  CALL GRARCC(IXC,IYC,IR,ANG1,ANG2)

  Purpose: draws a circular arc

  Parameters

 IXC,IYC - INTEGERs centre of circle

      IR - INTEGER radius of circle

    ANG1 - REAL angle of radius vector to beginning of arc (radians)

    ANG2 - REAL angle of radius vector to end of arc (radians)

  Errors:  ANG2 not greater than ANG1
           (ANG2 - ANG1) greater than 2pi

%GRCHAR
  
  CALL GRCHAR(ICH,IDEF)

  Purpose: defines the shape to be used to display a character 

  Parameters:

    ICH - INTEGER number of the character between 32 and 255 inclusive

    IDEF - INTEGER array of 8 words containing the definition in their least
                   significant bytes.

  Example:
           DIMENSION IDEF(8)
 C                                  ?B defines a binary number.
           DATA IDEF/?B00111000,
          1          ?B00111000,
          2          ?B00010000,
          3          ?B01111100,
          4          ?B10010010,
          5          ?B00111000,
          6          ?B01000100,
          7          ?B10000010/
           CALL GRCHAR(250,IDEF)
 C                                    print a stick-man
           PRINT *,CHAR(250)

 Errors: if ICH is outside the allowed range, the routine does nothing.

 Comment: VDU23

%GRCIRC

 CALL GRCIRC(IX,IY,IR,FILL) 

 Purpose: draws an outline or filled circle in the current graphics colour, 
          it will be truncated if it goes outside a graphics window
          or the edge of the screen. 

 Parameters:

    IX,IY - INTEGER x,y coordinates of the centre of the circle

    IR - INTEGER radius of the circle, may be positive or negative,
                 the sign is ignored.
    
    FILL - LOGICAL specifies whether an outline or filled circle is drawn 
                   FILL=.TRUE. for a filled circle


 Example:  
           CALL GRSETM(12)
           CALL GRGCOL(0,1)
  C                          draw an outline circle in logical colour 1
           CALL GRCIRC(400,400,300,.FALSE.)
           CALL GRGCOL(0,2)
  C              draw a filled circle in another colour inside it
           CALL GRCIRC(400,400,200,.TRUE.)

 Comments: To draw arcs of circles use the GRPLOT routine, values 160 to 183

%GRCLRG

 CALL GRCLRG

 Purpose: clears the graphics window, or whole screen if no graphics window
          is set, to the current graphics background colour

 Comments: Must not be used in WIMP programs.
           Gives the same result as GRVDU(16)  
           To clear a text screen use GRCLRT. 
%GRCLRT

 CALL GRCLRT

 Purpose: clears the text window, or whole screen if no text window is set,
          to the current text background colour

 Comments: Must not be used in WIMP programs.
           Gives the same result as GRVDU(12)  
           To clear a graphics screen use GRCLRG. 
%GRCMV

 CALL GRCMV(MODE,NEWMOD)

 Purpose: checks whether the requested screen mode number is valid for
          this monitor.

 Parameters:

    MODE- INTEGER mode number, unchanged on exit
 
    NEWMOD -INTEGER returns positive numbers in range 0 to 128 for 
            allowed values or negative numbers for errors
            If MODE is valid, returns NEWMOD the same as MODE, otherwise
            returns the number of the screen mode giving the mode which is
            closest to MODE.
           
 Errors: NEWMOD -1 illegal, no possible near equivalent mode
                -2 not enough memory available to use this mode

 Example:  to see whether 28 is a legal mode and if it is to set it.

           CALL GRCMV(28,NEW)
           IF(NEW .EQ. 28)THEN
             CALL GRSETM(28)
           ELSE
             WRITE(*,*)' Mode 28 not legal for this monitor'
             WRITE(*,*)' Value returned for NEW=',NEW
           ENDIF           

 Comments: Does not set the mode, only checks it.
           Related routine GRRMV, GRRVV
%GRCOPY
  
  CALL GRCOPY(IX1,IY1,IX2,IY2,IXN,IYN)

  Purpose: copies a rectangular area of screen to another part of the
           screen, defined by its lower left corner, the rectangles may
           overlap. It will be truncated if it goes outside a graphics
           window or the edge of the screen. 

  Parameters:

   IX1,IY1 - INTEGER co-ordinates of a corner of the rectangle to be copied

   IX2,IY2 - INTEGER co-ordinates of the opposite corner of the rectangle

   IXN,IYN - INTEGER co-ordinates of the lower left corner of the area 
                     to which the rectangle is to be copied

    Example:
             CALL GRCOPY(100,200,300,300,512,640)

    Result: the rectangle size (200,100) at (100,200) is copied to (512,640)

    Comments: the new rectangle may overlap the original rectangle when the
              new rectangle will show the graphics pattern of the original,
              but the overlapped part of the original will be destroyed.
              Known as BITBLT in some implementations.
              Gives same result as using GRPLOT 184 to 191 XXXX which one?

%GRCURS

  CALL GRCURS(ISTAT)

  Purpose: turns the flashing cursor on, or off

  Parameter:

   ISTAT - LOGICAL flag specifies the action.
           when ISTAT is .TRUE. turns on cursor, when .FALSE. turns it off
%GRDEFD

 CALL GRDEFD(BITS)

 Purpose: sets the dot/dash pattern for subsequent line drawing using GRPLOT

 Parameters:

    BITS - CHARACTER string of length less than 65, containing only
                     characters 0 and 1 defining the pattern. 
                     A single character resets the pattern to the default,
                     length 8 pattern '10101010'
                     
 Errors: Nothing happends for the following cases:
         More than 64 characters in string BITS
         BITS contains characters other than 0 or 1
         

 Example: Draw a dotted line and then reset to the defaults

           CHARACTER *  BITS
           DATA BITS/'0100111'
           CALL GRMOVE(100,100)
C                               set up the pattern and draw dashed line
           CALL GRDEFD(BITS)                      
           CALL GRPLOT(21,500,100)
C                                reset to default and draw a default line
           CALL GRDEFD('0')
           CALL GRPLOT(21,500,500)
C                                 draw a solid line
           CALL GRPLOT(5,100,500)

 Comments: See GRPLOT for the meaning of the offsets of 0 to 8 for each type.

          The different ways of plotting the line are:
      Plot range   Method
        16-23    Draw both endpoints. restart the pattern for each new line
        24-31    Final point omitted, pattern restarts for each new line
        32-39    Initial point omitted, pattern continues over new lines
        40-47    Both endpoints omitted, pattern continues over new lines

         Dotted lines can only be drawn with GRPLOT, other line drawing
         routines GRCIRC, GRDRAW, GRLINE, GRPOLY, GRRECT, GRTRI, always
         use solid lines.

%GRDPOL

 CALL GRDPOL(IXY,N,CLOSE,FILL,IWID,IDASH)

 Purpose: draws a polygon in the current graphics colour using 'Draw'
          commands so any shape may be filled.

 Parameters:

    IXY array (2,*) of (x,y) coordinates of the polygon in OS units

      N number of points in the polygon (must be at least 2)

  CLOSE LOGICAL is .TRUE.(1) if the last point is to be joined to the first
                (the winding rule may be added, see comments)

   FILL LOGICAL is .TRUE. for a solid polygon
 
        the following are not needed for filled polygons: 
 
   IWID width of the line in OS units*256 (0 for minimum width)

  IDASH dash pattern or 0 (.FALSE.) for solid line (see below)

 Error: less than two points requested so nothing happens

 Comments: 1) is slower than GRPOLY for very simple filled areas
           2) allows dashed lines to be 'Printed'. IDASH is made of
              4 bytes giving the amounts of on,off,on,off in OS units.
              The example in Tgraphics uses IDASH=?I120C060C with 
              IWID=6 so it produces a dash of 18x6, a gap of 12x6,
              a dot of 6x6 and a gap of 12x6. All 4 parts must be specified
              so a simple dashed line might use IDASH=?I0C0C0C0C and
              a simple dotted line: IDASH=?I06060606 with IWID=6.
           3) there is no outline drawn if FILL=.TRUE.
           4) CLOSE is normally 0(.FALSE.) or 1(.TRUE.) but may have the
              (winding rule)*2 added to it. Winding rules are:
                  0: non-zero (default)
                  1: negative
                  2: even-odd (decides what is outside by line to infinity)
                  3: positive
           5) triangular caps may be put on unCLOSEd paths using
              GRDTRI
           6) uses Draw_Stroke PRM2: 1503, PRM3: 3-540 
                or Draw_Fill   PRM2: 1502, PRM3: 3-538


%GRDRAW

 CALL GRDRAW(IX,IY)

 Purpose: draws a line from the previous point to the given point  
          in the current graphics colour; it will be truncated if it goes
          outside a graphics window or the edge of the screen. 

 Parameters:

    IX,IY - INTEGER x,y coordinates of the point

 Example:    CALL GRDRAW(200,50)

 Comments: Same as CALL GRPLOT(5,IX,IY)

%GRDTRI

 CALL GRDTRI(IEND,IWID,LENG)

 Purpose: sets up triangular endcaps for GRDPOL

 Parameters:

   IEND integer =1 for beginning of path, =2 for end
        (all other values do nothing)

   IWID width of arrow in units of linewidth [0:127]
        (>127 does nothing)

   LENG length of arrow in units of linewidth [0:127]
        (>127 does nothing)

 Comment: if both IWID and LENG =0 the cap returns to butt

%GRELIP

 CALL GRELIP(IX,IY,MAJOR,MINOR,ANGLE,FILL)

 Purpose: draws an ellipse in the current graphics colour.

 Parameters:

    IX,IY - INTEGER x,y coordinates of the centre of the ellipse

    MAJOR,MINOR - INTEGER semi-major and semi-minor axis lengths

    ANGLE - REAL angle in radians formed by the semi major axis and the
            horizontal direction. 
    
    FILL - LOGICAL specifies whether an outline or filled ellipse is drawn 
                   FILL=.TRUE. for a filled ellipse

 Errors: If an ellipse is too high, numerical inaccuracies may spoil its
         plotting. The effect starts to be noticeable at about height 2500
         (XXXXX in what co-ordinates??????) from the centre of the ellipse
         to its highest point.

 Example: CALL GRELIP(400,400,200,100,0.7,.FALSE.)

 Comments: Fortran version uses GRPLOT 192 to 207

%GRFILB

 CALL GRFILB(IX,IY)

 Purpose:  fills an arbitrary area around the given point using the current
         graphics foreground colour, stops at a non-background colour
         boundary, which should be a closed curve. It will not go outside a
         graphics window.

 Parameters:

    IX,IY - INTEGER x,y coordinates of the point at which filling commences    
 Errors: if the non-background colour boundary is not closed, fills all
         the screen

 Example:  CALL GRFILB(20,30)

 Comments: Same as CALL PLOT(133,IX,IY)

%GRFILF

 CALL GRFILF(IX,IY)

 Purpose:  fills an arbitrary area around the given point using the current
         graphics foreground colour, stops when it reaches a foreground
         coloured boundary, which should be a closed curve. It will not go
         outside a graphics window.

 Parameters:

    IX,IY - INTEGER x,y coordinates of the point at which filling commences    
 Errors: if the foreground colour boundary is not closed, fills all
         the screen

 Example:  CALL GRFILF(20,30)

 Comments: Same as CALL PLOT(141,IX,IY)

%GRGCOL

 CALL GRGCOL(IACT,ICOL)

 Purpose: Sets the current graphics colour in 2, 4 or 16 colour
          screen modes or changes the extended colour fill patterns
          *** On RISCOS 3.5 or greater, use GRSETC ***

 Parameters:

    IACT - INTEGER specifying the way to plot the colour when IACT <8
           or to change the patterns IACT >15

           0 overwrite the colour on the screen with colour ICOL
           1 OR the colour on the screen with colour ICOL
           2 AND the colour on the screen with colour ICOL
           3 EOR the colour on the screen with colour ICOL
           4 invert the colour on the screen, 
             (replace the colour on the screen with the colour made by
              EORing its logical colour number with (number of logical
               colours -1)
           5 leave the colour on the screen unchanged
           6 AND the colour on the screen with NOT colour ICOL
           7 OR the colour on the screen with NOT colour ICOL


            changing the extended colour fill (ECF) patterns, 
           16+n ECF pattern 1         48+n ECF pattern 3
           32+n ECF pattern 2         64+n ECF pattern 4
                  where n= 0 to 5 described above
            when ICOL = 0 the pattern is used as graphics foreground
                      = 128 as background 
            
    ICOL - INTEGER specifying the colour.
            Foreground colours have 0 < ICOL < 128
            background colours have 128 < ICOL < 255 where the logical
            colour used is  (ICOL -128)
 
 Errors:   Values of IACT other than those defined above give unpredictable
           results

  Example:  CALL GRGCOL(0,4)

 Comments:  use GRSETC for modern (RISCOS 3.5 etc) colour modes
            Must not be used in WIMP programs
 

%GRGETC

 CALL GRGETC(IX,IY,IR,IG,IB)

 Purpose: finds the physical colour of a point

 Parameters:

    IX,IY  - INTEGER x,y coordinates of the point to be tested

        IR - INTEGER returned amount of red (in the range 0 to 255)

        IG - INTEGER returned amount of green (in the range 0 to 255)

        IB - INTEGER returned amount of blue (in the range 0 to 255)

 Errors: if (IX,IY) is off the screen LOGCOL is set to -1

 Comments: see GRGETL to get logical coloyr in 2, 4 or 16 colour modes

%GRGETL

 CALL GRGETL(IX,IY,LOGCOL)

 Purpose: finds the logical colour of a point in 2, 4 or 16 colour modes

 Parameters:

    IX,IY  - INTEGER x,y coordinates of the point to be tested

    LOGCOL - INTEGER returns the logical colour at the point

 Errors: if (IX,IY) is off the screen LOGCOL is set to -1

 Comments: see GRGETC to get the physical colour in any mode

%GRGETM

 CALL GRGETM(M)

 Purpose: Gets the screen mode, which determines the number of colours, the
          screen resolution, the number of characters in a line and the 
          number of lines of text.

 Parameters:

    M - INTEGER the mode of screen being used;
             0 <= M <= 127: current screen mode
           128 <= M <= 255: shadow screen mode allowing 
           switching between two screens using OSBYTE 112
           and OSBYTE 113; it needs twice the screen memory.
                  M >  255: pointer to mode selector (RISC-OS 3.5)

 Errors: None

 Example:
      
      DIMENSION JTEMP(0:2)
C            print current mode
      CALL GRGETM(M)
      IF(M.LT.256) THEN
        PRINT *,' Screen mode:',M
      ELSE
C             mode selector, print number of bits/pixel
        LTEMP=(M-LOC(JTEMP))/4
        PRINT *,JTEMP(LTEMP+3),' bits per pixel'
      ENDIF

 Comments: 1) Most Acorn User Guides have a table of possible mode
              values; for example Appendix D of the RISC-OS 3 User Guide.
           2) RISC-OS 3.5 (and later) mode selectors contain:
              (0)  : 1
              (1)  : x resolution
              (2)  : y resolution
              (3)  : bits per pixel
              (4)  : frame rate (Hz) (-1 means use highest rate)
              (5,6): mode variable index, value of mode variable
                     (see GRRMV for definitions of mode variables)
               ... : more of the same
              (?)  : -1 to terminate

%GRGWIN

 CALL GRGWIN(IX1,IY1,IX2,IY2)

 Purpose: Sets a rectangular graphics window

 Parameters:

    IX1 - INTEGER X co-ordinate of lower left corner of window
 
    IY1 - INTEGER Y co-ordinate of lower left corner of window

    IX2 - INTEGER X co-ordinate of upper right corner of window
 
    IY2 - INTEGER Y co-ordinate of upper right corner of window

 
 Errors: If any of the parameters are outside the screen or the lower left
       point is not below and to the left of the upper right one, then no
       window is set up, and no warnings are given.

 Example:
            CALL GRGWIN(100,200,800,600)


 Comments:  This does not move the origin of graphics coordinates.
            All windows are cleared by CALL GRVDU(26)

%GRHOUR

 CALL GRHOUR(IHG)

 Purpose: turns Hourglass pointer on or off and also displays the Hourglass
          percentage indicator

 Parameter:

  IHG   - INTEGER flag for pointer type:
                        0: turn off Hourglass
                  1 to 99: 1 to 99% under hourglass 
            anything else: turn on hourglass

 Errors: none

 Comments: please turn off the Hourglass when you have finished with it.

%GRLINE

 CALL GRLINE(IX1,IY1,IX2,IY2)

 Purpose: Draws a line in the current colour between two points. Any part
          outside the current graphicswindow will not be drawn.

 Parameters:

    IX1 - INTEGER X co-ordinate of first point
 
    IY1 - INTEGER Y co-ordinate of first point

    IX2 - INTEGER X co-ordinate of second point
 
    IY2 - INTEGER Y co-ordinate of second point
 
 Example:  CALL GRLINE(800,1000,200,400)

 Comments: Same as GRMOVE(IX1,IY1) followed by GRDRAW(IX2,IY2)

%GRMOVE

 CALL GRMOVE(IX,IY)

 Purpose: Moves the current graphics cursor to the new point

 Parameters:

    IX - INTEGER X co-ordinate of the point
 
    IY - INTEGER Y co-ordinate of the point
 
 Example:   CALL GRMOVE(250,500)

 Comments: Same as CALL PLOT(4,IX,IY)

%GRORIG

 CALL GRORIG(IX,IY)

 Purpose: Moves the graphics origin to the specified point

 Parameters:

    IX - INTEGER X co-ordinate of the new origin of coordinates
                   measured from the left edge of the screen
 
    IY - INTEGER Y co-ordinate of the new origin of coordinates
                   measured from the bottom of the screen
 
 Example:

    CALL GRORIG(640,512)

 Results in: moving the graphics origin to the middle of a standard screen
             of size 1280x1024 OS units

 Comments: Moving the origin does not change the position of a graphics
           window which has been set up previously; it remains in the same
           place on the screen. However a graphics window set up
           subsequently will be defined relative to the new origin.
           This command is equivalent to the Basic: VDU29,IX;IY;

%GRPAL

 CALL GRPAL(LOGCOL,IRED,IGREEN,IBLUE)

 Purpose: sets the physical colour to be displayed for a logical colour
          in 2,4 16 colour modes

 Parameters:

    LOGCOL - INTEGER in the range 0:1 for 2 colour modes, 0:3 for 4-colour
                     modes, or 0:15 for 16 colour modes

    IRED   - INTEGER amount of red colour to be used (in range 0:15)

    IGREEN - INTEGER amount of green colour to be used (in range 0:15)

    IBLUE  - INTEGER amount of blue colour to be used (in range 0:15)
 
 Errors: the physical colours are taken modulo 16, i.e. only the least
         significant 4 bits are considered.

 Example: 

      PARAMETER (IGREY=12)
C          set colour 12 to light grey
      CALL GRPAL(IGREY,12,12,12)
C          select colour 12
      CALL GRCOL(0,IGREY)
C          plot solid circle
      CALL GRCIRC(100,100,100,.TRUE.)
C draws a light grey solid circle in the lower left of the screen

 Comments: the palette can be reset to the default by CALL GRVDU(20) or by
           resetting the screen mode with GRSETM
           Equivalent to Basic: VDU19,LOGCOL,16,IRED*16,IGREEN*16,IBLUE*16
           It can be used after using the logical colour for drawing, thus
           enabling rapid changes of colour.
           See GRLTOP to set a logical colour to a standard physical colour.

%GRPBOX

 CALL GRPBOX(IX1,IY1,IX2,IY2)       sets mouse/pointer bounding box

 Purpose: sets the bounding box for the mouse pointer

 Parameters:

  IX1,IY1 - INTEGERs bottom left corner of the bounding box for the pointer
                     must be in the range [-32768:32767]

  IX2,IY2 - INTEGERs top right corner of the bounding box for the pointer
                     must be in the range [-32768:32767]

 Errors: none

 Example:

C  limit the pointer to be in the bottom left quarter of the screen
      CALL GRPBOX(0,0,640,512)

 Comment: the box request is ignored if the coordinates are illegal 
 
%GRPBUT

 CALL GRPBUT(IX,IY,IB)

 Purpose: waits for mouse button click or a keyboard press, then returns the
          pointer values.

 Parameters:

  IX,IY   - INTEGERs returned position of the pointer

  IB      - INTEGER returned mouse button (1:adjust, 2:menu, 3:select)
                    or ASCII of the key pressed (32 to 126)

 Errors: none

 Comment: the program will stop if <Esc> is pressed
          

%GRPGET

 CALL GRPGET(IX,IY,IB)

 Purpose: gets the current pointer position and mouse button state

 Parameters:

  IX,IY   - INTEGERs returned position of the pointer

  IB      - INTEGER returned mouse button (1:adjust, 2:menu, 3:select)

 Errors: none

%GRPLOT

 CALL GRPLOT(K,IX,IY)

 Purpose: general plotting routine, whose action depends on the base value
          of K.  If the action demands drawing on the screen, it will be in
          the current graphics colour and will be truncated if it goes
          outside a graphics window or the edge of the screen. 

 Parameters:

     K - INTEGER type of plot

    IX - INTEGER X co-ordinate of point at which the plotting starts
 
    IY - INTEGER Y co-ordinate of point at which the plotting starts
 
 Example:
C        fill a first quadrant of a circle
C        move to the centre (CALL GRMOVE(512,640) is equivalent)
       CALL GRPLOT(4,512,640)
C        define the beginning relative to the centre (move relative)
       CALL GRPLOT(0,256,0)
C        draw quadrant (IX is the same as the centre,
C                       IY is anywhere on the vertical)
       CALL GRPLOT(181,512,1000)

 Comments: Values of K are as follows

      0 -  7 solid line including both end points
      8 - 15 solid line excluding final points
     16 - 23 dotted line including both end points
     24 - 31 dotted line excluding final points

     32 - 39 solid line excluding initial point
     40 - 47 solid line excluding both end points
     48 - 55 dotted line excluding initial point
     56 - 63 dotted line excluding both end points

     64 - 71 plot point
     72 - 79 horizontal line fill (left and right) to non-background
     80 - 87 triangle fill
     88 - 95 horizontal line fill (right only) to non-background

     96 -103 rectangle fill
    104 -111 horizontal line fill (left and right) to foreground
    112 -119 parallelogram fill
    120 -127 horizontal line fill (right only) to non-foreground

    128 -135 flood fill to non-background
    136 -143 flood fill to foreground 
    144 -151 outline circle
    152 -159 filled circle

    160 -167 outline circular arc
    168 -175 circular segment
    176 -183 circular sector (or filled circular arc)
    184 -191 move/copy rectangle

    192 -199 outline ellipse
    200 -207 filled ellipse
    208 -215 font printing
    216 -231 reserved for Acorn expansion
    232 -239 sprite plotting
    240 -255 user program calls

 Each base value may have one of 8 possible offsets added to
          it with meaning as follows:

         0 move cursor relative to the last graphics point visited
         1 plot relative using the current foreground colour
         2 plot relative using the logical inverse colour
         3 plot relative using the current background colour

         4 move cursor absolute to the screen position given
         5 plot absolute using the current foreground colour
         6 plot absolute using the logical inverse colour
         7 plot absolute using the current background colour

%GRPOLY

 CALL GRPOLY(N,IX,IY,FILL)

 Purpose: draws a polyline in the current graphics colour between a set of
          points. It will be truncated if it goes outside a graphics window
          or the edge of the screen.

 Parameters:

    N    - INTEGER the number of points on the polyline

    IX   - INTEGER array of X-coordinates of the points

    IY   - INTEGER array of Y-coordinates of the points

    FILL - LOGICAL is .FALSE. to draw a line, .TRUE. to fill the area inside                    with solid triangles with their apices at the first point

 Errors: any polyline with less than 2 points or a filled polyline with 2
         points are not drawn

 Example:
      DIMENSION IX(10),IY(10)
      PARAMETER (DTOR=57.296)
C           calculate the corners of a decagon of radius 200
      DO 10 I=1,10
      IX=200*COS(FLOAT(I)*36./DTOR)+400
      IY=200*SIN(FLOAT(I)*36./DTOR)+400
   10 CONTINUE
C           plot a solid decagon with origin at (400,400)
      CALL GRPOLY(10,IX,IY,.TRUE.)

 Comments: 1 For a closed polyline you must give it the 1st and last points
             the same.
           2 A 'filled' polyline which is not convex will produce curious
             results if the first point does not see each edge from the same
             side. It may be better to make an outline polygon (a closed
             polyline) and then use GRFILL with a point inside it.

%GRPPUT

 CALL GRPPUT(IX,IY)

 Purpose: positions the mouse pointer on the screen

 Parameters:

  IX,IY   - INTEGERs new coordinates for the pointer position

 Errors: none

 Comment: what happens if the point is outside the screen?

%GRPSET

 CALL GRPSET(IS)

 Purpose: turns the pointer on,off or disconnects it from the mouse

 Parameter:

  IS     - INTEGER newcondition for the pointer:
                   0: pointer invisible
                   1: pointer visible and connected to the mouse
                   2: pointer visible but disconnected to the mouse

 Errors: none

 Comment: there will be no change if the parameter is not 0,1 or 2.

%GRPSPD

 CALL GRPSPD(IS)

 Purpose: sets the speed of the pointer relative to the mouse

 Parameter:

  IS     - INTEGER new speed for the pointer
                   0: pointer remains fixed
                 127: very fast forwards
                -128: very fast backwards

 Errors: none

 Comments: 1) nothing will happen if the parameter is outside the allowed
              range
           2) this does not alter the configured mouse speed
           3) normally the speed is from 1 to 4.

%GRRECT

 CALL GRRECT(IX1,IY1,IX2,IY2,FILL)

 Purpose: draws outline or filled axis-aligned rectangle in the current
          graphics colour; it will be truncated if it goes outside the
          graphics window or the edge of the screen. 

 Parameters:

    IX1,IY1 - INTEGER x,y coordinates of one corner of the rectangle
 
    IX2,IY2 - INTEGER x,y coordinates of the opposite corner
                      of the rectangle

    FILL    - LOGICAL is .FALSE. for outline rectangle, or .TRUE. for filled

 Example:
C        set the colour 2
      CALL GRGCOL(0,2)
C        draw solid rectangle in bottom left of screen
      CALL GRRECT(0,0,300,200,.TRUE.)

%GRRMV

 CALL GRRMV(MODE,NVAR,IVAL)

 Purpose: reads information about a screen mode (Read Mode Variable)

 Parameters:

    MODE - INTEGER is the screen mode for which the variable is required.
                   Use a value of -1 for the current mode

    NVAR - INTEGER the variable number (0 to 12) required

    IVAL - INTEGER returns the value of the requested variable
 
 Errors: zero will be returned if the input parameters are invalid

 Example:
C          find the last column number for printing in the current mode
      CALL GRRMV(-1,1,MAXCOL)

 Comments: the variables are detailed in the programmers reference manual,
           but here is a summary

   0  contains bits defining the type of mode
   1  maximum print column (e.g. 79 for an 80 column mode)
   2  maximum print row (e.g. 31 for a 32 row mode)
   3  maximum logical colour (except it may be 63 for a 256 colour mode!)
   4  power of 2 to change pixels into OS X-coordinates
   5  power of 2 to change pixels into OS Y-coordinates
   6  number of bytes used for a screen row of pixels
   7  number of bytes in a screen buffer
   8  should not be used
   9  power of 2 to get number of bits used per pixel
  10  power of 2 to get number of bytes used per character
  11  maximum pixel number in X
  12  maximum pixel number in Y

%GRRVV

 CALL GRRVV(NVAR,IVAL)

 Purpose: reads a VDU variable (ReaD Vdu Variable)

 Parameters:

    NVAR - INTEGER the variable number (0 to 12 and 128 to 257) required

    IVAL - INTEGER returns the value of the requested variable
 
 Errors: zero will be returned in IVAL if NVAR is outside the allowed ranges

 Example:
C       get address of start of screen memory
      CALL GRRVV(148,ISTART)

 Comments: Variables 0 to 12 are the same as those returned by GRRDMV for
            the current mode
           Variables 128 to 257 contain information on the current state of
            the screen and are detailed in the Programmers Reference Manual
           Some useful variables are:
 128-131  graphics window in units of pixels
 132-135  text window
 136-137  graphics origin in OS units
 138-139  graphics cursor in OS units
 140-145  3 last graphics cursor positions in pixels
 148      address of screen memory to be written to
 149      address of screen memory to be displayed
 150      total screen memory
 151-152  GCOL action for foreground and background
 153-154  graphics foreground and background colours
 155-156  text foreground and background colours
 157-160  256 colour 'tints' for the above
 161      highest screen mode allowed
 162-165  sizes of graphics mode characters
 167-170  sizes of text mode characters
 256-257  size of the text window in characters

%GRSECT

  CALL GRSECT(IXC,IYC,IR,ANG1,ANG2,FILL)

  Purpose: draws a sector of a circle

  Parameters

 IXC,IYC - INTEGERs centre of circle

      IR - INTEGER radius of circle

    ANG1 - REAL angle of radius vector to beginning of arc (radians)

    ANG2 - REAL angle of radius vector to end of arc (radians)

    FILL - LOGICAL .TRUE. for filled sector, .FALSE. for outline only

  Errors:  ANG2 not greater than ANG1
           (ANG2 - ANG1) greater than 2pi

  Comment: filling is done by a flood fill to the same colour as the 
           outline. This will not work if there is a closed area already
           within the sector with the same colour.

%GRSEGC

  CALL GRSEGC(IXC,IYC,IR,ANG1,ANG2,FILL)

  Purpose: draws a segment of a circle

  Parameters

 IXC,IYC - INTEGERs centre of circle

      IR - INTEGER radius of circle

    ANG1 - REAL angle of radius vector to beginning of arc (radians)

    ANG2 - REAL angle of radius vector to end of arc (radians)

    FILL - LOGICAL .TRUE. for filled segment, .FALSE. for outline only

  Errors:  ANG2 not greater than ANG1
           (ANG2 - ANG1) greater than 2pi

  Comment: filling is done by a flood fill to the same colour as the 
           outline. This will not work if there is a closed area already
           within the segment with the same colour.

%GRSETC

 CALL GRSETC(IACT,IRED IGREEN,IBLUE)

 Purpose: Sets the current graphics colour in any screen mode

 Parameters:

    IACT   - INTEGER, INTEGER*2, or BYTE specifies the way:
                     to plot the colour when IACT <8
                     to change the patterns IACT >15(see GRGCOL).
                     Add 128 to set the background colour.

    IRED   - INTEGER, INTEGER*2, or BYTE: amount of red used (0 to 255) 

    IGREEN - INTEGER, INTEGER*2, or BYTE: amount of green used (0 to 255)

    IBLUE  - INTEGER, INTEGER*2, or BYTE: amount of blue used (0 to 255)
  

 Example:
      CALL GRSETC(0,128,128,128)
C         next foreground graphics in medium grey

 Comments: All parameters are treated modulo 256
           You may use GRGCOL for 2, 4 or 16 colour modes

%GRSETM

 CALL GRSETM(M)

 Purpose: Sets the screen mode, which determines the number of colours, the
          screen resolution, the number of characters in a line and the 
          number of lines of text.

 Parameters:

    M - INTEGER the mode of screen to be used 0
             0 <= M <= 127: current screen mode
           128 <= M <= 255: shadow screen mode allowing 
           switching between two screens using OSBYTE 112
           and OSBYTE 113; it needs twice the screen memory.
           Or: a pointer to a RISC-OS 3.5  mode selector

 Errors: Larger values of M need more memory. If there is not enough free 
         memory available the new mode will not be set.

 Example:

C (1)        set up screen for 16 colours with 640x256 pixels
      CALL GRSETM(12)

C (2)        request double screen in mode 12
      CALL GRSETM(140)
C            display  screen ND (ND = 1 or 2)
      CALL OSBYTE(112,ND)
C            write to screen NW (NW = 1 or 2)
      CALL OSBYTE(113,NW) 
C            OSBYTE is in the UTILS library

 Comments: 1) Changing the screen mode resets the graphics origin to the
              lower left corner of the screen, removes all windows and
              clears the screen. Some values of M are only available in
              higher values of the RISC-OS operating system. Most Acorn
              User Guides have a table of possible values for example
              Appendix D of the RISC-OS 3 User Guide.
           2) RISC-OS 3.5 (and later) mode selectors must contain:
              (0)  : 1
              (1)  : x resolution
              (2)  : y resolution
              (3)  : bits per pixel
              (4)  : frame rate (Hz) (-1 means use highest rate)
              (5,6): mode variable index, value of mode variable
                     (see GRRMV for definitions of mode variables)
               ... : more of the same
              (?)  : -1 to terminate
              It is very difficult to set these up but you could make a copy
              of the current mode selector (obtained with GRGETM), modify it
              and use the modified version for a new mode.
              N.B. the argument M is a pointer to the array, not the array
              itself, so you should call it with code like:
              C         MBUF contains the mode selector array
                    CALL GRSETM(LOC(MBUF))

%GRSETT

 CALL GRSETT(IRED IGREEN,IBLUE)

 Purpose: Sets the current text colour in any colour mode

 Parameters:

    IRED   - INTEGER amount of red used (0 to 255) 
                     add 256 to set the background colour

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

    IBLUE  - INTEGER amount of blue used (0 to 255)
 
 Errors: if the colour parameters are outside the range 0 to 255,
         unpredictable colours will result

 Example:
      CALL GRSETT(128,128,128)
C         next foreground text in medium grey

 Comments: You may use GRTCOL for logical colours in 2, 4 or 16 colour modes
           Use GRSETC to set the graphics colours
           Parameters must all be 4-byte integers (INTEGER*4)

%GRSPOT

 CALL GRSPOT(IX,IY)

 Purpose: plots a point in the current graphics colour provided it is
          within the screen and graphics window

 Parameters:

    IX,IY - INTEGER x,y coordinates of the point to be plotted

 Example:
C         draw a diagonal of dots
      DO 10 IXY=0,1016,8
   10 CALL GRSPOT(IXY,IXY)

 Comments: equivalent to the Basic: POINT IX,IY

%GRTAB

 CALL GRTAB(IX,IY)

 Purpose: sets the position for printing the text within the text window

 Parameters:

    IX - INTEGER the column for the next text (0 is the leftmost column)
 
    IY - INTEGER the row for the next text (0 is the top row)

 Result: (for functions)

 Errors: if the position is outside the screen or text window, printing will
         start at the top left of the window, equivalent to GRTAB(0,0)

 Example:
C          print on the bottom row of a 32 row screen
      CALL GRTAB(0,31)
      PRINT *,' this is the bottom row'

 Comments: equivalent to the Basic VDU31,IX,IY

%GRTCOL

 CALL GRTCOL(ICOL)

 Purpose: Sets the current text colour in 2, 4 or 16 colour screen modes 

 Parameter:
            
    ICOL - INTEGER specifying the colour.
            Foreground colours have 0 < ICOL < 128
            background colours have 128 < ICOL < 255 where the logical
            colour used is  (ICOL -128)
 

  Example:
C            set text colour to cyan
     CALL GRTCOL(6)

 Comments:  use GRSETT for all colour modes in RISCOS 3.5 etc.


%GRTRI

 CALL GRTRI(IX1,IY1,IX2,IY2,IX3,IY3,FILL)

 Purpose: draws outline or filled triangle in the current graphics colour;
          it will be truncated if it goes outside the graphics window or the
          edge of the screen. 

 Parameters:

    IX1,IY1 - INTEGER x,y coordinates of the first corner of the triangle
 
    IX2,IY2 - INTEGER x,y coordinates of the second corner of the triangle

    IX3,IY3 - INTEGER x,y coordinates of the third corner of the triangle

    FILL    - LOGICAL is .FALSE. for outline triangle, or .TRUE. for filled

 Example:
C        set the colour 3 
      CALL GRGCOL(0,3)
C        draw outline yellow isosceles triangle in bottom left of screen
      CALL GRRECT(0,0,300,100,100,300,.FALSE.)

%GRTWIN

 CALL GRTWIN(IX1,IY1,IX2,IY2)

 Purpose: Sets a rectangular text window

 Parameters:

    IX1 - INTEGER left column of window
 
    IY1 - INTEGER bottom row of window

    IX2 - INTEGER right column of window ( .GE. IX1)
 
    IY2 - INTEGER top column of window ( .LE. IY1)

 
 Errors: If any of the parameters are outside the screen, IX1 is greater than
         IX2 or IY1 is less than IY2, then no window is set up, and no
         warnings are given.

 Example:
C         print only on the top two lines of a 80 column screen
      CALL GRTWIN(0,1,79,0)

 Comments:  Remember that rows are numbered downwards
            Text rows and columns are subsequently numbered starting from the
            top left of the window
            All windows are cleared by CALL GRVDU(26)

%GRVDU

 CALL GRVDU(I)

 Purpose: send one byte to the screen driver

 Parameters:

    I - INTEGER containing byte to send to the screen driver

 Errors: bytes between 0 and 31 are introductions to control sequences;
         failing to complete such a sequence will give unpredictable results

 Example:
C           return the text cursor to 'home' position
      CALL GRVDU(30)

 Comments: bytes containing 32 to 255 just send that ASCII character to the
           screen
           Single byte control sequences which can be safely used are:
  0: do nothing
  1: send the next byte to the printer only
  2: send all following bytes also to the printer
  3: stop sending bytes to the printer
  4: print at text cursor (see GRWOT)
  5: print at graphics cursor (see GRWOG)
  6: restores screen output (see 21 below)
  7: rings 'bell'        8: back space           9: horizontal tab
 10: linefeed           11: reverse line feed   12: clear text window
 13: carriage return    14: page mode on        15: page mode off
 16: clear graphics window
 20: restore default colours
 21: disable screen display (this means that the following commands are
     interpreted, but no action is taken); re-enabled by 6 above
 26: restore text and graphics windows to full screen
 30: return text cursor to home position

%GRWAIT

 CALL GRWAIT

 Purpose: waits for vertical synchronisation of the video display to help in
          making flicker free animation

 Parameters:  none

 Example:
C         animate a moving character across the screen in steps of 4
C         start from 0 in X
      CALL GRMOVE(0,100)
C         now loop over steps
      DO 20 IX=4,1276,4
C         set colour to background
        CALL GRGCOL(0,0)
C         wait for framescan
        CALL GRWAIT
C         erase old character (A)
        CALL GRVDU(65)
C         move to new point
        CALL GRMOVE(IX,100)
C         set colour
        CALL GRGCOL(0,7)
C         plot new character (A)
        CALL GRVDU(65)
   20 CONTINUE

 Comments: the video frame is displayed 50 times per second. This routine
           allows synchronisation with the frame scan by waiting until the
           last line has been drawn at the bottom of the screen.
           The time until the next frame starts (during which the screen can
           be invisibly updated) depends on the screen mode; 
           it is ~3.5 msec for standard modes (0-17),
           ~0.8 msec for multi-sync modes (18-21),
           and ~1.4 msec for VGA modes (25-28)

%GRWBIG

 CALL GRWBIG(IX,IY,TEXT,ISCALE)

 Purpose: prints enlarged characters in the current graphics colour;
          it will be truncated if it goes outside the graphics window
          or the edge of the screen. 

 Parameters:

    IX,IY  - INTEGER graphics x,y coordinates of the bottom left of the
                     first character to print

    TEXT   - CHARACTER string of any length to be printed

    ISCALE - INTEGER magnification factor between 1 and 20

 Example:
C         set graphics colour to 1
      CALL GRGCOL(0,1)
C         print big red footnote
      CALL GRWBIG(0,0,'Press Spacebar',3)

 Comments: the characters are just magnifications of the standard set; they
           are not very pretty when large; better is to use outline fonts.
           This routine works in graphics mode, hence the colours and
           windows used are the graphics ones.

%GRWOG

 CALL GRWOG(IX,IY,TEXT)

 Purpose: prints text anywhere in the graphics screen in the current
          graphics colour; any parts outside the graphics window or screen
          will be truncated

 Parameters:

    IX,IY - INTEGER graphics x,y coordinates of the top left of the first
                  character to print

    TEXT  - CHARACTER of any length containing the text to print 
 
 Example:
C           print message in current graphics colour
      CALL GRWOG(0,1023,'this is the current colour')

 Comments:  This should not be used for printing text in a RISC-OS window,
            use WPTEXT with the same parameters

%GRWOT

 CALL GRWOT(IX,IY,TEXT)

 Purpose: prints text at any tab position in the text window in the current
          text colour. Text will wrap round horizontally or cause the text
          window to scroll vertically if it is too long

 Parameters:

    IX   - INTEGER column within the text window to start printing
    IY   - INTEGER row within the text window to start printing

    TEXT - CHARACTER of any length containing the text to print 
 
 Example:
C           print message in current text colour
      CALL GRWOT(0,0,'this is the current colour')

 Comments: 1. See GRWOG for printing in graphics mode
           2. If (IX,IY) is outside the text window, printing will start at
              the top left.
           3. This should not be used for printing text in a RISC-OS window,
              use WPTEXT
