      SpriteOps a FORTRAN SpriteOps subroutine library.

%SPADD

 LOGICAL FUNCTION SPADD(ISTOR,SNAM1,SNAM2,IBELO)

 Purpose: Adds sprite 'SNAM2' to 'SNAM1' in area ISTOR, either below it, or
          on its right. 'SNAM2' is then deleted.

 Parameters:

   ISTOR - INTEGER sprite area array,
                   or: 0 for system sprites

   SNAM1 - CHARACTER sprite name of sprite to be added to
           may be INTEGER address for a sprite in a user area

   SNAM2 - CHARACTER sprite name of sprite to add to SNAME1

   IBELO - LOGICAL defines where the sprite is to be added
                   .TRUE.,  'SNAM2' is added below 'SNAM1'.
                   .FALSE., 'SNAM2' is added to the right of 'SNAM1'.

 Result: .TRUE. if sprites are added correctly, .FALSE. otherwise.

 Comment: 'SNAM2' must be defined by its CHARACTER name, not by its address.
          This function may change the addresses of sprites in ISTOR.
          The two sprites must be of the same width (or height) if IBELO
          is .TRUE. (.FALSE.)
          Uses Sprite_Op 35, PRM2 p 419, PRM3 p 1-786

%SPADDR

 LOGICAL FUNCTION SPADDR(ISTOR,SNAME,ISADD)

 Purpose: Finds the address of sprite 'SNAME' in user area ISTOR.
          This address may then be used for fast access to the sprite

 Parameters:

   ISTOR - INTEGER user sprite area array where the sprite is stored

   SNAME - CHARACTER name of sprite to find

   ISADD - INTEGER returned sprite address

 Result: .TRUE. if sprite found OK, .FALSE. otherwise.

 Comment: The address found may be corrupted by any command which alters the
          definitions of any sprites in the area.
          Uses the 'Select sprite' operation, so that it could then be
          plotted with GRPLOT(237,IX,IY) etc. This is not generally useful.
          Uses Sprite_Op 24, PRM2 p 406, PRM3 p 1-775

%SPALOD

 LOGICAL FUNCTION SPALOD(ISTOR,FILENM)

 Purpose: Loads sprite area ISTOR from file 'FILENM'.

 Parameters:

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area

   FILENM - CHARACTER name of file containing sprite area

 Result: .TRUE. if sprite area loaded correctly, .FALSE. otherwise.

 Comment: A user area must be initialised with function SPINIT before
          trying to load a file into it.
          Uses Sprite_Op 10, PRM2 p 399, PRM3 p 1-768

%SPAMRG

 LOGICAL FUNCTION SPAMRG(ISTOR,FILENM)

 Purpose: Merges the sprite area from file 'FILENM' into sprite area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array to be merged into.
                   or: 0 for system area.

   FILENM - CHARACTER name of file containing sprite area to merge

 Result: .TRUE. if sprite areas merged correctly, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          ISTOR must be big enough to contain all the new sprites. It is
          only after they are loaded that those with duplicate names are
          eliminated.
          Uses Sprite_Op 11, PRM2 p 400, PRM3 p 1-769

%SPASAV

 LOGICAL FUNCTION SPASAV(ISTOR,FILENM)

 Purpose: Saves the sprite area ISTOR to file 'FILENM'

 Parameters:

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area.

   FILENM - CHARACTER name of file to contain the sprite area

 Result: .TRUE. if sprite area saved correctly, .FALSE. otherwise.

 Comment: Only the active area is saved, any unused space is ignored
          Uses Sprite_Op 12, PRM2 p 401, PRM3 p 1-751

%SPASIZ

 LOGICAL FUNCTION SPASIZ(ISTOR,NSPR,ISIZE,JFREE)

 Purpose: Gets characteristics of a sprite area

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area.

   NSPR  - INTEGER returned number of stored sprites

   ISIZE - INTEGER returned size of area (in bytes)

   JFREE - INTEGER returned free space in area (in bytes)

 Result: .TRUE. if values are found correctly,
         .FALSE. if sprite area is corrupted.

 Comment: Use SPASYS to create a system area.
          Uses Sprite_Op 8, PRM2 p 397, PRM3 p 1-766

