SMOKE 1.06 (8/28/02)
a Winamp visualization plug-in by Ryan Geiss
copyright (c) 2001-2002 Nullsoft, Inc.
http://www.nullsoft.com/free/smoke/
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
5. TROUBLESHOOTING
6. known issues
7. using line-in (for live shows, etc.)
8. acknowledgements
9. version history
1. Requirements
-----------------------
Required:
* Hardware-based 3D graphics acceleration (i.e. a video card with 3D support)
* DirectX 8.0 or later ( http://www.microsoft.com/windows/directx/ )
* Winamp 2.72 or later ( http://www.winamp.com/ )
* Windows 98/ME/2000/XP/etc.
Recommended:
* 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
mode.
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
5. TROUBLESHOOTING
-----------------------
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 ]
[ voodoofiles.com - 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')
[ Driverzone.com ]
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.
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 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 http://www.nullsoft.com/free/vms/ .
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
bigger.
-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
length.
-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.
-tweaks
-sound: saw the negative user comments on at winamp.com, 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
-optimizations
-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
-hotkeys
-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
-misc
-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 http://www.nullsoft.com/free/smoke/
-hotkeys:
-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)
-particles:
-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
-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.