home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / fortran77_210 / library / docs / spriteop < prev    next >
Encoding:
Text File  |  1994-01-30  |  13.0 KB  |  303 lines
  1.  
  2.       SpriteOps a FORTRAN SpriteOps subroutine library.   18 Nov 1991
  3.  
  4.   ************************************************************************
  5.                     C O P Y R I G H T    N O T I C E
  6.  
  7.                      Copyright D.J & K.M. Crennell,
  8.               P.O. Box 64, Didcot, Oxon, OX11 0TH.
  9.  
  10.  This software is in the Public Domain and may not be sold or included in any
  11.  program that will be sold, without written permission from the authors.
  12.  
  13.  The authors must be given credit in any publications using this software.
  14.  
  15.  The software may be copied and distributed as long as no changes are made
  16.  and this copyright notice is included. Please send any suggested
  17.  improvements to the authors. 
  18.  
  19.  In no circumstances shall the authors be liable for any damage, loss of
  20.  profits, or any indirect or consequential loss arising out of the use of
  21.  this software or inability to use this software, even if they have been
  22.  advised of the possibility of such loss.
  23.  
  24.  The authors do their best to ensure that this library is distributed virus
  25.  free.
  26.   ************************************************************************
  27.  
  28.      The source of this library is assembler, and is not included.
  29.      The library is %.lib.SpriteOp
  30.  
  31. Notes:
  32.   1. These emulate the OS_SpriteOp n commands (SWI &2E), which all have
  33. different numbers of arguments, so a separate routine is included for each
  34. one e.g. for OS_SpriteOp 9 use SPOP09 and OS_SpriteOp 24 use SPOP24
  35.  
  36.   2. The routines may be used as LOGICAL FUNCTIONS, in which case they
  37. return .TRUE. if there is an error, .FALSE. if no error. They can also be
  38. called as SUBROUTINEs when errors can be detected by including a special
  39. return in the subroutine call of the form: *label
  40.  (e.g. CALL SPOP02('FILE',0,*990) will GOTO 990 on an error)
  41.  Details of the error can be found by calling subroutine SPOPER.
  42.  
  43.   3. All variables are INTEGERS, except for sprite and file names which are 
  44. CHARACTER. E.g. 'SNAME' in this document.
  45.         
  46.   4. Sprites are stored either in a user area, or in the system area. The
  47. routines decide which one to use by looking at the contents of the first
  48. word of the sprite area ISTOR:
  49.  =0, system area;
  50.  >0, user area (when it will add 256 to the SpriteOp number).
  51.   Sprites in the system area must be called by name (CHARACTER).
  52.   Sprites in a user area may be called by name (CHARACTER) or address
  53. (INTEGER) when the routine adds another 256 (512 in all) to the Op code.
  54. (See page 383 P.R.M.).
  55. The sprite addresses are found using SpriteOps 14, 16 & 24.
  56.  
  57.                   ******************************
  58.  
  59.        SPOP02(FILENM,IPAL)  (page 395 P.R.M.)
  60. Screen save to file 'FILENM' with the palette if IPAL =1, or without if
  61. IPAL =0
  62.  
  63.        SPOP03(FILENM)   (page 396 P.R.M.)
  64. Screen load from file 'FILENM', changing mode and palette to that of the
  65. file.
  66.  
  67.        SPOP08(ISTOR,ISPSIZ,NSPRIT,ISPR1,IFREE)  (page 397 P.R.M.)
  68.  Finds the characteristics of the sprite area ISTOR. Results are:
  69.     ISPSIZ: size of sprite area (bytes)
  70.     NSPRIT: number of sprites
  71.     ISPR1 : offset to first sprite (bytes)
  72.     IFREE : offset to first free area
  73.  
  74.        SPOP09(ISTOR)  (page 398 P.R.M.)
  75.  Initialises the array ISTOR as a sprite area. ISTOR must be a large enough
  76. array with word 1 containing the area size in bytes, and word 3 equal to 16
  77. (start of sprite storage).
  78.  
  79.        SPOP10(ISTOR,FILENM)  (page 399 P.R.M.)
  80.  Loads the sprite area ISTOR from the file 'FILENM'
  81.  
  82.        SPOP11(ISTOR,FILENM)  (page 400 P.R.M.)
  83.  Merges the sprite area from the file 'FILENM' onto the sprite area in ISTOR.
  84.  
  85.        SPOP12(ISTOR,FILENM)  (page 401 P.R.M.)
  86.  Saves the sprite area ISTOR to the file 'FILENM'
  87.  
  88.        SPOP13(ISTOR,ISPRIT,SNAME,LENGTH)  (page 402 P.R.M.)
  89.  Finds the 'SNAME' of the ISPRITth sprite in the area ISTOR. The character
  90. string returned has length LENGTH.
  91.  
  92.        SPOP14(ISTOR,SNAME,IPAL,ISADD)  (page 403 P.R.M.)
  93.  Defines the sprite 'SNAME' in area ISTOR to be the part of the screen
  94. defined by the recangle from the old to the current cursor positions.
  95.  If IPAL =0 no palette data stored; if =1, stores palette data.
  96.  Returns the sprite address in ISADD
  97.  
  98.        SPOP15(ISTOR,SNAME,IPAL,IWID,IHITE,MODE)  (page 404 P.R.M.)
  99.  Reserve space for the sprite named 'SNAME' in array ISTOR. 
  100.  If IPAL =0 no palette data stored; if =1, stores palette data.
  101.  IWID,IHITE are the width and height of the sprite in pixels
  102.  MODE is the MODE to be used for this sprite
  103.  
  104.        SPOP16(ISTOR,SNAME,IPAL,IX1,IY1,IX2,IY2,ISADD)  (page 405 P.R.M.)
  105.  Defines the sprite 'SNAME' in area ISTOR to be the part of the screen
  106. defined by the recangle from (IX1,IY1) to (IX2,IY2), where IX1,IY1 are less
  107. than IX2,IY2.
  108.  If IPAL =0 no palette data stored; if =1, stores palette data.
  109.  Returns the sprite address in ISADD
  110.  
  111.        SPOP24(ISTOR,SNAME,ISADD)  (page 406 P.R.M.)
  112.  Selects the sprite 'SNAME' in array ISTOR for plotting. Returns the sprite
  113. address in ISADD.
  114.  
  115.        SPOP25(ISTOR,SNAME)  (page 407 P.R.M.)
  116.  Deletes sprite 'SNAME' from area ISTOR
  117.  
  118.        SPOP26(ISTOR,SNAME,SNNEW)  (page 408 P.R.M.)
  119.  Renames the sprite 'SNAME' in area ISTOR as 'SNNEW'. (N.B. these names can
  120. not be addresses as in note 4)
  121.  
  122.        SPOP27(ISTOR,SNAME,SNNEW)  (page 409 P.R.M.)
  123.  Copies the sprite 'SNAME' in area ISTOR to 'SNNEW'. (N.B. these names can
  124. not be addresses as in note 4)
  125.  
  126.        SPOP28(ISTOR,SNAME,IACT)  (page 410 P.R.M.)
  127.  Plots sprite 'SNAME in area ISTOR at graphics cursor. IACT is similar to
  128. the 1st argument of GCOL, but must be set to 8 to use the mask while
  129. plotting.
  130.  
  131.        SPOP29(ISTOR,SNAME)  (page 412 P.R.M.)
  132.  Creates a mask for sprite 'SNAME' in area ISTOR. Initially all the pixels
  133. are set opaque.
  134.  
  135.        SPOP30(ISTOR,SNAME)  (page 413 P.R.M.)
  136.  Deletes the mask for sprite 'SNAME' in area ISTOR.
  137.  
  138.        SPOP31(ISTOR,SNAME,IROW)  (page 414 P.R.M.)
  139.  Inserts a row of colour zero at IROW in the sprite 'SNAME' in area ISTOR.
  140. All rows above it are shifted up.
  141.  
  142.        SPOP32(ISTOR,SNAME,IROW)  (page 415 P.R.M.)
  143.  Deletes the row at IROW in the sprite 'SNAME' in area ISTOR. All rows below
  144. it are shifted down.
  145.  
  146.        SPOP33(ISTOR,SNAME)  (page 416 P.R.M.)
  147.  Flips the sprite 'SNAME' in area ISTOR about its X-axis.
  148.  
  149.        SPOP34(ISTOR,SNAME,IX,IY,IACT)  (page 417 P.R.M.)
  150.  Plots sprite named 'SNAME' from area ISTOR at graphics co-ordinates IX,IY
  151. IACT is similar to the 1st argument of GCOL, but must be set to 8 to use
  152. the mask while plotting.                            
  153.  
  154.        SPOP35(ISTOR,'SNAM1','SNAM2',IHORIZ)  (page 419 P.R.M.)
  155.  Adds the sprite 'SNAM2' to 'SNAM1' in area ISTOR. 'SNAM2' is then deleted.
  156. If IHORIZ is 0, 'SNAM2' is added to the right of 'SNAM1'.
  157. If IHORIZ is 1, 'SNAM2' is added below 'SNAM1'.
  158. The two sprites must be of the same height (or width) if IHORIZ is 0 (1).
  159.  
  160.        SPOP36(ISTOR,SNAME,IBITS,IX,IY,ISCALE,IPXTR)  (page 421 P.R.M.)
  161.  Sets the pointer shape from sprite 'SNAME' in area ISTOR.
  162.  IBITS - a word of bits (0 to 6)specifying the functionality:
  163.    0-3 pointer shape number (currently in range 1 to 4)
  164.    4   if clear, set the pointer shape data
  165.    5   if clear, set the palette from the sprite
  166.    6   if clear, program the pointer shape number
  167.  (IX,IY) give the offset to the active point from the origin of the sprite.
  168.  ISCALE may be zero when the natural size is taken, or it is an array of 4
  169. integers specifying the scale factors:
  170.    1 multiplier for X 
  171.    2 multiplier for Y 
  172.    3 divider    for X            
  173.    4 divider    for Y
  174.  IPXTR is a BYTE array which allows logical colours to be used when plotting
  175. the sprite. Pixel of colour N in the sprite is translated to the colour
  176. given by the Nth byte in IPXTR.
  177.                           
  178.        SPOP40(ISTOR,SNAME,IWIDTH,IHITE,MASK,MODE)  (page 423 P.R.M.)
  179.  Gets sprite information of sprite 'SNAME' in area ISTOR. returns:
  180.    IWIDTH,IHITE give the size in pixels
  181.    MASK is 0 for no mask, 1 for mask
  182.    MODE is the defined graphics mode.
  183.  
  184.        SPOP41(ISTOR,SNAME,IX,IY,ICOL,ITINT)  (page 424 P.R.M.)
  185.  Reads the colour of the pixel at (IX,IY) for sprite 'SNAME' in area ISTOR
  186. into ICOL and ITINT (ITINT will be set to zero for <256 colour modes).
  187.  
  188.        SPOP42(ISTOR,SNAME,IX,IY,ICOL,ITINT)  (page 425 P.R.M.)
  189.  Sets the pixel IX,IY of sprite 'SNAME' in area ISTOR to the colour ICOL
  190. (and ITINT for 256 colour modes).
  191.  
  192.        SPOP43(ISTOR,SNAME,IX,IY,MASK)  (page 426 P.R.M.)
  193.  Reads the state of the mask at pixel (IX,IY) for sprite 'SNAME' in area
  194. ISTOR into MASK. (MASK =0 is transparent, =1 is solid)
  195.  
  196.        SPOP44(ISTOR,SNAME,IX,IY,IMASK)  (page 427 P.R.M.)
  197.  Sets mask pixel (IX,IY) to transparent when IMASK is 0, opaque when 1
  198.  
  199.        SPOP45(ISTOR,SNAME,ICOLM)  (page 428 P.R.M.)
  200.  Inserts a column of colour zero at ICOLM in the sprite 'SNAME' in area
  201. ISTOR. All columns to the right of it are shifted.
  202.  
  203.        SPOP46(ISTOR,SNAME,ICOLM)  (page 429 P.R.M.)
  204.  Deletes the column at ICOLM in the sprite 'SNAME' in area ISTOR. All
  205. columns beyond it are shifted back.
  206.  
  207.        SPOP47(ISTOR,SNAME)  (page 430 P.R.M.)
  208.  Flips the sprite 'SNAME' in ISTOR about its Y-axis.
  209.  
  210.        SPOP48(ISTOR,SNAME)  (page 431 P.R.M.)
  211.  Plots the mask of sprite 'SNAME' in area ISTOR at the graphics cursor
  212. position with the background colour and action.
  213.  
  214.        SPOP49(ISTOR,SNAME,IX,IY)  (page 432 P.R.M.)
  215.  Plots the mask of sprite 'SNAME' in area ISTOR at the position (IX,IY) with
  216. the background colour and action.
  217.  
  218.        SPOP50(ISTOR,SNAME,IX,IY,ISCALE)  (page 433 P.R.M.)
  219.  Plots the scaled mask of sprite 'SNAME' in area ISTOR at the position
  220. (IX,IY) with the background colour and action. If you don't want it scaled,
  221. use SPOP49.
  222.  ISCALE is an array of 4 integers specifying the scale factors:
  223.    1 multiplier for X 
  224.    2 multiplier for Y 
  225.    3 divider    for X            
  226.    4 divider    for Y
  227.  
  228.        SPOP51(ICHAR,IX,IY,ISCALE)  (page 434 P.R.M.)
  229.  Plots the ASCII character ICHAR scaled at the position (IX,IY)
  230.  ISCALE is an array of 4 integers specifying the scale factors:
  231.    1 multiplier for X 
  232.    2 multiplier for Y 
  233.    3 divider    for X            
  234.    4 divider    for Y
  235.  
  236.        SPOP52(ISTOR,SNAME,IX,IY,IACT,ISCALE,IPXTR)  (page 435 P.R.M.)
  237.  Plots scaled sprite named 'SNAME' from area ISTOR at graphics co-ordinates
  238. IX,IY IACT is similar to the 1st argument of GCOL, but must be set to 8 to
  239. use the mask while plotting.
  240.  ISCALE is an array of 4 integers specifying the scale factors:
  241.    1 multiplier for X 
  242.    2 multiplier for Y 
  243.    3 divider    for X            
  244.    4 divider    for Y
  245.  IPXTR is a BYTE array which allows logical colours to be used when plotting
  246. the sprite. Pixel of colour N in the sprite is translated to the colour
  247. given by the Nth byte in IPXTR.
  248.  
  249.        SPOP53(ISTOR,SNAME,IX,IY,ISCALE,IPXTR)  (page 437 P.R.M.)
  250.  Plots scaled sprite named 'SNAME' from area ISTOR at graphics co-ordinates
  251. IX,IY. Anti-aliasing is performed on the sprite as it is scaled, and the
  252. colours of the pixels must lie on a linear grey scale. Note: this can be
  253. quite slow.
  254.  ISCALE is an array of 4 integers specifying the scale factors:
  255.    1 multiplier for X 
  256.    2 multiplier for Y 
  257.    3 divider    for X            
  258.    4 divider    for Y
  259.  IPXTR is a BYTE array which allows logical colours to be used when plotting
  260. the sprite. Pixel of colour N in the sprite is translated to the colour
  261. given by the Nth byte in IPXTR.
  262.  
  263.        SPOP54(ISTOR,SNAME)  (page 439 P.R.M.)
  264.  Removes the left hand wastage from the sprite 'SNAME' in area ISTOR.
  265.  
  266.        SPOP60(ISTOR,SNAME,ISAVE,IREGS)  (page 440 P.R.M.)
  267.  Switches VDU output to the selected sprite 'SNAME' in ISTOR. The register
  268. values are returned in IREGS(1:4) so that they can be used later with NPOP60
  269. to go back to the previous state e.g. normally VDU commands output to the
  270. screen.
  271.  ISAVE detemines how/if the vdu parameters of the screen are to be saved:
  272.       0: not saved (the state of the screen will be lost, e.g. graphics 
  273. cursor position, windows etc.).
  274.       1: use the system area (do not use this option, see page 440 PRM)
  275.   other: ISAVE is an array of length at least that given in bytes by SPOP62.
  276.  
  277.  Note: There are 2 routines for OS_SpriteOp 60, NPOP60 restores the previous
  278. output state.
  279.  
  280.        NPOP60(IREGS)
  281.  Resets the VDU output to that given by the arguements (see SPOP60)
  282.  
  283.        SPOP61(ISTOR,SNAME,ISAVE,IREGS)  (page 442 P.R.M.)
  284.  Switches VDU output to the selected mask of sprite 'SNAME' in ISTOR. The
  285. register values are returned in IREGS(1:4) so that they can be used later
  286. with NPOP60 to go back to the previous state e.g. normally VDU commands
  287. output to the screen.
  288.  ISAVE detemines how/if the vdu parameters of the screen are to be saved:
  289.       0: not saved (the state of the screen will be lost, e.g. graphics 
  290. cursor position, windows etc.).
  291.       1: use the system area (do not use this option, see page 440 PRM)
  292.   other: ISAVE is an array of length at least that given in bytes by SPOP62.
  293.  
  294.       SPOP62(ISTOR,SNAME)  (page 444 P.R.M.)
  295.  Finds the size of the save area (in BYTES) of sprite 'SNAME' in area ISTOR
  296. which is needed in sprite_ops 60 and 61 when a user ISAVE array is used.
  297.  
  298.        SPOPER(IERR,ERRTXT,LENTXT)
  299. If there is an error (detected by one of the SPOP functions returning .TRUE.)
  300. this subroutine will return the error number (IERR) and LENTXT characters of
  301. text in 'ERRTXT'. If the CHARACTER size of 'ERRTXT' is too small for the
  302. whole message, it will be truncated.
  303.