home *** CD-ROM | disk | FTP | other *** search
/ Amiga Computing 60 / ac060.adf / Utilities / Ameko.doc / Ameko.doc
Text File  |  1993-02-15  |  13KB  |  305 lines
  1.  
  2.                                 Ameko v1.01
  3.  
  4.                   (C) Copyright Carl Revell, 3 February 1993
  5.  
  6.                             ALL RIGHTS RESERVED
  7.  
  8.  
  9.  
  10. DISCLAIMER
  11. ----------
  12.  
  13. THE AUTHOR IS NOT RESPONSIBLE FOR ANY DAMAGE CAUSED BY THE USE OR MISUSE OF
  14. THIS DOCUMENTATION AND/OR THE PROGRAM(S) IT DESCRIBES.
  15.  
  16.  
  17.  
  18. INTRODUCTION
  19. ------------
  20.  
  21. Ameko is an Amiga conversion of a program called Neko which was written by
  22. Dara T. Khani to run under Windows on PCs. The idea for Ameko was inspired by
  23. Dara's Neko program, however the code and Amiga implementation of Ameko are
  24. my own work.
  25.  
  26. When the program is run, a small kitten called Ameko runs around within
  27. the confines of the program's window, chasing the mouse pointer. If Ameko
  28. reaches the edge of the window and the mouse pointer is outside the window
  29. boundaries then Ameko will scratch at the window border in a vain attempt
  30. to get at the mouse pointer.
  31.  
  32. If there is no mouse movement within a predetermined length of time, then
  33. Ameko starts to fall asleep, eventually curling up and entering the land
  34. of nod. If the mouse is then moved, Ameko is startled and wakes up. Once the
  35. haze has cleared from in front of his eyes, he is off again, chasing the
  36. mouse pointer.
  37.  
  38.  
  39.  
  40. SYSTEM REQUIREMENTS
  41. -------------------
  42.  
  43. Amiga computer with at least 512K RAM with KICKSTART 2.0 or later.
  44. (KickStart 1.3 owners see MISCELLANEOUS section below)
  45.  
  46. Ameko has been tested on the following configurations...
  47.  
  48. Amiga 500 Plus, Amiga 600, Amiga 600HD, Amiga 1200, Amiga 1200HD (GVP 85MB
  49. Maxtor), Amiga 1500 (68000), Amiga 1500 (GVP 50MHz 68030), Amiga 1500 (GVP
  50. 28MHz 68040), Amiga 3000, Amiga 4000.
  51.  
  52.  
  53.  
  54. USAGE
  55. -----
  56.  
  57. Ameko should at all times be run from Workbench by double-clicking on the
  58. appropriate program icon.
  59.  
  60. There are two different program icons. One runs the Interlaced version of
  61. Ameko and the other runs the Non-Interlaced version. Two versions were
  62. required because the Interlaced version (the one I orginally developed)
  63. appeared stretched on a non-interlaced screen. I could have combined both
  64. interlaced and non-interlaced graphics into a single program but I would
  65. have sacrificed the size of the program for convenience. Most users will
  66. want to run one version or the other and won't have to lose the memory that
  67. the other screen mode's graphics would have consumed. Simple, huh ?!? If you
  68. don't know which version you should run, run them both and see which one
  69. looks best on your display.
  70.  
  71. Ameko can be run from the CLI/Shell but was not designed with that in mind so
  72. I wouldn't do it if I were you. Anyway, you cannot adjust any startup options
  73. if running Ameko from the CLI/Shell (see ToolTypes below). The only reason
  74. alot of programs enable CLI/Shell startup (apart from use of the console) is
  75. so they can be run from the Startup-Sequence upon boot-up. Because Ameko
  76. requires Kickstart 2.0 or later, it can always be automatically run at
  77. boot-up by placing it in the WBStartup drawer of your boot disk.
  78.  
  79.  
  80.  
  81. TOOLTYPES
  82. ---------
  83.  
  84. Ameko can be configured to your own personal taste by modifying the icon's
  85. ToolTypes. These can be accessed by clicking once on the program icon and
  86. then either pressing Right-Amiga + I or selecting the Information... option
  87. from the Workbench Icons menu. The values that you can change and their
  88. effect are listed below. For more information on changing ToolTypes see your
  89. Amiga Workbench manual.
  90.  
  91. LEFT      = nn where nn is the number of pixels from the left edge of the
  92.             screen that the Ameko window will open up. Negative values and
  93.             values larger than your screen's width should be handled and
  94.             automatically adjusted by the program. I stress the word SHOULD.
  95.  
  96. TOP       = nn where nn is the number of pixels from the top edge of the
  97.             screen that the Ameko window will open up. Negative values and
  98.             values larger than your screen's height should be handled and
  99.             automatically adjusted by the program. I stress the word SHOULD.
  100.  
  101. WIDTH     = nn where nn is the starting width of the Ameko window in pixels.
  102.             The program should replace any stupid values (like negative or
  103.             zero width) with a reasonable default which it calculates based
  104.             on screen values. No guarantee is given that it will always
  105.             choose the correct value so I suggest sticking to sensible
  106.             values to be safe.
  107.  
  108. HEIGHT    = nn where nn is the starting height of the Ameko window in pixels.
  109.             The program should replace any stupid values (like negative
  110.             height) with a reasonable default which it calculates based on
  111.             screen font. I would suggest that you try and keep your values
  112.             for HEIGHT within sensible bounds just in case.
  113.  
  114. SLEEP     = nn where nn is the time (in seconds) that the mouse must remain
  115.             stationary before Ameko starts to fall asleep. Permissible
  116.             values for nn are 1 to 3600 seconds (1 second to 1 hour).
  117.  
  118. SOUND     = nn where nn is either YES or ON which will play a sound sample
  119.             when the Ameko window is opened and again when it is closed.
  120.  
  121.             OR
  122.  
  123.             nn where nn is either OFF or NO which will disable the playing
  124.             of a sound sample when the Ameko window is opened and closed.
  125.  
  126.  
  127. DONOTWAIT = This is really only to tell Workbench not to wait for the
  128.             program's return if you put it in the WBStartup drawer on your
  129.             boot device. If you don't already know, any programs placed into
  130.             the WBStartup drawer are automatically run when Workbench is
  131.             loaded which means you can drag the Ameko icon into your
  132.             WBStartup drawer on your boot disk and let the little fella run
  133.             riot automatically, every time you boot up your Amiga. It's best
  134.             not to alter or delete this ToolType unless you know what you're
  135.             doing.
  136.  
  137. TOOLPRI   = Amiga beginners need not read this section, just leave the
  138.             ToolType set to it's default value which is 21.
  139.             If you are interested, this sets the Task Priority of Ameko above
  140.             all others (on my system anyway) which I found necessary to
  141.             reduce the flickering which occurred when the mouse was moved
  142.             around a lot (see TECHNICAL SECTION below). I found no problem
  143.             with speed or operation of my Amiga with this high task priority,
  144.             but if you experience any difficulties then by all means raise or
  145.             lower this value appropriately. Remember, +127 is the highest
  146.             priority, -128 is the lowest and most normal programs should be
  147.             set to TASKPRI 0.
  148.  
  149. If for some obscure reason you wish to disable a particular ToolType, you
  150. can simply enclose it within a pair or angled brackets. For instance, to
  151. disable the LEFT=50 ToolType, just change it to <LEFT=50>. This is an
  152. excellent way to disable ToolTypes, whilst still enabling you to see the
  153. syntax of ToolTypes so you don't forget that it is LEFT=nn and not
  154. WINLEFT=nn, etc..
  155.  
  156. Ameko has built-in defaults for most of the ToolTypes in case any get
  157. completely deleted from the icon. They are...
  158.  
  159. LEFT   = 32
  160. TOP    = 32
  161. WIDTH  = 100
  162. HEIGHT = 100
  163. SLEEP  = 5 (seconds)
  164. SOUND  = ON
  165.  
  166.  
  167.  
  168. TRICKS AND TIPS
  169. ---------------
  170.  
  171. If you select the Ameko window by clicking once within its boundaries, then
  172. you have the ability to send Ameko straight to sleep and also stop him from
  173. chasing the mouse pointer. You do this by clicking once with your right
  174. mouse button. To wake him up again and let him chase the mouse pointer just
  175. click the right mouse button again. Remember, you must select the Ameko
  176. window first for this feature to work.
  177.  
  178.  
  179.  
  180. TECHNICAL SECTION
  181. -----------------
  182.  
  183. Not really a technical section, more a chance for me to explain why part of
  184. the program is written the way it is and to ask for advice from anyone who
  185. 'knows their onions' when it comes to programming.
  186.  
  187. The program is written in 'C' and although I can program in 680x0 assembler
  188. (software houses, my details are below!) I considered 'C' to be the best
  189. choice. I may recode some or maybe all of the program in 680x0 at a later
  190. date, but it does just fine for now.
  191.  
  192. Basically, a window is opened and then the program is sent to sleep, waiting
  193. on either a CloseWindow message or a timed delay message sent from the
  194. timer.device. So, when the program isn't calculating Ameko's position or
  195. actually drawing him, then it is Waiting and allowing other tasks to get
  196. their share of the CPU. If the TaskPri is set to anything below the
  197. input.device (20 on my system) then the Ameko graphics 'flicker' within a
  198. certain (but not always stationary) area of the screen. Ameko does a WaitTOF
  199. before actually calling EraseImage and DrawImage, but (calculated guess time)
  200. because so many other tasks have priorities higher than Ameko they all get
  201. woken up before Ameko so by the time Ameko comes back from it's WaitTOF call
  202. the video beam is several inches down the screen. This is worse when you
  203. rapidly move the mouse, I guess because the input.device is busy handling
  204. all the new events before CPU is given to lower priority tasks.
  205.  
  206. I thought of how I could double-buffer the Ameko window but when you think
  207. that the window can be sized to full screen and with the introduction of the
  208. 'AGA' chipset can be 8-planes deep, would require, even just on a 640 x 512
  209. screen (640/8)bytes*512bytes*8planes*2buffers = 655Kb(approx) of CHIP RAM.
  210. This is plain stupid for a 'toy' like Ameko and even then there is still the
  211. problem of implementing window double-buffering. These same memory problems
  212. arise if you think about using a SuperBitMap window too.
  213.  
  214. My solution was to raise the task priority of Ameko to equal or above that
  215. of the input.device. That way, Ameko can pre-empt or at least share CPU time
  216. on an equal basis with the input.device. The flicker has all but disappeared
  217. and system performance is not noticably affected. This is achieved by the
  218. ToolType TASKPRI=21 so it's not permanently hard-coded into the program
  219. enabling people to make their own decision on task priority. I have had no
  220. problems with TASKPRI=21.
  221.  
  222. If anyone has any good ideas on another way to fix the flickering without
  223. raising task priority I would love to hear from them (details below).
  224.  
  225.  
  226.  
  227. MISCELLANEOUS (just to prove I could spell it)
  228. -------------
  229.  
  230. Any bugs, letters, ideas and suggestions would be welcome (details below).
  231.  
  232. I may well do a Kickstart 1.3 version of Ameko but this depends on the
  233. response I get from Kickstart 1.3 owners. If you are using Kickstart 1.3 and
  234. would like me to write a version of Ameko then write me a letter (don't send
  235. me any disks as I can't return them). I can't promise anything, but you
  236. never know! Alternatively, do the decent thing and upgrade to Kickstart 2.
  237. Not only will it enable you to run Ameko (your main reason for upgrading I'm
  238. sure!) but it has many benefits that are not immediately obvious and more
  239. and more software either has added features on Kickstart 2 machines or, in
  240. some cases, requires Kickstart 2. Kickstart 2 is very much like an iceberg,
  241. a little of its advantages can be seen above water like the new-look
  242. Workbench and requesters but most of its improvements and benefits are
  243. hidden below the surface and are not immediately obvious - however, they are
  244. there!
  245.  
  246.  
  247.  
  248. ACKNOWLEDGEMENTS
  249. ----------------
  250.  
  251. Dara T.Khani   - Author of the Windows version of Neko, source of
  252.                  inspiration.
  253.  
  254. Mike Coupland  - Prolific software author and great friend.
  255.  
  256. Alex Slater    - Originator of Barking Polecat Software and general all round
  257.                  good guy. Are your out there? Give me a call.
  258.  
  259. Andrew Rowe    - Sysop of Silica Systems Technical BBS (number below). Dial
  260.                  in and leave me mail or just look around.
  261.  
  262. Darren Knowles - Still working on KnowlesPaint <laughs>!?
  263.  
  264.  
  265.  
  266. AMEKO HISTORY
  267. -------------
  268.  
  269. Version 1.01, 2 February 1993.
  270.  
  271. - Changed the section of code that calculates the sleeping frames of
  272.   animation. They are now much more optimised and far less 'messy' than
  273.   v1.00. This has enabled improved control over the playback of the sleeping
  274.   animation frames, especially the speed of frame playback. Ameko no longer
  275.   hyperventilates while snoring, hurrah !
  276.  
  277. - Added the SLEEP ToolType so the user can specify how long the mouse must
  278.   remain stationary before Ameko starts falling asleep.
  279.  
  280. -------------
  281.  
  282. Version 1.00, 27 January 1993.
  283.  
  284. Initial release. (Wow, not much to tell your kids!)
  285.  
  286. -------------
  287.  
  288.  
  289.  
  290. AUTHOR
  291. ------
  292.                             //
  293. Name:         Carl Revell \X/
  294.  
  295. Modem:        +44-(0)81-309-6675
  296.  
  297. NorMail:      8 Western Road,
  298.                  MAIDSTONE,
  299.                  Kent,
  300.                  ME16 8NE,
  301.                  England.
  302.  
  303.  
  304. Have Fun !
  305.