17 Bit Software 2: Collection B

home *** CD-ROM | disk | FTP | other *** search

/ 17 Bit Software 2: Collection B / 17Bit_Collection_B.iso / files / 2175.dms / in.adf / ASwarm3 / ASwarm3.doc < prev next >

Wrap

Text File | 1992-07-09 | 17.2 KB | 492 lines

ASwarm III Manual NAME ---- SYS:WBStartup/ASwarm3 SYNOPSIS -------- ASwarm3 CX_POPKEY=<HotKey> CX_POPUP=<YES | NO> BLANKKEY=<HotKey> TIMEOUT=<1 - 3600> CLIENTTIMEOUT=<1 - 60> DISPLAY=<Display Type> WASPS=<1 - 20> BEES=<1 - 100> SPEED=<1 - 5> TIGHTNESS=<1 - 11> DESCRIPTION ----------- ASwarm is a screen blanker with two levels of protection, the first of which is an animation of bees chasing wasps, hence "swarm". The second level of protection will erase this animation if it cannot be displayed at a reasonable rate in order to prevent the animation itself from burning into the screen. SOURCE ------ The source code is included, and can be compiled with SAS/C 5.10a or with a registered copy of DICE V2.06.37. COPYING PRIVELIGES ------------------ ASwarm is free to be spread on public-domain and shareware disks, as long as they are sold for labor and diskette cost only - the software itself may not be sold. For use in commercial products, the permission of the author is required. ASwarm may be copied and distributed via electronic networks such as the Internet. It may also be placed on anonymous FTP servers, mailboxes or bulletin board systems. SUPPORT ------- Jake "Wulf" Rose # Version III INTERNET: jaker@csugrad.cs.vt.edu Markus Illenseer # DICE Gro_e Kurf|rstenstra_e 1 D-4800 Bielefeld 1 Germany INTERNET: markus@techfak.uni-bielefeld.de IRC: ill Matthias Scheler # Server-client model info Alter Milchhof 10 D-4400 M|nster Germany INTERNET: tron@uni-paderborn.de IRC: Tron Please refer to "COMMON PROBLEMS" before you contact anyone for a bug report. Of course, any comments are appreciated. PURPOSE AND THEORY ------------------ ASwarm is a screenblanker. The animation during blanking phase is loosely based upon Jeff Buterworth's "xswarm" for the X11 Windowing System. A screen blanker's goal should be to blank (disable) the screen output in order to prevent burning images into the monitor's phosphor. As it is boring just to disable the screen, and as the Amiga can handle multitasking, we are able to animate objects on the screen for entertainment, or simply as a reminder that the monitor is on. The problem with doing this is, of course, that the animations displayed could also burn-in the monitor. This could happen when the screenblanker doesn't have enough time to draw and the graphics rest in the same place for long periods of time. When the screen blanker doesn't have enough CPU time, it's because there is a CPU-intensive program, such as a ray-tracer or C-compiler, running. As the screenblanker isn't as important to the user as the monitor, the blanker draws the graphics only when it has CPU time. When it doesn't, the screenblanker's draw routine is disabled and the screen is literally blanked (black) until it regains CPU time. This is done with a simple server-client model. The server runs with a normal priority, but just has a WaitPort()-loop (No real CPU-use) to detect the time-out and to detect the amount of CPU time. The client is started when the server reaches the TIMEOUT. The client runs with a low priority. When the server reaches the CLIENTTIMEOUT and finds that the client wasn't able to draw anything, the screen is blacked out. In order to reduce the amount of CPU time that the screenblanker itself uses, accuracy in the display was sacrificed by only using integer mathematics. The difference in the animation itself is not particularly noticeable. VERSION ------- To prevent a version war, the originators renamed "ASwarm" "ASwarm II". There are some other versions of xswarm available for the Amiga, such as ASwarm, the IPC-Port-Blanker for DMouse, and Swarm. To further prevent the version war, I've renamed "ASwarm II" "ASwarm III". There are too many changes to list here, but the most important are that the swarm movement routines were rewritten so that there are no defined swarms - instead, there are a number of bees and a number of wasps, and they form their own swarms naturally - and that the user interface on the option panel was significantly improved. I've also rewritten much of this manual to reflect the changes that I have made as well as to correct mistakes that existed in the original document (primarily grammatical and spelling errors, but there were also some technical errors and some important information was left out). As ASwarm can be compiled with either DICE or SAS/C, you can detect the Version with "version ASwarm FULL" from the CLI. It will show you the compiler used. The default is SAS/C. STARTING -------- ASwarm is a Commodity, therefore it only runs under WB Release 2.0 (V37.175) and higher. A commodity is normally started in the WBStartup drawer so that it will load automatically upon boot-up. Just copy ASwarm3 and ASwarm3.info to SYS:WBStartup (or drag its icon to the WBStartup drawer). To get ASwarm started without rebooting, double-click on its icon. If the Tool Types aren't yet changed, a window is displayed. This is the "option panel" of ASwarm. ASwarm is now started. After 60 seconds of keyboard, mouse, and other input device inactivity, the screen will be blanked. You can start ASwarm from the CLI or another shell. For example you can start ASwarm in the S:User-Startup file: RUN >NIL: <NIL: ASwarm3 CX_POPUP=NO The arguments for CLI-Start are exactly the same as the ToolTypes for the WB-start. ARGUMENTS --------- As does every good Commodity, ASwarm supports Tool Type entries. Click on the ASwarm icon and press Right-Amiga and i to change or add a ToolType entry. In the ToolType list there is (per default) entered: DONOTWAIT # Tell WB to not wait on a return CX_POPUP=YES # Display the window when starting STARTPRI=-120 # low priority for starting These ToolTypes are the normal way to give arguments for Commodities and pure WB-programs. Please refer to your AmigaDOS Manual (Section Workbench Programs especially chapter The WBStartup Drawer) to get an idea of how the ToolType entries work. TOOL TYPES: DONOTWAIT When started from WBStartup, this lets WB know that it shouldn't wait for ASwarm to finish (ASwarm keeps running). STARTPRI=-120 When started from WBStartup, this is the starting prioritiy of ASwarm. CX_POPKEY=<HotKey> Please see below for HotKey definitions. CX_POPKEY's HotKey combination opens the option panel of ASwarm. CX_POPUP=<YES | NO> When ASwarm is started, the option panel may be displayed when set to "YES" or *any* other String than "NO". BLANKKEY=<HotKey> Please see below for HotKey definitions. BLANKKEY's HotKey combination instantly blanks the screen at any time. TIMEOUT=<1 - 3600> This sets the amount of time over which no input events may occur in order for the screen to blank. CLIENTTIMEOUT=<1 - 6> This sets the amount of time during which the animation is frozen that will cause the screen to be blacked out. DISPLAY=<Display Type> Please see below for the display types. WASPS=<1 - 20> The number of wasps (leaders). BEES=<1 - 100> The number of bees (followers). SPEED=<1-5> The speed (5 is fastest) of the display TIGHTNESS=<1 - 11> The closeness with which the bees chase the wasps. NOTE: ToolTypes are case-sensitive, so make sure your capitalization matches that shown above. HOT KEYS -------- Refer to your AmigaDOS Manual ("The Extras Programs/The Commodities Drawer") to get a valid list of the available hot keys, the following may be obsolete with a new Commodities.library version: SYNOPSIS: [<qualifier> [<qualifier>...]] <key> Qualifier keywords (Press and hold one or more qualifier) alt either Alt key ralt right Alt key lalt left Alt key shift either Shift key rshift right Shift key lshift left Shift key capslock Caps Lock key rcommand right Amiga key lcommand left Amiga key control Control key numericpad Enables the use of a key on the numeric keypad rbutton Click (and hold) the right mouse button midbutton Click (and hold) the middle mouse button (only avail for mice with a connected third button!) leftbutton Click (and hold) the left mouse button newprefs Preferences changed diskremoved Disk removed diskinserted Disk inserted Keys (to be pressed and released, only ONE Key can be chosen) a .. z, 0 .. 9, etc. Normal keys f1 .. f10 Function keys up, down, left, right Cursor keys help Help key del Delete key return Return key enter Enter key (MUST be combined with 'numericpad'!) backspace Backspace key esc Escape key space Space key comma Comma key upstroke Upstroke key Examples lalt ralt enter ramiga f10 alt x lalt numericpad enter NOTE: Choose your hotkeys carefully. Commodities have a high priority in the input events chain and will override existing definitions. Some hotkeys also don't make sense or will collide with other tools or functions. NOTE: The workbench screen will be moved to front when the options panel is brought up with the HotKey. NOTE: When a combination of qualifiers and keys is illegal, ASwarm will NOT start (and will NOT display an error-code). Example for illegal combinations: lalt a b # Two keys specified leftbutton # No key specified control lcommand rcommand # Reboots the system (oops!) EDIT WINDOW ----------- When CX_POPUP is set to "YES" and ASwarm is being started, or when the HotKey was pressed, the option panel is displayed on the Workbench. You will see some gadgets and a scrollable list of display modes. TIMER: The value for the timeout of the blanker. After this time (in seconds) the blanker will display the swarm. TIMER may have a value between between 1 and 3600. CLIENT TIMEOUT: The time the server gives to the client for not being able to draw anything, after which the screen will be blacked out to prevent burn-ins. TIGHTNESS: The proximity of the bees to the wasps being chased. (the higher the tightness, the closer they chase) SPEED: The timeslice to use in calculating the new positions of the wasps and bees. It does not actually affect display performance. WASPS: The number of wasps (leaders). BEES: The number of bees (followers). HIDE: (click or press 'h') Hide the window. ASwarm will continue to run and retain the current settings. BLANK: (click or press 'b') Blank immediately. All then new entered values will be stored and activated. QUIT: (click or press 'q') Quit. ASwarm will be removed from memory, losing any changes which you haven't added to the tool types. DISPLAY MODE: (Please refer to the notes below!) Choose a desired Mode for the Display during blank-time. Use the scroll-bar to display other available modes. This depends on the used system. COMMODITIES EXCHANGE -------------------- With the Exchange tool, you can temporarly disable or permanently kill ASwarm and other commodities. Please refer to the AmigaDOS Manual (Section AmigaDOS Reference and Workbench Programs) for further information on Exchange. DISPLAY MODES ------------- Please have care here! We are *not* responsible for *any* user errors. The given list depends on the system used. All newer Amigas, such as A500+ and A3000 have the ECS Denise for extended Screen Modes (Not all Amigas with Kick 2.0 on ROM have a ECS Denise.). Of course, you can start the desired Modes, but not all modes are available on all monitors! Please refer to the manual of your monitor and to the AmigaDOS manual (Section Workbench Programs, AddMonitor) for more information. Why? Simply because you can *destroy* your Monitor! The following are the standard display modes: NTSC or Multiscanning display required -------------------------------------- NTSC:Lores NTSC:Hires NTSC:SuperHires NTSC:Lores-Interlaced NTSC:Hires-Interlaced NTSC:SuperHires-Interlaced PAL or Multiscanning display required ------------------------------------- PAL:Lores PAL:Hires PAL:SuperHires PAL:Lores-Interlaced PAL:Hires-Interlaced PAL:SuperHires-Interlaced Multiscanning display required ------------------------------- VGA-ExtraLores VGA-ExtraLores-Interlaced VGA-Lores VGA-Lores-Interlaced Productivity Productivity-Interlaced A2024 or multiscanning display required --------------------------------------- A2024_10Hz A2024_15Hz Overscan is used in all modes. You can adjust your overscan-size with the ScreenMode preference tool. NOTE: Do not use VGA modes on a non-multiscanning or non-VGA-Monitor Do not even test modes if you aren't sure about your monitor's capabilities. NOTE: Productivity mode will provide the smoothest animation of any of the modes, as it is high-resolution and non-interlaced. COMMON PROBLEMS --------------- - ASwarm does not run if Workbench wasn't started because it needs the Mode Names to be installed. This normally done by an Icon called "Mode_Names" placed in the WBStartup directory. You will have to setup these manually with "BindMonitor" if you don't use the Workbench. - If you're running ARQ 1.6 or below, try the following: Change the timeout to a low value (eg 5 seconds), then type in the CLI: wait 10 <RETURN> (do not wait for the prompt) dir bafasel: <RETURN> (device blafasel: nonexisting) ASwarm will blank as usual, but then ARQ pops up a requestor ON the ASwarm-Screen! You can't close the Screen until you click on "Abort", and ASwarm can't blank the screen anymore, either! (Its CloseScreen() Command waits for the succesful return...) This is a bug in ARQ! It's dangerous in some cases, and may burn the image of the requestor into the display. Martin Laubach, the author of ARQ, is being contacted. - You are running a C-Compiler or a raytracer. ASwarm goes blank and doesn't show the swarm, but during disk access the swarm comes up for a while. This is not a bug, this is a feature of ASwarm! This is the way ASwarm blanks when the system is under high CPU load. Since CPU usage during disk access is generally low, it may start the animation again during these times. - Collision with other Blankers. You may run as many blankers as you want, such as Dmouse, Spliner, and FracBlanc. ASwarm always tries to move its screen to front when it detects that it's behind another. - When a disk is inserted, ASwarm "unblanks". This is normal. Disk-replacement is detected as an input event. As all input events disable the blanker, this one does as well. - ASwarm doesn't start, though it's been placed in WBStartup. There are two reasons why this might happen. First, make sure that ASwarm's STARTPRI ToolType value is negative. This is to insure that the Workbench runs ASwarm after having run Mode_Names, which has no STARTPRI ToolType and therefore defaults to 0. Another possibility is that an illegal combination of hot keys was used. Enter new ones with the CX_POPKEY and BLANKKEY ToolTypes, and be sure to test them. - ASwarm displays the window though the Tool Type CX_POPUP is set to 'NO'. This happens when ASwarm is started when it's already running. - ASwarm makes a noise when it blanks the screen. This may happen when a display mode is chosen for the blanker that is different from the one currently on-screen. It's perfectly normal and is no danger. - ASwarm makes flickers on the monitor when it blanks the screen. This happen when ASwarm blanks to a PAL screen, but the screen it cleared was NTSC (or vice-versa). The monitor needs a bit of time to synchronize. Again, nothing dangerous. MY CREDITS ---------- Markus Illenseer and Matthias Scheler for not only porting a most excellent program to AmigaDOS and doing a nice job of it, but also for giving me the source code to muck with. Thanks a lot! Chris Fury, Paul Miller and others for beta-testing ASwarm III. ARUS, The Amiga User Group at Virginia Tech, for 2.0 support. Windex window-washing liquid, for having such a funny name that happens to also abbreviate "Wasp Index". Douglas Adams, for the Hitchhiker's Guide. I would have been lost without it (some would argue that I'm lost anyway). THEIR CREDITS (syntax edited, semantics intact) ------------- Jeff Buterworth for his xswarm routine available for X11. Matt Dillon for Dice. So we could make ASwarm be compilable with the most common low-cost C-Compiler. SAS-C group for well done work. As yet the SAS version of ASwarm is faster and shorter... IRC-guys in Oulu to make world-wide communication easy and to be able to chat about programmings ideas. (...and schlamm bugs!) AUGUP, Amiga Group of Uni Paderborn, for their beta-testings. Commodore Amiga group for this great system. Hope to see some great new stuff this year! Dire Straits for the background music.