GEISS 2, v1.0 (6/17/03)
  a Winamp audio-visualization plug-in by Ryan Geiss
  copyright (c) 2003 Nullsoft, Inc.
  Geiss 2 Homepage: http://www.nullsoft.com/free/geiss2/
  Geiss 2 Support: http://forums.winamp.com/forumdisplay.php?forumid=151


Table of Contents
-----------------------
    1. what is Geiss 2?
    2. requirements
    3. installation
    4. tweaking
    5. usage
    6. known issues
    7. using line-in (for live shows, etc.)
    8. other tips; misc. info
    9. version history




What is Geiss 2?
-----------------------
Geiss 2 is a Winamp audio-visualization plug-in that lets you
fly through the sound waves of the music you're listening to.  




2. Requirements
-----------------------
    Required:
      * Windows 98, ME, 2000, or XP.  (Windows 95 is not supported.)
      * One of the following:
          * Winamp 2.72 or later
          * Winamp 3 with the Classic Visualization Component
      * A processor that supports the MMX instruction set.

    Recommended:    
      * An 800+ MHz processor 




3. Installation
-----------------------
    Geiss 2 can be installed to Winamp 2 or 3 (or both, but you'd have
    to run the installer twice).  

    To install to Winamp 3, just run the installer as usual.  Then
    launch Winamp 3 and hit CTRL+P to load the Preferences screen.
    Then, on the left, scroll down to 'ClassicVis' and select it.  
    (If you don't see it, you probably need to download the
    Classic Visualization Component).  Now you should see a list 
    of visualization plugins on the right; select Geiss 2, and click 
    'start' to run it.

    To install to Winamp 2, run the installer as usual, but note that
    if you also have Winamp 3 installed, you'll have to manually
    choose the Winamp 2 directory, since it installs to Winamp 3
    by default.  Once the installation is complete, launch Winamp 2 
    and hit CTRL+P to load the Preferences screen.  Select 'visualization' 
    under 'plug-ins' on the left.  Now you should see a list of 
    visualization plugins on the right; select Geiss 2, and click 
    'start' to run it.  In the future, you can use the shortcut key 
    CTRL+SHIFT+K to run Geiss 2, and ALT+K to configure it.