%SPASYS

 LOGICAL FUNCTION SPASYS(NK)

 Purpose: Changes the size of the system sprite area

   NK     - INTEGER number of kilobytes to increase the system sprite
                    area

 Result: .TRUE. if area size changed, .FALSE. otherwise.

 Comment: Uses OS_ChangeDynamicArea, PRM2 p 797, PRM3 p 1-377

%SPCHAR

 LOGICAL FUNCTION SPCHAR(ICHAR,IX,IY,SCALE)

 Purpose: Plots the ASCII character ICHAR scaled at IX,IY using the current
          graphics foreground colour and action (see graphics library GRGCOL)

 Parameters:

     ICHAR  - INTEGER ASCII value of the character to be drawn

     IX,IY  - INTEGER OS coordinates of lower left corner of character

     SCALE  - COMPLEX (SCX,SCY) where the character is scaled by SCX in x
                       and SCY in y before being plotted

 Result: .TRUE. if character plotted OK, .FALSE. otherwise.

 Comment: This plots the character using the default system font.
          Use GRWOG in the graphics library if no scaling is needed.
          Use GRBIG in the graphics library to print enlarged text.
          Uses Sprite_Op 51, PRM2 p 434, PRM3 p 1-802

%SPCMSK

 LOGICAL FUNCTION SPCMSK(ISTOR,SNAME)

 Purpose: Creates a mask for sprite 'SNAME' in ISTOR with all pixels solid

 Parameters:

   ISTOR - INTEGER sprite area array,
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite requiring a mask
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if mask created OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 29, PRM2 p 412, PRM3 p 1-780

%SPCOPY

 LOGICAL FUNCTION SPCOPY(ISTOR,SNAME,SNNEW)

 Purpose:  Copies sprite 'SNAME' in ISTOR to 'SNNEW' also in ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be copied
           may be INTEGER address for a sprite in a user area

   SNNEW - CHARACTER name of new sprite (copied from SNAME)

 Result: .TRUE. if copy created OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 27, PRM2 p 409, PRM3 p 1-778

%SPCPAL

 LOGICAL FUNCTION SPCPAL(ISTOR,SNAME)

 Purpose: Creates the palette for sprite 'SNAME' in ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array,
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite requiring a palette
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if palette created OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 37, PRM3 p 1-790

%SPDEFC

 LOGICAL FUNCTION SPDEFC(ISTOR,SNAME,IPAL)

 Purpose: Defines sprite 'SNAME' as the rectangle from old to the current
          graphics cursor positions (inclusive) and stores it in area ISTOR.
          The current palette is saved if IPAL is .TRUE.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is to be stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be defined

   IPAL  - LOGICAL .TRUE. if the palette is also to be saved with the sprite

 Result: .TRUE. if sprite stored OK, .FALSE. otherwise.

 Comment: If a sprite of the same name already exists, it is overwritten.
          This function may change the addresses of sprites in ISTOR.
          The 'old' and 'current' graphics cursor positions are the last two
          coordinate pairs used in graphics commands. For Example:
C         draw a diagonal line in a box size (200,100)
      CALL GRLINE(IX1,IY1,IX1+200,IY1+100)
C         this has defined two graphics points
C         save the rectangle with these points as opposite corners
C         as sprite 'MYSPRT' (without palette info.). The sprite is just
C         a diagonal line
      CALL SPDEFC(ISTOR,'MYSPRT',.FALSE.)
C
          Uses Sprite_Op 14, PRM2 p 403, PRM3 p 1-774

%SPDEFR

 LOGICAL FUNCTION SPDEFR(ISTOR,SNAME,IPAL,IX1,IY1,IX2,IY2)

 Purpose: Defines sprite 'SNAME' as the rectangle from (IX1,IY1)
          to (IX2,IY2) inclusive, and stores it in area ISTOR.
          The current palette is saved if IPAL is .TRUE.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is to be stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be stored

   IPAL  - LOGICAL .TRUE. if the palette is also to be saved with the sprite

   IX1,IY1 - INTEGER OS coordinates of the bottom left corner of the sprite

   IX2,IY2 - INTEGER OS coordinates of the top right corner of the sprite

 Result: .TRUE. if sprite stored OK, .FALSE. otherwise.

 Comment: If a sprite of the same name already exists, it is overwritten.
          This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 16, PRM2 p 405, PRM3 p 1-774

