                                    Blursk 1.3

          Copyright (c) 2002 by Steve Kirkendall
 Freely redistributable under the Gnu GPL version 2 or later

                   <kirkenda@cs.pdx.edu>
          http://www.cs.pdx.edu/~kirkenda/blursk/


Blursk is a visualization plugin for XMMS.  It was inspired
by the "Blur Scope" plugin, but Blursk goes far beyond that.
It supports a variety of colormaps, blur patterns, plotting
styles, and other options.  The only things that haven't
changed are parts of the XMMS interface and configuration
code.

To configure Blursk, select it in the Visualization Plugin
menu, and then click the [Configure] button, as usual.  If
Blursk is running while you're configuring it, then you can
see the effects of your changes immediately as you make them.

Right-clicking on the Blursk window will also bring up the
configuration dialog.  Dragging the left mouse button will
move the window, and Blursk will even remember that position
the next time you start it.

Blursk allows you to store combinations of settings as a
"preset".  The preset controls are located at the top of
the configuration dialog, above the options.  The controls
consist of a combo box where you can type in the name of a
preset, and three buttons for loading/saving/erasing the
preset named in the combo box.  Changing the name in the
combo box has no direct affect on the configuration; you
must press one of the buttons to make something happen.

As a special case, loading "Random preset on quiet" will
cause Blursk to randomly choose one of the other presets
each time silence is detected on the input.  You can end the
random choices by loading any other preset, or by altering
any property of the current preset.

Blursk also supports a variety of full-screen modes.  First
you must configure the full-screen method by clicking the
[Advanced] button on the Configure dialog.  (The full-
screen options are described at the end of this file.)
After that, you should be able to switch to full-screen
mode by typing <Alt-Enter> or <F> in the Blursk window.
To switch back, hit <Alt-Enter> again.

=============================================================
COMMANDS
-------------------------------------------------------------

Blursk's animation window is sensitive to the following
keys.  These should work in full-screen modes too, except
when Blursk is running in the root window.

    <F> or <Alt-Enter>  Toggle full-screen mode on/off
           <I>          Show track info
        <Z> or <Y>      Previous track
           <X>          Play
           <C>          Pause
           <V>          Stop
           <B>          Next track
           <Up>         Increase volume
          <Down>        Decrease volume

The mouse is also supported.  The following actions work
in the Blursk window or full-screen mode.  Most of these
work when Blursk is running in the root window too, if
the mouse is in the [Blursk] button.

* Drag an edge of the window to resize it.
* Drag the interior of the window to move it.
* While in full-screen mode, click on the window to revert
  to window mode.
* Right-click to bring up the configuration dialog.
* Middle-click to paste a configuration string into Blursk.
* Move the scroll wheel to change the volume.

=============================================================
CUT & PASTE
-------------------------------------------------------------

Blursk supports "cut & paste" as a convenient way to share
settings.  It uses a short string to represent the current
settings; this string becomes the "Primary Selection" for
your workstation.  You can paste this string into email,
web pages, or wherever.  If you paste a string into Blursk,
Blursk will load the settings encoded in the string.

COPY:  To copy the current settings into a document, first
       bring up the Configure dialog by right-clicking on
       the Blursk window.  Then simply push in the [Copy]
       button at the bottom of the dialog.

       The [Copy] button will remain pushed in until you
       click the [Copy] button again, or until some other
       application claims the primary selection.  As long
       as the button remains pushed in, you should be able
       to paste into any other application, such as a text
       editor.  (Many applications use the middle mouse
       button to paste.)

PASTE: To load settings from another document, select the
       string in the usual manner.  (For most applications,
       this simply means dragging the mouse through the
       text -- the highlighted text immediately becomes
       the primary selection.)

       Then middle-click on the Blursk animation window.
       (Not the Configure dialog!)  Blursk will parse the
       string, and adjust its configuration to match
       whatever it was able to parse from the string.

=============================================================
OPTIONS
-------------------------------------------------------------

BASE COLOR
    This allows you to select the drawing color.  Some
    colormaps add extra colors, but all of them will use
    this color as a reference in one way or another.

