home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / wst!blz1.dms / in.adf / docs / rilibdocs.lha / RIZoneJoyLib.doc < prev   
Encoding:
Text File  |  1994-09-05  |  8.5 KB  |  261 lines
  1. Library Name:
  2.   rianimlib #64
  3.  
  4. Authors:
  5.   ReflectiveImages, 17 Mayles Road, Southsea, Portsmouth, Hampshire, UK PO4 8NP
  6.  
  7. OverView:
  8.   Another Reflective Images Library, belongs in the amosfunclib no?
  9.  
  10. Authors Docs:
  11.  
  12. Reflective Images Zone-Joystick Library v1.2
  13. ============================================
  14.  
  15. By Stephen McNamara, original Joy Library by Steve Matty
  16. (c)1994 Reflective Images
  17.  
  18. This version: 1.2
  19.         18/6/94
  20.  
  21. This library contains commands for setting up zones and testing the status
  22. of the joysticks attached to the Amiga.
  23.  
  24. New additions to this library allow you to have multiple lists of zones
  25. (refered to as zonetables in this doc).  To maintain compatibility with
  26. older versions of the library, zonetable 0 is equivalent of the original
  27. list of zones used in the library.  You cannot adjust the size of zonetable
  28. 0 (its size is 256 zones), nor can you delete it.  The new zonetables can
  29. be from 1 to 65536 in size, there are 16 available zonetable numbers.
  30.  
  31. All commands that change or test zones will work on the last zonetable that
  32. was selected with the command UseZoneTable.  The default table is number 0.
  33.  
  34. Command list:
  35.       ZoneInit [zone_num]|[start_zone,end_zone]
  36.       Setzone zone#,x1,y1,radius
  37.       Setzone zone#,x1,y1,x2,y2
  38.       a.w=Zone(x,y)
  39.       a.w=ZoneTest(start_zone[,end_zone],x,y)
  40.       ad.l=ZoneTable
  41.     (*) size.l=ZoneTableSize (table#)
  42.     (*) UseZoneTable table#
  43.     (*) NewZoneTable table#,size
  44.     (*) FreeZoneTable table#
  45.  
  46.       jf.b=JFire(joy#)
  47.       jv.b=JVert(joy#)
  48.       jh.b=JHoriz(joy#)
  49.       af.b=AllFire [bit_pattern]
  50.  
  51. (*)=new for this version of the Zone-Joystick library.
  52.  
  53.  
  54. Statement: ZoneInit
  55. ------------------------------------------------------------------------
  56. Modes  : Amiga/Blitz
  57. Syntax : ZoneInit [zone_num]|[start_zone,end_zone]
  58.  
  59.   This command is used to clear any zones currently set.  The optional
  60.   parameters allow you to select either a single zone or a range of zones
  61.   to reset.
  62.  
  63.  
  64. Statement/Function: Setzone
  65. ------------------------------------------------------------------------
  66. Modes  : Amiga/Blitz
  67. Syntax : Setzone zone#,x1,y1,radius
  68.          Setzone zone#,x1,y1,x2,y2
  69.  
  70.   This command lets you set up zones for testing.  The first version is
  71.   used when you want to set up a circular zone and the second when you want
  72.   a rectangular one.  With rectangular zones, x1,y1 should be the top left
  73.   corner of the rectangle and x2,y2 should be the bottom left.
  74.  
  75.   If used as a function, this command returns TRUE or FALSE to say whether
  76.   or not the change was made.
  77.  
  78.   Note: The max zone number for zonetable 0 is 255.
  79.   A zone number outside the range of the current table will
  80.         cause this command to abort.
  81.         Zones can be defined in any order.
  82.         Circular zones are used in exactly the same way as rectangular
  83.         ones.
  84.  
  85.  
  86. Function: Zone
  87. ------------------------------------------------------------------------
  88. Modes  : Amiga/Blitz
  89. Syntax : a.w=Zone(x,y)
  90.  
  91.   This command takes the co-ordinates x,y and checks to see if they are
  92.   inside any of the defined zones.  The zones are searched in order,
  93.   starting at 0 and going through to the size of the zonetable-1.  This
  94.   command will return the first zone that the co-ordinates were found to
  95.   be inside, you should note that both types of zones are tested
  96.   (rectangular and circular).
  97.  
  98.   This command returns either -1 for not inside a zone or the zone number.
  99.  
  100.  
  101. Function: ZoneTest
  102. ------------------------------------------------------------------------
  103. Modes  : Amiga/Blitz
  104. Syntax : a.w=ZoneTest(start_num[,end_num],x,y)
  105.  
  106.   This command is the same as the Zone command except that it allows you
  107.   to select either one individual zone to test or a range of zones.  You
  108.   should, though, ensure that end_num if greater than start_num.
  109.  
  110.   This command returns either -1 for not inside a zone or the zone number.
  111.  
  112.  
  113. Function: ZoneTable
  114. ------------------------------------------------------------------------
  115. Modes  : Amiga/Blitz
  116. Syntax : ad.l=ZoneTable
  117.  
  118.   This function returns the address in memory of the zone information
  119.   storage area for the current zonetable. The zones are stored one after
  120.   the other, with each zone taking up 8 words (16 bytes) in the data area,
  121.   making a total size of 2048 bytes.  They are stored in the following way:
  122.  
  123.     Rectangular:    +0: x1
  124.         +2: y1
  125.         +4: x2
  126.         +6: y2
  127.  
  128.     Circular: +0: x1
  129.         +2: y1
  130.         +4: radius of zone
  131.         +6: -1 <-- this is set to show that the
  132.                    zone is circular.
  133.  
  134.     Undefined zone: +0: -1
  135.         +2: -1
  136.         +4: -1
  137.         +6: -1
  138.  
  139.   The first longword (4 bytes) of the zonetable is used to hold the size,
  140. in zones, of the table (thus the true size of the zonetable is 4+number of
  141. zones*8).
  142.  
  143.  
  144. Function: ZoneTableSize
  145. ------------------------------------------------------------------------
  146. Modes  : Amiga/Blitz
  147. Syntax : size.l=ZoneTableSize
  148.  
  149.   This function returns the size, in zones, of the current zonetable.  It
  150. is equivalent of doing: size.l=peek.l(ZoneTable).
  151.  
  152.  
  153. Statement/Function: NewZoneTable
  154. ------------------------------------------------------------------------
  155. Modes  : Amiga/Blitz
  156. Syntax : NewZoneTable table#,size
  157.  
  158.   This command will attempt to allocate a new zonetable with the given
  159. table number.  If the table already exists it will be deleted.  The maximum
  160. size for a zonetable is 65536 zones.  If used as a function, this command
  161. will return FALSE for failure or TRUE for success.  You should note that
  162. all zones are automatically reset in the new table and that creating a
  163. table does not make it the current table, this must be done with
  164. UseZoneTable.
  165.   Valid zonetable numbers range from 0 to 15.
  166.  
  167.   IMPORTANT NOTE: you cannot define the size of zonetable 0.  You cannot
  168. use this command to alter it in any way.
  169.  
  170.  
  171. Statement/Function: UseZoneTable
  172. ------------------------------------------------------------------------
  173. Modes  : Amiga/Blitz
  174. Syntax : UseZoneTable table#
  175.  
  176.   This command is used to change the current zonetable to the selected one.
  177. If used as a function, it will return TRUE for success or FALSE for
  178. failure.
  179.   Valid zonetable numbers range from 0 to 15.
  180.  
  181.  
  182. Statement/Function: FreeZoneTable
  183. ------------------------------------------------------------------------
  184. Modes  : Amiga/Blitz
  185. Syntax : FreeZoneTable table#
  186.  
  187.   This command is used to free a zonetable from memory.  If used as a
  188. function, it will return TRUE or FALSE.  When successfully called, this
  189. command will free the zonetable and change the currently used zonetable to
  190. table number 0.
  191.   Valid zonetable numbers range from 0 to 15.
  192.  
  193.   IMPORTANT NOTE: you cannot free zone table 0.
  194.  
  195.  
  196. Function: JFire
  197. ------------------------------------------------------------------------
  198. Modes  : Amiga/Blitz
  199. Syntax : jf.b=JFire(joy#)
  200.  
  201.   This command tests the fire button status of the joystick joy#, where
  202.   joy# is between 1 and 4.  You should note that, as with all the joystick
  203.   commmands, joy#=1 refers to the Amiga's joystick port, joy#=2 refers to
  204.   the mouse port, and joy#=3 or joy#=4 refer to the four player adapter
  205.   ports.
  206.  
  207.   This command returns 0 for fire button not pressed or -1 for pressed
  208.  
  209.  
  210. Function: JHoriz
  211. ------------------------------------------------------------------------
  212. Modes  : Amiga/Blitz
  213. Syntax : jh.b=JHoriz(joy#)
  214.  
  215.   This command is used to test the horizontal direction of the selected
  216.   joystick.  It returns:
  217.  
  218.     0: No horizontal direction
  219.            -1: Joystick left
  220.           1: Joystick right
  221.  
  222.  
  223. Function: JVert
  224. ------------------------------------------------------------------------
  225. Modes  : Amiga/Blitz
  226. Syntax : jv.b=JVert(joy#)
  227.  
  228.   This command is used to test the vertical direction of the selected
  229.   joystick.  It returns:
  230.  
  231.     0: No vertical direction
  232.            -1: Joystick up
  233.           1: Joystick down
  234.  
  235.  
  236. Function: AllFire
  237. ------------------------------------------------------------------------
  238. Modes  : Amiga/Blitz
  239. Syntax : af.b=AllFire [(bit_pattern)]
  240.  
  241.   This command is used to test the fire button status of all four
  242.   joysticks.  It returns a byte with the first four bits giving the
  243.   joystick status, false=fire button not pressed, true=fire button pressed.
  244.   The following bits belong to joysticks:
  245.  
  246.     bit 0: joystick 1 (joystick port)
  247.     bit 1: joystick 2 (mouse port)
  248.     bit 2: joystick 3 (four player adaptor)
  249.     bit 3: joystick 4 (four player adaptor)
  250.  
  251.   The optional bit pattern can be used to restrict the testing of the fire
  252.   buttons.  If a bit in the pattern is clear (false) then the joystick it
  253.   belongs to will not have its fire button tested,
  254.  
  255.     e.g. AllFire (%0011) will test joysticks 1 and 2 and return the
  256.              result.  It will return false for joysticks 3 and 4.
  257.  
  258.  
  259.  
  260. >>END  
  261.