4. Tweaking
-----------------------
    
    a) GETTING A GOOD FRAMERATE
    
    To get Geiss 2 to look its best, you want to maximize the size of
    the internal rendering, while still maintaining a framerate of 30
    frames per second.
    
    To do this in windowed mode, simply expand the window until you see
    the framerate (F5) drop. 
    
    In desktop mode, you'll need to adjust the [desktop-mode or fake-
    fullscreen-mode] downsampling value on the second tab of the config 
    screen.  If you're getting 30 fps consistently, try increasing this 
    number further toward 1.  If you're dropping below 30 fps, try 
    decreasing this number.  You can also try switching Windows to 16-
    bit color, or dropping Windows to a lower resolution.
    
    For [true] fullscreen mode, the most important factor is the display
    mode that you select on the first tab of the config panel.  The
    higher the resolution you select here, the more pixels Geiss 2 has
    to compute every frame, and thus, the slower it will be.  So, again,
    if you're getting 30 fps consistently, try increasing the resolution
    here.  If you're not, decrease it.  
    
    In fullscreen mode, you can also adjust the 'Vertical Screen Size'
    to add a widescreen look to the plugin.  The lower the % here, the 
    less processing the plugin has to do, and the more likely you are
    to get 30 fps.  Finally, you can also adjust the downsampling for
    fullscreen mode, but the visual quality will be less than if you
    just changed the fullscreen display mode and/or adjusted the
    'vertical screen size'.
       

    b) REFRESH RATES AND MAXIMUM FRAMERATE SYMBIOSIS

    For the smoothest animation, you need to configure Geiss 2
    so that there is no frame skipping.  To do this, the
    monitor's refresh rate must be an integer multiple of the 
    'max framerate' that you allow Geiss 2 to run at.

    For example, if your monitor is running at 75 Hz (meaning that
    it refreshes the image 75 times per second), then you would 
    want to select one of the following values for the 'max 
    framerate' option:

        1, 3, 5, 15, 25, 75

    These values are optimal because they evenly divide into the
    refresh rate of the monitor, and that means that each image
    (frame) that is sent to the video card will be displayed
    for a consistent number of refresh cycles on the monitor.  
    Otherwise, one frame might get shown for 4 refreshes, then
    the next one for just 3, and so on, making for jerky animation.

    Your monitor's refresh rate is configurable, and whatever
    you have it normally set to in Windows is what it will be
    when you go to run Geiss 2 in Windowed or Fake Fullscreen
    modes.  To view or change it, go to Start->Settings->Control
    Panel->Display->Settings tab->Advanced->Monitor tab.

    When you run Geiss 2 in Fullscreen mode, though, the refresh 
    rate changes (along with the display mode) to whatever you 
    selected in the Geiss 2 config panel, in the 'Display Mode' 
    box (in the 'Fullscreen' section).

    Here are the optimal maximum framerates for some other common 
    monitor refresh rates:

       REFRESH   OPTIMAL FRAMERATES
       -------   ------------------
        60 Hz     1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60
        66 Hz     1, 2, 3, 6, 11, 22, 33, 66
        70 Hz     1, 2, 5, 7, 10, 14, 35, 70
        72 Hz     1, 2, 3, 4, 6, 8, 9, 12, 18, 24, 36, 72
        75 Hz     1, 3, 5, 15, 25, 75
        85 Hz     1, 5, 17, 85
        100 Hz    1, 2, 4, 5, 10, 20, 25, 50, 100
        120 Hz    1, 2, 3, 4, 5, 6, 8, 10, 12, 15, 20, 24, 40, 60, 120

    LCD'S AND LAPTOPS
    -----------------
    Note that many LCD flatpanel displays (including laptops) run 
    natively at one refresh rate ONLY - usually 60 Hz - even though 
    the display driver might provide other options besides this.  
    So, if you have an LCD, it's best to keep it running in 60 Hz 
    at ALL times (or whatever its native refresh rate is).

    Finally, another tip for getting smooth animation: minimize
    (or close) any other windows/programs.  Even simple ones that
    don't seem like they'd be interfering can sometimes do very
    naughty things...
    



5. Usage
-----------------------
    Hit 'F1' while Geiss 2 is running to display a list of 
    accelerator keys.  These will let you display the current
    framerate, change tracks, browse the playlist, control
    the animation, and so on.

    ESC:    exit plugin
    F1:     display help
    F2/F3:  display song title, length            
    F4:     display misc. info
    F5:     display fps                   
    ALT-ENTER or double click: 
            toggle fullscreen

    L:      lock/unlock current map          
    ##:     go to certain map (##=digits)
    SPACE:  randomize map (+shift/ctrl=?)

    p:      randomize color palette      
    P:      lock/unlock color palette
            
    w/W:    cycle through waves
    o:      toggle waveform on/off            
    j/J:    adjust wave size
    k/K:    adjust wave smoothing

    Q-E-A-S-D-F-G: various effects
    i:      toggle autoshift
    I:      manual shift now
    h/H:    diff now (2 versions)
    t:      embed song title
    y:      toggle dither
    m:      toggle munge
    PGUP/PGDN: adjust decay
    HOME:   decay off
    DEL:    decay now
    END:    toggle beat-driven decay
    INSERT: toggle mouse zooming

    PLAYBACK:
    Z/X/C/V/B: prev/play/pause/stop/next
    N:     navigate playlist
    U:     toggle shuffle
    R:     toggle repeat
    up/down arrows: adjust volume
    left/right arrows: seek
    left/right arrows + SHIFT: fast seek




6. Known Issues
---------------
    1. When running any card in a 'dualhead' setup that creates a double-width
       (2048x768) or double-height (1024x1536) virtual desktop spanning two
       monitors, if the width or height of the window goes beyond 2048, then
       the you just see black in the part beyond 2048; i.e., the plugin does
       not fill the whole window.




