Programming Information

Purpose

To be straight forward and blunt: Winamp visualization plugins are cool. Writing one can be a pain in the butt trying to get the basic stuff off the ground, stuff like creating a window, connecting to Winamp, reading keyboard input and so on. The SDK that Justin provides is great but the leap from a 2D GDI example to 3D is a little frightening. Hopefully by releasing some sample code this will help more people create better and better plug-ins.

If you find this useful please send me email. And if you find bugs or write improvements please send them to me so that I can add them. I want this to evolve into a collaberative effort.

Technology

I had to make some technology decisions when starting out on this project. I choose Direct X, partly because I already know COM and partly because I did not want to be stuck with particular hardware the way that Glide is. I used the DirectX 6 SDK, the latest version at the time I write this. You can order the SDK from Microsoft. You will need that to compile my code.

Direct X 6 isn't available on Windows NT at the time of writing, so you'll need to use Windows 98.

I used Direct 3D Retained Mode. This provides a higher level access to the 3D world than Intermediate Mode. So far I've been able to do everything with that, but if the need arises it will be possible to mix both technologies. Direct Draw would be the way to go for cool tripy 2D graphics, but at the moment I don't deal with that.

I compiled with Microsoft VC 6.0. I was tempted to use MFC to do the configuration dialog, but I'm worried about people not having the latest MFC DLLs on their machine.

Update - July 2000

Unfortunately "Immediate Mode" Direct3D is much more low level and harder to program.

Open GL

Installation

To play the plugin just use the DLL provided. To compile your own changes you will need to get your build environment set up.

• Get the Winamp SDK from Winamp. You don't need it to compile but you will want to refer to it.
• First get the Direct X SDK running. My version didn't have the Direct X 6 client application so I had to download that and install it. Get some samples compiling and running. You'll have to adjust your Directory settings for the Lib and Include directories.
• Unzip the vis_d3d_v#.zip file into a directory Vis_D3D.
• Load the dsp file as a workspace in VC 6.0
• I find it convenient to compile straight into my Winamp directory. Adjust this setting under Project Settings/General Tab/Output Files
• Compile and make sure it runs properly before making any adjustments. Most likely errors you will get is VC not being able to find Libs.
• It would be possible to compile from the command line but I won't bother with instructions.

Adjusting the code

• I suggest that you get comfortable with the code as it is first. Read it all. Make sure you understand the over-all execution flow, in particular how I initialize Winamp and how Winamp calls my functions.
• As a first step, and to prove that you really are compiling and building the DLL, make some adjustments in the #define values - change the colors or positions of the objects.
• Its up to you, but I would suggest that you spend some time building on top of the code that is already in there, so you really get familiar with it. Add new Keyboard functionality. Change the lighting, change the formula to generate the 3D objects. If you get cool results send stuff to me to incorporate!
• Depending on what you want to do you can either completely gut the code or start completely from scratch. If you want to use Direct 3D Immediate Mode, Direct Draw or Open GL or Glide then you won't really be able to re-use much code except for the basic setup stuff.
• Good luck.

Resources

• The DirectX SDK has lots of example programs.
• The SDK documentation is sparse but helpful. It even covers some 3D theory.
• Computer Graphics by Foley, Van Dam is the real classic. Used it in Univerity. If you want to get deep into 3D you're going to have to by up on cross products and matrices and all that math stuff.

If anyone knows of any really good Direct 3D books I'd love to hear from you, I haven't been impressed by anything I've seen so far.

Debugging

Have fun. Debugging this kind of app is not easy. Firstly you can't use Windows NT yet so you might do some rebooting of Windows 98.

It won't take you long to realize that its a pain to debug full screen Plugins. Recommendation is to develop a windowed version first. I've read that you need to debug full screen Direct Draw by using a remote machine - I'll update this with some info if I get that up and running. Another interesting possibility is trying to get a Dual monitor setup in Windows 98 - you might be able to run the plugin on the primary display and VC on the secondary.

Setting a breakpoint in VC:

• Make the output directory of your DLL compilation the Plugins directory of your installation of Winamp. (Settings/General Tab/Output Directories)
• Make sure you are compiling the "Debug" version of your DLL.
• Set breakpoints. For example in init()
• Select "Go" from the Debug menu (F5)
• First time through a dialog box asks what the executable is. Browse until you find the "winamp.exe" file that you run winamp with.
• Ignore the warning message about winamp not having debug information.
• Winamp will start and once you start it using your plugin the breakpoints will be hit

  Start the Tutorial