%SPDELC

 LOGICAL FUNCTION SPDELC(ISTOR,SNAME,ICOLM)

 Purpose: Deletes the column of pixels at ICOLM from sprite 'SNAME' in area
          ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have a column removed
           may be INTEGER address for a sprite in a user area

   ICOLM - INTEGER pixel column for removal (numbered from 0 at the left)

 Result: .TRUE. if column is removed OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 46, PRM2 p 429, PRM3 p 1-797

%SPDELM

 LOGICAL FUNCTION SPDELM(ISTOR,SNAME)

 Purpose: Deletes the mask for sprite 'SNAME' in area ISTOR.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have its mask deleted
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if sprite mask is deleted OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 30, PRM2 p 413, PRM3 p 1-781

%SPDELP

 LOGICAL FUNCTION SPDELP(ISTOR,SNAME)

 Purpose: Deletes the palette for sprite 'SNAME' in area ISTOR.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have its palette deleted
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if sprite palette is deleted OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 37, PRM3 p 1-790

%SPDELR

 LOGICAL FUNCTION SPDELR(ISTOR,SNAME,IROW)

 Purpose: Deletes row at IROW from sprite 'SNAME' in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have a row deleted
           may be INTEGER address for a sprite in a user area

   IROW  - INTEGER row to delete (numbered from 0 at the bottom)

 Result: .TRUE. if row is deleted OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 32, PRM2 p 415, PRM3 p 1-783

%SPDELS

 LOGICAL FUNCTION SPDELS(ISTOR,SNAME)

 Purpose: Deletes sprite 'SNAME' from area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be deleted
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if sprite is deleted OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 25, PRM2 p 407, PRM3 p 1-776

%SPERR

 SUBROUTINE SPERR(IERR,ERRTXT)

 Purpose: returns the error number and message after a SpriteOp library
          member has returned .FALSE. (indicating an error)

 Parameters:

   IERR  - INTEGER returned error number. This is zero if there is no error.

   ERRTXT- CHARACTER returned error message, padded with blanks on the right.
           If the length is too short, the message is truncated.

%SPFLPX

 LOGICAL FUNCTION SPFLPX(ISTOR,SNAME)

 Purpose: Flips sprite 'SNAME' in ISTOR about its X-axis.

 Parameters:

   SNAME - CHARACTER name of sprite to be flipped
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if sprite is flipped OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 33, PRM2 p 416, PRM3 p 1-784

%SPFLPY

 LOGICAL FUNCTION SPFLPY(ISTOR,SNAME)

 Purpose: Flips sprite 'SNAME' in ISTOR about its Y-axis.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be flipped
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if sprite is flipped OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 47, PRM2 p 430, PRM3 p 1-798

%SPINFO

 LOGICAL FUNCTION SPINFO(ISTOR,SNAME,IWIDTH,IHITE,MASK,MODE,LPAL)

 Purpose: Gets the characteristics of the sprite 'SNAME' in area ISTOR.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite
           may be INTEGER address for a sprite in a user area

   IWIDTH- INTEGER returned width of sprite in pixels

   IHITE - INTEGER returned height of sprite in pixels

   MASK  - LOGICAL returned: .TRUE. if the sprite has a mask,
                             .FALSE. if the sprite has no mask

   MODE  - INTEGER returned screen mode when the sprite was created

   LPAL  - INTEGER returned length of the stored palette in BYTES
                            or =0 if none

 Result: .TRUE. if characteristics of sprite were found OK,
         .FALSE. otherwise.

 Comment: Uses Sprite_Op 40, PRM2 p 423, PRM3 p 1-791
           and Sprite_Op 37, PRM3 p 1-790


