Getting started with the Whorld Freeframe plugin

Installation

Start by downloading the plugin.

Most softwares reserve a special folder for freeframe plugins. If your software does this, simply copy WhorldFF.dll to the special folder. Be sure to do this BEFORE launching your software, since it probably only checks for plugins during startup. Otherwise, consult your software's documentation.

IMPORTANT: In addition to installing the plugin, you should also install some Whorld patches, because otherwise the plugin won't do much. Use the following procedure:

1. Find your "My Documents" folder. If you're unfamiliar with Windows, there are various ways to do this. One reliable way is to go to the Start menu, select "Documents", and then select "My Documents".
2. In your "My Documents" folder, create a subfolder called WhorldFF. The subfolder name must be spelled correctly. The subfolder's path should look something like this (assuming you're the Administrator):

   C:\Documents and Settings\Administrator\My Documents\WhorldFF

3. Copy the patches from this distribution into the WhorldFF subfolder.

Uninstalling

Just delete the WhorldFF.dll and the Whorld patches, and that's all there is to it.

Parameters

WhorldFF exposes the following freeframe parameters:

Patch

Selects a patch from your WhorldFF folder; 0 to patches - 1.

Speed

Master speed; 0 = min, .5 = nominal, 1 = max.

Zoom

Magnification; 0 = min, .5 = nominal, 1 = max.

Hue

Shifts the hues in the entire image; 0 to 360 degrees.

Damping

Applied to origin motion and zoom; 0 = none, 1 = max.

Trail

Slinky effect applied to origin motion; 0 = none, 1 = max.

Rings

Maximum number of rings; 0 = none, 1 = unlimited.

Tempo

If origin motion is "Random", the jump rate: 0 to 250 BPM.

X Pos

If origin motion is "Drag", the origin X-coordinate.

Y Pos

If origin motion is "Drag", the origin Y-coordinate.

Your software probably won't support all of these parameters, but it's supposed to support at least the first four, according to the freeframe specification. If it doesn't, complain to whoever makes your software, not to me :).

Patches

You can put any Whorld patches you like in the WhorldFF folder, not just the ones provided in this distribution. By all means use the Whorld application to create your own patches. NOTE however that you should use Whorld version 1.4 or higher to create patches for the plugin, because otherwise your patches won't be able to specify effects or master controls.

Your patches are loaded in alphabetical order. This means you can determine the order in which they appear in the plugin (if you care), by naming them appropriately. For example, you could begin each patch name with a number, like this:

00 foo.whp
01 blah.whp
etc.

Troubleshooting

If you're able to run the plugin, but it only displays pentagons, and the patch slider doesn't do anything, it's because the plugin didn't find any patches. The most likely reason is that you put them in the wrong folder. Remember, there's a unique "My Documents" folder for each user. The plugin looks in "My Documents\WhorldFF" for the CURRENT user, and nowhere else.

Some patches may cause performance problems, e.g. the frame rate may drop, or your software may become unresponsive. If this occurs, here are some things to try:

1. Use a more powerful gamer-style PC.
2. Use a lower-resolution video mode.
3. Lower the Rings parameter, if your software supports it.
4. Figure out which patches cause trouble, and don't use them.
5. Edit the patches to reduce their performance requirements.

It may help to read the "Performance" chapter in Whorld's documentation. Briefly, any of the following can cause problems: wide lines, fill mode, outline mode, x-ray mode, Bézier curves, excessive poly sides, extreme star factor, or excessive ring count. The easiest solution is usually to reduce the Ring count, either directly via the Rings master control, or indirectly by increasing the Ring Spacing parameter.

For more information, see whorld.org

Known bugs

When you change patches, the other parameters (Speed, Zoom, etc.) don't snap to the new patch's values. Sorry!

Kopyleft 2006 Chris Korda, All Rites Reversed.