COLOR OPTIONS
    The first item here is the color style.  It controls the
    way that Blursk will generate a color map.  In addition
    to a variety of hardcoded color styles, there is also a
    "Random" setting which causes one of the other color
    maps to be chosen at random; in addition, each time the
    blur motion changes (see below), a new color map will be
    chosen.

    The fade options come next.  Images are always drawn in
    the color at one end of the color map (usually the
    brightest end); over time, the image color is shifted
    toward the other end of the color map.  This option
    controls the speed at which this shifting takes place.

    The next option determines which color the signal will
    be drawn in.  "Normal signal" uses the brightest color,
    "White signal" forces the brightest color to be white,
    and "Cycling signal" causes the signal to be drawn in
    different colors.

    Setting the "Contour lines" flag will add some other
    white lines to the color map.

    Setting "Hue on beats" will cause a different base color
    to be chosen when Blursk detects beats in the music.
    Unfortunately, the beat detector isn't very good yet.

    The default background color is "Black backgnd", but
    you can also choose "White" (really light gray),
    "Dark" (a dark version of the base color), "Shift"
    (120 degrees around the color wheel from the base
    color), "Color" (a random color), or "Flash" (the
    background color flickers in response to the music).

BLUR OPTIONS
    Blur motion is the first option in this group.  It
    determines the way that the image's pixels drift.
    There are many blur motions supported here, plus
    "Random", "Random slow", and "Random quiet" settings
    which cause one of the other blur motions to be chosen
    randomly, either at regular intervals or at the start
    of a quiet period.

    Next is the switching speed.  When you change blur
    styles (or "Random" does it for you), the new style
    doesn't instantly replace the old style.  It happens
    gradually, under control of the switch speed option.

    The third option in this section controls the type of
    blurring.

    Next is the "stencil" option.  Blursk contains a
    variety of bitmapped images; this options allows you
    to incorporate one of the images into the blur motion
    in a subtle way.  "Random stencil" chooses one of the
    images randomly whenever the blur motion changes.
    "Maybe stencil" does the same except that it usually
    chooses no image at all.

    The "Slow motion" option cuts the frame rate in half.
    This slows down the image's motion, and it also reduces
    the CPU load.

EFFECTS
    The first option in this section controls the way that
    the sound signal is converted to an (X,Y) position in
    the window.

    The next option controls the way that those points are
    plotted on the window.  The "Radar" setting is unusual
    in that it uses the X value as a radius, and the Y value
    as a brightness.  "Edges" also uses Y as a brightness,
    and uses X to select a position along the perimeter of
    the window.

    The "Thick on beats" flag attempts to make the renderer
    use thicker lines when the sound is loud.  For some
    combinations of options, this can make the entire image
    seem to throb in step with the music.

    The next option controls flashing.  When Blursk detects
    a beat, it can brighten the whole image, invert the
    whole image, or add a bitmap image (from the same pool
    or images as the "blur stencil" option).  If this option
    is set to "Random flash", then it will choose a bitmap
    randomly; except if the stencil option is also random,
    then blursk will use the stencil bitmap for flashing.

    The effect option is next.  The "Normal effect" converts
    the pixel values to colors directly.  The "Bump effect"
    interprets the pixel values as heights, and chooses a
    color based on height differences to achieve a cheap
    3D effect.  The "Anti-fade effect" cycles the colormap
    at exactly the same speed as fading, so that pixels tend
    to remain the same color as they fade, so you see mostly
    the blurring and motion but not the fading.  The "Ripple
    effect" causes the fade to be subtly nonlinear.

    The "floaters" option offers a way to spice up some
    of the more sedate configurations.  "Dots" causes random
    flashing dots to be added to the image.  The other values
    add persistent dots which follow the blur motion, leaving
    trails.

=============================================================
ADVANCED OPTIONS
-------------------------------------------------------------

