SMOKE 1.06 (8/28/02)
  a Winamp visualization plug-in by Ryan Geiss
  copyright (c) 2001-2002 Nullsoft, Inc.

What is Smoke?
Smoke is a Winamp plug-in that generates souplike audio-driven 
visuals through the simulation of fluid dynamics.

Section Listing
    1. requirements
    2. installation
    3. tweaking
    4. usage
    6. known issues
    7. using line-in (for live shows, etc.)
    8. acknowledgements
    9. version history

1. Requirements
      * Hardware-based 3D graphics acceleration (i.e. a video card with 3D support)
      * DirectX 8.0 or later ( )
      * Winamp 2.72 or later  ( )
      * Windows 98/ME/2000/XP/etc.

      * A 500+ MHz processor is highly recommended if the fluid simulation 
           is to run at an appreciable level of detail.  
      * Any old 3D card will do... except the really old ones that can't 
           render to a texture (instead of the framebuffer).

2. Installation
    To install Smoke, simply run the installation program.
    It will place vis_smoke.dll in your [winamp\plugins] directory,
    as well as this documentation file, smoke.html.
    To configure Smoke, hit CTRL+P (for Preferences) from within
    Winamp.  On the left, under plug-ins, click 'Visualization', then
    select 'Smoke' on the right, then click 'Configure'.  
    To run Smoke, you can then click 'Start', or just hit CTRL+SHIFT+K.

    If you encounter any problems, don't give up; there's a ~90% 
    chance your problem can be fixed by following the steps in the
    TROUBLESHOOTING section below.

3. Tweaking
    THE PRIMARY FACTOR in determining the quality of the image
    is the color depth of the display; 32-bit color is a must.
    16-bit color will work, but will look really, really bad
    on most cards.  

    How do you select the color depth?   The answer is different 
    depending on if you're running Smoke in Windowed or Fullscreen
    For Windowed mode, the color depth is determined by 
    (and is the same as) the color depth of your current Windows
    display mode.  To find out what this is and/or change it,
    go to the Start Menu -> Settings -> Control Panel -> Display
    Properties, then click the 'Settings' tab on the right, and
    look in the box labeled 'colors'.

    For Fullscreen mode, the color depth is simply determined by 
    the video mode you select from the Smoke config panel.

    Other tips:

    * Stand back from the monitor when in fullscreen mode;
      'Smoke' tends to look better when you can relax on
      the other side of the room and watch it.  Having Smoke 
      occupy your entire field of vision tends to lessen 
      its visual appeal.