7. Using Line-In
-----------------------
    If you want to use your sound card's Line-In or CD Audio inputs for
    sound data (instead of mp3 files), you can do this; in fact, this
    will work for any viz plugin, not just this one!  Do the following:
        
        1) CONNECT WIRES
            Connect your audio source (a stereo, a live feed, whatever) into
            the line-in (or microphone) 1/8" (headphone-size) jack on your 
            sound card.  You might want to test & verify that your cable is 
            good before doing this.
        
        2) SELECT SOUND INPUT CHANNEL & ADJUST VOLUME
            In Windows, double-click the speaker icon in your systray (where
            the clock is).  Then, on the menu, go to Options -> Properties
            and select the "Recording" option.  Then make sure the Line In
            (or Microphone) input channel (whichever is appropriate for
            your case) is SELECTED (with a check mark) and that the volume 
            is close to, or at, the maximum.  Hit OK.           
        
        3) TELL WINAMP TO USE LINE-IN
            Open Winamp, and hit CTRL+L (the "Open Location" hotkey).  Now
            type in "linein://" as the location you want to open.  (Leave out
            the quotes and make sure you use FORWARD slashes.)  Hit PLAY
            ('x' key for the lazy), and the little built-in oscilloscope (or 
            spectrum analyzer) in Winamp should start showing your signal.
            If the signal looks flattish, you might want to double-check the 
            volume from Windows' Volume Control, or adjust the sound level 
            at the (physical) source.
                
        4) RUN IT
            Run Geiss 2 as usual.  If the waves are too small or large, 
            either adjust the volume from Windows' Volume Control, or adjust
            the sound level at the source.       




8. Other Tips; Misc. Info
-----------------------
    1. A fast CPU, fast memory, and a fast frontside bus are the most
       important components for getting Geiss 2 to run at a high framerate
       at high resolutions.  A fast AGP graphics card helps, too (thanks
       to the increased bandwidth to video memory) but keep in mind that
       Geiss 2 doesn't use any hardware (3D) video features.  Finally,
       Geiss 2 usually runs the fastest (in windowed/desktop/fake fullscreen
       modes) when Windows is in 16-bit color.
    
    2. Don't set the maximum framerate beyond 30 frames per second; 
       Geiss 2 was designed with that cap in mind, and it will look
       bad if you go beyond it.    

    3. For the best graphics performance, try to close as many other 
       applications as you can, before running the plugin, especially 
       those that tend to work in the background, such as anti-virus 
       software, file-swapping software, e-mail programs, messageing
       programs, and so on.  If you must leave other applications 
       open, try to minimize them (i.e. shrink the window down to the 
       taskbar) so that they stay out of the painting loop.
    
    4. In general, it's a very good idea to use only Microsoft-certified 
       WHQL (Windows Hardware Quality Labs) drivers for your video card.
       Often people want to get the newest, fastest beta drivers, but 
       these drivers are almost ALWAYS riddled with new bugs.

    5. Multiple Monitors: It is recommended that whenever you modify your 
       Windows multimon setup (i.e. turn an adapter on/off, change its 
       color depth, etc.), you reboot Windows before running this plugin.  
   
    6. Please remember to look away every 15 minutes.
        
    7. 'Geiss' rhymes with 'frozen water'.

    8. Geiss 2 is the sequel to Geiss, which debuted
        in 1998.  Geiss 2 is better because:
        
        * it's stable (heh)
        * it can go beyond 800x600 (up to 2048x2048)
        * it can blend between maps
        * it has DESKTOP MODE
        * it is multimon-friendly
        * it lets you steer with the mouse (hit INSERT)
        * it now lets you accurately limit the framerate
        * you can now select your refresh rate for 
            fullscreen modes.  (in the original Geiss,
            you had no control over this, and sometimes
            the screen got squished.)
        * it manually constructs its own main loop out
            of various chunks of assembly code.  For each 
            chunk, it tests many options to find the one
            that is fastest on *your* particular machine,
            and then uses that.  After running for about
            30 seconds, it should know exactly which code
            chunks work best on your machine, and be
            manually stitching them together (no calls or
            jumps!) and running the dynamically-generated
            code.
        * it has a bunch of new maps, color palettes, and
            effects
        * no animals were eaten by the author during the
            development of this plugin.



9. Version History
-----------------------
1.0 - 17 June 2003
    -Initial release.