MISCELLANY
    The "CPU speed" option gives you a simple way to affect
    the CPU load, by changing the image resolution.  The
    "Fast CPU" setting uses the full resolution of the
    window.  "Medium CPU" reduces the horizontal resolution
    by half, and then interpolates points to expand the
    image to fill the window.  The blur motions will be
    distorted, but it should still look interesting.  The
    "Slow CPU" setting reduces both vertical and horizontal
    resolution.

    The "Show window title" option causes the Blursk window
    to be displayed as a normal application window, with a
    title bar.  Normally it is displayed without a title
    bar, like a dialog, but some window managers don't let
    dialogs choose their own position.  This option is
    normally off; if Blursk is unable to create its window
    where you normally want it, then try turning this
    option on.

    The "Show info" option causes the track number and song
    title to be shown in the image.

BEAT SENSITIVITY
    The beat sensitivity slider affects the beat sensor,
    which is used by the "hue on beats", "blur on beats",
    and "flash" features.  Moving the slider to the left
    makes it less sensitive; moving it right increases
    sensitivity.  Sadly, this isn't nearly as effective as
    I'd hoped.

FULL SCREEN
    Blursk supports full-screen displays in a variety of
    ways, each with their own quirks.  The exact list of
    possible values depends on the libraries that were
    available when blursk was configured and compiled, so
    some of the following methods might not be available
    to you.

        "Disabled"      
            Full-screen mode isn't used.

        "Use XMMS"
            Full-screen is supported via the XMMS full-
            screen library functions.  This only works
            on XFree86, and only with recent versions of
            XMMS.  It works by temporarily setting your
            video card to its lowest supported resolution,
            and then resizing & repositioning the Blursk
            window to fill visible part of the desktop.

        "Use XV"
            Full-screen is supported via the "XV" video
            extension (also known as "XVideo").  To find
            out if your X server supports XV, run the
            "xdpyinfo" program and look for "XVideo" in
            the list of extensions.  XV depends on special
            hardware to scale a small image up to fill the
            screen.

        "Use XV doubled"
            This also uses the "XV" video extension, but
            in a slightly different way.  It tries to
            avoid color artifacts that "Use XV" can
            create where different colors meet, by
            doubling the vertical & horizontal resolution.
            This may interfere with the normal smoothing
            function of your video card, and it will
            probably be slower since the image is four
            times larger.

    The "Shared memory" flag only affects the "Use XV"
    and "Use XV doubled" methods.  It causes Blursk to
    use the shared memory versions of the XV imaging
    functions.  Shared memory is faster than the normal
    functions, but it doesn't work over a network.

    The "Alternative YUV" flag only affects the "Use XV"
    and "Use XV doubled" methods.  There are many ways
    to convert RGB colors used by X-windows into YUV
    colors used by XVideo.  By default, Blursk uses
    YCbCr-601, but setting this flag will make it use
    YCbCr-709.  Use whichever looks better on your
    system.

    The "In root window" flag is cool.  For the "Use XV"
    and "Use XV doubled" methods, this flag causes Blursk
    to send the image to the display's root window.  The
    Blursk image then shows as animated wallpaper!
    IMPORTANT NOTE: To revert to windowed mode, click the
    [Blursk] button that appears where the Blursk window
    used to be.

    The "Mask out edges" flag can be used to blacken the
    right and bottom edges.  Sometimes XV doesn't display
    those pixels correctly, which can be distracting.
    If this happens to you, then turn on this option.

    The "Revert to window at end" flag tells Blursk to
    switch back to window mode whenever the sound ends
    -- usually at the end of an album.

=============================================================
KNOWN BUGS
-------------------------------------------------------------

KDE's window manager doesn't support the "In root window"
option.  Also, the "Show window title" option should be
left off; otherwise KDE will always move the window to
the upper left corner when you exit full-screen mode.

Gnome's Sawfish window manager has its own quirks.  The
"Show window title" must be turned on, or the Blursk
window will appear in a goofy place.

Many window managers have trouble with the "Use XMMS"
full-screen method.  Some WMs don't center the full-screen
image, so you see stripes from other windows around two
of the edges.  Some loose window focus, so the keystrokes
aren't detected, and the only way to switch back to
windowed mode is via the left mouse button.
