UltraWhorld Freeframe Plugin
UltraWhorld is an enhanced version of the original Whorld Freeframe
The main enhancement is that UltraWhorld exposes
nearly all of the Whorld application's parameters and switches. This
allows you to run Whorld from within your favorite VJ application,
without sacrificing the Whorld application's extensive real-time
controls; in short, the best of both Whorlds. :)
UltraWhorld has an unusually large number of Freeframe parameters.
Unfortunately some VJ softwares limit the number of parameters a
Freeframe plugin can expose. UltraWhorld is most useful with VJ softwares
that don't limit Freeframe parameters, e.g.
Start by downloading the plugin.
Most softwares reserve a special folder for freeframe plugins. If your
software does this, simply copy UltraWhorld.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
IMPORTANT: In addition to installing the plugin, you may also want to
install some Whorld patches. Use the following procedure:
- 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".
- 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
- Copy the patches from this distribution into the WhorldFF
Just delete UltraWhorld.dll and the Whorld patches, and that's all
there is to it.
UltraWhorld features the ability to load a Whorld playlist (.whl),
unlike the original WhorldFF plugin which only loads patches. There
are two methods for loading a playlist in UltraWhorld:
- Create a special initialization file in "My Documents\WhorldFF"
which directs the plugin to your playlist. The file is plain text,
so you can create it using Notepad or any other text editor. The
file MUST be called "UltraWhorld.ini", and it should contain a single
line, consisting of the word "Playlist", followed by an equals sign,
followed by the absolute path to the desired playlist, like this:
Replace C:\Whatever\YourPlaylist.whl with an absolute path to the
desired playlist. Do NOT enclose the path in quotes. It's OK if it
contains embedded spaces.
- Copy your playlist to the "My Documents\WhorldFF" folder and then
rename it to "UltraWhorld.whl". With this method, the playlist MUST be
called "UltraWhorld.whl", otherwise the plugin won't find it.
NOTE that first method (.ini file) is preferable, because of a problem
with the way the Whorld application stores paths in playlists. If you
choose to use the second method, you should check UltraWhorld.whl for
broken links, by opening it in the Whorld application. If Whorld finds
broken links, it will give you an opportunity to repair them. Be sure
the save the playlist afterwards.
If UltraWhorld doesn't find a Whorld playlist via one of the above
methods, it defaults to WhorldFF's behavior, i.e. it looks for patches
in the folder "My Documents\WhorldFF" and loads them in alphabetical
order. Note that in this case there will only be one bank.
Parameters - Notes
Some of UltraWhorld's parameters are switches, rather than continuous
controls. There are two types of switches, boolean and event
(momentary). According to the Freeframe specification,
- 0.0 defined as false and anything else defined as true.
- Similar to boolean but for a momentary push button style
trigger. 1.0 is set momentarily to trigger the event.
An example of an event is Rotate Hue (90 degrees). The way it works is
that the event is triggered when the parameter transitions to the value
1.0 (from any other value). To trigger the event twice in a row, set
the parameter to 1.0, set it to any other value, and then set it to 1.0
The last parameter (Save Patch) is a momentary switch which saves the
current settings as a new Whorld patch. The resulting patch is saved to
the folder "My Documents\WhorldFF\Saved". The filename is synthesized
from the current date and time. This feature is handy if you develop a
cool setting in UltraWhorld and want to use it in the Whorld
Finally, note that the X and Y position parameters don't do anything
unless Origin Motion is set to "Drag". The Origin Motion parameter
works as follows:
- 0.0 to 1/3
- Origin is parked: X/Y position parameters do nothing.
- 1/3 to 2/3
- Origin can be dragged, using X/Y position parameters.
- 2/3 to 1.0
- Origin makes random jumps, at frequency set by Tempo.
Parameters - Reference
- Bank - Selects a bank in a Whorld playlist.
- Patch - Selects a patch from the WhorldFF folder or a Whorld playlist bank.
- 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.
- Hue Loop Length - If "Loop Hue" is enabled, loop size in degrees.
- Canvas Scale - Scale of drawing area; 0 = 100%, 1 = 300%.
- Copies - Number of copies; 0 = 1, 1 = 20.
- Spread - Distance of copies from the origin; 0 to 600 pixels.
- X Position - If origin motion is "Drag", the origin X-coordinate.
- Y Position - If origin motion is "Drag", the origin Y-coordinate.
The geometry parameters (Ring Growth, Ring Spacing, etc.) are
Offsets which are ADDED to the corresponding value from the current
patch. Values less than .5 have a negative effect, values greater than
.5 have a positive effect, and at .5, the parameter is unaffected. If
the parameter is being modulated by an oscillator, the master offset
shifts the modulated value.
- Ring Growth - How fast rings expand; 0 = max reverse, 1 = max forward.
- Ring Spacing - Space between each ring; 0 = min, 1 = max.
- Line Width - Width of each ring; 0 = min, 1 = max.
- Poly Sides - Number of sides each ring has; 0 = min, 1 = max.
- Rotate Speed - Amount each ring rotates per frame; 0 = max clockwise, 1 = max counter-clockwise.
- Aspect Ratio - Stretches the rings horizontally or vertically; 0 = max vertical, 1 = max horizontal.
- Skew Radius - Amount each ring's origin shifts per frame; 0 = max negative, 1 = max positive.
- Skew Angle - Direction of the per-frame origin shift; 0 = max clockwise, 1 = max counter-clockwise.
- Star Factor - Causes sides of a ring to bulge outward, or collapse inward; 0 = max inward, 1 = max outward.
- Pinwheel - Rotates the points of a star; 0 = max clockwise, 1 = max counter-clockwise.
- Color Speed - How fast the ring hue cycles around the color wheel; 0 = max clockwise, 1 = max counter-clockwise.
- Lightness - Lightness of the ring color; 0 = min, 1 = max.
- Saturation - Saturation of the ring color; 0 = min, 1 = max.
- Bk Hue - Background color's hue; 0 = min, 1 = max.
- Bk Lightness - Background color's lightness; 0 = min, 1 = max.
- Bk Saturation - Background color's saturation; 0 = min, 1 = max.
- Even Curve - Curvature at even vertices; 0 = max negative, 1 = max positive.
- Odd Curve - Curvature at odd vertices; 0 = max negative, 1 = max positive.
- Patch Mode (boolean) - If true, patch selection affects geometry parameters only.
- Center Origin (event) - Centers the origin.
- Origin Motion - Selects type of origin motion; 0 = none (park), .5 = drag, 1 = random.
- Loop Hue (boolean) - If true, limits hue cycling to a subset of the color wheel.
- Rotate Hue (event) - Rotates hues of both new and existing rings by 90 degrees.
- Invert Color (boolean) - If true, all colors are inverted.
- Mirror (boolean) - If true, output is quad-mirrored.
- Fill (boolean) - If true, rings are filled.
- Outline (boolean) - If true, filled rings are outlined in background color.
- X-Ray (boolean) - If true, rings are drawn in XOR mode.
- Random Phase (event) - Randomizes modulator phases.
- Reverse (boolean) - If true, rings collapse inward instead of expanding outward.
- Convex (boolean) - If true, rings form a convex shape instead of concave one.
- Clear (event) - Clears the screen by deleting all rings.
- Zoom Center (boolean) - If true, zooming is relative to center of screen rather than drawing origin.
- Save Patch (event) - Saves the current settings as a Whorld patch in "My Documents\WhorldFF\Saved".
- Even Shear - Curve asymmetry at even vertices; Even Curve must be nonzero.
- Odd Shear - Curve asymmetry at odd vertices; Odd Curve must be nonzero.
Global parameters (they affect all existing rings, not just new ones):
- Glob Line Width - Global version of Line Width.
- Glob Poly Sides - Global version of Poly Sides.
- Glob Rotation - Global rotation.
- Glob Aspct Ratio - Global version of Aspect Ratio.
- Glob Skew Radius - Global version of Skew Radius.
- Glob Skew Angle - Global version of Skew Angle.
- Glob Star Factor - Global version of Star Factor.
- Glob Pinwheel - Global version of Pinwheel.
- Glob Even Curve - Global version of Even Curve.
- Glob Odd Curve - Global version of Odd Curve.
- Glob Even Shear - Global version of Even Shear.
- Glob Odd Shear - Global version of Odd Shear.
If you're able to run the plugin, but 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 the CURRENT USER's "My Documents\WhorldFF", 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:
- Use a more powerful gamer-style PC.
- Use a lower-resolution video mode.
- Lower the Rings parameter.
- Figure out which patches cause trouble, and don't use them.
- 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 http://whorld.org
When you change patches, the other parameters (Speed, Zoom, etc.) don't
snap to the new patch's values. Sorry!
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version. This program is distributed in the hope that
it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
the GNU General Public License for more details. You should have
received a copy of the GNU General Public License along with this
program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330, Boston, MA 02111 USA.
Kopyleft 2007 Chris Korda, All Rites Reversed.