%SPINIT

 LOGICAL FUNCTION SPINIT(LEN,ISTOR)

 Purpose: Initialises ISTOR as a sprite area

 Parameters:

   LEN   - INTEGER dimension (in words) of ISTOR
                   or =0 to reinitialise the system sprite area

   ISTOR - INTEGER array to be used as a sprite area.
                   unused if the system sprite area is to be cleared

 Result: .TRUE. if the area is initialised OK, .FALSE. otherwise.

 Comment: Initialising an area removes any existing sprites.
          Uses Sprite_Op 09, PRM2 p 398, PRM3 p 1-767

%SPINSC

 LOGICAL FUNCTION SPINSC(ISTOR,SNAME,ICOLM)

 Purpose: Inserts a column of colour zero at position ICOLM into sprite
          'SNAME' in area ISTOR. The old column ICOLM and those to the right
          of it are all shifted right by one column.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have a column inserted
           may be INTEGER address for a sprite in a user area

   ICOLM - INTEGER column number where the new column is inserted
                   (numbered from 0 at the left)

 Result: .TRUE. if sprite is altered OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 45, PRM2 p 428, PRM3 p 1-796

%SPINSR

 LOGICAL FUNCTION SPINSR(ISTOR,SNAME,IROW)

 Purpose: Inserts a row of colour zero at position IROW into sprite 'SNAME'
          in area ISTOR. The old row IROW and those above it are all shifted
          up one row.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to have a row inserted
           may be INTEGER address for a sprite in a user area

   IROW  - INTEGER row number where new row is inserted,
                   (numbered from 0 at the bottom)

 Result: .TRUE. if sprite is altered OK, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 31, PRM2 p 414, PRM3 p 1-782

%SPLEFT

 LOGICAL FUNCTION SPLEFT(ISTOR,SNAME)

 Purpose: Shifts the sprite 'SNAME' left in area ISTOR until there are no
          unused columns on the left, then removes any unused words from the
          right of the sprite.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be truncated
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if able to truncate the sprite, .FALSE. otherwise.

 Comment: This function may change the addresses of sprites in ISTOR.
          Uses Sprite_Op 54, PRM2 p 439, PRM3 p 1-805

%SPNAME

 LOGICAL FUNCTION SPNAME(ISTOR,ISPRT,SNAME)

 Purpose: Finds the name of sprite ISPRT in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array
                   or: 0 for system area.

   ISPRT - INTEGER number of sprite in the store (starting with 1)

   SNAME - CHARACTER returned name of sprite. Unused space in SNAME is filled
           with blanks, or the name is truncated if SNAME is too small. For
           safety, make it at least 12 characters long.

 Result: .TRUE. if sprite name is returned OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 13, PRM2 p 402, PRM3 p 1-771

%SPPL

 LOGICAL FUNCTION SPPL  (ISTOR,SNAME,IACT)

 Purpose: Plots sprite 'SNAME' from area ISTOR with its bottom left corner at
          the graphics cursor;
          i.e. the last position used in any graphics command.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be plotted
           may be INTEGER address for a sprite in a user area

   IACT  - INTEGER plot action. See SPPLXY for details

 Result: .TRUE. if sprite plotted OK, .FALSE. otherwise.

 Comment: plotting will not spread outside any graphics window defined with
          GRGWIN
          Uses Sprite_Op 28, PRM2 p 410, PRM3 p 1-779

%SPPLAA

 LOGICAL FUNCTION SPPLAA(ISTOR,SNAME,IX,IY,SCALE,IPXTR)

 Purpose: Plots scaled sprite 'SNAME' from area ISTOR at (IX,IY)
          Anti-aliasing is performed on the sprite as it is scaled, and the
          colours of the pixels must lie on a linear grey scale in a 16 colour
          mode.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area.
   SNAME - CHARACTER name of sprite to be plotted
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGER OS coordinates to plot the sprite

   SCALE - COMPLEX (SCX,SCY) scaling factors for the size of the plotted
                   sprite in x and y
           or
           INTEGER 0 to keep the natural sprite scale

   IPXTR - CHARACTER string in which the value of each character defines the
                     colour corresponding to its position in the string.
                     This can be used to make a linear gradation of colours.
           or
           INTEGER 0 meaning the natural colours are used

 Result: .TRUE. if sprite plotted OK, .FALSE. otherwise.

 Comment: This can be quite slow because of the anti-alias calculation
          so use SPPLSC if you don't need anti-aliasing,
          or SPPLXY if you don't need scaling either.
          Uses Sprite_Op 53, PRM2 p 437, PRM3 p 1-804

