-----------------------------------------------------------------------
WINAMP 2.X VISUALIZATION PLUG-IN "MEGA SDK"
('Vis Mega SDK' for short)
('VMS' for shorter)
-----------------------------------------------------------------------
Description: A codebase for rapidly creating robust and feature-rich
DX8-based visualization plug-ins of your own.
Version: custom version based on 1.05 beta 1; upgraded to use DX9.
Released: n/a
Author: Ryan Geiss
Copyright: (c) 2002-2007 Nullsoft, Inc.
VMS HOMEPAGE: http://www.nullsoft.com/free/vms/
VMS AT WINAMP: http://www.winamp.com/nsdn/winamp2x/dev/plugins/vis.jhtml
SUPPORT FORUM: http://forums.winamp.com/forumdisplay.php?forumid=147
-----------------------------------------------------------------------
TABLE OF CONTENTS
-----------------
1. Purpose of this package
2. Features
3. Required software
4. Setting up the build environment
5. Starting Your Own Plugin Based on the Framework
6. Writing your own Plugin: A Brief Tour
7. Order of Function Calls
8. Using Data From the Base Class (CPluginShell)
9. Adding Controls to the Config Panel
10. Enabling Additional Tabs (pages) on the Config Panel
11. Using Visual C++ to Debug your Plugin
12. Releasing a Plugin
13. Tips to pass on the the user, in your documentation
14. Performance Tips for DirectX 8
15. Other Resources
16. Known Bugs
17. Version History
18. License
Purpose of this package
-----------------------
This package is for DEVELOPERS who want to write their own
visualization plugins.
It aims to provide a codebase that enables all developers
(beginning to advanced) to easily build robust Winamp 2.x
visualization plugins whose graphics are to be generated
though the DirectX 8 API. This codebase will 1) drastically
reduce the time it takes to write your plugin, 2) ensure
that it is robust (if you follow directions), and 3) give
you built-in support for many cool features, such as
multiple monitors. (See below for more details.)
Feel free to base any plugins on this "framework".
Features
--------
-DESKTOP MODE. Lets your plugin run as animated wallpaper,
with very little CPU overhead. (Your plugin can also
run in windowed or fullscreen modes, and the user can
switch between all 3 on the fly.)
-SUPERIOR MULTIMON SUPPORT. Your plugin will work on systems
with multiple display adapters, as well as systems with
a multi-head card. For multi-head cards that treat all
screens as one giant display (ie. resolutions like 2048x768
or 1024x1536), your users can even use 'fake' fullscreen mode
to run your plugin fullscreen on just one monitor!
-SOUND ANALYSIS: the framework provides your plugin with a
super-high-quality FFT (fast fourier transform) for doing your
own frequency analysis, or for drawing spectra. Framework also
provides super-simple loudness levels for 3 bands (bass,
mids, and treble) and at varying attenuation (damping) rates.
-A very nice CONFIGURATION PANEL is provided for the plugin.
On the first page (tab) of the config panel are all the
settings that all plugins share in common [handled by VMS];
on subsequent tabs, you add your own controls, for settings
that are specific to your plugin. The example plugin also
shows you how to easily handle the reading/writing of settings
that you add to/from the .INI file that will store your
plugin's settings.
-OTHER PERKS like a runtime help screen and playlist; high-precision
timing (accurate to 10 microseconds, or 0.00001 seconds);
pause-filtering (so your timing code won't got haywire
when Winamp is unpaused); and many others.
-CPU-FRIENDLY: when the window is minimized, or when you're
in fullscreen mode and ALT-TAB out, the plugin sleeps to
preserve CPU. FPS limiting also does its best to preserve
CPU, while at the same time, accurately limiting the FPS.
-ERROR FEEDBACK: provides detailed error messages to the user
on failure, as well as suggestions on how to fix problems.
Required software
-----------------
1. Nullsoft Winamp 2.X (~1 MB)
http://www.winamp.com/
2. Microsoft DirectX 8.0+ - (~11 MB)
http://www.microsoft.com/windows/directx/
3. Microsoft Developer Studio (Visual C++) 6.0
(a retail product)
4. Microsoft DirectX 8.0 SDK (Software Development Kit) - (~173 MB)
http://www.microsoft.com/windows/directx/
(then click the 'msdn' icon in the lower right, under
"info for developers")
*** NOTE that you can use a later SDK, such as 8.1b; but if you
do, then your plugin will only run on systems with that version
(or later) of the DirectX runtime installed! ***
*** You can also install several versions of the SDK into
different directories, and as long as the 8.0 sdk paths are
selected in Dev Studio (see below), your plugin will only
require the 8.0 runtime. ***
5. MSDN (Microsoft Developer Network) help library (OPTIONAL) (~1GB)
(also a retail product; optional, but highly recommended
to have around. If you can't get the CD's, though, you
can always access the help database online at
http://msdn.microsoft.com/library/ )
Setting up the build environment
--------------------------------
[Note: for Visual C++ .Net users, see below]
1. Make sure DirectX 8.0 or later is installed.
2. Make sure the DirectX 8.0 SDK (source development kit) is installed.
** (see notes above & below) **
3. Configure Visual C++ to use the [appropriate] DX8 SDK:
In Visual C++, go to Tools, then Options. Click on the
'Directories' tab. Under 'Show directories for:', select
'Include Files.' Then, below, add the INCLUDE folder
underneath the folder into which you installed the DX8 SDK.
Now highlight your addition and use the fancy-looking 'up'
arrow icon to move it to the top of the list of directories.
Now do the same thing for the LIB folder. Under 'Show
directories for:', select 'Library Files.' Now add the LIB
folder underneath the folder into which you installed the
DX8 SDK. Again, use the fancy-looking 'up' arrow icon
to move it to the top of the list of directories.
*** NOTE that if you have multiple DirectX 8 SDK's (such as 8.0
and 8.1b) installed to different directories, you'll want the
earliest one (hopefully 8.0) to be first in the list; that's
the one that will get used when you compile & link. Otherwise,
your plugin will only run on systems with the other version
(or later) of the DirectX runtime installed! ***
4. (optional) you might want to set Visual C++ up to use
4 spaces instead of symbolic tabs, to keep the formatting
of new code that you write consistent with this code.
If you want to do this, go to menu:Tools->Options, click
the 'Tabs' tab, set the 'Tab Size' to 4 and click on
'Insert Spaces'.
[FOR VISUAL C++ .NET USERS:]
You'll want to start a fresh DLL-based project and manually
add all the source/header files to it. Then go into project
settings and make it **Use MFC in a SHARED DLL**.
Starting Your Own Plugin Based on the Framework
-----------------------------------------------
1. Copy the files in the 'ExPlugin' folder to a new folder,
such as 'MyPlugin' - it can be anything.
2. In the new folder, rename the workspace file ExPlugin.dsw
to MyPlugin.dsw (or equivalent).
3. Open the new workspace file (that you just renamed) in Visual C++.
4. Go to menu:Build->Configurations and select 'plugin - Win32 Debug'.
5. Go to menu:Project->Settings
a. In the upper-left corner, where it says 'Settings For:',
select 'All Configurations' from the dropdown box.
b. Click the 'debug' tab, and under 'Executable for debug
session', point it to winamp.exe (most likely
c:\program files\winamp\winamp.exe). (This will enable
you to debug your plugin using Visual C++.)
c. Click the 'link' tab, and under 'Output file name',
enter the name of the .DLL to write (such as
c:\program files\winamp\plugins\vis_myplugin.dll).
This should start with 'vis_' and end in the
'.dll' extension. This DLL will be your plugin.
d. click OK.
6. On the left you should see the workspace view (if not, hit ALT+ZERO)
to bring it up) with 3 tabs at the bottom (ClassView, ResourceView,
FileView). Click 'FileView'. Expand everything in this view so you
can see all the files.
7. Open 'defines.h' by double-clicking it. Now edit this file according
to the comments, to give your plugin a name, a version number, enter
the author's name, copyright string, the name of the .INI file you
want to save the user's settings in, the name of the documentation
file, and so on. (You can always come back and change these values
later, of course).
Now you're ready to build & run the plugin:
8. Press F7 to build the plugin.
a. If you get any of these error messages:
fatal error C1083: Cannot open include file: 'd3d8.h'...
fatal error C1083: Cannot open include file: 'd3dx8.h'...
Then you haven't added the DX8 SDK *include* path to your
build environment. See 'To set up the build environment'
above.
b. If you any linker error messages, such as this one:
LINK : fatal error LNK1104: cannot open file "d3d8.lib"
Then you haven't added the DX8 SDK *library* file path to your
build environment. See 'To set up the build environment'
above.
9. Copy the files 'ex_tex.jpg' and 'vms_desktop.dll' from the MyPlugin
directory to your Winamp PLUGINS folder (usually c:\program files\
winamp\plugins).
10. Run Winamp, press CTRL+P to select your plugin, and make sure that
it appears in the list. Notice that the name matches what you
entered into the 'defines.h' file as APPNAME; if you didn't change
it, it will appear as 'Example Plugin v1.04 / VisMegaSDK' (or
something similar). Next, configure the plugin, hit OK, & run it
by clicking 'Start'.
Writing your own Plugin: A Brief Tour
-------------------------------------
This starts out by pointing you at the important source code,
then by showing you around the resource editor and, finally,
the DirectX 8 and MSDN help libraries.
1. Take a look at each of the 6 files in the 'My Plugin Source Files'
and 'My Plugin Header Files' groups. These will give you an idea
of the code that makes up the example plugin. All of the
behind-the-scenes code is wrapped up in the 'Framework Files'
group, which you shouldn't have to bother with (unless you
want to).
2. Take a close look at plugin.h. This is the C++ class that makes
up your plugin. Note that the class is derived from the
CPluginShell class (which is in pluginshell.h/cpp), so it inherits
all its functions & variables. What you see here (in plugin.h)
are the data members and functions ADDED for this specific
(example) plugin, as well as the 12 pure virtual functions we've
implemented from the base class.
3. Take a close look at plugin.cpp. READ THE BRIEF COMMENTS AT THE
TOP OF THOSE 12 VIRTUAL FUNCTIONS TO GET AN IDEA OF WHEN THEY'RE
CALLED AND WHAT THEY DO.
4. Next we'll go into the Resource Editor.
Click the 'ResourceView' tab at the bottom of the Workspace view.
Then expand 'plugin resources' by double-clicking it, expand
'Dialog' in the same way, and double-click 'IDD_CONFIG' to open
the template for the config panel. You can now double-click
individual controls to edit their properties; move/resize them;
press CTRL+T to test the dialog; press CTRL+D to define the tab
order; and even add new controls (using the floating toolbar)
(note that added controls require a lot of support code in
plugin.cpp; see 'Adding Controls to the Config Panel' below).
Also expand the 'Icon' folder on the left (just after 'Dialog')
and double-click IDI_PLUGIN_ICON. This is the icon used in the
taskbar, window title, and ALT+TAB screen when your plugin is
running. Note that there are 5 different icons within this one,
all at different resolutions and color depths, accessible by
changing the 'device' (just above the enlarged icon in the
resource editor). So, when you go to update the icon, don't forget
to update it for all devices!
5. In Windows, go to Start Menu -> Program Files -> Microsoft
DirectX 8 SDK -> DirectX Documentation (Visual C++). This
is the help library for DirectX 8; you will need to refer to
it religiously in order to get anything done in DirectX 8.
The good news is, it's *extremely* well-written.
6. In Windows, go to Start Menu -> Program Files -> Microsoft
Developer Network -> MSDN Library. This is the help library
for the general Win32 platform, but might not have info on
DirectX 8 (depending on when your version was published).
If you couldn't get the MSDN CD's, you can access the MSDN
library online at:
http://msdn.microsoft.com/library/
You'll have to do this from time to time to write a plugin,
but not nearly as often as you'll be accessing the DirectX 8
help library.
You might also want to take a look at the useful goodies inside
utility.cpp; they could come in handy.
That's it; you've now seen all the 'screens' you'll spend 99% of
your time on, in order to write your own plugin.
Order of Function Calls
-----------------------
The only code that will be called by the plugin framework are the
12 virtual functions in plugin.h. But in what order are they called?
A breakdown follows. A function name in { } means that it is only
called under certain conditions.
Order of function calls...
When the PLUGIN launches
------------------------
INITIALIZATION
OverrideDefaults
MyPreInitialize
MyReadConfig
<< DirectX gets initialized at this point >>
AllocateMyNonDx8Stuff
AllocateMyDX8Stuff
RUNNING
+--> { CleanUpMyDX8Stuff + AllocateMyDX8Stuff } // called together when user resizes window or toggles fullscreen<->windowed.
| MyRenderFn
| MyRenderUI
| { MyWindowProc } // called, between frames, on mouse/keyboard/system events. 100% threadsafe.
+----<< repeat >>
CLEANUP
CleanUpMyDX8Stuff
CleanUpMyNonDx8Stuff
<< DirectX gets uninitialized at this point >>
When the CONFIG PANEL launches
------------------------------
INITIALIZATION
OverrideDefaults
MyPreInitialize
MyReadConfig
<< DirectX gets initialized at this point >>
RUNNING
{ MyConfigTabProc } // called on startup & on keyboard events
CLEANUP
[ MyWriteConfig ] // only called if user clicked 'OK' to exit
<< DirectX gets uninitialized at this point >>
Using Data From the Base Class (CPluginShell)
---------------------------------------------
The base class from which your CPlugin class (in plugin.cpp) is
derived is called CPluginShell and is defined in pluginshell.cpp.
Many of its data members are 'protected', which means that only that
class itself, *plus derived classes*, can access them. ('Public'
members can be accessed by anyone; 'private' are unaccessible even
to derived classes.)
The protected data members and methods (functions) are as follows.
Generally, you should treat the data members as READ-ONLY; the only
exception is in OverrideDefaults(), where you can modify some of
their values to alter the "default defaults". See the comments at
the top of OverrideDefaults() in plugin.cpp for more information.
Here are all of the members & methods maintained by the plugin shell,
and available to CPlugin:
// GET METHODS
// ------------------------------------------------------------
int GetFrame(); // returns current frame # (starts at zero)
float GetTime(); // returns current animation time (in seconds) (starts at zero) (updated once per frame)
float GetFps(); // returns current estimate of framerate (frames per second)
eScrMode GetScreenMode(); // returns WINDOWED, FULLSCREEN, FAKE_FULLSCREEN, DESKTOP, or NOT_YET_KNOWN (if called before or during OverrideDefaults()).
HWND GetWinampWindow(); // returns handle to Winamp main window
HINSTANCE GetInstance(); // returns handle to the plugin DLL module; used for things like loading resources (dialogs, bitmaps, icons...) that are built into the plugin.
char* GetPluginsDirPath(); // usually returns 'c:\\program files\\winamp\\plugins\\'
char* GetConfigIniFile(); // usually returns 'c:\\program files\\winamp\\plugins\\something.ini' - filename is determined from identifiers in 'defines.h'
// GET METHODS THAT ONLY WORK ONCE DIRECTX IS READY
// ------------------------------------------------------------
// The following 'Get' methods are only available after DirectX has been initialized.
// If you call these from OverrideDefaults, MyPreInitialize, or MyReadConfig,
// they will return NULL (zero).
// ------------------------------------------------------------
HWND GetPluginWindow(); // returns handle to the plugin window. NOT persistent; can change!
int GetWidth(); // returns width of plugin window interior, in pixels.
int GetHeight(); // returns height of plugin window interior, in pixels.
int GetBitDepth(); // returns 8, 16, 24 (rare), or 32
LPDIRECT3DDEVICE8 GetDevice(); // returns a pointer to the DirectX 8 Device. NOT persistent; can change!
D3DCAPS8* GetCaps(); // returns a pointer to the D3DCAPS8 structer for the device. NOT persistent; can change.
D3DFORMAT GetBackBufFormat(); // returns the pixelformat of the back buffer (probably D3DFMT_R8G8B8, D3DFMT_A8R8G8B8, D3DFMT_X8R8G8B8, D3DFMT_R5G6B5, D3DFMT_X1R5G5B5, D3DFMT_A1R5G5B5, D3DFMT_A4R4G4B4, D3DFMT_R3G3B2, D3DFMT_A8R3G3B2, D3DFMT_X4R4G4B4, or D3DFMT_UNKNOWN)
D3DFORMAT GetBackBufZFormat(); // returns the pixelformat of the back buffer's Z buffer (probably D3DFMT_D16_LOCKABLE, D3DFMT_D32, D3DFMT_D15S1, D3DFMT_D24S8, D3DFMT_D16, D3DFMT_D24X8, D3DFMT_D24X4S4, or D3DFMT_UNKNOWN)
char* GetDriverFilename(); // returns a text string with the filename of the current display adapter driver, such as "nv4_disp.dll"
char* GetDriverDescription(); // returns a text string describing the current display adapter, such as "NVIDIA GeForce4 Ti 4200"
// FONTS & TEXT
// ------------------------------------------------------------
LPD3DXFONT GetFont(eFontIndex idx); // returns a D3DX font handle for drawing text; see shell_defines.h for the definition of the 'eFontIndex' enum.
int GetFontHeight(eFontIndex idx); // returns the height of the font, in pixels; see shell_defines.h for the definition of the 'eFontIndex' enum.
// MISC
// ------------------------------------------------------------
td_soundinfo m_sound; // a structure always containing the most recent sound analysis information; defined in pluginshell.h.
void SuggestHowToFreeSomeMem(); // gives the user a 'smart' messagebox that suggests how they can free up some video memory.
// CONFIG PANEL SETTINGS
// ------------------------------------------------------------
// *** only read/write these values during CPlugin::OverrideDefaults! ***
int m_start_fullscreen; // 0 or 1
int m_start_desktop; // 0 or 1
int m_fake_fullscreen_mode; // 0 or 1
int m_max_fps_fs; // 1-120, or 0 for 'unlimited'
int m_max_fps_dm; // 1-120, or 0 for 'unlimited'
int m_max_fps_w; // 1-120, or 0 for 'unlimited'
int m_show_press_f1_msg; // 0 or 1
int m_allow_page_tearing_w; // 0 or 1
int m_allow_page_tearing_fs; // 0 or 1
int m_allow_page_tearing_dm; // 0 or 1
int m_minimize_winamp; // 0 or 1
int m_desktop_show_icons; // 0 or 1
int m_desktop_textlabel_boxes; // 0 or 1
int m_desktop_manual_icon_scoot; // 0 or 1
int m_desktop_555_fix; // 0 = 555, 1 = 565, 2 = 888
int m_dualhead_horz; // 0 = both, 1 = left, 2 = right
int m_dualhead_vert; // 0 = both, 1 = top, 2 = bottom
int m_save_cpu; // 0 or 1
int m_skin; // 0 or 1
td_fontinfo m_fontinfo[NUM_BASIC_FONTS + NUM_EXTRA_FONTS];
D3DDISPLAYMODE m_disp_mode_fs; // a D3DDISPLAYMODE struct that specifies the width, height, refresh rate, and color format to use when the plugin goes fullscreen.
Adding Controls to the Config Panel
-----------------------------------
There are four basic aspects of adding a new control to the config panel,
outlined below.
1. Add the control to one of the property pages in the config panel (2..8),
via the Resource Editor. Note that you should not modify the config
panel itself (IDD_CONFIG) or the first property page (IDD_PROPSHEET_1).
Also, do not resize the page dialogs or the config panel; they are designed
to fit on a 640x480 screen, and should not be expanded.
2. Add a variable (data member) to represent the control to your CPlugin class,
in plugin.h.
3. In plugin.cpp:
a. initialize the variable to its default value in MyPreInitialize(),
b. read its value from the INI file in MyReadConfig(), and
c. write its value to the INI file in MyWriteConfig().
4. In plugin.cpp, in the MyConfigTabProc function, **when 'nPage' is
the index (2..8) of the tab on which the control was placed:**
a. add code under WM_INITDIALOG to set the state of the control
(from the variable) when the config panel is started
b. add code under WM_COMMAND, case IDOK, to read the state
of the control and save the result in the variable
c. add a handler for your new control underneath WM_HELP, so that
when the user clicks the '?' in the config panel titlebar,
then clicks on your control, they get a helpful messagebox
explaining what the control does.
Enabling Additional Tabs (pages) on the Config Panel
----------------------------------------------------
By default, only two 'tabs' (pages) are enabled on the config panel.
The first is handled by the framework, and should not be modified;
the second, and any you add, are handled in plugin.cpp, in MyConfigTabProc().
The maximum number of tabs/pages is 8 (unless you want to modify the
framework files).
To add a third page (for example), simply open defines.h, and give a name
to the tab by setting the value of CONFIG_PANEL_BUTTON_3. This is all you
have to do to make the tab appear! To add controls to the new page, see
the above section entitled 'Adding Controls to the Config Panel.'
If you want to extend the framework to add a 9th page (?!), you need to:
1. create a dialog called IDD_PROPPAGE_9 (style=child, border=none, visible, ctrl parent, control).
2. in config.cpp, increment MAX_PROPERTY_PAGES
3. in config.cpp, add IDD_PROPPAGE_9 to g_proppage_id[]
4. in config.cpp, call AddButton for it
Using Visual C++ to Debug your Plugin
-------------------------------------
1. Build the plugin in the 'Debug' configuration
(menu:Build->Configurations, then select 'debug').
2. Go to menu:Project->Settings (ALT+F7) and click the
'Debug' tab. Under 'Executable for debug session',
point it to winamp.exe.
3. Press F5 to start debug session; it will launch winamp.
4. You can now configure your plugin or run it; just set a
breakpoint anywhere in your code (F9) and when the code
gets to that point, it will break, and you can look at
variable values and browse structures (SHIFT+F9), jump
around on the call stack (ALT+7), and so on.
Releasing a Plugin
------------------
1. Build in Release Mode
Once you're done debugging and ready to share your plugin
with others, go to menu:Build->Configurations and select
'plugin - Win32 Release', then go to menu:Build->Clean and
menu:Build->Rebuild All. Building in release mode makes
your code smaller and faster (but doesn't allow debugging).
2. Package it up an a self-installing .EXE
Here you'll want to download the Nullsoft Superpimp Install
System (NSIS) from http://www.nullsoft.com/free/nsis/ to
make your users' lives easier.
Then read the instructions at the top of the install script
file 'installer.nsi' (next to DOCUMENTATION.TXT) and edit the
install script to reflect the name and version of your plugin,
the paths & filenames & destination paths of everything you
want packaged up, and the output installer filename.
After installing NSIS, editing installer.nsi, and doing
a final release build, run a command something like this
from the command prompt (you'll have to adjust the paths):
"c:\program files\Nsis\makensis" C:\MyProjects\MyPlugin\installer.nsi
If all goes well, you'll have a file named something like
'myplugin_100.exe' in your MyPlugin directory. Test it
out on a fresh machine to make sure the install screens
say the right thing and install the right files, and
you're set to go!
3. Checklist: (prior to actually running makensis.exe)
* Did you update the version number and APPNAME in defines.h?
* Did you do a final pass on the tab ordering (CTRL+D from the
Resource Editor) of the config panel?
* Did you add WM_HELP handlers to new controls on the config panel?
* If you added any MessageBox() commands, did you supply the right
HWND parameter? (The messagebox will pop up on the same monitor
that that HWND is on.)
* Did you test your plugin in Desktop Mode, while Winamp is
*paused*, and then try moving icons around, to make sure that
you're properly handling the 'redraw' flag in MyRenderFn()?
* Did you update the version numbers throughout installer.nsi?
* Did you update the help screen text? (see top of plugin.cpp)
* Did you do your final build in Release mode?
* Did you write/update documentation?
Does the config panel link to it work?
* Did you make/update a webpage?
Does the config panel link to it work?
Tips to pass on the the user, in your documentation
---------------------------------------------------
1. 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.
2. If you want Winamp to listen to your sound card's Line-In or Mic-In
(or other audio input channel on your system) for driving the
visuals, just do the following:
1. CONNECT WIRES
Connect your audio source (a stereo, a live feed, whatever) into
the line-in (or microphone) 1/8" jack on your sound card.
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
in Winamp, and the little built-in oscilloscope (or spectrum
analyzer) in Winamp should start showing your signal.
4. RUN YOUR VISUALIZATION PLUGIN OF CHOICE
If the plugin seems to be responding too much or too little,
try adjusting the volume from Windows' Volume Control, or adjust
the sound level at the source.
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
or file-swapping software. Also, 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. LCD screens: Note that most LCD screens (flatpanels) run at 60 Hz only,
meaning that they update the screen 60 times per second. However,
sometimes the video driver reports that it supports other refresh
rates, such as 72, 75, 85, etc. It is strongly recommended that
[for fullscreen mode, and for Windows in general] you choose a
display mode with a 60 Hz refresh rate, for the smoothest possible
animation. For this plugin, you will also want to choose
Maximum Framerates that divide evenly into 60 - such as 60, 30, 20,
15, 12, 10, 6, 5, and so on - so that the # of times the LCD shows
each frame of animation remains constant, resulting in the smoothest
possible animation.
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.)
that you reboot Windows before running this plugin.
6. Video Capture: If you'd like to save sequences of video from this plugin,
there are several programs out there that will let you do this. Warning:
you will need a ton of free hard drive space, and a fast CPU helps. A
few of these programs are:
"FRAPS" http://www.fraps.com/
"Hypercam" http://www.hyperionics.com
(That's it, for now. PLEASE include the tip about live audio input!)
Performance Tips for DirectX 8
------------------------------
1. Minimize state changes (SetTexture, SetTextureStageState,
and SetRenderState) at all cost; group polygons together
that share the same rendering settings and send them all
together. You will be amazed at the performance gain.
2. Use Vertex Buffers and Index Buffers for all your static
geometry (i.e. vertices/indices that don't change every
frame - like a static model that doesn't change, even
though it might move around, rotate, resize, etc. due
to the world/view/projection matrices). These buffers
will keep the geometry in video memory (if possible) so
that the data doesn't have to cross the bus every frame;
if not, they'll try to at least place the geometry/indices
in AGP memory. If you don't use these driver-managed
buffers (and instead use DrawPrimitiveUP and
DrawIndexedPrimitiveUP), you're keeping all of your data
in non-AGP system memory, and unless the data is very
small, you can expect a major bottleneck. Note that for
dynamically-generated vertex data (i.e. vertices are
generated each frame - like when you draw a waveform),
you don't have a choice.
If you follow these two tips and use common sense (and know
the basic theory behind how 3D accelerators work), you should
be getting 30 fps on a Voodoo 3 (assuming your overdraw is low,
i.e. you don't draw each pixel on the screen more than once or
twice per frame).
For more tips, look in the DX8 SDK Documentation, or look on
the web.
Other Resources
---------------
1. DX8 SDK: The DX8 documentation that came with your DX8 SDK is,
by far, the most critical resource you have. It fully documents
the entire API, and much more. The SDK also comes with tons of
samples and their source code.
2. NSDN: the Nullsoft Developer Network, where the Winamp API
is published: http://www.winamp.com/nsdn/winamp2x/
If you want to do anything in MyWindowProc() that involves
communicating with the Winamp window directly (such as
querying for the song title/time/length, querying the playlist,
adjusting the panning, toggling shuffle, etc.), you'll need
to delve into NSDN. It's all extremely straightforward and
simple. For a few examples of how to talk to the main Winamp
window, check out PluginShellWindowProc() in pluginshell.cpp.
3. Here are links to a few sites with good DirectX tutorials/faqs/code:
The X-Zone: http://www.mvps.org/directx/
Gamedev.net: http://www.gamedev.net/reference/
Known Bugs
----------
1. When running [true] fullscreen in a multimon setup,
sometimes when the user presses ALT-TAB to switch away from the plugin
and to another window, the plugin will minimize. The 'sometimes' is
determined as follows:
-if the user releases TAB before depressing ALT, the window
minimizes (undesired behavior).
-if the user depresses ALT before releasing TAB, the window does
not minimize (desired behavior).
2. Desktop Mode: some features are not implemented yet. They are:
-right-click -> cut/copy/paste/rename
-right-click -> "send to" doesn't work on all machines
-no keyboard commands (delete, enter, arrows, CTRL+X/C/V/Z)
-no drag-and-drop for files
-desktop shortcuts mostly work when you double-click them,
but on some machines bring up an "open/save" dialog
instead of actually launching the file.
That's it for now.
If anyone finds a solution for any of these bugs, please post the solution
in the VMS forum, and it will be included in the next VMS release.
Version History
-----------------------------------------------------------------------
[v1.05 beta 1 - June 26, 2003]
-revamped the way keyboard commands are routed between your plugin
and the plugin shell. Before, the shell captured certain keys
('p' for playlist, 'zxcvb' for playback, 's' for shuffle, 'F1'
for help, ESC to exit, arrows for volume/seeking, etc.)
and the plugin was unable to override these. Now, the shell
will pass the WM_KEYDOWN/WM_CHAR message to the plugin
(MyWindowProc) first, to see if it wants to process it. If the
plugin steals the key, it returns 0, and the shell ignores it.
If the plugin does not process the key, it returns 1, and then
the shell is free to process it.
*** NOTE that if you are upgrading to VMS 1.05, this means you'll have to
*** update the way your WM_CHAR and WM_KEYDOWN handlers work in plugin.cpp!
*** [primarily, you'll have to return 0 when you handle a key, and 1
*** otherwise.]
-added key: 'r' for repeat
-added SKINNING; if you have Winamp 2.90+, you can now check the
'integrate with winamp' checkbox and the plugin [when running in
windowed mode] will be skinned just like Winamp. The integrated
window works just like any other Winamp window; it docks with
other windows, CTRL+TAB cycles between them all, and lots of new
keys work (J, L, CTRL+P, ALT+E, etc.).
-fixed bug (or error in judgment?) where fake fullscreen mode window
would actually run at the *bottom* of the Z order when running
on a multiple monitor setup. The problem was that if you clicked
on any other window, the taskbar would pop up, potentially overtop
of the plugin. Since there's really no way around this, I decided
(before) to just stick the plugin at the bottom of the Z order in
this case. Well, this is now fixed; the plugin tries its best
to stay on top, but watch out - if you try and click on any other
windows, the taskbar WILL pop up. If you want to avoid that,
you'll have to run in true fullscreen mode.
-improved audio and video synchronization
-the current framerate is now used to tell Winamp, each frame,
exactly how far in advance it should give us the audio data.
For example, if we're getting 20 fps, we should get the
audio 50 ms in advance for the proper video frame to appear
when the user will actually hear those audio samples.
-timing: added calls to beginTimePeriod and endTimePeriod, so the assumed
granularity for Sleep() is now 2 ms (down from 10 ms).
This means that CPU usage will dramatically drop, and
fortunately, there should be no effect on framerate accuracy.
-desktop mode: added 'show icons' option to the desktop mode options
dialog, so users can uncheck it (and hide/disable the icons) if they
like.
-user can no longer shrink the window to less than 64x48 in size.
(often the minimum size will be higher than this though; see
WM_GETMINMAXINFO in pluginshell.cpp).
-user can now switch modes (windowed <-> fullscreen <-> desktop mode)
immediately. (before, it was blocked until frame 5.)
-(fixed a small bug in the example plugin, where handler for WM_KEYUP
returned DefWindowProc instead of 1).
-any time the DirectX setup fails when starting up (or switching to)
windowed mode, the window coords are now saved to disk as a 256x256
window placed at (64,64). That way, if the problem was due to running
out of video memory, it will be less likely to recur.
-config panel:
-added two more fonts: one for the playlist, and another for the
help screen.
-it's now easy to add your own fonts to the font dialog in the
config panel; just add the appropriate #defines in the file
defines.h. Then you can access them easily from plugin.cpp by
calling GetFont(EXTRA_1), GetFont(EXTRA_2), and so on, up to
GetFont(EXTRA_5). You can also get their height by calling
GetFontHeight(EXTRA_1) through GetFontHeight(EXTRA_5).
-greatly improved the installer script.
-now selects winamp2 dir by default, if both winamp 2 & 3 are installed.
-fixed a bug where the plugin wasn't being correctly set as the default plugin
in winamp. Also, this is no longer an option - it just automatically does it.
-now, when you go to install to winamp 3, it checks to see if ClassicVis
is installed. If it is, you're set; if not, it prompts you to go download
it. If you choose not to, it alerts you that the installation failed.
-the FFT class (fft.cpp, fft.h) now has 2 extra optional init parameters.
-'bEqualize' is 1 by default; set it to 0 to have a non-equlized FFT;
bass frequencies will be much higher in magnitude than treble frequencies.
-'envelope_power' is 1.0 by default; adjust it to change the characteristics
of the resulting frequency spectrum (see comments in fft.cpp, in
InitEnvelopeTable). Set this to a negative value to not use an envelope.
-the help screen is no longer pre-rendered to a texture; it is now just drawn every
frame that it's needed. (Decided that that precious memory on some 8MB graphics
cards was more important than having a good framerate, on some cards, while viewing
the help screen.)
-added some nice macros to MyRenderUI() in plugin.cpp; makes the code for drawing
text much simpler.
-added 2 functions, GetDriver and GetDesc, which will return text strings with the
name & description of the currently active display adapter. (search these
strings for vendor substrings like "nvidia", using strstr or something similar,
to do vendor-specific bug workarounds. blech.)
-fixed a bug in SSE detection
-added handy memset_MMX() function to utility.cpp (alongside memcpy_MMX)
-fixed tabbing order for controls config panel tab #1 (doh)
-in 'defines.h', you now specify a long name + a short name for your plugin.
The long name is used for the description string in winamp's list of plugins;
the short name is used for the window caption.
-in the example plugin, in plugin.cpp, the F3 key (show song length)
is now a three-state toggle: off, current time, and current time / total
length.
[v1.04 - October 29, 2002]
-DESKTOP MODE: the icing on the cake.
-Allows users to run your plugin as animated wallpaper, with very
little cpu overhead. Uses no overlays or other unusual hardware
features.
-Just make sure you include the file 'vms_desktop.dll' with your
plugin; it is required for Desktop Mode to work properly.
It's small, though - only 48 kb. This file is now included
in the sample install script (installer.nsi).
-You can toggle Desktop Mode on/off at runtime by hitting ALT+D.
And as before, you can toggle Fullscreen via ALT+ENTER.
-Not all features of the desktop are fully implemented, but most
of the most-frequently-used features should be working.
For a list of the features not yet implemented, see the
'Known Bugs' section above.
-CHANGES MADE TO PLUGIN.H,CPP: (isolated for ease-of-merging purposes)
1. added a few config settings; see OverrideDefaults()
in PLUGIN.CPP.
2. added 'redraw' flag to MyRenderFn - see the comments
at the top of MyRenderFn. Make sure you respect this
flag, or else, when the user moves icons around in
Desktop Mode while Winamp is paused, your plugin
will mysteriously start animating.
3. added the 'MyRenderUI' function - please break your
text-rendering code in MyRenderFn off into this function.
4. removed the ClipPlaylist() functions and, instead, provided
pointers to some values as params to MyRenderUI() that tell
you where to place text in each of the corners. As you
draw text, be sure to update these values, so that any
text drawn by the plugin shell (parent class) won't try to
draw text overtop of your text.
-Plugins based on VMS now remember the window position when they last
(successfully) exited windowed mode, and use that as the
default when they re-enter windowed mode (during the same
session or in a later session). If there is an error creating
that window (too big/not enough video memory, off-screen
because display mode resolution decreased, etc.) it will
revert to the default window size & position.
-Config Panel:
-For users with DualHead cards that run two monitors as one
virtual display (e.g. 2048x768 or 1024x1536), you can now
specify which half of the screen you want Fake Fullscreen Mode
and Desktop Mode to occupy, or both. See the 'DualHead'
button on the config panel.
-Added an option to save cpu usage by using a more-tolerant
framerate limitation algorithm - saves 0-20%. Default: ON.
-Fixed appearance of the help screen by adding +0.5-texel offset;
on some cards, help screen text was kind of jaggy and munged.
-Release builds no longer log window messages to the debug
output stream.
-The D3DX font for the help screen text is now created at
initialization time, instead of on demand.
-Framework Files:
-renamed 'fontdialog.cpp' to 'config2.cpp', since it now contains
more than just the font dialog code.
-added 'desktop_mode.cpp' and 'icon_t.h' to support Desktop Mode.
-Changes made to the sample installer script: [installer.nsi]
-added UnInstall options for winamp 2 and 3
-simplified things by using some !define's at the top
-updated it to look for Winamp 3's new executable
name: winamp3.exe (in addition to the old, which was
studio.exe)
-----------------------------------------------------------------------
[v1.03 - August 27, 2002]
[MAJOR CHANGES]
-audio:
-vastly improved frequency analysis by multiplying the waveform by a
bell-shaped envelope before sending it to the FFT, lessening the
frequency response of the old square filter and producing a more
precise frequency analysis. Also improved it by doing a 1024-sample
FFT (instead of a 512). Special thanks goes out to Alan Seefeldt
and Alan Peevers for sharing their extensive knowledge in this area!
-config panel:
-split it into separate property sheets, so that
future updates to VMS (this sdk) will be easier to integrate
with code based on previous versions. Also, this gives developers
a lot more space to add things to the config panel.
-split the settings for 'fake fullscreen' mode and regular
fullscreen mode into two separate sets of controls, instead
of sharing controls; it was too confusing that way.
-added option to minimize winamp when going fullscreen.
Only actually minimizes winampwhen going fullscreen
(or fake fullscreen) AND winamp and the plugin window
are situated on the same monitor.
-added user-configurable fonts to the config panel.
-text:
-added a built-in playlist!
-added some sample code (in plugin.cpp / RenderText()) for showing
the current song title, position, and length.
-timing:
-oops... hi-precision timer was disabled in last version!
-also discovered an even more high-precision timer, which provides
a time sampling precision of from 1 to 5 *MICRO*seconds!
-ditched the 'frame delay' system and replaced it with a 'max fps'
system that should work more intuitively, and be extremely
accurate (thanks to the new timer).
-classes:
-got rid of InitMyGDIStuff() and CleanUpMyGDIStuff() - not really needed
-got rid of MyPreRenderFn() - also not really needed
-in windowed mode, if there is not enough video memory to create
the window at the default size, the window will now try to shrink
further and further, until it is small enough to work.
-fixed problem where the plugin wouldn't show up in the plug-ins list
in Winamp, if the user didn't have DX8 or later installed. Now
it does show up in the list, and if they try to run/configure it
and DX8 is missing, it will indicate this, and even offer to
take them to the MS DirectX website to download it.
-also started calling LoadLibrary("d3d8.dll") before calling
Direct3DCreate8(), so the latter wouldn't crash on systems
without DX8.
-yanked the fractal stuff out of the example plugin; too complicated.
[MINOR CHANGES]
-now more resilient when user turns off some display (in a multimon
setup), then goes to run the plugin on that display (because they
didn't return to the config panel and update the display adapter
selection).
-improved suggested actions for when the plugin fails to start
because there is not enough video memory; suggestions now
include turning off other programs that might be using up
video memory (Windows Media Player, NetMeeting, and so on).
-config panel: disabled caps checking; sometimes requesting
the caps fails when you dynamically enable/disable monitors in
a multimon setup, so adapters that really exist (and are on)
would be missing in the list.
-config panel: added a sample combobox & slider to the 2nd property page,
which now features a checkbox, slider, and combobox, all
as simple examples for the plugin developer to build off of.
-noticed that multipsampling only works with D3DSWAPEFFECT_DISCARD,
so the code is now protected against using D3DSWAPEFFECT_COPY_VSYNC
with multisampling. The config panel has also been updated to
indicate to the user that if page tearing is disallowed,
multisampling will not function. This is a limitation of
the DirectX 8 API.
-added OverrideDefaults() function; see comments in plugin.cpp
-revamped the sample beat detection code
-tightened up the interface to CPluginShell
-made DirectX get initialized earlier (and cleaned up later)
so that GetWidth() and GetHeight() would be valid longer
-moved srand(time(NULL)) up to top of MyPreInitialize, in case
the developer wants to randomly initialize any of their
variables there.
-modified PrepareFor2DDrawing() so that it always makes the range
of X,Y coords -1..1 (before it was -width/2..width/2, and similarly
for height). Also inverted Y, so that y==-1 is actually at the
top of the screen, and Y==1 is at the bottom.
-added PrepareFor3DDrawing()
-improved auto-selection of best-match video mode; now, if it can't
find the exact pixel format that was in the INI file,
if will try other video modes that have the same bit depth,
but a different arrangement of the bits. [This applies to both
the config panel, AND when you go to run the plugin fullscreen.]
-respected key repeat count for playlist navigation (up/down), volume
adjust (up/down), and seeking (left/right).
-fixed a bug where the plugin would close on WM_KEYUP/VK_ESCAPE. Now,
instead, it closes on WM_KEYDOWN/VK_ESCAPE. This was a problem when
you hit ESCAPE to close some other app (on WM_KEYDOWN), then the focus
went to the plugin, and WM_KEYUP/VK_ESCAPE got sent to the plugin.
Not sure why it was even like this in the first place...
-fixed a timing but where, when the frame delay was zero (or fps
was unlimited), and the plugin was using the low-precision timer,
the fps reading would blow up and m_time would stop.
-fixed a bug w/a parameter to CreateFont: max font weight was
900; 'twas calling it with 1000
-fixed bug with context menu cleanup
-fixed a bug where winamp playback nav. keys (zxcvbs) were
handled under WM_KEYDOWN; should have been under WM_CHAR.
-fixed a bug where DXContext was calling DestroyWindow (on the final
exit of the plugin), when in fact, the window had already been
destroyed (by Windows, it seems).
-fixed a bug in config panel, where list of video modes wasn't updating
when you changed the fullscreen adapter.
-fixed a bug where DXContext was remembering the native windows display
mode for the first monitor that the window was created on, only.
This was a problem because if two monitors had different bit depths,
and you ran it and switched to another monitor by toggling fullscreen,
it would try to create a device with a back buffer whose bit depth
was that of the original monitor. To fix this, it now does the
following: the first time it creates a window, before changing the
display mode, it remembers the native display mode for all the
adapters present, then uses the appropriate one whenever it needs
it.
-deleted the 'DX8 Includes' project folder from the workspace;
use 'External Dependencies' folder instead, it automatically
points you to the right directories.
-----------------------------------------------------------------------
[1.02, August 5, 2002]
-Fixed bug where the plugin would minimize if you were running
[true] fullscreen with multiple monitors, and went to click
in another window. Previously the workaround was to use fake
fullscreen mode, but now this is not necessary. Fake fullscreen
mode still remains, though; for the rationale, see the help text
for the 'fake fullscreen mode' checkbox in the config panel.
-Decided that InitMyNonDx8Stuff() should be called first, instead
of last, and that CleanUpMyNonDx8Stuff() should be called last,
not first.
-Might have fixed a bug with high-precision timer.
-Added a custom icon (...which the developer can modify, of course).
-----------------------------------------------------------------------
[1.01, July 19, 2002]
-Initial release
-----------------------------------------------------------------------
License
-------
Copyright (C) 1999-2002 Nullsoft, Inc.
This source code is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this source code or the software it produces.
Permission is granted to anyone to use this source code for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this source code must not be misrepresented; you must not
claim that you wrote the original source code. If you use this source code
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original source code.
3. This notice may not be removed or altered from any source distribution.