4. Usage
    Hit 'F1' while Smoke is running to display a list of hotkeys.  
    These will let you display the fps, change tracks, browse the 
    playlist, etc.

    ESC    exit plugin
    F1     show/hide help
    F2     show/hide song title
    F3     show/hide song length
    F4     show/hide debug info
    F5     show/hide fps
    ALT-ENTER or double click: toggles fullscreen mode
	F      Freeze/unFreeze smoke color
	N      randomize smoke color
	M      Manual mode on/off
	1-9    Manually generate plumes
    G      optimize Gridsize (takes ~5 sec.)
	T      tracer particles on/off
    u/U    adjust turbulence
    +/-    adjust animation speed
	r/R    adjust color saturation
	o/O    adjust particle opacity
	l/L    adjust particle trail length
    SPACE  clear screen
    P      show/hide playlist
    S      toggle shuffle
    ZXCVBSR+-           control winamp
    up,down arrows      control volume
    left,right arrows   seek; hold SHIFT for fast seek

    If Smoke fails to initialize or freezes while running, try the 
    following steps to resolve the problem.  In 90% of cases the 
    problem can be fixed.

    1)  Make sure you have the latest version of Microsoft DirectX
        (8.1 at the time this documentation was written).  Even if 
        you already have it, consider re-installing it, since files 
        can be corrupted over time, and because poorly-written video 
        drivers can sometimes break your DirectX installation.
    2)  Update your video driver, or try other drivers.  A "driver" 
        is a piece of software that translates graphics-related commands 
        from programs, like Smoke, into the native language of your 
        specific graphics hardware.

        There are typically three sources for video drivers: 
            1) those from the card manufacturer's website
            2) those from the chip manufacturer's website 
                ("reference" drivers for the chip that powers the card)
            3) those that shipped with Windows

        Give them all a shot.  Track down every driver you can find for
        your card, and try it.  If your card isn't top-of-the-line, try 
        uninstalling your driver and use Windows Update to install the 
        drive that came with Windows (especially if it's a Voodoo card).  
        If it is top-of-the-line, try the various drivers available on
        the card or chip manufacturer's website.  Try the most recent 
        *certified* drivers first, as these have been tested the most
        thoroughly; if that doesn't work, try the "beta" (pre-release)
        driver, in case they've fixed the problem that's hampering you
        right now.  However, it's sometimes even more common to see 
        "broken" (buggy) beta drivers (ahem, nVidia!) that don't work, 
        than to see stable beta drivers that have fixed old problems.
        Here is a list of some common card/chip manufacturers and where 
        to get their drivers:
            [ Matrox   ]
            [ nVidia   ]
            [ 3dfx (voodoo cards) - remnants of a home page ]
            [ - your best bet for 3dfx drivers & support ]
            [ Diamond  ]
            [ Creative ]
            [ Trident  ]
            [ ATI      ] (requires javascript. click 'technical support' 
                in the lower left, then 'find a driver')
        Here are some sites that mirror (or link to) drivers from many sources:
            [ CNET ] (then click 'Utilities & Drivers', then 'Display & Video')
            [ ]

6. Known Issues
    On older video cards and many laptops, the tracer particles might
    show up as black streaks or dots (instead of subtle white streaks).  
    If this happens to you, try disabling the particles (from the config
    panel); their effect is subtle enough that the plugin should still
    look acceptable without them.

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.
            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.           
            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 SMOKE
            Run Smoke 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. Acknowledgements
    I would like to sincerely thank Ronald Fedkiw, Jos Stam, and their 
    colleagues, for their incredible work on the simulation of stable 
    fluids, without which this program would have never been possible.
	Also, thanks to Ryan Geiss for writing VMS (the Visualization Mega
	SDK) upon which this plugin's code (after version 1.06) was based.
	You can get VMS at .

9. Version History
1.06 - 28 August 2002
    -ported old code to VMS (the winamp "visualization MEGA sdk")
        -> now requires DX8.
        -> now has fantastic support for multimon
        -> now has fantastic audio response
	-added edge-darkening, so that the screen won't usually be 
		completely filled will color; there should always be some
		black background in there.
    -ravamped gridsize recalculation system & timing
    -made the turbulence randomly vary a bit, over time
    -at startup, or after hitting 'G', the gridsize will now 
        try to re-optimize, for 3 seconds each (with a 1-second
        break in between), up to 5 times, or until the target
        fps is acheived satisfactorily; whichever comes first.
    -now, if during runtime, the fps is too high or too low (by
        > 10%) for a solid 8 seconds, it will automatically
        resize the grid.
    -reduced default buoyancy by 5%
    -config panel: disabled particle settings when 'disable particles' checked
    -fixed a tiny memory leak in the fluid sim
    -tweaked audio analysis that softer sounds (during quiet songs) will be more
        likely to produce bursts of smoke.  

1.05b - 7 August 2002
    -noticed (after almost a year?!!) that the swirls have always been swirling
        clockwise!  Fixed this, so now swirls go both directions.
    -overhaul on audio analysis; had made major changes since 1.05, to calibrate
        audio for the new rendering style, but new code was buggy.
    -refined the strength & size of the plumes, for better sync to audio.
    -slowed down the default rate of color change a bit.
    -lowered the default amount of turbulence a bit.
    -increased default animation speed a bit.
    -cut down the plume strength when pressure calc. quality is high
    -added a messagebox to warn the user if they're trying to run it
        in a Window, when windows is in 16-bit color.
    -fixed a really dumb bug with the 'u' key; it was adjusting the animation
        speed, not the turbulence!
    -(overall, just a bunch of parameter & range tweaks that should make things
        look much better.)

1.05 - 30 July 2002
    -Smoke now looks more like water, since it now uses iterative rendering 
        to visually propagate the fluid.  (This allows the simulation resolution 
        to be quite large - up to 1024x1024 if your video card can handle it -
        and highly detailed.)  However, the name will remain as 'Smoke'.
    -revamped audio response system & color schemes to work better with new 
        image propagation method.
    -added 'hard cuts' to the color model, so the color will stay mostly the 
        same for some amount of time, and then suddely switch.
1.04 - 18 Apr 2002
    -fluid sim:
        -fixed horizontal/vertical 'runs' in the fluid, caused by high 
            turbulence setting.  Also cranked effective vorticity up 20%
            to account for the damping factor introduced by the H/V run fix.
        -cranked up default pressure calc. quality; realized it has a huge 
            impact on the visual quality, no matter what the gridsize is.
        -added options for even-greater quality of pressure calculations 
            to the config panel
        -found a bug where the plumes at the top were bigger than the plumes
            from the bottom; was related to order of looping (x vs. y-major)
            for u & v velocity advection.  Was unable to fix it, though, so
            instead, cheated & made plumes @ top smaller and plumes @ bottom 
        -fixed a bug w/semilagrangian advection and where it samples
            the velocity field; before, it was using the same point to
            sample the u and v values, but realized that this was illegal
            and made 2 separate samples - one for u, one for v.  Will be
            a tad slower, but advection should be much more accurate now.
        -optimized pressure calculation by using super-basic prefetches
        -optimized semilagrangian advection by providing guess vector
            for each cell, based on previous cell's advection vector;
            HUGE performance/quality gain!
    -audio response/plumes:
        -slightly lowered the beat sensitivity; had been noticing over & 
            over that sometimes beats were triggered too often.
        -made the plumes slightly smaller (they were huge in 1.04 beta 1)
        -expanded smoke plume entry angle range by 50%
        -gave plumes a minimum brightness
        -adjusted (strength, size, duration, and falloff) of plumes
            according to quality of pressure calculations.  (Before,
            higher-than-normal quality led to tiny, muted plumes.)
    -misc. tweaks:
        -increased default size of window (for windowed mode, of course).
        -aligned particles to 'fronts' of the plumes, and for any trail 
        -vastly improved edge velocity damping
        -allowed vorticity to vary over time, by up to 10%, just to change 
            things up a bit.
        -allowed color saturation to vary over time, by up to 10%
        -slightly lessened default amount of color damping (slowed the slow 
            fade to black)

1.04 beta 1 - 7 Feb 2002
    -smoke now minimizes Winamp when it starts.  Feature can be disabled from the
        config panel if not desired.  
        -sound: saw the negative user comments on at, freaked out, and 
            completely revamped the audio response engine.  Also, smoke plumes should 
            be larger & more powerful now.
        -color: added a dominant color that slowly varies over time, instead of randomly
            picking a brand new color for every plume.  This should create a more
            color-coordinated image over time.  
        -color: lowered default r/g/b color ranges from [0.2 - 1.2] to [0.1 - 1.1].
        -color: increased the amount of color damping in general, since there are 
            more plumes created now, and they tend to be bigger.
        -smoke: slightly lowered divisors for CG method (==better but slower pressure calx)
        -smoke: weakened default gravity; also, slider now defaults to middle
        -cached 1/cellsize computation in several places
        -got rid of density
        -compacted cellinfo structure; integrated color for better cacheing
        -inlined semilagrangian & fCGMethod functions
        -removed redundant *dt computation at end of CGmethod pass (when velocities get updated)
        -optimized some fine things in semilagrangian (big impact!)
        -removed unnecessary double-init of daF,daR,daQ,daP to zero
        -changed help key from 'H' to F1
        -changed 'show debug info' key from 'I' to F4
        -changed fps key from 'F' to F5
        -added 'F' key to freeze color scheme
        -added 'N' key to randomize color scheme
        -cleaned up the config panel a bit
        -calibration: removed '(calibrating...)' message when you hit the 'G' key
        -calibration: changed the way auto-optimize works; now, instead of just 
            doing it once at startup, it does it twice in a row, to ensure a more
            accurate framerate.

1.03 - 7 Dec 2001
    -config panel:
        -replaced gridsize selection with 'Target FPS' selection
        -added 'don't show ''press h for help'' or calibration messages' checkbox
        -added 'fade-to-black speed' (color damping) slider, for smoke color
        -added 'don't use alpha transparency' checkbox for particles; use this
            if the particles appear black.
        -added 'view docs' button
        -added 'defaults' button
        -added 'fonts' button and ability to adjust fonts
        -added button that links you to
        -added color saturation hotkeys (r/R)
        -added manual mode ('m', 0-9) so you can control the plumes of smoke
        -added key to display debug info: 'i'
        -added 'k' to toggle smoke on/off
        -added l/L to adjust particle trail Length
        -added o/O to adjust particle Opacity
        -added G to initiate a Gridsize optimization.  Once it finishes a short
            analysis, the gridsize will be adjusted to more accurately reach
            the Target FPS that you set from the config panel.
    -for users who might have been getting the message "failed to create m_lpDDSImageHW",
        did some things to try to fix this (removed the perhaps-unnecessary 
        DDSCAPS_VIDEOMEMORY flag, and added a 2nd try at 256x256 texture size).
    -fixed bug where particles & text couldn't be seen at the same time
        (moved DrawText calls to after EndScene - GDI conflict)
    -smoke plumes:
        -added persistence (they last more than 1 frame now)
        -made variance apply only in 1D (no longer 2D): the dimension perpendicular to the edge the plume is on
        -made plumes on bottom more likely to be hot, and plumes on top more likely to be cool
        -changed rho's range from 0..1 to 0.4..0.6
        -cranked color variance up from 0.1 to 0.25
        -changed default color ranges from 0-1 to .2-1.2, to compensate for
            the new color damping (fade-to-black)
        -made option to fix bug with some video cards (especially on laptops) where 
            the particles appeared black; requires selecting the 'don't use alpha 
            transparency' option from the config panel.
        -stopped particles from disappearing/sparkling away; all particle trails are now
            at least 2.5 pixels long (screen space).
        -playlist should now work in Windows ME!
        -fixed bug where currently-playing song wouldn't be highlighted in red
            if it had an '&' in the title
        -made it a little faster by only updating the list when you hit 'p'.
    -fixed bug in cleanup (exit) code - when deallocating a 2D array, tried to clean up
        H columns instead of W columns.
    -fixed terrible known bug w/framerate; animation quality only looked good at 15fps;
        now it looks good at any fps.  (had to pull dt out of per-timestep application of forces to smoke)
    -fps is now accurate even if you pause the song for a while, or some other system-stalling event occurs
    -fixed spacebar so it damps all values (even pressure fields)
    -protected vs. running w/o music playing
    -made velocity damping at edges oscillate from 0..1 over time (was always at 0)
    -removed support for 24-bit color, because it is evil
    -added 'press h for help' message at startup, and a checkbox to the config panel
        to disable it.
    -made help screen more legible by making 2 columns
    -user no longer selects the gridsize; instead, you select the fps (framerate) you want.
        It automatically adjusts to the right gridsize to get that framerate.  When it
        starts, it looks at whether or not you're in fullscreen or windowed mode, and at the
        last session's FPS and gridsize, and it computes the ideal new gridsize based on that
        information plus the new FPS desired (if it has changed since the last session).
        After running for about 64 frames of animation, it then takes a look to see if
        the it's on-target (the actual framerate matches the desired one) and, if not,
        adjusts the gridsize to get closer to the actual fps.  Most of the time this
        adjustment is very minor.  
        Whenever you resize the window, Smoke now automatically reoptimizes the gridsize.
        It takes into account the new aspect ratio, the target FPS, and past performance
        information to find the ideal gridsize to acheive the target FPS and make the 
        grid cells as square as possible (for best visual quality).

        To force an adjustment (gridsize optimization) while
        running Smoke, use the 'G' key.
    -might have fixed the problem where plugin wouldn't show up in the list of Winamp
        plugins (from the Prefs->Viz screen) because a recent enough DirectX wasn't 
        installed.  (stopped linking to ddraw.lib; instead use LoadLibrary and
        GetProcAddress to find/call DirectDrawCreate[Ex].)

1.02 - 2 Nov 2001
    -Initial worthwhile release.