%SPPLSC

 LOGICAL FUNCTION SPPLSC(ISTOR,SNAME,IX,IY,IACT,SCALE,IPXTR)

 Purpose: Plots scaled sprite 'SNAME' from area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be plotted
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGER OS coordinates to plot the sprite

   IACT  - INTEGER plot action. See SPPLXY for details

   SCALE - COMPLEX (SCX,SCY) scaling factors for the size of the plotted
                   sprite in x and y
           or
           INTEGER 0 to keep the natural sprite scale

   IPXTR - INTEGER 0 meaning the natural colours are used
              or
           CHARACTER string in which the value of each character defines the
                     colour corresponding to its position in the string.
                     Not used for more than 256 colours

 Result: .TRUE. if sprite plotted OK, .FALSE. otherwise.

 Comment: Use SPPLXY if you need neither scaling nor colour translation.
          Uses Sprite_Op 52, PRM2 p 435, PRM3 p 1-803

%SPPLTR

 LOGICAL FUNCTION SPPLTR(ISTOR,SNAME,IFLAG,ISRCE,IACT,TRANS,IPXTR)

 Purpose: Plots sprite  'SNAME' from area ISTOR according to a general linear
          transformation (not available in RISC-OS 2)

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be plotted
           may be INTEGER address for a sprite in a user area

   IFLAG - INTEGER flag determining the transform to be used
                 =0: use all of sprite and linear transform
                 =1: use all of sprite and final parallelogram
                 =2: use ISRCE of sprite and linear transform
                 =3: use ISRCE of sprite and final parallelogram

   ISRCE - INTEGER array defining which piece of the sprite to plot
                   Used only if IFLAG > 1
                   1: minimum x-pixel
                   2: maximum y-pixel
                   3: maximum x-pixel
                   4: minimum y-pixel
                   If IFLAG < 2 then these take the default values
                     (0, height, width, 0)

   IACT  - INTEGER plot action. See SPPLXY for details

   TRANS - REAL*4 array of linear transformation matrix (IFLAG = 0 or 2)
                   XPLOT = IX*TRANS(1) + IY*TRANS(3) + TRANS(5)
                   YPLOT = IX*TRANS(2) + IY*TRANS(4) + TRANS(6)
                  TRANS(5 & 6) are in OS units, the others dimensionless.
             or   array of final parallelogram vertices (IFLAG = 1 or 3)
                  (X1,Y1, X2,Y2, X3,Y3, X4,Y4) in OS units.
                  For a normal transformation these are numbered clockwise
                  starting from the top left

   IPXTR - INTEGER 0 meaning the natural colours are used
              or
           CHARACTER string in which the value of each character defines the
                     colour corresponding to its position in the string.

 Result: .TRUE. if sprite plotted OK, .FALSE. otherwise.

 Comment: plotting will not spread outside any graphics window defined with
          GRGWIN
          Uses Sprite_Op 56, PRM3 p 1-806

%SPPLXY

 LOGICAL FUNCTION SPPLXY(ISTOR,SNAME,IX,IY,IACT)

 Purpose: Plots sprite 'SNAME' from area ISTOR at coordinates (IX,IY)

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be plotted
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS coordinates in OS units defining where the bottom left
                    corner of the sprite is to be placed.

   IACT  - INTEGER plot action. Values are:
                   0: overwrite colour on screen
                   1: 'OR' with colours on screen
                   2: 'AND' with colours on screen
                   3: 'EOR' with colours on screen
                   4: invert colour on screen
                   5: do nothing
                   6: 'AND' with the colour on screen the 'NOT' of the sprite
                   7: 'OR' with the colour on screen the 'NOT' of the sprite
                   8: plot the masked sprite

 Result: .TRUE. if sprite plotted OK, .FALSE. otherwise.

 Comment: plotting will not spread outside any graphics window defined with
          GRGWIN
          Uses Sprite_Op 34, PRM2 p 417, PRM3 p 1-785

