home *** CD-ROM | disk | FTP | other *** search
/ Amiga Computing 66 / ac066a.adf / Ameko.doc < prev    next >
Text File  |  1993-08-30  |  16KB  |  405 lines
  1.  
  2.                            Ameko/Ameko_AGA v1.20
  3.  
  4.                   (C) Copyright Carl Revell, 25 July 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. Ameko_AGA
  44. REQUIRES a KICKSTART 3.0 or later equipped Amiga.
  45.  
  46. (KickStart 1.3 owners see MISCELLANEOUS section below)
  47.  
  48. Ameko has been tested on the following configurations...
  49.  
  50. Amiga 500 Plus, Amiga 600, Amiga 600HD, Amiga 1200HD (GVP 85MB Maxtor), Amiga
  51. 1500 (68000), Amiga 1500 (GVP 50MHz 68030), Amiga 1500 (GVP 28MHz 68040),
  52. Amiga 4000-030.
  53.  
  54.  
  55. Ameko_AGA has been tested on the following configurations...
  56.  
  57. Amiga 1200HD (GVP 85MB Maxtor), Amiga 4000-030.
  58.  
  59.  
  60.  
  61. USAGE
  62. -----
  63.  
  64. Ameko should at all times be run from Workbench by double-clicking on the
  65. appropriate program icon.
  66.  
  67. Kickstart 1.2/1.3 owners should really think about upgrading to KS2.
  68.  
  69. Kickstart 2.0 owners should double-click on the Ameko program icon.
  70.  
  71. Kickstart 3.0 owners should double-click on the Ameko or Ameko_AGA program
  72. icon. Ameko_AGA is preferable if running a 16 or more colour Workbench.
  73.  
  74. Ameko can be run from the CLI/Shell but was not designed with that in mind so
  75. I wouldn't do it if I were you. Anyway, you cannot adjust any startup options
  76. if running Ameko from the CLI/Shell (see ToolTypes below). The only reason
  77. alot of programs enable CLI/Shell startup (apart from use of the console) is
  78. so they can be run from the Startup-Sequence upon boot-up. Because Ameko
  79. requires Kickstart 2.0 or later, it can always be automatically run at
  80. boot-up by placing it in the WBStartup drawer of your boot disk.
  81.  
  82.  
  83.  
  84. AMEKO_AGA ADDENDUM
  85. ------------------
  86.  
  87. Yep, as promised, Ameko_AGA is here. Ameko_AGA is functionally the same as
  88. Ameko except that the Ameko kitten is `coloured-in', but it makes such a
  89. difference to the program.
  90.  
  91. Ameko_AGA can be run on a normal 4-colour Workbench or Public Screen and will
  92. look similar to the original Ameko. Preferably however, you should run Ameko
  93. on a 16 (or more) colour Workbench (See section 5-9 of the Workbench 3.0
  94. manual - ScreenMode Editor if unsure how to change screen mode). Ameko_AGA
  95. will run on an 8-colour screen, but the colours are all used by Workbench and
  96. Ameko_AGA will not change them automatically to Ameko's colours (because it
  97. would affect how your Workbench looks). You can change the kitten's colour
  98. manually on an 8-colour screen by running Prefs/Palette and changing colours
  99. 4 and 5 (the 8 colours are numbered 0-7) - use a 16+ colour screen, it looks
  100. much better and is easier too!
  101.  
  102. Ameko may look funny when opened on a public screen with more than 4 colours.
  103. This is dependent on whether the task owning the public screen lets Ameko_AGA
  104. change the colours in its palette. It is really a case of "Suck it and see."
  105.  
  106.  
  107.  
  108. TOOLTYPES
  109. ---------
  110.  
  111. Ameko can be configured to your own personal taste by modifying the icon's
  112. ToolTypes. These can be accessed by clicking once on the program icon and
  113. then either pressing Right-Amiga + I or selecting the Information... option
  114. from the Workbench Icons menu. The values that you can change and their
  115. effect are listed below. For more information on changing ToolTypes see your
  116. Amiga Workbench manual.
  117.  
  118. LEFT      = nn where nn is the number of pixels from the left edge of the
  119.             screen that the Ameko window will open up. Negative values and
  120.             values larger than your screen's width should be handled and
  121.             automatically adjusted by the program. I stress the word SHOULD.
  122.  
  123. TOP       = nn where nn is the number of pixels from the top edge of the
  124.             screen that the Ameko window will open up. Negative values and
  125.             values larger than your screen's height should be handled and
  126.             automatically adjusted by the program. I stress the word SHOULD.
  127.  
  128. WIDTH     = nn where nn is the starting width of the Ameko window in pixels.
  129.             The program should replace any stupid values (like negative or
  130.             zero width) with a reasonable default which it calculates based
  131.             on screen values. No guarantee is given that it will always
  132.             choose the correct value so I suggest sticking to sensible
  133.             values to be safe.
  134.  
  135. HEIGHT    = nn where nn is the starting height of the Ameko window in pixels.
  136.             The program should replace any stupid values (like negative
  137.             height) with a reasonable default which it calculates based on
  138.             screen font. I would suggest that you try and keep your values
  139.             for HEIGHT within sensible bounds just in case.
  140.  
  141. SLEEP     = nn where nn is the time (in seconds) that the mouse must remain
  142.             stationary before Ameko starts to fall asleep. Permissible
  143.             values for nn are 1 to 3600 seconds (1 second to 1 hour).
  144.  
  145. SOUND     = nn where nn is either YES or ON which will play a sound sample
  146.             when the Ameko window is opened and again when it is closed.
  147.  
  148.             OR
  149.  
  150.             nn where nn is either OFF or NO which will disable the playing
  151.             of a sound sample when the Ameko window is opened and closed.
  152.  
  153. PUBSCREEN = <name> where <name> is the name of a Public Screen. Ameko will
  154.             open up on a Public Screen of your choice enabling you to use
  155.             Ameko with your favourite WP or COMMS package, etc. If no
  156.             PUBSCREEN ToolType is supplied or the requested screen is not
  157.             available then Ameko will conveniently open up on the Default
  158.             Public Screen which is invariably Workbench.
  159.             Ameko_AGA may behave unpredictably on public screens other
  160.             than Workbench. See Ameko_AGA ADDENDUM above for more details.
  161.  
  162. SIZE      = <nn> where <nn> is either BIG or SMALL. You may have heard that
  163.             size isn't important, but in this case, it can be! Select the
  164.             setting which looks best on your display. BIG is best for
  165.             non-interlaced displays and SMALL is best for interlaced mode.
  166.  
  167. DONOTWAIT = This is really only to tell Workbench not to wait for the
  168.             program's return if you put it in the WBStartup drawer on your
  169.             boot device. If you don't already know, any programs placed into
  170.             the WBStartup drawer are automatically run when Workbench is
  171.             loaded which means you can drag the Ameko/Ameko_AGA icon into
  172.             your WBStartup drawer on your boot disk and let the little fella
  173.             run riot automatically, every time you boot up your Amiga. It's
  174.             best not to alter or delete this ToolType unless you know what
  175.             you're doing.
  176.  
  177. TOOLPRI   = Amiga beginners need not read this section, just leave the
  178.             ToolType set to it's default value which is 21.
  179.             If you are interested, this sets the Task Priority of Ameko above
  180.             all others (on my system anyway) which I found necessary to
  181.             reduce the flickering which occurred when the mouse was moved
  182.             around a lot (see TECHNICAL SECTION below). I found no problem
  183.             with speed or operation of my Amiga with this high task priority,
  184.             but if you experience any difficulties then by all means raise or
  185.             lower this value appropriately. Remember, +127 is the highest
  186.             priority, -128 is the lowest and most normal programs should be
  187.             set to TASKPRI 0. I am increasingly disillusioned by the fact
  188.             that the flickering may not be reduced as much as I though with
  189.             this ToolType. To be frank, I just don't know!
  190.  
  191. If for some obscure reason you wish to disable a particular ToolType, you
  192. can simply enclose it within a pair or angled brackets. For instance, to
  193. disable the LEFT=50 ToolType, just change it to <LEFT=50>. This is an
  194. excellent way to disable ToolTypes, whilst still enabling you to see the
  195. syntax of ToolTypes so you don't forget that it is LEFT=nn and not
  196. WINLEFT=nn, etc..
  197.  
  198. Ameko has built-in defaults for most of the ToolTypes in case any get
  199. completely deleted from the icon. They are...
  200.  
  201. LEFT       = 32
  202. TOP        = 32
  203. WIDTH      = 100
  204. HEIGHT     = 100
  205. SLEEP      = 5 (seconds)
  206. SOUND      = ON
  207. SIZE       = SMALL
  208. <PUBSCREEN =>
  209.  
  210.  
  211.  
  212. TRICKS AND TIPS
  213. ---------------
  214.  
  215. If you select the Ameko window by clicking once within its boundaries, then
  216. you have the ability to send Ameko straight to sleep and also stop him from
  217. chasing the mouse pointer. You do this by clicking once with your right
  218. mouse button. To wake him up again and let him chase the mouse pointer just
  219. click the right mouse button again. Remember, you must select the Ameko
  220. window first for this feature to work.
  221.  
  222.  
  223.  
  224. TECHNICAL SECTION
  225. -----------------
  226.  
  227. Not really a technical section, more a chance for me to explain why part of
  228. the program is written the way it is and to ask for advice from anyone who
  229. 'knows their onions' when it comes to programming.
  230.  
  231. The program is written in 'C' and although I can program in 680x0 assembler
  232. (software houses, my details are below!) I considered 'C' to be the best
  233. choice. I may recode some or maybe all of the program in 680x0 at a later
  234. date, but it does just fine for now.
  235.  
  236. Basically, a window is opened and then the program is sent to sleep, waiting
  237. on either a CloseWindow message or a timed delay message sent from the
  238. timer.device. So, when the program isn't calculating Ameko's position or
  239. actually drawing him, then it is Waiting and allowing other tasks to get
  240. their share of the CPU. If the TaskPri is set to anything below the
  241. input.device (20 on my system) then the Ameko graphics 'flicker' within a
  242. certain (but not always stationary) area of the screen. Ameko does a WaitTOF
  243. before actually calling EraseImage and DrawImage, but (calculated guess time)
  244. because so many other tasks have priorities higher than Ameko they all get
  245. woken up before Ameko so by the time Ameko comes back from it's WaitTOF call
  246. the video beam is several inches down the screen. This is worse when you
  247. rapidly move the mouse, I guess because the input.device is busy handling
  248. all the new events before CPU is given to lower priority tasks.
  249.  
  250. I thought of how I could double-buffer the Ameko window but when you think
  251. that the window can be sized to full screen and with the introduction of the
  252. 'AGA' chipset can be 8-planes deep, would require, even just on a 640 x 512
  253. screen (640/8)bytes*512bytes*8planes*2buffers = 655Kb(approx) of CHIP RAM.
  254. This is plain stupid for a 'toy' like Ameko and even then there is still the
  255. problem of implementing window double-buffering. These same memory problems
  256. arise if you think about using a SuperBitMap window too.
  257.  
  258. My solution was to raise the task priority of Ameko to equal or above that
  259. of the input.device. That way, Ameko can pre-empt or at least share CPU time
  260. on an equal basis with the input.device. The flicker has all but disappeared
  261. and system performance is not noticably affected. This is achieved by the
  262. ToolType TASKPRI=21 so it's not permanently hard-coded into the program
  263. enabling people to make their own decision on task priority. I have had no
  264. problems with TASKPRI=21.
  265.  
  266. If anyone has any good ideas on another way to fix the flickering without
  267. raising task priority I would love to hear from them (details below).
  268.  
  269.  
  270.  
  271. MISCELLANEOUS (just to prove I could spell it)
  272. -------------
  273.  
  274. Any bugs, letters, ideas and suggestions would be welcome (details below).
  275.  
  276. Thanks for all the people who have written to me to show their appreciation
  277. for Ameko. Sorry to those Kickstart 1.3 owners who requested a KS1.3 version
  278. of Ameko for not currently having coded one, but all is not lost and one
  279. might still surface!
  280.  
  281.  
  282.  
  283. ACKNOWLEDGEMENTS
  284. ----------------
  285.  
  286. Dara T.Khani   - Author of the Windows version of Neko, source of
  287.                  inspiration.
  288.  
  289. Mike Coupland  - Prolific software author and great friend.
  290.  
  291. Giles McArdell - Great GFX man, who so promptly `coloured-in' the Ameko
  292.                  kitten for me enabling a swift release of Ameko_AGA.
  293.  
  294. Alex Slater    - Originator of Barking Polecat Software and general all round
  295.                  good guy. So you wrote to me; I wrote back and since then
  296.                  I've heard no more. Please write/phone again!
  297.  
  298. Andrew Rowe    - Sysop of Silica Systems Technical BBS (number below). Dial
  299.                  in and leave me mail or just look around.
  300.  
  301. Darren Knowles - Still working on KnowlesPaint <laughs>!?
  302.  
  303.  
  304.  
  305. AMEKO HISTORY
  306. -------------
  307.  
  308. Version 1.20, 27 July 1993.
  309.  
  310. - Added the PUBSCREEN ToolType to Ameko can be opened on a Public Screen
  311.   enabling user's to have Ameko on their WP program, etc...
  312.  
  313. - Added the SIZE ToolType and incorporating the once two seperate programs
  314.   Ameko and Ameko_Lo into one executable. Program size is increased but
  315.   flexibility is gained in doing so and makes distribution and compilation
  316.   alot easier for me!
  317.  
  318. - Changed the way Layers are handled during window resizing. All apparent
  319.   reported bugs (Ameko drawn in window border) seem to have been cleared up,
  320.   although I suggest program performance has been compromised 8-( I will, of
  321.   course try and achieve a better solution.
  322.  
  323. -------------
  324.  
  325. Version 1.01, 2 February 1993.
  326.  
  327. - Changed the section of code that calculates the sleeping frames of
  328.   animation. They are now much more optimised and far less 'messy' than
  329.   v1.00. This has enabled improved control over the playback of the sleeping
  330.   animation frames, especially the speed of frame playback. Ameko no longer
  331.   hyperventilates while snoring, hurrah !
  332.  
  333. - Added the SLEEP ToolType so the user can specify how long the mouse must
  334.   remain stationary before Ameko starts falling asleep.
  335.  
  336. -------------
  337.  
  338. Version 1.00, 27 January 1993.
  339.  
  340. Initial release. (Wow, not much to tell your kids!)
  341.  
  342. -------------
  343.  
  344.  
  345.  
  346. AMEKO_AGA HISTORY
  347. -----------------
  348.  
  349. Version 1.20, 27 July 1993.
  350.  
  351. - Initial release, functions as Ameko v1.20 but in colour!
  352.  
  353. - Released in conjunction with Ameko v1.20 and with the same version number.
  354.   Has the same features as Ameko v1.20 but Ameko is now in colour! From now
  355.   on, Ameko and Ameko_AGA are to be treated as totally separate programs
  356.   whose version numbers should increase independently.
  357.  
  358. ------------
  359.  
  360.  
  361.  
  362. CONTACT US AT...
  363. ----------------
  364.  
  365. I am looking for artwort/ideas to inspire future projects, maybe even
  366. commercial if they're good enough. Please feel free to send me your ideas for
  367. programs or samples of your artwork at the address below.
  368.  
  369. I can be contacted from the following information for bug reports, ideas,
  370. money (dream on), examples of your productions - code, art, music etc...
  371.  
  372. The programmer/artist who so brilliantly 'coloured in' the Ameko graphics
  373. can also be contacted with samples of your work or your appreciation at
  374. the address below.
  375.  
  376.  
  377.  
  378. AUTHOR
  379. ------
  380.                             //
  381. Name:         Carl Revell \X/
  382.  
  383. Modem:        +44-(0)81-309-5258
  384.  
  385. SnailMail:    8 Western Road,
  386.               MAIDSTONE,
  387.               Kent,
  388.                  ME16 8NE,
  389.                  England.
  390.  
  391.  
  392. GFX MAN (the guy who so expertly 'painted' the colour version of Ameko)
  393. -------
  394.  
  395. Name:         Giles McArdell
  396.  
  397. SnailMail:    12 Upton Road,
  398.               BEXLEYHEATH,
  399.               Kent,
  400.               DA6 8LQ,
  401.               England.
  402.  
  403.  
  404. Have Fun !
  405.