

				 Bomb

	       automatic interactive visual stimulation
		    Scott Draves <spot@draves.org>

			http://draves.org/bomb




how to run and use bomb
-----------------------


platform-specific information:

linux

  untar, then say "make install".

  if the DISPLAY environment variable is set, then bomb opens an X
  window and runs there.  8, 16, and 24-bit displays are supported.

  otherwise bomb uses svgalib, and must be run as root in a `graphics
  capable virtual console'.  the usual way to get this is to hit
  Control-Alt-F2 and log in as root.  this one runs full-screen and at
  a higher frame-rate than with X.

  the file guile.txt documents how to script bomb in lisp, so that you
  can compose rather than improvise.  you can do much more powerful
  scripting with the Max version, which is documented in its own
  distribution (note this feature is currently disabled).

  command line options:

  -root   causes the image to be displayed in the root window,
          automatically a single image is magnified to fit the screen
          and a backing pixmap is used.

  -magnify x    causes the 320x200 image to be scaled by a factor of x.

  -tile [x]     causes the image to be tiled on the root window, can be
                used in combination with magnify, without an argument
                enough tiles are created to cover the root, with an
                option an x by x grid of tiles centered on the center
                of the screen will be created, if the screen is filled
                automatically a backing pixmap is used.

  -nobackpixmap    by default when the bomb images fill the screen a root
                   background image is created that layers the
                   background to allow seamless movement of windows
                   across a working bomb without blank areas appearing
                   and reappearing, but this can be slow especially
                   with a single large image.  so if this is too slow,
                   or if you dont want it use this feature use this
                   option.

  -noshm     the MIT SHM is used by default if compiled in, use this if
             for some reason you dont want to use it.

  -nosound   disable sound input, do not even open the /dev/dsp device.

  -randomstart     do not melt the splash page, start with random mode.

  -quiet     no output to stdout or stderr.  this is essential for use
             with xscreensaver!

  -rule xxx  Run with a particular rule, depending on xxx.  available
             rules are acidlife, anneal, rugrug, static, flame, brain,
             image, shade, quad, fuse, wave, fuse, slip, rug, and rd.
             You may add them together, or subtract them, in which
             case, they become rules to avoid.  For example:

    bomb -rule flame                    # flame mode only
    bomb -rule flame+image              # flame and image modes
    bomb -rule -static                  # any but static
    bomb -rule -static-fuse             # any but static or fuse 


  -jpeg      jpeg compress quicktime output (instead of raw).
             Control-V starts and stops recording to a
	     quicktime file.

  notes:

  a typical resource to work with xscreensaver is:

    xscreensaver.programs: bomb -tile -quiet -rule rd

  I find that the best effect is to use bomb -tile. It creates the smoothest
  animation, and as it has the smallest generated pixmap you get smooth
  window movement across bomb without too much of a computential hit.

  If you say "env fps=1 bomb ..." then it will run at one frame per
  second, and so use very little CPU.

    env fps=1 bomb -tile 


mac

  big-bomb runs with replicated pixels, so it fills more of the screen.

  ssaver-bomb exits on keyboard input so that it can work as a screen
  saver with autolaunch (http://www.stclairsw.com/alch_bg.html).

  for best effect, set your screen to eight bits per pixel and the
  lowest number of pixels.


win32

  make sure you used a 32-bit unzip program (one that supports long
  file names).



basic operation
---------------

if you run it and leave it alone (ie don't touch the keyboard), it
will go into automatic mode (automode).  put on your favorite audio
CD, sit back, and enjoy the show.  use Control-C or ESC (or Command-Q
on the mac) to exit.

a collection of ~20 parameters control how the image on the screen
changes.  each parameter set defines a particular texture, shape, or
effect.  as long as the parameters remain unchanged the same basic
visual pattern will evolve on screen.  in automode the parameters are
occasionally varied at random.

`bomb' starts out with roughly the same parameters every time: a
boiling texture dissolving the title page. if you wait, the parameters
will change and new effects will appear.


keyboard commands
-----------------