%SPPM

 LOGICAL FUNCTION SPPM(ISTOR,SNAME)

 Purpose: Plots the mask of sprite 'SNAME' in area ISTOR with its bottom left
          corner at the graphics cursor;
          i.e. the last position used in any graphics command.
          Solid bits are plotted in the graphics background colour, clear
          bits are ignored. The plot 'Action' is taken from the last call to
          GRGCOL (or is zero by default).

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite for which the mask is to be plotted
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if mask plotted OK, .FALSE. otherwise.

 Comment: plotting will not spread outside any graphics window defined with
          GRGWIN
          Uses Sprite_Op 48, PRM2 p 431, PRM3 p 1-799

%SPPMSC

 LOGICAL FUNCTION SPPMSC(ISTOR,SNAME,IX,IY,SCALE)

 Purpose: Plots the scaled mask of sprite 'SNAME' in area ISTOR.
          Solid bits are plotted in the graphics background colour, clear
          bits are ignored. The plot 'Action' is taken from the last call to
          GRGCOL (or is zero by default).

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite of which th mask is to be plotted
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS coordinates in OS units defining where the bottom left
                    corner of the mask is to be placed.

   SCALE - COMPLEX (SCX,SCY) scaling factors for the size of the plotted
                   sprite mask in x and y
           or
           Use FUNCTION SPPMXY if you don't need scaling.

 Result: .TRUE. if mask plotted OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 50, PRM2 p 433, PRM3 p 1-801

%SPPMXY

 LOGICAL FUNCTION SPPMXY(ISTOR,SNAME,IX,IY)

 Purpose: Plots the mask of sprite 'SNAME' in area ISTOR at (IX,IY).
          Solid bits are plotted in the graphics background colour, clear
          bits are ignored. The plot 'Action' is taken from the last call to
          GRGCOL (or is zero by default).

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite for which the mask is to be plotted
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS coordinates in OS units defining where the bottom left
                    corner of the mask is to be placed.

 Result: .TRUE. if mask plotted OK, .FALSE. otherwise.

 Comment: plotting will not spread outside any graphics window defined with
          GRGWIN
          Uses Sprite_Op 49, PRM2 p 432, PRM3 p 1-800

%SPRENA

 LOGICAL FUNCTION SPRENA(ISR,SNAME,SNNEW)

 Purpose: Renames sprite 'SNAME' in area ISTOR as 'SNNEW'

 Parameters:

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area.

   SNAME - CHARACTER name of sprite to be renamed
           may be INTEGER address for a sprite in a user area

   SNNEW - CHARACTER new name of sprite

 Result: .TRUE. if sprite renamed OK, .FALSE. otherwise.

 Comment: The address of the sprite will remain unchanged by this function
          It is an error to rename to a name which already exists.
          Uses Sprite_Op 26, PRM2 p 408, PRM3 p 1-777

%SPRESV

 LOGICAL FUNCTION SPRESV(ISTOR,SNAME,IPAL,IWIDTH,IHITE,MODE)

 Purpose: Reserves space and creates a blank sprite 'SNAME' in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array.
                   or: 0 for system area.

   SNAME - CHARACTER name of blank sprite to be created

   IPAL  - LOGICAL .TRUE. if the palette is to be saved, .FALSE. otherwise

   IWIDTH- INTEGER width of the sprite in pixels

   IHITE - INTEGER height of the sprite in pixels

   MODE  - INTEGER screen mode for the sprite or -1 for current mode
                  (or mode specifier in RISC-OS 3.5 )

 Result: .TRUE. if sprite is created OK, .FALSE. otherwise.

 Comment: 1) SNAME can not be an address, even in a user area.
          2) If you want the sprite to have a mask, use SPCMSK afterwards
          3) A mode specifier is used by RISC-OS 3.5 (and greater) to define
             the way pixels are stored. It may be:
             a) an ordinary MODE number (0-255)
             b) a pointer to a Mode selector structure (even number >255)
              (see PRM 3 p 5-80)
             c) a sprite mode word (odd number >255)
              (see PRM 3 p 5-87)
             Use CALL GRGETM(MODE) to get the current mode or mode selector
          4) Uses Sprite_Op 15, PRM2 p 404, PRM3 p 1-773, p 5-93

