home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilst / useful / ReadMe / !ReadMe next >
Encoding:
Text File  |  1995-12-05  |  26.8 KB  |  1,064 lines
  1. Description of modules by Nicholas Kingsley
  2. *******************************************
  3.  
  4. (C) Nicholas Kingsley 1995
  5.  
  6. IMPORTANT : 
  7. -----------
  8.  
  9. Although you can freely use these modules in your own programs, you may not
  10. modify or reverse engineer them.
  11.  
  12. In addition, valid output may not be given if incorrect values are used.  
  13. This is especially true for the routines that directly modify the screen, as,
  14. although there are validity checks for addresses, values given may still
  15. be incorrect
  16.  
  17. You must make no assumptions about how they work, or where internal data
  18. is stored.  However, all values stored in registers are preserved before they
  19. are modified, except when a register returns a value.
  20.  
  21. I accept no responsibility for any damage caused through the use or
  22. misuse of these modules.
  23.                                                            
  24. I currently don't know whether these modules will work on any other machine
  25. apart from the A3010/20 and 4000.
  26.  
  27. I have tried to remove all possible bugs, but if you find any or have
  28. any comments, please E-Mail me at : nicholk@dcs.rhbnc.ac.uk (until May '96)
  29.  
  30. Routines that have test programs have "¤ Has a test program ¤" after them
  31.  
  32. THE MODULES 
  33. -----------
  34.  
  35. In this ReadMe file are descriptions of the following SWI's :
  36.          
  37.          SWI Number:
  38.  
  39. Colour   (&C0000)
  40. Error    (&C0080)
  41. File     (&C0100)
  42. GCIO     (&C0200)
  43. IRQFile  (&C0400)
  44. Menu     (&C0800)
  45. Number   (&C1000)
  46. Read     (&C2000)
  47. Screen   (&C4000)
  48. System   (&C8000)
  49. IRQText  (&D0000)
  50. Random   (&D0040)
  51. Sprite   (&D00C0)
  52. ReDefine (&D01C0)
  53.  
  54. These modules, although very useful for BASIC programs, are designed to be 
  55. used in languages which don't have certain features built in, for example
  56. assembler doesn't have a random number generator built-in, and thus the
  57. Random SWI could be useful.
  58.                                         
  59. As all modules have full help text, I'll only list the bare essentials
  60. here.
  61.  
  62. No module is re-entrant, so if you want to use one in an interrupt, then
  63. you've have to use the CallBack routine.
  64.   
  65. MAJOR UPDATE : 4/10/95 - Make sure all SWI's use the X form.  Re-assemble
  66.                          with new version of Extasm.  Replace all checks for
  67.                          memory below &8000 with a valid memory check.
  68. UPDATED : 9/10/95 - Remove bug with routines that use a copy routine
  69.  
  70. ************************************************************************
  71.  
  72. ERROR MODULE
  73. ------------
  74.  
  75. Error_SError
  76.  
  77. This module allows you to display a standard error message, as dictated
  78. by the Style Guide.
  79.  
  80. Registers used : 
  81.  
  82. R0 - Pointer to program name
  83. R1 - Pointer to error message
  84. R2 - Error number
  85.  
  86. *SError <Program name> <description of problem> <error number>
  87.  
  88. ¤ Has test program ¤
  89.  
  90. ************************************************************************
  91.  
  92. SCREEN MODULE
  93. -------------
  94.  
  95. Screen_TextEntry
  96.  
  97. This provides better input facilities over the INPUT command or OS_ReadLine
  98. SWI.
  99.  
  100. It can convert lower-case letters to upper-case, only allow numbers, 
  101. display stars for any characters pressed, automatic return, ignore
  102. cursor/function etc. keys.
  103.  
  104. UPDATED : 22/7/95 - Add new option, improve speed from MOV R0,<n>/SWI OS_WriteC to SWI OS_WriteI+<n>, improve escape detection & removing
  105. UPDATED : 6/8/95  - Add routine to allow the HOME key to reset cursor
  106. position and clear the input line, and to ignore various other keys.  Also
  107. allow both DELETE keys to act in the same way.  Change ANDS Rx,Rx,#T_xxx to
  108. TST Rx,#T_xxxx
  109. UPDATED : 7/9/95  - Allow input area to be filled with any valid ASCII value, if new bit (9) is set
  110. UPDATED : 9/9/95  - Improve conversion to upper-case.  Now does it in three commands
  111. UPDATED : 5/11/95 - Improve checking routines.  Now a few lines less
  112.  
  113. Registers used : 
  114.  
  115. R0 - X
  116. R1 - Y
  117. R2 - Length of input
  118. R3 - Input state : Bit 0 - Conversion to uppercase
  119.                    Bit 1 - Allow only alphabetic characters
  120.                    Bit 2 - Allow only numbers
  121.                    Bit 3 - Display star
  122.                    Bit 4 - Return as soon as length reached
  123.                    Bit 5 - Use NULL as terminator instead of CR
  124.                    Bit 6 - Allow spaces
  125.                    Bit 7 - Y,y, N or n only
  126.                    Bit 8 - Allow only non-alphanumeric characters
  127.                    Bit 9 - Use guidance markers
  128. R4 - Start address of input
  129. R5 - ASCII value for filling input area (Guidance markers)
  130.  
  131. Returns :
  132.  
  133. R0 - Length of input
  134.  
  135. ¤ Has a test program ¤
  136.  
  137. Screen_CharCopy
  138.  
  139. This copies a character over a given number of times either to the screen or to memory (in which case it can be used as a memory fill).  It is equivalent
  140. to BASIC's STRING$ command (if address = 0).
  141.  
  142. UPDATED : 7/9/95 - Allow multiple characters to be stored in memory.  Add memory check.
  143.  
  144. Registers used : 
  145.  
  146. R0 - Character (must be > 31, if address is 0)
  147. R1 - Number of iterations
  148. R2 - Start address of storage (used only if > 0)
  149.  
  150. NOTE : You will only get screen output if address is 0
  151.  
  152. ¤ Has a test program ¤
  153.  
  154. Screen _GotoXY
  155.  
  156. This moves the cursor to a given X and Y coordinate.  It is especially
  157. useful in machine code as it saves the programmer having to fiddle around
  158. with the code to send VDU bytes
  159.  
  160. UPDATED : 22/7/95 - Removes branch.  Instead does an SWI OS_WriteI first, followed by 2 OS_WriteC's
  161.  
  162. Registers used : 
  163.  
  164. R0 - X
  165. R1 - Y
  166.  
  167. ¤ Has a test program ¤
  168.  
  169. Screen_Box
  170.  
  171. Screen_Box is only really useful if you re-define the 8 * 8 character
  172. font.  It is designed to draw a box anywhere on the screen using UDG
  173. characters.  This allows boxes to be displayed in text-only modes, or where
  174. pixel co-ordinates are too accurate.
  175.  
  176. UPDATE : 6/8/95 - Fix bug
  177.  
  178. Registers used : 
  179.  
  180. R0 - X
  181. R1 - Y
  182. R2 - X length
  183. R3 - Y length
  184. R4 - ASCII start value
  185.  
  186. Screen_TextMenu
  187.  
  188. This SWI is designed to allow text menu creation where all the options
  189. start on the same column.
  190.  
  191. UPDATED : 6/8/95 - Improve cursor movement slightly by removing LDRB. 
  192. Instead place cursor position in extra register.  Also change memory error
  193. address.  Change ANDS Rx... to TST
  194.  
  195. UPDATED : 11/8/95 - Remove bug (would only add 1 line)
  196. UPDATED : 5/11/95 - Reduce conversion to upper-case by one line
  197.  
  198. Registers used : 
  199.  
  200. R0 - Pointer to text address
  201. R1 - X
  202. R2 - Y
  203. R3 - Vertical line spacing value
  204. R4 - Terminator
  205. R5 - Menu separator
  206. R6 - Validate field value (Bit 0 Set - Convert lower-case characters to upper-case)
  207.  
  208. Returns :
  209.  
  210. R0 - Last address used
  211.  
  212. ¤ Has a test program ¤
  213.  
  214. Screen_TelePrint
  215.  
  216. For some games, displaying characters one at a time followed by a cursor
  217. fits well with the software's theme, and this SWI allows you to "teleprint"
  218. characters, just like The Terminator, Universal Soldier and others.
  219.  
  220. UPDATED : 6/8/95 - Remove LDRB, by placing row value in register
  221.  
  222. Registers used : 
  223.  
  224. R0 - Pointer to start of text
  225. R1 - X
  226. R2 - Y
  227. R3 - Terminator (no pun intended)
  228. R4 - Foreground colour
  229. R5 - Background colour
  230. R6 - Cursor colour
  231. R7 - Extra value
  232.  
  233. ¤ Has a test program ¤
  234.  
  235. Screen_WriteC
  236.  
  237. This SWI works in much the same way as OS_WriteC, except for 2 important
  238. differences : You set positions by a pixel value , and not by row or column, 
  239. and each line can have a different colour, allowing multi-coloured 
  240. characters.
  241.  
  242. Registers used : 
  243.  
  244. R0 - Pointer to start of screen address
  245. R1 - Pointer to start of colour address
  246. R2 - X Size of screen
  247. R3 - ASCII value of character to be displayed
  248. R4 - X
  249. R5 - Y
  250. R6 - X scale value (Bit 31 set - overwriting is performed)
  251.                    (Bit 30 set - each line has individual colour)
  252. R7 - Y scale value
  253.  
  254. UPDATED : 12/9/95 - Add bit 30 operation, which now allows each line to have
  255. a seperate colour, as the standard every 8 lines
  256.  
  257. ¤ Has a test program ¤
  258.  
  259. Screen_Write0
  260.  
  261. This routine displays a string of characters, terminated by an ASCII 0
  262. character, using Screen_WriteC.
  263.  
  264. NOTE : You can produce text that is slanted by modifying a parameter. 
  265. However, doing so will modify the coordinate system, and you must make
  266. appropriate allowances for that.
  267.  
  268. NOTE : It should be noted that using Screen_Write0 to display 40 characters,
  269. each 8 * 8 takes exactly the same time as OS_Write0.  Increasing the size
  270. of the characters does not exponentially increase the time taken.
  271.  
  272. NOTE : With Screen_WriteC and Screen_Write0, there is no checking for
  273. out-of-bounds co-ordinates.
  274.  
  275. Registers used : 
  276.  
  277. R0 - Pointer to start of screen address
  278. R1 - Pointer to start of colour address
  279. R2 - X size
  280. R3 - Pointer to start of text address
  281. R4 - X
  282. R5 - Y
  283. R6 - X scale (Bit 31 set - perform overwriting)
  284. R7 - Y scale
  285.  
  286. ¤ Has a test program ¤
  287.  
  288. Screen_CentreText
  289.  
  290. This centres text on a given line, based on the number of columns for a
  291. given mode.  It is totally mode independent.
  292.  
  293. Registers used : 
  294.  
  295. R0 - Y
  296. R1 - ASCII value of terminator
  297. R2 - Pointer to start address of text
  298.  
  299. ¤ Has a test program ¤
  300.  
  301. Screen_FilledBox
  302.  
  303. FilledBox fills a rectangular area of screen with a given character,
  304. background and foreground colour.
  305.  
  306. UPDATED : 29/10/95 - Remove duplicate code
  307.  
  308. Registers used : 
  309.  
  310. R0 - X
  311. R1 - Y
  312. R2 - X Width
  313. R3 - Y Width
  314. R4 - Foreground colour
  315. R5 - Background colour
  316.  
  317. ¤ Has a test program ¤
  318.  
  319. Screen_VerticalWipe
  320.  
  321. This routine clears a screen, by deleting every second line.  As two lines
  322. start from different positions, you'll find that after the routine has
  323. finished, you'll have a clear screen.
  324.  
  325. CONVERTED TO MODULE : 1/8/95.  Mode independence added.
  326. UPDATED : 11/8/95 - Allow second screen data to be used instead of colour.
  327.  
  328. Registers used : 
  329.  
  330. R0 - Pointer to start address of screen
  331. R1 - Colour value
  332. R2 - Second address
  333.  
  334. ¤ Has a test program ¤
  335.  
  336. Screen_HorizontalWipe
  337.  
  338. This routine also clears the screen, by deleting every second pixel.  It works in more or less the same way as Screen_VerticalWipe.
  339.  
  340. CONVERTED TO MODULE : 1/8/95.  Mode independence added.
  341. UPDATED : 11/8/95 - Allow second screen data to be used instead of colour.
  342.  
  343. Registers used : 
  344.  
  345. R0 - Pointer to start address of screen
  346. R1 - Colour value
  347. R2 - Second address
  348.  
  349. ¤ Has a test program ¤
  350.  
  351. Screen_StepWipe
  352.  
  353. This routine also clears the screen, by skipping an increasing number of 
  354. bytes.  
  355.  
  356. CONVERTED TO MODULE : 6/8/95.  Mode independence added.
  357. UPDATED : 11/8/95 - Allow second screen data to be used instead of colour.
  358.  
  359. Registers used : 
  360.  
  361. R0 - Pointer to start address of screen
  362. R1 - Colour value
  363. R2 - Second address
  364.  
  365. ¤ Has a test program ¤
  366.  
  367. Screen_BlockCopy40
  368.  
  369. This routine allows groups of 40 bytes to be copied from one area of 
  370. memory to another.  This would mostly be used to copy data from one
  371. screen bank to another
  372.  
  373. CONVERTED TO MODULE : 4/9/95
  374.  
  375. Registers used : 
  376.  
  377. R0 - Source address (must be word aligned)
  378. R1 - Destination address (must be word aligned)
  379. R2 - Number of bytes to copy (must be multiples of 40 bytes)
  380.     
  381. NOTE : There has been no checks for word-alignment nor for checking
  382. the number of bytes.  In addition, there have been no allowances for
  383. over-lapping areas of memory.  This is to allow the routine to work at the
  384. fastest speed possible.
  385.  
  386. ¤ Has a test program ¤
  387.  
  388. Screen_BlockCopy1
  389.  
  390. This routine allows groups of bytes to be copied.
  391.  
  392. CONVERTED TO MODULE : 4/9/95
  393.  
  394. Registers used : 
  395.  
  396. R0 - Source address 
  397. R1 - Destination address 
  398. R2 - Number of bytes to copy 
  399.  
  400. ¤ Has a test program ¤
  401.  
  402. Screen_WriteM
  403.  
  404. This module is somewhat like Screen_Write0, but allows different colours
  405. in both the horizontal and vertical direction.
  406.  
  407. Registers used :
  408.  
  409. R0 - X position (in pixels)
  410. R1 - Y position (in pixels)
  411. R2 - Pointer to start address of character
  412. R3 - Type (Bit 31 Set - Allow any background data to show through)
  413. R4 - Width of screen (in pixels)
  414. R5 - Start address of screen
  415.  
  416. NOTE : This routine tries to be as quick as possible.
  417.  
  418. CONVERTED TO MODULE : 8/11/95
  419.  
  420. ¤ Has a test program ¤
  421.  
  422. Screen_RasterBars
  423.  
  424. This routine displays a number of raster bars, created using the "RasterBars"
  425. program, onto the current screen
  426.  
  427. Registers used :
  428.  
  429. R0 - Start address of the current screen
  430. R1 - Start address of the colour data
  431. R2 - Starting row number
  432. R3 - Screen width (in pixels)
  433.  
  434. NOTE : To make the routine as fast as possible, no memory checking is 
  435.        performed.  This means that you should only use this routine on
  436.        256 screens, which are mulitple of 320 bytes
  437.  
  438. CONVERTED TO MODULE : 1/12/95
  439.  
  440. ¤ Has test program ¤
  441.  
  442. ************************************************************************
  443.  
  444. MENU MODULE
  445. -----------
  446.  
  447. Menu_Select
  448.  
  449. This would mostly be used in conjunction with the Screen_TextMenu SWI.  It
  450. allows easy selection of text-based options, using the cursor key to move
  451. a selecting character up and down and the return key to select an option.
  452. It returns a value for the left and right cursor, so you can choose to
  453. ignore them, or call some function if either are pressed.
  454.  
  455. Registers used : 
  456.  
  457. R0 - X
  458. R1 - Start Y value for selecting character
  459. R2 - Number of options
  460. R3 - Starting option number
  461. R4 - ASCII value of selector
  462. R5 - Delay
  463. R6 - Spacing between options
  464.  
  465. Returns :
  466.  
  467. R0 - Code
  468. R1 - Position
  469.  
  470. ¤ Has a test program ¤
  471.  
  472. ************************************************************************
  473.  
  474. COLOUR MODULE
  475. -------------
  476.  
  477. Colour_SetValue
  478.  
  479. This allows you to set the text colours foreground or background, set the
  480. border colour or clear the screen.  
  481.  
  482. This allows you to select any colour without worrying about which ColourTrans
  483. value to use, and having to shift values etc.
  484.  
  485. UPDATED : 6/8/95 - Remove possible bug.  Replace all ANDS Rx, Ry... with
  486. TST Ry...
  487.  
  488. Registers used : 
  489.  
  490. R0 - Red value
  491. R1 - Green value
  492. R2 - Blue value
  493. R3 - Type (Bit 0 set - Set forground colour)
  494.           (Bit 1 set - Set background colour)
  495.           (Bit 2 set - Set border colour)
  496.           (Bit 3 set - Clear screen)
  497.  
  498. ¤ Has test program ¤
  499.  
  500. Colour_ScreenBackground
  501.  
  502. This allows you to set the colour of the screen background, without the need
  503. to clear the screen to invoke the new colour.
  504.  
  505. Registers used : 
  506.  
  507. R0 - Pointer to start address of screen
  508. R1 - X size
  509. R2 - Colour
  510. R3 - Replace colour
  511.  
  512. Colour_FadeText
  513.  
  514. This allows you to fade text up or down and finish with a given colour
  515.                  
  516. Registers used : 
  517.  
  518. R0 - Pointer to start address of text
  519. R1 - ASCII value of terminator
  520. R2 - X
  521. R3 - Y
  522. R4 - Control data
  523. R5 - Final colour
  524.        
  525. UPDATED : 5/11/95 - Replace an AND Rx,Ry with a TST Ry
  526.  
  527. ¤ Has a test program ¤
  528.  
  529. Colour_Shade
  530.  
  531. This routine returns addresses of different coloured shades, which is
  532. especially useful for Screen_WriteC or Screen_Write0
  533.  
  534. Registers used : 
  535.  
  536. R0 - Shade number
  537.  
  538. Returns :
  539.  
  540. R0 - Address of desired shade
  541.  
  542. ************************************************************************
  543.  
  544. SYSTEM MODULE
  545. -------------
  546.  
  547. System_Save
  548.  
  549. This module allows the users current wimp mode and sound parameters to be
  550. saved to a temporary file, which can then be restored at a later date.
  551.                                                   
  552. NOTE : If an error occurs for some reason, it is up to the user to
  553. shut the file and take appropriate action
  554.  
  555. UPDATED : 7/8/95 - Allow saving of sound channel numbers
  556.  
  557. Registers used : 
  558.  
  559. R0 - Number of sound channels
  560. R1 - Sample length
  561. R2 - Sample period
  562. R3 - Pointer to Channel Handler
  563. R4 - Pointer to Scheduler
  564.  
  565. System_Load
  566.  
  567. This module loads a saved system file back into the appropriate
  568. memory locations
  569.  
  570. UPDATED : 7/8/95 - Allow loading of sound channels
  571.  
  572. Registers used : 
  573.  
  574. None
  575.  
  576. Returns :
  577.  
  578. R0 - Previous mode number
  579.  
  580. ************************************************************************
  581.  
  582. READ MODULE
  583. -----------
  584.  
  585. Read_VduVariable
  586.  
  587. This module allows you to read a VDU variable without the need to set up
  588. your own arrays.
  589.  
  590. Registers used : 
  591.  
  592. R0 - Variable number
  593.  
  594. Returns :
  595.  
  596. R0 - Resultant value
  597.  
  598. ¤ Has a test program ¤
  599.  
  600. Read_FreeMemory
  601.  
  602. This routine allows you to check how much free application memory you have
  603. by storing it in a system variable.
  604.  
  605. UPDATED : 7/8/95 - Add *command
  606. UPDATED : 5/10/95 - System variable set up when module is loaded.  When run
  607.                     from the command line, it will now display the value in
  608.                     bytes (b), kilobytes (K) or megabytes (Mb) 
  609.  
  610. Registers used : 
  611.  
  612. None
  613.  
  614. Returns :
  615.  
  616. R0 - Amount of free memory in bytes.
  617.  
  618. ¤ Has a test program ¤
  619.  
  620. Read_OSVersion
  621.  
  622. This routine shows which RISC OS version the module is currently running on.
  623. In addition, it stores the value in a system variable.
  624.                                        
  625. Registers used :
  626.  
  627. None
  628.  
  629. Returns :
  630.  
  631. R0 - OS Version number
  632.  
  633. CONVERTED TO MODULE : 17/8/95 - Add system variable
  634. UPDATED : 5/10/95 - System variable is now set up when module is loaded
  635.  
  636. ¤ Has a test program ¤
  637.  
  638. UPDATED : 21/11/95 - Add finalisation code : Now kills defined variables
  639.  
  640. ************************************************************************
  641.  
  642. RANDOM MODULE
  643. -------------
  644.  
  645. Random_CreateSeed
  646.  
  647. This sets the starting seed value.  
  648.  
  649. Registers used : 
  650.  
  651. R0 - Seed value
  652.  
  653. Returns :
  654.  
  655. R0 - Final seed value
  656.  
  657. ¤ Has a test program ¤
  658.  
  659. Random_Number
  660.  
  661. This generates a random number between 0 and either 255 or 429496725 depending on a number given.
  662.  
  663. UPDATED : 4/8/95 - New routine to give number between 0 and 255 or 0 and 429496725
  664.  
  665. Registers used : 
  666.  
  667. R0 - Highest range (0 - Creates a random number where the probability of a number less than &80000000 is very remote)
  668.  
  669. Returns :
  670.  
  671. R0 - Random number
  672.  
  673. ¤ Has a test program ¤
  674.  
  675. ************************************************************************
  676.  
  677. NUMBER MODULE
  678. -------------
  679.  
  680. Number_Pad 
  681.  
  682. This module pads a given positive decimal integer number to a given number
  683. of characters, and with a given ASCII value.  The output length will always
  684. be EXACTLY the length given. 
  685.  
  686. This SWI is useful for any programs where decimal output must always be of
  687. fixed length, for example scores in games.
  688.  
  689. UPDATED : 21/7/95 - Improve initial pad display/storing.  Improved display
  690.           calculation & slightly faster character output/storage
  691.  
  692. Registers used : 
  693.  
  694. R0 - Number
  695. R1 - ASCII value to use for padding
  696. R2 - Number of characters for padding
  697. R3 - X
  698. R4 - Y
  699. R5 - Address to store text result (if 0 then output to screen)
  700.  
  701. ¤ Has a test program ¤
  702.  
  703. ************************************************************************
  704.  
  705. FILE MODULE
  706. -----------
  707.  
  708. File_Compress
  709.  
  710. This routine will compress a given memory range into a file, will the 
  711. result that it should save disk space.  The routine used produces a 
  712. very good size reduction if there is a lot of sequential repetition, and so
  713. is best for graphic data
  714.  
  715. Registers used : 
  716.  
  717. R0 - Pointer to start address of filename
  718. R1 - Start address of compression
  719. R2 - End address of compression
  720. R3 - Screen output 
  721.  
  722. File_Decompress
  723.  
  724. This routine will decompress data from a file and store it in memory.
  725.  
  726. Registers used : 
  727.  
  728. R0 - Pointer to start address of filename
  729. R1 - Start address of decompression
  730. R2 - Type of decompression
  731. R3 - Screen output 
  732.  
  733. ¤ Has a test program ¤
  734.  
  735. File_BinAppend
  736.  
  737. RiscOS 3.11 doesn't allow files to be appended easily.  This 
  738. routine fixes that problem.
  739.  
  740. CONVERTED TO MODULE : 13/8/95 - *command added
  741.  
  742. Registers used :
  743.  
  744. R0 - Pointer to start address of input filename 1
  745. R1 - Pointer to start address of input filename 2
  746. R2 - Pointer to start address of output filename
  747. R3 - Screen output (if > 0 show how routine is getting on)
  748.  
  749. ¤ Has a test program ¤
  750.  
  751. ************************************************************************
  752.  
  753. GCIO MODULE
  754. ----------
  755.  
  756. GCIO_DetectJoystick
  757.  
  758. This SWI detects whether the joystick module is active or not.  It returns :
  759.  
  760. Bit 0 Set - Port 1 present
  761. Bit 1 Set - Port 2 present
  762.  
  763. Registers used : 
  764.  
  765. None
  766.  
  767. Returns :
  768.  
  769. R0 - Port values
  770.  
  771. GCIO_Joystick
  772.  
  773. This SWI is useful if you want to use some offset value in an array,
  774. in order to move objects.  It converts the normal joystick values from 
  775. either port into a direction number between 0 and 10.
  776.  
  777. The top 3 bits (bits 7 to 5) represent the fire button states.
  778.  
  779. UPDATED : 6/8/95 - Replace all ANDS Rx, Ry.. with TST Ry
  780.  
  781. Registers used : 
  782.  
  783. R0 - Port number
  784.  
  785. Returns :
  786.  
  787. R0 - Value
  788.  
  789. GCIO_Key
  790.  
  791. This module is useful for games, with the same reasons as AltJoystick.
  792. It reads the keyboard and returns a movement value between 0 and 10.  Bits 
  793. 7 to 5 return the 'fire button' status.
  794.  
  795. Registers used : 
  796.  
  797. R0 - Pointer to start address of 7 bytes
  798.  
  799. Returns :
  800.  
  801. R0 - Value
  802.  
  803. ************************************************************************
  804.  
  805. IRQFILE MODULE
  806. --------------
  807.  
  808. IRQFile_DataLoad 
  809.  
  810. This module will attempt to load a data file into a given area of memory
  811. in the background (under interrupts).  This allows the main program to
  812. continue while the data is loading.  This routine must NOT be called again until it has finished.
  813.  
  814. Registers used : 
  815.  
  816. R0 - Pointer to start address of filename
  817. R1 - Start address of load
  818. R2 - Load type
  819.              
  820. ¤ Has a test program ¤
  821.  
  822. IRQFile_Status
  823.  
  824. This routine returns a value based on the progress made while loading the
  825. data
  826.  
  827. Registers used : 
  828.  
  829. None
  830.  
  831. Returns :
  832.  
  833. R0 - Status of routine
  834.  
  835. IRQFile_Abort
  836.  
  837. This routine aborts the loading system, closes the file used and removes
  838. the interrupt system
  839.  
  840. Registers used : 
  841.  
  842. None
  843.  
  844. NOTE : These routines have only been tested on a A3010, and MAY not work on 
  845. the RiscPC600, 700 or 7000.  I hope to be solving this problem soon.
  846. In addition, if you abort a program using the ESC key you will
  847. get an abort on data transfer error, which although is fairly harmless 
  848. should be avoided either by making sure you don't press the ESC key
  849. until the routine has finished, or by setting up another escape handler to 
  850. call IRQFile_Abort.
  851.  
  852. In addition, this module MAY not work with Risc OS 2 machines.
  853.  
  854. ************************************************************************
  855.  
  856. IRQTEXT MODULE
  857. --------------
  858.  
  859. IRQText_Print
  860.  
  861. This SWI allows text to be printed to the screen under interrupts, allowing
  862. the main program to continue with something else.  This routine must NOT be called again until it has finished.
  863.  
  864. Registers used :
  865.  
  866. R0 - Pointer to start of text address
  867. R1 - ASCII value of terminator
  868.  
  869. UPDATED : 21/11/95 - Fix finishing print bug
  870.  
  871. ¤ Has a test program ¤
  872.  
  873. IRQText_Status
  874.  
  875. This SWI allows you to check to see whether the interrupt printing has 
  876. finished or not
  877.  
  878. Registers used :
  879.  
  880. None
  881.  
  882. Returns :
  883.  
  884. R0 - Status of print routine
  885.  
  886. IRQText_Abort
  887.  
  888. This SWI aborts the interrupt printing process
  889.  
  890. Registers used : 
  891.  
  892. None
  893.  
  894. NOTE : These routine have only been tested on a A3010, and MAY not work on 
  895. the RiscPC600, 700 or 7000.  I hope to be rectifying this problem soon.
  896. In addition, if you abort a program using the ESC key you will
  897. get an abort on data transfer error, which although is fairly harmless 
  898. should be avoided either by making sure you don't use the ESC key until
  899. you know that the routine has finish, or by setting up another escape handler
  900. to call IRQText_Abort.
  901.  
  902. If you print something while IRQText_Print is working, all further
  903. characters will be printed at the last cursor position.
  904.  
  905. In addition, this module MAY not work with Risc OS 2 machines.
  906.  
  907. ************************************************************************
  908.  
  909. SPRITE MODULE
  910. -------------
  911.  
  912. Sprite_DisplayNormal
  913.  
  914. This module is used to display a sprite using internal colour numbers only,
  915. which is the format used in my SprToData program.  It has been designed
  916. with full clipping in mind, and so can be very slow (depending on the size of the sprite).
  917.  
  918. CONVERTED TO MODULE : 5/9/95 - Mask against background added
  919.  
  920. Registers used : 
  921.  
  922. R0 - Start address of sprite data
  923. R1 - Top left X coordinate for plotting
  924. R2 - Top left Y coordinate for plotting
  925. R3 - Internal colour number of mask
  926. R4 - Start address of output (normally screen)
  927. R5 - Width of output area
  928. R6 - Height of output area
  929. R7 - Type field, based on the following :
  930.  
  931.      Bit 31 Set - Use mask colour against sprite colour
  932.      Bit 30 Set - Use mask colour against colour at current location
  933.      Bits 7-0   - Which sprite that you want displayed
  934.                                             
  935. Returns :
  936.  
  937. R0 - Last address read
  938.  
  939. NOTE : Bits 31 and 30 exclude each other
  940. NOTE : This module allows you to store sprite data anywhere in memory, which
  941.        means you don't have to display them!
  942.  
  943. Sprite_DisplayPreShift
  944.  
  945. This routine will display a sprite much quicker than with the previous
  946. routine.  To get around the fact that the positioning location has to
  947. be word aligned, the sprite should be pre-shifted.
  948.  
  949. Registers used :
  950.  
  951. R0 - Start address of sprite memory
  952. R1 - X Position
  953. R2 - Y Position
  954. R3 - Start address of screen
  955. R4 - Width of screen
  956. R5 - Height of screen
  957.  
  958. Returns :
  959.  
  960. R0 - Last address read
  961.  
  962. CONVERTED TO MODULE : 6/9/95
  963.  
  964. Sprite_FindPreShifts
  965.  
  966. This routine MUST be called before Sprite_DisplayPreShift, to speed up
  967. finding which pre-shifted sprite must be destroyed.
  968.  
  969. Registers used :
  970.  
  971. R0 - Start address of sprite memory
  972.  
  973. Returns :
  974.  
  975. R0 - Pre-shifts NOT found (< 0 - All found)
  976.  
  977. CONVERTED TO MODULE : 6/9/95
  978.  
  979. NOTE : These routines require data to be in the format created by the 
  980. "SprToData" program, and may return unpredicatable results if it isn't.
  981.  
  982. Sprite_DisplayFast
  983.  
  984. This routine allows sprite data (converted by NewSprPlt program) to be
  985. display anywhere on screen at a very fast rate.  This is done by assuming
  986. that the colour 0 (which can be change in the aformentioned program) is
  987. always skipped.  This means that only non-black pixels are plotted
  988.  
  989. Registers used :
  990.  
  991. R0 - Start address of screen
  992. R1 - Start address of sprite data
  993. R2 - X Position
  994. R3 - Y Position
  995. R4 - Screen width
  996.  
  997. Returns :
  998.  
  999. Nothing
  1000.  
  1001. CONVERTED TO MODULE : 10/11/95 - Increase amount of data read in at once
  1002.                                  (now 10 bytes, with offset and colour
  1003.                                   interleaved)
  1004.                                  Fix bugs in conversion program
  1005.  
  1006. ¤ Has a test program ¤
  1007.  
  1008. ************************************************************************
  1009.  
  1010. REDEFINE MODULE
  1011. ---------------
  1012.  
  1013. ReDefine_SetOfKeys
  1014.  
  1015. This routine allows the user to redefine the actions of keys, in games.  All
  1016. keys are detected, and are displayed in a given colour after each keypress.
  1017. Duplicate keys are not allow, of course.
  1018.  
  1019. Registers used :
  1020.  
  1021. R0 - Start address of text giving action names to all required keys.  Each 
  1022.      name must be seperated by a "|", and the whole list terminated a 0
  1023.      byte
  1024. R1 - Starting column number for displaying names
  1025. R2 - Starting row number for displaying names
  1026. R3 - Pointer to address holding 2 * 4 byte &BBRRGG00 colours (foreground, background), for displaying names
  1027. R4 - Pointer to address holding 2 * 4 byte &BBRRGG00 colours (foreground, background), for user key presses
  1028. R5 - Spacing :
  1029.  
  1030.      Bits 31-16 - Row spacing (number of lines between each name)
  1031.      Bits 15-0  - Column spacing (number of columns between names and 
  1032.                                   enteries)
  1033. R6 - Start address of storage
  1034. R7 - Bits 7-0 : Use voice number given (if > 0) to warn of duplicates
  1035.      Bit  8   : If set, then convert all lowercase characters to uppercase
  1036.      Bit  9   : Return as soon as all text and keys have been displayed.  
  1037.                 This is useful for multi-player games, as it allows you to
  1038.                 display all the players keys at once.
  1039.  
  1040. CONVERTED TO MODULE : 9/9/95 - Conversion to uppercase added, as well as
  1041.                       pointers to colours            
  1042. UPDATED : 21/11/95 - Add return-as-soon-as-possible code
  1043.  
  1044. NOTE : If any codes are not reconized, then "* Undefined *" will be
  1045. displayed
  1046.  
  1047. ¤ Has a test program ¤
  1048.  
  1049. ReDefine_Chars
  1050.  
  1051. This routine allows you to load in a compressed BBC font file, and change
  1052. all define characters to the new shapes
  1053.  
  1054. Registers used :
  1055.  
  1056. R0 - Pointer to start of filename
  1057.  
  1058. CONVERTED TO MODULE : 20/9/95 
  1059.  
  1060. *RChar
  1061.  
  1062. This command resets the current font to the system font
  1063.  
  1064. COMMAND ADDED : 20/9/95