it's also possible to change the parameters manually with the
keyboard.  the space bar randomizes all parameters and clears the
screen.  it can be used as a `reject button': if the program is doing
something stupid, hit the space bar and a new (and hopefully better)
effect will appear.  this is the crudest possible control.

the rest of the keys are mapped to commands that adjust the various
parameters.  the normal layout is described below.  access to the
easier-to-remember `mood organ' mappings follow.

the middle row of keys (asdfghjkl;') changes the rule.  the rule
controls the basic algorithm used by the effect.  variants of a rule
can be accessed by pressing the same key repeatedly (try hitting
'f' or 'g' several times).

  a  rug          3
  s  image rug    1
  d  RD           2  (RD = reaction/diffusion)
  f  rotor/flame  9
  g  acidlife     2
  h  multi rug    1
  j  anneal rug   2
  k  slip         1
  l  rug rug      1
  ;  brain rug    1
  '  fish/slugs   2
  A  static       1
  F  fuse         4
  G  quad         1


the lower row of keys (zxcvbn) randomize individual parameters for
finer control:

  z  change speed/texture
  x  fill screen
  c  change color
  v  next shape
  b  next shape II
  n  toggle rhythm
  m  next shape III

v is context sensitive, think of it as getting the `next shape'.  eg
in image rule it loads a new image, in rotor rule it picks a new
harmony or flame, in the brain it changes the excitation rules.  b is
a variant of v, be sure to try it with the brain.  use m and b with
RD.  m in image mode uses the image sequences.



the top row selects an individual parameter to vary.  after the
parameter is selected, the ,. keys (unshifted <>) move the value up
and down.  eg while in image rule try pressing r, then several commas.
you can also type a number followed by RETURN to enter a specific
value, or repeatedly hit the parameter key to increment/toggle the
value (try uuuu)

  q  color map
  w  beat size
  e  beat speed
  r  texture/speed
  t  # icons in window
  y  icon sequence
  u  toggle smooth color
  i  texture/mask -- unusable
  o  misc
  p  blit rect size
  [  speed of shape change
  ]  speed of driver rule
  \  assoc search time
  {  hot time
  }  cool time
  |  brain rule
  P  brain shift
  O  cycle bkg (in rug2)
  I  smooth/random underflow

advanced behavior
-----------------

  B   fade to black
  Q   enter automode
  0   (zero) disable automode
  L   toggle mode lock
  =   dump frame to dribble dir (PPM format)
  +   toggle periodic dribble
  Z   new image and clear screen (good for image mode)
  WER pulse colormap
  C   invert driver
  /   load driver
  D   permute colormap by rotating bits of indices (press 8 times = identity)
  S   toggle smooth/plain cmap
  J   double board horiz
  H   double board vert
 ^F   toggle display frame rate and audio input (not on linux)
 ^V   toggle writing to quicktime *.mov

random, useless, and broken
---------------------------

  Y   cooler
  U   hotter
  V   previous drift pattern
  T   brighten


other organs
------------

the above keyboard commands allow exploration of bomb's entire
parameter space, but by using clumsy random-walking and type-a-number
interfaces.  keybaord mappings called `organs' allow you to (eg) map a
single parameter across the whole keyboard.  in these modes the space
bar and exit-program commands still function, but all the other keys
(including shift and control combinations) are mapped to the
parameter.

the basic organs are

  1     standard
  2     mood
  3     shape
  4     color

[[ currently the digits 1-4 have been hijacked and are bound to change
   the organ rather than type-in-numbers ]]

bomb starts out with the standard organ described above.  the shape
organ drives with different images.  the color organ picks the
colormap (even keys produce smooth/looped colors; odd keys produce
plain colormaps).  the mood organ binds entire parameter sets to
individual keys (only a-n so far).



audio input
-----------

the mac, SGI, and win32 versions support audio input.  the linux
version will only work if you have a functional /dev/dsp device.  as
of now, bomb makes only minimal and rather simplistic use of the audio
signal.  some of the modes are uneffected by audio; 's', ';', and 'f'
are three that work relatively well.

the 'n' key toggles use of audio, if available and applicable.

on win32, a beep during startup indicates that the audio driver
could not be opened, and bomb will run without it.

