home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 616.lha / ASwarmII_v1.1 / ASwarm.doc.pp / ASwarm.doc
Text File  |  1992-03-01  |  19KB  |  513 lines
  1.         ASwarm II V1.1 - Manual
  2.  
  3.  
  4. NAME
  5.     SYS:WBStartup/ASwarm
  6.  
  7. SYNOPSIS
  8.     ASwarm    CX_POPKEY=<Hot Key>
  9.         CX_POPUP=<YES | NO>
  10.         TIMEOUT=<1 - 3600>
  11.         CLIENTTIMEOUT=<1 - 60>
  12.         DISPLAY=<Display Type>
  13.         WASPS=<1 - 10>
  14.         BEES=<1 - 500>
  15.         CYCLE=<YES | NO>
  16.         AIM=<YES | NO>
  17.         SPEED=<1 -4>
  18.  
  19. DESCRIPTION
  20.     Screenblanker with high security, does not burn in the graphic
  21.     into the screen. Is funny to watch. Runs only under Release 2.0
  22.     of Workbench.
  23.  
  24. SOURCE
  25.     The source code is included, it can be compiled with SAC/S 5.10a or
  26.     with Dice V2.06.37 (registered version only) (or newer).
  27.  
  28. COPYRIGHT
  29.     ASwarm is free to be spread on public-domain and shareware disks, as
  30.     long as they are sold for a reasonable charge that is less than $6 or
  31.     DM 8,-. For use in commercial products the permission of the author is
  32.     required.
  33.     ASwarm may be copied and distributed via electronic networks such
  34.     as the Internet, also it may be moved on anonymous ftp-servers,
  35.     mail-boxes or BBS's.
  36.  
  37. AUTHOR & SUPPORT
  38.     Markus Illenseer            # Graphic routines
  39.     Große Kurfürstenstraße 1        # Documentation
  40.     D-4800 Bielefeld 1            # Dice Support
  41.     Germany
  42.     INTERNET: markus@techfak.uni-bielefeld.de
  43.     ZERBERUS: markus%techfak.uni-bielefeld.de@uucp.zer
  44.     IRC: ill
  45.  
  46.     Matthias Scheler            # Server-Client modell
  47.     Alter Milchhof 10            # Source
  48.     D-4400 Münster                # SAS/C Support
  49.     Germany
  50.     INTERNET: tron@uni-paderborn.de
  51.     ZERBERUS: tron%uni-paderborn.de@uucp.zer
  52.     IRC: Tron
  53.  
  54.     SUPPORT FTP ADDRESS:
  55.     ftp.uni-paderborn.de (131.234.2.32) anonymous access.
  56.  
  57.     Please first refer to 'KNOWN PROBLEMS' below, before you contact
  58.     us for a Bug-report, any comment is welcomed.
  59.  
  60. CHANGES
  61.  
  62.    For those who already know ASwarm II V1.0 just the changing points.
  63.    ASwarm II V1.1 has these new features:
  64.     AIM - Mode added. Now the bees search for the nearest Wasp.
  65.     CYCLE - Colorcycling of the bees can be disabled now.
  66.     SPEED - 5 Speed modi added.
  67.     WASPS formerly SWARMS, both Tool Types are accepted.
  68.           There are no Swarms in the AIM mode and the Number of bees
  69.           is been divided to the wasps.
  70.     BEES - Now contains the COMPLETE Number of Bees.
  71.     HOT KEY - If wrong, ASwarm shows that as '<NONE>' in the Edit-Window.
  72.    Speed improvement. New Gfx-Routines. Proper Messagehandling.
  73.    Smaller Code. New Docs.
  74.  
  75.  
  76. PURPOSE & THEORY
  77.     ASwarm is a screenblanker. The graphic during blanking phase is based
  78.     upon Jeff Buterworth's 'XSwarm' for X11-Windows.
  79.  
  80.     A screenblankers goal should be to blank (disable) the screenoutput
  81.     and to prevent burning in pixels or ghosted pictures on    the Monitor.
  82.  
  83.     As it is boring just to disable the screen, and as the Amiga can
  84.     handle multitasking, we could also draw some funny stuff while blanking
  85.     the screen. Only problem is that, when we draw something, we must take
  86.     care that our drawing doesn't itself burns into the monitor.
  87.  
  88.     This usually happens, when the screenblanker has not enough time
  89.     to draw, so the graphics rest on the same place. When the
  90.     screenblanker has not enough Cpu-time, it's because there is another
  91.     cpu-greedy programm, such as a raytracer or C-compiler.
  92.  
  93.     Well, as the screenblanker isn't important for the user, we found
  94.     a way to manage both cases: Screenblanker has Cpu-Time or not.
  95.     When he has Cpu-Time, the blanker draws the funny graphics, when
  96.     he hasn't, the screenblanker-draw routine is disabled and the screen is
  97.     really blanked (black) until he gains back Cpu-Time.
  98.  
  99.     This is done with a simple server-client modell. The server runs
  100.     with a normal priority, but just has a WaitPort()-loop (No real
  101.     Cpu-use !) to detect the time-out and to detect the amount of Cpu-time.
  102.     The client is started when the server reached the TIMEOUT, the client
  103.     runs with a low priority. When the server reached the CLIENTTIMEOUT and
  104.     remarks that the client wasn't able to draw anything, then the screen
  105.     is really blanked.
  106.  
  107.    There was a discussion on comp.sys.amiga.misc for Screenblankers,
  108.    at all, i found that ASwarm completely fits on the demanded Features
  109.    and Requirements.
  110.  
  111. VERSION
  112.     To prevent a Version War, we renamed ASwarm to ASwarm II .
  113.     There are some other versions of ASwarm or Swarm available, such
  114.     as ASwarm as IPC-Port-Blanker for DMouse, written by
  115.     Markus Illenseer (written in KickPascal, available with Source
  116.     on demand), or Swarm by Nescum (sorry, dunno his real name), with
  117.     assembler subroutines for the drawing, unfortunately not with the
  118.     multiple-swarm option, and not based on the original routines.
  119.  
  120.     As ASwarm can be compiled with DICE _and_ (or) SAS/C, you can
  121.     detect the Version with: (CLI) Version ASwarm full
  122.     It will show you the used compiler. Default is SAC/S.
  123.     Also the size of the binary should differ:
  124.         13176  Bytes for the DICE version.
  125.         10808  Bytes for the SAS/C version.
  126.  
  127. STARTING
  128.     ASwarm is a COMMODITY, therefore it _only_ runs under WB Release
  129.     2.0 (V37.175) and higher. A Commodity is normally started in the
  130.     WBStartup-drawer. So it will be automatically started on the WB-start
  131.     (LoadWB, usually in the startup-sequence).
  132.     So, just copy ASwarm and ASwarm.info to SYS:WBStartup.
  133.  
  134.     To get ASwarm started without rebooting now, double-click the icon.
  135.     If the Tool Types aren't yet changed, a window shows up.
  136.     This is the 'Edit-window' of ASwarm.
  137.  
  138.     Now click on the Gadget 'Hide' or the 'Close-Gadget' to close
  139.     the window.
  140.  
  141.         ASwarm is now started. After 60 seconds the screen will be
  142.     blanked, of course only when the user doesn't touch the keyboard or
  143.     the mouse.
  144.  
  145.     You can start ASwarm from the CLI or another Shell.
  146.     For example you can start ASwarm in the S:User-Startup:
  147.         RUN >NIL: <NIL: ASwarm CX_POPUP=NO
  148.  
  149.     The arguments for CLI-Start are exactly the same as the Tool Types
  150.     for the    WB-start.
  151.  
  152. ARGUMENTS
  153.     As every good Commodity, ASwarm supports Tool Type entries.
  154.     Click the ASwarm.info and press Right-Amiga and i to change or
  155.     add a Tool Type entry.
  156.  
  157.     In the Tool Type list there is (per default) entered:
  158.  
  159.         CX_POPUP=YES        # Show up the window when starting
  160.         DONOTWAIT        # Tell WB to not wait on a return
  161.         STARTPRI=-120        # low priority for starting
  162.  
  163.     These Tool Types are the normal way to give arguments for Commodities
  164.     and pure WB-programms.
  165.     Please refer also to your AmigaDOS Manual (Section Workbench Programms
  166.     especially chapter The WBStartup Drawer) to get an idea of the Tool
  167.     Types entries.
  168.  
  169. TOOL TYPES
  170.         DONOTWAIT        When started from WBStartup, let
  171.                     WB know that it doesn't have to wait
  172.                     for ASwarm.
  173.  
  174.         STARTPRI=-120        When started from WBStartup, this
  175.                     is the starting prioritiy of ASwarm.
  176.  
  177.         CX_POPKEY=<Hot Key>    Please see below for the Hotkeys.
  178.                     The hotkey opens the Edit-Window
  179.                     of ASwarm.
  180.  
  181.         CX_POPUP=<YES | NO>    When ASwarm is started, the Edit-
  182.                     Window may show up when set to
  183.                     'YES' or any (!) other String
  184.                     than 'NO'.
  185.  
  186.         TIMEOUT=<1 - 3600>    This is the timeout counter in
  187.                     seconds. During this time NO input
  188.                     from the user must recognize in order
  189.                     to start the blanker. Usual time is
  190.                     about 60 secs.
  191.  
  192.         CLIENTTIMEOUT=<1 - 6>   After this time, the server
  193.                     disables the screen, he has then
  194.                     remarked that the client can't draw
  195.                     anything due of Cpu-time. Usual
  196.                     time is about 5 secs.
  197.  
  198.         DISPLAY=<Display Type>    Please see below for the Display Types.
  199.                     Here you can change the size of the
  200.                     screen on which ASwarms draws.
  201.  
  202.         WASPS=<1 - 10>        The number of drawn Wasps.
  203.  
  204.         BEES=<1 - 500>        The number of bees.
  205.  
  206.         AIM=<YES | NO>        Search-the-nearest-Wasp mode enabeld.
  207.  
  208.         SPEED=<1 - 4>        Slow down ASwarm. 4 is maximum speed.
  209.  
  210.         CYLCE=<YES | NO>    Disable the Colorcycling of the bees.
  211.  
  212. HOT KEYS:
  213.     Refer to your AmigaDOS Manual (Section The Extras Programs,
  214.     The Commodities Drawer) to get a valid list of the available hot
  215.     keys, the following may obsolete on a new "commodities.library"
  216.     version.
  217.  
  218.     SYPNOSIS:  [<qualifier> [<qualifier>...]] <key>
  219.  
  220.         Qualifier keywords (Press and hold one or more qualifier)
  221.  
  222.         alt           either Alt key
  223.         ralt          right Alt key
  224.         lalt          left Alt key
  225.         shift         either Shift key
  226.         rshift        right Shift key
  227.         lshift        left Shift key
  228.         capslock      Caps Lock key
  229.         rcommand      right Amiga key
  230.         lcommand      left Amiga key
  231.         control       Control key
  232.         numericpad    Enables the use of a key on the numeric keypad
  233.         rbutton       Click (and hold) the right mouse button
  234.         midbutton     Click (and hold) the middle mouse button
  235.                       (only avail for mice with a connected third button!)
  236.         leftbutton    Click (and hold) the left mouse button
  237.         newprefs      Preferences changed
  238.         diskremoved   Disk removed
  239.         diskinserted  Disk inserted
  240.  
  241.  
  242.         Keys (to be pressed and released, only ONE Key can be chosen)
  243.  
  244.         a .. z, 0 .. 9, etc.   Normal keys
  245.         f1 .. f10              Function keys
  246.         up, down, left, right  Cursor keys
  247.         help                   Help key
  248.         del                    Delete key
  249.         return                 Return key
  250.         enter                  Enter key
  251.                     (MUST be combined with 'numericpad'!)
  252.         backspace              Backspace key
  253.         esc                    Escape key
  254.         space                  Space key
  255.         comma                  Comma key
  256.         upstroke               Upstroke key
  257.  
  258.  
  259.         Examples
  260.  
  261.         lalt ralt return
  262.         rcommand f10
  263.         alt x
  264.         lalt numericpad enter
  265.  
  266.  
  267.    NOTE: Choose your hotkeys CAREFULLY, because Commodities have a high
  268.      priority in the input events chain (i.e. will override existing
  269.      definitions). Also some hotkeys don't make sense or do collide
  270.      with other tools or functions of the WB.
  271.  
  272.    NOTE: The Workbench screen will be moved to front before starting the tool
  273.      via HotKey.
  274.  
  275.    NOTE: When a combination of qualifiers and keys is illegal, ASwarm
  276.      will start, but the Hot Key won't work.
  277.      Example for illegal combinations:
  278.         lalt a b            # Two keys specified
  279.         control rcommand lcommand    # trivial :-)
  280.         lbutton             # No key specified
  281.  
  282.  
  283. EDIT WINDOW
  284.     When the CX_POPUP is set to 'YES' and ASwarm is being started or when
  285.     the hot key was pressed, a window shows up on the Workbench.
  286.     Normally, the workbench is moved to the front.
  287.  
  288.     We've tested ASwarm's Edit Window under many circumstances,
  289.     please give us a short note when you have a problem with it.
  290.  
  291.     You will see some Gadgets and a Scroll-List. In the Titlebar of
  292.     the window you'll see the hot key definition (may not complete).
  293.  
  294.     The values inside the Text-Gadgets are via default set to the
  295.     supplied Arguments in the Tool Types or CLI-Parameters.
  296.     On a wrong Enter, the value will be reset to the old value.
  297.  
  298.     TIMER:        The specified value for the timeout of the
  299.             blanker. After this time (in seconds) the ASwarm
  300.             shows up. Value may between 1 and 3600.
  301.  
  302.     CLIENT TIMEOUT:    The time the server gives to the client for not
  303.             being able to draw anything, then the screen will
  304.             be blanked really to prevent burn-ins.
  305.  
  306.     WASPS:        The number of the flying Wasps.
  307.  
  308.     BEES:        The number of the bees.
  309.  
  310.     HIDE:        (click or press 'h') Hide the window. All then new
  311.             entered values will be stored and acivated on the
  312.             next blank.
  313.  
  314.     BLANK:        (click or press 'b') Blank immediately. All then
  315.             new entered values will be stored and activated.
  316.  
  317.     QUIT:        (click or press 'q')
  318.  
  319.     DISPLAY MODE:    (Please refer to the notes below!) Choose a
  320.             desired Mode for the Display during blank-time.
  321.             Use the scroll-bar to show up other available
  322.             modes. This depends on the used system.
  323.  
  324.     AIM:        Checkbox. If checker is shown, the aim-mode is enabled.
  325.  
  326.     SPEED:        Enter value between 1 and 4. 4 is maximum speed.
  327.  
  328.     CYCLE:        Disable the colorcycling for the bees.
  329.  
  330.  
  331. COMMODITIES EXCHANGE
  332.     With the Exchange Tool, you can temporarly stop ASwarm with
  333.     DISABLE, restart it with ENABLE, remove ASwarm with KILL (as would do
  334.     a Quit in the Edit-Window), SHOW up the Edit-Window, and HIDE the
  335.     Edit-Window.
  336.  
  337.     The Exchange Tool is a comfort way to remove or dis/enable
  338.     ASwarm.
  339.  
  340.     Please refer to the AmigaDOS Manual (Section AmigaDOS Reference
  341.     and Workbench Programms) for further docs on Exchange Tool.
  342.  
  343.  
  344.  
  345. DISPLAY MODES:
  346.     Please, please, please have care here !!!! We are NOT responsible
  347.     for ANY user-error. The given list depends on the used System.
  348.     All newer Amigas, such as A500+ , A3000 do have the ECS Denise
  349.     for extended Screen Modes (Not all Amiga's with Kick 2.0 on ROM
  350.     do have a ECS Denise..). Of course you can start the desired
  351.     Modes, but not all modes are available on all MONITORS !
  352.     Please do refer to your Manual of the Monitor and to the AmigaDOS
  353.     Manual (Section Workbench Programms, AddMonitor) for more
  354.     informations.
  355.  
  356.     Why ? Simply because you can DESTROY your Monitor!
  357.  
  358.         Here is a list of the (normally given) ECS Display Modes:
  359.  
  360.         NTSC:Lores
  361.         NTSC:Hires            # Tron's preferred Mode
  362.         NTSC:SuperHires
  363.         NTSC:Lores-Interlaced
  364.         NTSC:Hires-Interlaced
  365.         NTSC:SuperHires-Interlaced
  366.         PAL:Lores
  367.         PAL:Hires
  368.         PAL:SuperHires            # Ill's preferred Mode
  369.         PAL:Lores-Interlaced
  370.         PAL:Hires-Interlaced
  371.         PAL:SuperHires-Interlaced
  372.         VGA-ExtraLores                  # -
  373.         VGA-ExtraLores-Interlaced    #
  374.         VGA-Lores                       #
  375.         VGA-Lores-Interlaced            #   Multiscan Monitor needed
  376.         Productivity                    #
  377.         Productivity-Interlaced         # -
  378.         A2024_10Hz                      #
  379.         A2024_15Hz                      #   A2024 needed.
  380.  
  381.    Other Modes are available, but not mentioned.
  382.  
  383.     Overscan is used for all modes, adjust your Overscan-size with
  384.     the ScreenMode Preference Tool.
  385.  
  386.     This list will only be avaible if the icon called "Mode_Names"
  387.     supplied with Workbench 2.0 is in the WBStartup directory of
  388.     your boot drive.
  389.  
  390.     NOTE:
  391.          DON'T use VGA-Modes on a NON-Multisync or NON-VGA-Monitor
  392.          DON'T even test Modes if you aren't sure about your
  393.          Monitor-capacibilities.
  394.  
  395.     As the original XSwarm runs on a X11-Workstation, and as those
  396.     ones have high graphics resolutions, I prefer SuperHires, as
  397.     this Mode comes    near to them.
  398.  
  399. KNOWN PROBLEMS:
  400.     We do know of some problems and strange behaviours, some of them
  401.     aren't strange anymore, when you read this:
  402.  
  403.     -  Are your running ARQ 1.66 or below ?
  404.        (A replacement Tool for the system requestors).
  405.        Then you may try this:
  406.  
  407.        Change the timeout to a low value, e.g. 5 secs, then type in
  408.        the CLI: wait 10 <RETURN>      (do not wait for the prompt)
  409.                 dir bafasel: <RETURN> (device blafasel: nonexisting)
  410.  
  411.        ASwarm will blank as usual, but then ARQ pops up a requestor
  412.        ON the ASwarm-Screen !! You can't close the Screen until you
  413.        click on 'Abort'. And ASwarm can't blank the screen either
  414.        anymore ! (It's ScreenClose() Command waits for the succesfull
  415.        return...)
  416.  
  417.        This is a BUG in ARQ ! It's dangerous in some cases. It may
  418.        burn in the requestor... (Martin Laubach, author of ARQ is
  419.        being contacted.. and promised to add a switch in a new version)
  420.  
  421.     -  You are running a C-Compiler or a raytracer. ASwarm goes
  422.        blank, but doesn't show any swarm, and during disk-access ASwarm
  423.        comes up for a while.
  424.  
  425.        This is not a Bug, this is the FEATURE of ASwarm !! This is
  426.        the way ASwarm blanks when high Cpu-use happens on the startup.
  427.        And during disk-access the Cpu-time is usually less, so ASwarm
  428.        may find time to draw something.
  429.  
  430.     -  Collision with other Blankers. Well, in fact you can run as
  431.        many Blankers as you want. Such as DMouse, Spliner, FracBlanc.
  432.       ASwarm does always try to move it's screen to front, when it
  433.        detects to be behind some other screens.
  434.  
  435.     -  When a disk is inserted, ASwarm closes the screen (dis-blanks).
  436.        This is normal. Disk-replacement is detected as an input
  437.        Event. As all input events shall disable the Blanker this one
  438.        should, too.
  439.  
  440.     -  The window doesn't open if the hotkey is pressed. Perhaps you
  441.        have supplied a wrong hotkey description. Use Exchange to open
  442.        the window if the windowtitle is like "HotKey=<NONE>" it is the
  443.        hotkey description.
  444.  
  445.     -  ASwarm shows up the window though the Tool Type CX_POPUP is
  446.        set to 'NO'. This happens when ASwarm is started twice.
  447.        (Double-click (or call from CLI) = start, another double-click
  448.        (or call from CLI) opens the window)
  449.  
  450.     -  ASwarm is damn slow. Huh .. sorry :-) The Authors have fast
  451.        machines.. Try to reduce the swarm-size (BEES) and the amount
  452.        of swarms. Or use another, less big screen.
  453.  
  454.     -  ASwarm makes noice when it blanks the screen. This may happen
  455.       when a Display Mode is choosen, which is not of the size of
  456.        the since then activ screen. Nothing dangerous.
  457.  
  458.     -  ASwarm makes flickers on the Monitor when it blanks the Screen.
  459.        This happen when ASwarm blanks on a PAL-Screen, but the since
  460.        then or then active Screen is or was NTSC. (Or vice versa)
  461.        The Monitor needs a bit time to synchronize again. Nothing
  462.        dangerous.
  463.  
  464.     -  There is a 70Hz hack. This hack has problems with the productivity
  465.        Environment. No Bug of ASwarm.
  466.  
  467.  
  468. CREDITS:
  469.     Jeff Butterworth for his xswarm routine available for
  470.     X11-Workstations as a xlock mode or a stand-alone program.
  471.  
  472.     Matt Dillon for Dice. So we could make ASwarm be compilable in
  473.     the most common low-cost C-Compiler. (Only registered version)
  474.     Ah, yes. Greetings to Stefan Becker! :-)
  475.  
  476.     SAS/C group for well done work. As yet the SAS version of ASwarm
  477.     is faster and shorter...
  478.  
  479.     Maybe we should try to give support for other C-Compiler, I'll
  480.     try Maxon C++ (yet in Beta-State) ..
  481.  
  482.     IRC-guys in Oulu to make world-wide communication easy and to be
  483.     able to chat about programmings ideas. (And Schlamm-Bugs :-)
  484.  
  485.     Roger 'Budda' Westlund, who told me about 70Hz Problem.
  486.  
  487.     Willi 'Amico' Raeckers, always sitting on my nervs, asking for a new
  488.     version.
  489.  
  490.     Jörg 'Skull' Bublath, having the idea for the Aim-Mode.
  491.  
  492.     Markus 'Corwin' Stipp, for helping us with DICE.
  493.  
  494.     AUGUP, Amiga Group of Uni Paderborn, for their testings.
  495.     (ASwarm wasn't very long in Beta-state)
  496.  
  497.     Fred Fish, Mr. Public Domain, hope you like this enough to place
  498.     it onto one of your new 'Fishes'. Permission herebye given.
  499.     (Grmbl.. We're on FF590 and i still have no streamer device :^)
  500.  
  501.     Commodore Amiga group for this great system. Hope to see some
  502.     great new stuff this year ! (I'm already collecting my bucks..)
  503.  
  504.     Dire Straits for the background music :-)
  505.  
  506. FINAL
  507.     Ever seen 'After Dark' ?
  508.     Combine several screenblankers on the SAME screen (Warp, Spliner,
  509.     ASwarm on the same screen :-) Change the graphic routine and the
  510.     so given blanker via random or time-table.
  511.     We want to work on this... I have MANY ideas for screenblankers.
  512.    Oh yes, there is already 'Shadowmaster', but don't like it.
  513.