%SPRMSK

 LOGICAL FUNCTION SPRMSK(ISTOR,SNAME,IX,IY,MASK)

 Purpose: Reads the state of the mask pixel (IX,IY) of sprite 'SNAME'
          in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite whose mask is to be tested
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGER pixel position to be tested in the mask
                    measured from (0,0) at the bottom left

   MASK  - LOGICAL returned .TRUE. if the mask is solid,
                            .FALSE. if it is transparent

 Result: .TRUE. if mask state is obtained OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 43, PRM2 p 426, PRM3 p 1-794

%SPRPIX

 LOGICAL FUNCTION SPRPIX(ISTOR,SNAME,IX,IY,ICOLR,ITINT)

 Purpose: Reads the colour of the pixel (IX,IY) of sprite 'SNAME'
          in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite for checking
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS position of the pixel
                    measured from (0,0) at the bottom left

   ICOLR - INTEGER returned colour of the pixel: 0 to 63 in 256 colour modes,
                   0 to #colours-1 for 2, 4 and 16 colour modes

   ITINT - INTEGER returned tint of the pixel for 256 colour modes
                   or zero for 2, 4, and 16 colour modes

 Result: .TRUE. if colour is obtained OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 41, PRM2 p 424, PRM3 p 1-792

%SPSETP

 LOGICAL FUNCTION SPSETP(ISTOR,SNAME,IPOIN,IX,IY,SCALE,IPXTR)

 Purpose: Sets the pointer shape from sprite 'SNAME' in area ISTOR


 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be used for a pointer
           may be INTEGER address for a sprite in a user area

   IPOIN - INTEGER pointer number to use
                   currently pointers in the range 1 to 4 are allowed
               Add 16 if you want to show the pointer, but not remake it
               Add 32 if you want to leave the palette as currently set
               Add 64 if you want to remake the pointer, but not show it

   IX,IY - INTEGER giving the offset to the active point from the top left
                   corner of the sprite. Note, this is not from the origin of
                   the sprite, but where the point of the normal arrow is.
                   Both IX and IY are positive or zero.

   SCALE - COMPLEX (SCX,SCY) scaling factors in x and y from the size
                    of the sprite to the plotted pointer
           or
           INTEGER 0 to keep the natural sprite scale

   IPXTR - INTEGER 0 meaning the natural colours are used
              or
           CHARACTER string in which the value of each character defines the
                     colour corresponding to its position in the string.
                     E.g. in a 4-colour mode
        CHARACTER*4 IXPTR
        IXPTR=CHAR(0)//CHAR(2)//CHAR(1)//CHAR(3)
                     would invert colours 1 and 2 in the sprite

 Result: .TRUE. if pointer created OK, .FALSE. otherwise.

 Comments:  1) you must use a 4-colour mode for a pointer, otherwise you
          will see a blank pointer. Mode 8 works well with 32x16 pixels,
          making it square and the maximum size.
            2) colour 0 is transparent, and colour 2 does not work in
          high-resolution mono modes.
            3) uses Sprite_Op 36, PRM2 p 421, PRM3 p 1-788

%SPSLOD
 LOGICAL FUNCTION SPSLOD(FILENM)

 Purpose: loads graphics screen from a file, changing mode and palette
          to that of the file. 

 Parameters:

    FILENM - CHARACTER filename from which to load the screen

 Result: .TRUE. if file read OK; .FALSE. if failed, call SPERR to
         find error


 Comments: *** Do not use in RISOS 3.5 or greater ***           
           If a graphics window is in effect, only that area will be filled.
           Equivalent to OSCLI('SCREENLOAD '//FILENAM)
           Uses SpriteOp #3 (PRM p 396(2))

%SPSSAV

 LOGICAL FUNCTION SPSSAV(FILENM,IPAL)

 Purpose: saves graphics screen to a file, with or without palette

 Parameters:

    FILENM - CHARACTER filename to which to save the screen.

    IPAL - INTEGER when =0 palette is not saved, =1 it is

 Result: .TRUE. if file created OK; .FALSE. if failed, call SPERR to
         find error

 Comments: *** Do not use in RISOS 3.5 or greater ***           
           If a graphics window is in effect, only that area will be saved.
           Equivalent to OSCLI('SCREENSAVE '//FILENAM) if palette saved
           Uses SpriteOp #2 (PRM p 395(2))

%SPWMSK

 LOGICAL FUNCTION SPWMSK(ISTOR,SNAME,IX,IY,MASK)

 Purpose: Sets the pixel at (IX,IY) in the mask of sprite 'SNAME'
          in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite for which the mask is to be changed
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS position of the pixel to set in the mask
                    measured from (0,0) at the bottom left

   MASK  - LOGICAL .TRUE. to set the mask pixel solid,
                   .FALSE. to set it transparent

 Result: .TRUE. if mask pixel set OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 44, PRM2 p 427, PRM3 p 1-795

%SPWPIX

 LOGICAL FUNCTION SPWPIX(ISTOR,SNAME,IX,IY,ICOLR,ITINT)

 Purpose: Sets the colour of the pixel at (IX,IY) of the sprite 'SNAME'
          in area ISTOR

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be changed
           may be INTEGER address for a sprite in a user area

   IX,IY - INTEGERS position of the pixel to set;
                    measured from (0,0) at the bottom left

   ICOLR - INTEGER new colour for the pixel: 0 to 63 in 256 colour modes,
                   0 to #colours-1 for 2, 4 and 16 colour modes

   ITINT - INTEGER new tint for the pixel
                   This should be 0, 64, 128 or 192 for 256 colour modes
                   For other modes it is a dummy.

 Result: .TRUE. if pixel set OK, .FALSE. otherwise.

 Comment: Uses Sprite_Op 42, PRM2 p 425, PRM3 p 1-793

%SP2MSK

 LOGICAL FUNCTION SP2MSK(ISTOR,SNAME)

 Purpose: Switches VDU output to mask of sprite 'SNAME' in area ISTOR
          This means that all following graphics commands will write directly
          to the sprite's mask until the function SP2SCR is called.
          The origin of the graphics coordinates is the bottom left corner of
          the sprite.
          N.B. the only colours allowed are:
            0: making a transparent pixel
      and   1: for 2 colour modes
       or   3: for 4 colour modes
       or  15: for 16 colour modes
       or  63: with tint 192 for 256 colour modes

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite whose mask is to be written to
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if VDU output switched OK, .FALSE. otherwise.

 Comment: In a wimp program you should not call the wimp poll with the VDU
          redirected to a sprite mask.
          Uses Sprite_Op 61, PRM2 p 442, PRM3 p 1-813

%SP2SCR

 LOGICAL FUNCTION SP2SCR()

 Purpose: Resets the VDU output back to the screen
          This is used to restore the status quo after using
          functions SP2MSK or SP2SPR

 Result: .TRUE. if VDU output restored OK, .FALSE. otherwise.

%SP2SPR

 LOGICAL FUNCTION SP2SPR(ISTOR,SNAME)

 Purpose: Switches VDU output to sprite 'SNAME' in area ISTOR
          This means that all following graphics commands will write directly
          to the sprite until the function SP2SCR is called.
          The origin of the graphics coordinates is the bottom left corner of
          the sprite.

 Parameters:

   ISTOR - INTEGER sprite area array where the sprite is stored
                   or: 0 for system area

   SNAME - CHARACTER name of sprite to be written to
           may be INTEGER address for a sprite in a user area

 Result: .TRUE. if VDU output switched OK, .FALSE. otherwise.

 Comment: In a wimp program you should not call the wimp poll with the VDU
          redirected to a sprite.
          Uses Sprite_Op 60, PRM2 p 440, PRM3 p 1-811
