772 lines
47 KiB
HTML
772 lines
47 KiB
HTML
<HTML>
|
|
<A NAME="milkdrop_preset_authoring_top">
|
|
<PRE>
|
|
|
|
<B>MILKDROP preset authoring guide</B>
|
|
<A HREF="milkdrop.html">return to milkdrop.html</A>
|
|
|
|
|
|
|
|
* * *
|
|
Note that there is another, quite comprehensive, Preset Authoring Guide
|
|
available on the web at <A HREF="http://www.milkdrop.co.uk/">http://www.milkdrop.co.uk/</A>, which is continually
|
|
updated and expanded through the hard work of a few dedicated preset
|
|
authors. Whereas this guide (the one you are currently viewing) gives the bare
|
|
technical specifications for writing your own presets, the guide at milkdrop.co.uk
|
|
'starts at the beginning' and walks you through all of the mathematics and subtleties
|
|
of 'rolling your own', explaining things in great detail. The guide at milkdrop.co.uk
|
|
is very highly recommended to anyone who wishes to learn more about creating their
|
|
own presets.
|
|
* * *
|
|
|
|
|
|
<B>Section Listing</B>
|
|
-----------------------
|
|
1. <A HREF="#1">about presets</A>
|
|
2. <A HREF="#2">preset authoring - basic</A>
|
|
3. <A HREF="#3">preset authoring - advanced</A>
|
|
a. <A HREF="#3a">per-frame equations</A>
|
|
b. <A HREF="#3b">per-pixel equations</A>
|
|
c. <A HREF="#3c">preset initialization code and q1-q8</A>
|
|
d. <A HREF="#3d">custom shapes & waves</A>
|
|
e. <A HREF="#3e">quality assurance</A>
|
|
f. <A HREF="#3f">debugging</A>
|
|
g. <A HREF="#3g">function reference</A>
|
|
|
|
|
|
<A NAME="1">
|
|
<B>1. About Presets</B>
|
|
-----------------------
|
|
A 'preset' is a collection of parameters that tell MilkDrop how to
|
|
draw the wave, how to warp the image around, and so on. MilkDrop
|
|
ships with around ~100 built-in presets, each one having a distinct
|
|
look and feel to it.
|
|
|
|
Using MilkDrop's built-in "preset-editing menu", you can edit presets
|
|
on the fly, from within the program. You can make slight adjustments
|
|
to existing presets, then save over them; or you can change lots of
|
|
things, so the preset doesn't look anything like the original, and
|
|
then save it under a new name. You can even write insane new
|
|
mathematical equations, of your own imagination, into your preset
|
|
files and come up with things that MilkDrop has never done before!
|
|
|
|
Each preset is saved as a file with the ".milk" extension, so you can
|
|
easily send them to your friends or post them on the web. You can also
|
|
go to <A HREF="http://www.nullsoft.com/free/milkdrop">http://www.nullsoft.com/free/milkdrop</A> and then jump to the
|
|
"preset sharing forum" to see what other people have come up with,
|
|
or post your own cool, new presets.
|
|
|
|
|
|
<A NAME="2">
|
|
<B>2. Preset Authoring - Basic</B>
|
|
-----------------------
|
|
|
|
You can edit the properties of the current preset by hitting 'M',
|
|
which brings up the "preset-editing menu". From this menu you
|
|
can use the up and down arrow keys to select an item. Press
|
|
the RIGHT arrow key to move forward through the menu and select
|
|
the item (note: you can also hit SPACE or RETURN to do this);
|
|
***press the LEFT arrow key to go back to the previous menu.***
|
|
|
|
Pressing 'M' while the menu is already showing will hide the menu;
|
|
pressing ESCAPE will do the same thing. Press 'M' again to bring
|
|
the menu back.
|
|
|
|
Once you've reached an item on the menu whose value can be edited,
|
|
use the UP and DOWN arrow keys to increase or decrease its value,
|
|
respectively. Changes will register immediately. Use PAGE UP and
|
|
PAGE DOWN to increase the value more quickly. Hold down SHIFT
|
|
and use the UP/DOWN arrow keys to change the value very slowly.
|
|
Hit RETURN To keep the new value, or ESC to abort the change.
|
|
|
|
If the item you're editing is a text string, you can use the
|
|
arrow keys to move around. The Insert key can be used to toggle
|
|
between insert and overtype modes. You can hold shift and use
|
|
the arrow keys (home, end, left, right) to make a selection,
|
|
which will be identified by brackets []. You can then use CTRL-C
|
|
or CTRL-X to copy or cut text. CTRL-P pastes. When finished
|
|
editing, hit RETURN To keep the new string, or ESC to abort the
|
|
change.
|
|
|
|
You'll want to get into the habit of using SCROLL LOCK whenever
|
|
you're making changes to a preset that you intend to save;
|
|
otherwise, the preset is sure to keep randomly changing on you.
|
|
You might ask me, "why don't you just automatically lock the
|
|
preset while the menu is up?" I will answer you, "because in
|
|
the instant between exiting the menu and going to save the preset,
|
|
the preset might then switch, and you'd lose your changes." Then
|
|
you might ask me, "then why don't you just leave it locked
|
|
whenever the user makes a change from the menu?" and I will say
|
|
to you, "because I hate it when programs do things like that. You
|
|
have an idea in your brain about the state of the Scroll Lock key,
|
|
because you're the one setting that state. I want your mind to
|
|
always be up-to-date." And you might then ask me: "how large is
|
|
large?" And I will tell you: "thirty."
|
|
|
|
There are also some hotkeys that will allow you to change certain
|
|
common parameters to the current preset. These are listed below.
|
|
|
|
MOTION
|
|
i/I - zoom in/out
|
|
[ / ] - push motion to the left/right (dx)
|
|
{ / } - push motion up/down (dy)
|
|
< / > - rotate left/right (rot)
|
|
o/O - shrink/grow the amplitude of the warp effect
|
|
|
|
WAVEFORM
|
|
W - cycle through waveforms
|
|
j/J - scale waveform down/up
|
|
e/E - make the waveform more transparent/more solid
|
|
|
|
BRIGHTNESS
|
|
d/D - decrease, increase decay (fades image to black over time)
|
|
g/G - decrease, increase gamma (brightness)
|
|
|
|
VIDEO ECHO effect
|
|
q/Q - scale 2nd graphics layer down/up
|
|
a/A - decrease/increase alpha of 2nd graphics layer
|
|
F - flip 2nd graphics layer (cycles through 4 fixed orientations)
|
|
|
|
|
|
|
|
<A NAME="3">
|
|
<B>3. Preset Authoring - Advanced</B>
|
|
-----------------------
|
|
|
|
This section describes how to use the 'per-frame' and 'per-pixel'
|
|
equations to develop unique new presets.
|
|
|
|
|
|
<A NAME="3a">
|
|
<B>a. PER-FRAME EQUATIONS</B>
|
|
----------------------
|
|
|
|
When you hit 'm' to show the preset-editing menu, several items
|
|
show up. If you explore the sub-menus, you'll see that
|
|
all of the properties that make up the preset you're currently
|
|
viewing are there. The values you can specify here (such as
|
|
zoom amount, rotation amount, wave color, etc.) are all static
|
|
values, meaning that they don't change in time. For example,
|
|
take the 'zoom amount' option under the 'motion' submenu.
|
|
If this value is 1.0, there is no zoom. If the value is 1.01,
|
|
the image zooms in 1% every frame. If the value is 1.10, the
|
|
image zooms in 10% every frame. If the value is 0.9, the image
|
|
zooms out 10% every frame; and so on.
|
|
|
|
However, presets get far more interesting if you can take these
|
|
parameters (such as the zoom amount) and animate them (make them
|
|
change over time). For example, if you could take the 'zoom
|
|
amount' parameter and make it oscillate (vary) between 0.9 and
|
|
1.1 over time, the image would cyclically zoom in and out, in
|
|
time.
|
|
|
|
You can do this - by writing 'per-frame' and 'per-pixel'
|
|
equations. Let's start with 'per-frame' equations. These are
|
|
executed once per frame. So, if you were to type the following
|
|
equation in:
|
|
|
|
zoom = zoom + 0.1*sin(time);
|
|
|
|
...then the zoom amount would oscillate between 0.9 and 1.1
|
|
over time. (Recall from your geometry classes that sin()
|
|
returns a value between -1 and 1.) The equation says: "take
|
|
the static value of 'zoom', then replace it with that value,
|
|
plus some variation." This particular equation would oscillate
|
|
(cycle) every 6.28 seconds, since the sin() function's
|
|
period is 6.28 (PI*2) seconds. If you wanted it to make it
|
|
cycle every 2 seconds, you could use:
|
|
|
|
zoom = zoom + 0.1*sin(time*3.14);
|
|
|
|
Now, let's say you wanted to make the color of the waveform
|
|
(sound wave) that gets plotted on the screen vary through time.
|
|
The color is defined by three values, one for each of the main
|
|
color components (red, green, and blue), each in the range 0 to 1
|
|
(0 is dark, 1 is full intensity). You could use something like this:
|
|
|
|
wave_r = wave_r + 0.5*sin(time*1.13);
|
|
wave_g = wave_g + 0.5*sin(time*1.23);
|
|
wave_b = wave_b + 0.5*sin(time*1.33);
|
|
|
|
It's nice to stagger the frequencies (1.13, 1.23, and 1.33) of
|
|
the sine functions for the red, green, and blue color components
|
|
of the wave so that they cycle at different rates, to avoid them
|
|
always being all the same (which would create a greyscale wave).
|
|
|
|
Here is a full list of the variables available for writing per-frame
|
|
equations:
|
|
|
|
NAME WRITABLE? RANGE DESCRIPTION
|
|
---- --------- ----- -----------
|
|
zoom yes >0 controls inward/outward motion. 0.9=zoom out 10% per frame, 1.0=no zoom, 1.1=zoom in 10%
|
|
zoomexp yes >0 controls the curvature of the zoom; 1=normal
|
|
rot yes controls the amount of rotation. 0=none, 0.1=slightly right, -0.1=slightly clockwise, 0.1=CCW
|
|
warp yes >0 controls the magnitude of the warping; 0=none, 1=normal, 2=major warping...
|
|
cx yes 0..1 controls where the center of rotation and stretching is, horizontally. 0=left, 0.5=center, 1=right
|
|
cy yes 0..1 controls where the center of rotation and stretching is, vertically. 0=top, 0.5=center, 1=bottom
|
|
dx yes controls amount of constant horizontal motion; -0.01 = move left 1% per frame, 0=none, 0.01 = move right 1%
|
|
dy yes controls amount of constant vertical motion; -0.01 = move up 1% per frame, 0=none, 0.01 = move down 1%
|
|
sx yes >0 controls amount of constant horizontal stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
|
|
sy yes >0 controls amount of constant vertical stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
|
|
wave_mode yes 0,1,2,3,4,5,6,7 controls which of the 8 types of waveform is drawn
|
|
wave_x yes 0..1 position of the waveform: 0 = far left edge of screen, 0.5 = center, 1 = far right
|
|
wave_y yes 0..1 position of the waveform: 0 = very bottom of screen, 0.5 = center, 1 = top
|
|
wave_r yes 0..1 amount of red color in the wave (0..1),
|
|
wave_g yes 0..1 amount of green color in the wave (0..1)
|
|
wave_b yes 0..1 amount of blue color in the wave (0..1)
|
|
wave_a yes 0..1 opacity of the wave (0..1) [0=transparent, 1=opaque]
|
|
wave_mystery yes -1..1 what this parameter does is a mystery. (honestly, though, this value does different things for each waveform; for example, it could control angle at which the waveform was drawn.)
|
|
wave_usedots yes 0/1 if 1, the waveform is drawn as dots (instead of lines)
|
|
wave_thick yes 0/1 if 1, the waveform's lines (or dots) are drawn with double thickness
|
|
wave_additive yes 0/1 if 1, the wave is drawn additively, saturating the image at white
|
|
wave_brighten yes 0/1 if 1, all 3 r/g/b colors will be scaled up until at least one reaches 1.0
|
|
ob_size yes 0..0.5 thickness of the outer border drawn at the edges of the screen every frame
|
|
ob_r yes 0..1 amount of red color in the outer border
|
|
ob_g yes 0..1 amount of green color in the outer border
|
|
ob_b yes 0..1 amount of blue color in the outer border
|
|
ob_a yes 0..1 opacity of the outer border (0=transparent, 1=opaque)
|
|
ib_size yes 0..0.5 thickness of the inner border drawn at the edges of the screen every frame
|
|
ib_r yes 0..1 amount of red color in the inner border
|
|
ib_g yes 0..1 amount of green color in the inner border
|
|
ib_b yes 0..1 amount of blue color in the inner border
|
|
ib_a yes 0..1 opacity of the inner border (0=transparent, 1=opaque)
|
|
mv_r yes 0..1 amount of red color in the motion vectors
|
|
mv_g yes 0..1 amount of green color in the motion vectors
|
|
mv_b yes 0..1 amount of blue color in the motion vectors
|
|
mv_a yes 0..1 opacity of the motion vectors (0=transparent, 1=opaque)
|
|
mv_x yes 0..64 the number of motion vectors in the X direction
|
|
mv_y yes 0..48 the number of motion vectors in the Y direction
|
|
mv_l yes 0..5 the length of the motion vectors (0=no trail, 1=normal, 2=double...)
|
|
mv_dx yes -1..1 horizontal placement offset of the motion vectors
|
|
mv_dy yes -1..1 vertical placement offset of the motion vectors
|
|
decay yes 0..1 controls the eventual fade to black; 1=no fade, 0.9=strong fade, 0.98=recommended
|
|
gamma yes >0 controls display brightness; 1=normal, 2=double, 3=triple, etc.
|
|
echo_zoom yes >0 controls the size of the second graphics layer
|
|
echo_alpha yes >0 controls the opacity of the second graphics layer; 0=transparent (off), 0.5=half-mix, 1=opaque
|
|
echo_orient yes 0,1,2,3 selects an orientation for the second graphics layer. 0=normal, 1=flip on x, 2=flip on y, 3=flip on both
|
|
darken_center yes 0/1 if 1, help keeps the image from getting too bright by continually dimming the center point
|
|
wrap yes 0/1 sets whether or not screen elements can drift off of one side and onto the other
|
|
invert yes 0/1 inverts the colors in the image
|
|
brighten yes 0/1 brightens the darker parts of the image (nonlinear; square root filter)
|
|
darken yes 0/1 darkens the brighter parts of the image (nonlinear; squaring filter)
|
|
solarize yes 0/1 emphasizes mid-range colors
|
|
monitor yes any set this value for debugging your preset code; if you hit the 'N' key,
|
|
the value of 'monitor' will be posted in the upper-right corner of milkdrop.
|
|
for example, setting "monitor = q3;" would let you keep an eye on q3's value.
|
|
|
|
time NO >0 retrieves the current time, in seconds, since MilkDrop started running
|
|
fps NO >0 retrieves the current framerate, in frames per second.
|
|
frame NO retrieves the number of frames of animation elapsed since the program started
|
|
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
|
|
-note that if Scroll Lock is on, 'progress' will freeze!
|
|
|
|
bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
|
|
mid NO >0 -same, but for mids (middle frequencies)
|
|
treb NO >0 -same, but for treble (high) frequencies
|
|
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
|
|
mid_att NO >0 -same, but for mids (middle frequencies)
|
|
treb_att NO >0 -same, but for treble (high) frequencies
|
|
|
|
meshx NO 8-128 tells you the user's mesh size in the X direction. always an integer value.
|
|
meshy NO 6-96 tells you the user's mesh size in the Y direction. always an integer value.
|
|
|
|
q1 yes any }
|
|
q2 yes any }
|
|
q3 yes any }
|
|
q4 yes any } Used to carry information between the per-frame code
|
|
q5 yes any } and the per-pixel code; see below.
|
|
q6 yes any }
|
|
q7 yes any }
|
|
q8 yes any }
|
|
|
|
|
|
Some of the variables are read-only, meaning that you shouldn't change
|
|
their values them through the equations. You can; it won't stop you;
|
|
but the results are unpredictable.
|
|
|
|
You can also make up to 30 of your own variables. For example:
|
|
|
|
my_volume = (bass + mid + treb)/3;
|
|
zoom = zoom + 0.1*(my_volume - 1);
|
|
|
|
This would make the zoom amount increase when the music is loud,
|
|
and decrease when the music is quiet.
|
|
|
|
HOWEVER, custom variables do not carry over from per-frame equations
|
|
to per-pixel equations; if you set a custom variable's value in the
|
|
per-frame equations, and try to read it in the per-pixel equations,
|
|
you will not get the correct value. Instead, you have to "bridge the
|
|
gap" using 8 special variables: q1 through q8. This is usually only
|
|
used when you want to precompute some custom values in the per-frame
|
|
equations for later use in the per-pixel equations. For a good
|
|
example of this, see the 'dynamic swirls' preset. See below for
|
|
more information on q1-q8.
|
|
|
|
|
|
|
|
<A NAME="3b">
|
|
<B>b. PER-PIXEL EQUATIONS</B>
|
|
-----------------------
|
|
|
|
So far we've discussed only how to change parameters based on
|
|
time. What if you wanted to also vary a parameter, such as the
|
|
zoom amount, in different ways, for different locations on the
|
|
screen? For example, normally, the result of the 'zoom' parameter
|
|
is to just do a flat zoom. This doesn't look very realistic,
|
|
because you don't see any perspective in the zoom. It would be
|
|
better if we could give a unique zoom amount to each pixel on
|
|
the screen; we could make the pixels far away from the center
|
|
zoom more, and this would give it more perspective. In order
|
|
to do this, we use "per-pixel" equations, instead of per-frame
|
|
equations.
|
|
|
|
The code for this per-pixel equation is simple:
|
|
|
|
zoom = zoom + rad*0.1;
|
|
|
|
Where 'rad' is the radius of the pixel if it were cast into
|
|
polar coordinates; from another perspective, 'rad' is the distance
|
|
of the pixel from the center of the screen. 'rad is zero at the
|
|
center, and 1 at the corners. So if we run the above code,
|
|
the image will be zoomed into 10% more at the edges of the screen
|
|
than at the center.
|
|
|
|
The per-pixel equations are really just like the per-frame equations,
|
|
except for a variables. The following variables are available
|
|
exclusively to per-pixel equations (and not to per-frame equations):
|
|
|
|
NAME WRITABLE? RANGE DESCRIPTION
|
|
---- --------- ----- -----------
|
|
x NO 0..1 retrieves the x-position of the current pixel. At the very left edge of the screen this would be 0; in the middle, 0.5; and at the right, 1.
|
|
y NO 0..1 retrieves the y-position of the current pixel. At the very top edge of the screen this would be 0; in the middle, 0.5; and at the bottom, 1.
|
|
rad NO 0..1 retrives the distance of the pixel from the center of the screen. At the center of the screen this will be zero, and at the corners, 1.
|
|
(The middle of the edges will be 0.707 (half of the square root of 2).
|
|
ang NO 0..6.28 retrieves the angle of the current pixel, with respect to the center of the screen.
|
|
If the point is to the right of the center, this is zero; above it, it is PI/2 (1.57); to the left, it is PI (3.14); and below, it is 4.71 (PI*3/2).
|
|
If it is just a dab below being directly to the right of the center of the screen, the value will approach 6.28 (PI*2).
|
|
(note: this is simply the arctangent of y over x, precomputed for you.)
|
|
|
|
zoom yes >0 controls inward/outward motion. 0.9=zoom out 10% per frame, 1.0=no zoom, 1.1=zoom in 10%
|
|
zoomexp yes >0 controls the curvature of the zoom; 1=normal
|
|
rot yes controls the amount of rotation. 0=none, 0.1=slightly right, -0.1=slightly clockwise, 0.1=CCW
|
|
warp yes >0 controls the magnitude of the warping; 0=none, 1=normal, 2=major warping...
|
|
cx yes 0..1 controls where the center of rotation and stretching is, horizontally. 0=left, 0.5=center, 1=right
|
|
cy yes 0..1 controls where the center of rotation and stretching is, vertically. 0=top, 0.5=center, 1=bottom
|
|
dx yes controls amount of constant horizontal motion; -0.01 = move left 1% per frame, 0=none, 0.01 = move right 1%
|
|
dy yes controls amount of constant vertical motion; -0.01 = move up 1% per frame, 0=none, 0.01 = move down 1%
|
|
sx yes >0 controls amount of constant horizontal stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
|
|
sy yes >0 controls amount of constant vertical stretching; 0.99=shrink 1%, 1=normal, 1.01=stretch 1%
|
|
|
|
time NO >0 retrieves the current time, in seconds, since MilkDrop started running
|
|
fps NO >0 retrieves the current framerate, in frames per second.
|
|
frame NO retrieves the number of frames of animation elapsed since the program started
|
|
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
|
|
-note that if Scroll Lock is on, 'progress' will freeze!
|
|
|
|
bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
|
|
mid NO >0 -same, but for mids (middle frequencies)
|
|
treb NO >0 -same, but for treble (high) frequencies
|
|
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
|
|
mid_att NO >0 -same, but for mids (middle frequencies)
|
|
treb_att NO >0 -same, but for treble (high) frequencies
|
|
|
|
meshx NO 8-128 tells you the user's mesh size in the X direction. always an integer value.
|
|
meshy NO 6-96 tells you the user's mesh size in the Y direction. always an integer value.
|
|
|
|
q1 yes any }
|
|
q2 yes any }
|
|
q3 yes any }
|
|
q4 yes any } Used to carry information between the per-frame code
|
|
q5 yes any } and the per-pixel code; see below.
|
|
q6 yes any }
|
|
q7 yes any }
|
|
q8 yes any }
|
|
|
|
|
|
The main reason for distinction between per-frame and per-pixel equations
|
|
is simple: SPEED. If you have a per-pixel equation that doesn't make use
|
|
of the x, y, rad, or ang variables, then there's no reason for it to be
|
|
executed per-pixel; it could be executed once per frame, and the result
|
|
would be the same. So, here's a maxim to write on the wall:
|
|
|
|
"If a per-pixel equation doesn't use at least one of the variables
|
|
{ x, y, rad, ang }, then it should be actually be a per-frame
|
|
equation."
|
|
|
|
You might be wondering how on earth all these formulas could be computed
|
|
for every pixel on the screen, every frame, and still yield a high frame
|
|
rate. Well, that's the magic of the hamster. And the fact that it really
|
|
does the processing only at certain points on the screen, then interpolates
|
|
the results across the space between the points. In the config panel,
|
|
the "mesh size" option defines how many points (in X and Y) there are at
|
|
which the per-pixel equations are actually computed. When you crank this
|
|
option up, you start eating up CPU cycles rather quickly.
|
|
|
|
|
|
|
|
<A NAME="3c">
|
|
<B>c. PRESET INITIALIZATION CODE AND q1-q8</B>
|
|
-----------------------
|
|
In MilkDrop 1.03 and later, you can write code that is executed only
|
|
once, at the start of a preset. This code allows you to set the initial
|
|
value of your own (user-defined) variables (such as 'my_variable'), as well
|
|
as the q1..q8 variables. Any variable that is accessible in the per-frame
|
|
equations is also accessible here, <EM>for reading</EM>; however, most of them will not
|
|
be affected if you change them here, because they are overwritten by the base
|
|
variable values of the preset at the start of each frame! (i.e. the values
|
|
of the variables are reset to the values from the menus at the beginning of
|
|
each frame.) In effect, most of these variables are treated as 'read-only'
|
|
in the initialization code. If you do read (access) their values, you will
|
|
get the base values - the ones baked into the preset (via the menu system).
|
|
|
|
The variables that are <EM>writable</EM> include only q1..q8, and
|
|
<EM>any custom variables that you want to create & initialize for later use.</EM>
|
|
|
|
If you write to the values of q1..q8, these will become the new 'base values'
|
|
to which q1..q8 are initialized at the start of each frame, for the per-frame
|
|
code. So when you access (read) q1-q8 in the per-frame code, you'll get the
|
|
values that were set at the end of the preset init code. You can then
|
|
modify them (or not) in the per-frame code, and they will then be readable by
|
|
the per-pixel code; but they will not persist to the next frame; they will be
|
|
reset again, at the start of the next frame, to the values they had at the
|
|
end of the preset init code. <B>See the <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A> image for a diagram
|
|
of the flow of the values of the q1-q8 varibles.</B>
|
|
|
|
In the per-pixel code, the q1-q8 values start (for the first pixel in any frame)
|
|
as the values they had at the end of the per-frame code. If you modify q1-q8
|
|
in the per-pixel code, those modified values will carry over from pixel to
|
|
pixel. Next frame, they will be reset to whatever value they had at the end
|
|
of the [next frame's execution of the] per-frame code. (It's all in the diagram.)
|
|
|
|
If you declare & assign values to your own new variables here, however, these
|
|
values are 'sticky' like q1-q8; they can be modified by the per-frame code,
|
|
and they will retain their (modified) values from frame to frame.
|
|
|
|
One final note: when you edit the preset init code and apply it (by hitting
|
|
CTRL+ENTER), the init code will re-execute immediately. However, when you
|
|
edit the regular per-frame/per-pixel code and hit CTRL+ENTER, the preset init
|
|
code will NOT be re-executed; the results of the last execution will persist.
|
|
If you change per-frame/per-pixel code and want to re-execute the initialization
|
|
code (i.e. to randomize it or reset the preset), you'll have to save it and re-
|
|
load it.
|
|
|
|
|
|
|
|
<A NAME="3d">
|
|
<B>d. CUSTOM SHAPES AND WAVES</B>
|
|
----------------------
|
|
As of MilkDrop 1.04, two new features are available: custom shapes, and custom
|
|
waves. A preset can have up to 4 of each.
|
|
|
|
With custom shapes, you can draw an n-sided shape (with 3-100 sides) anywhere
|
|
on the screen, at any angle and size, in any color, and at any opacity. You
|
|
even have the option to map the previous frame's image onto the shape, which
|
|
makes for some incredible possibilities (such as realtime hardware fractals -
|
|
see the 'Geiss - Feedback' preset). You can also write per-frame code to
|
|
control all of these things about the shape(s). This way, they can react to
|
|
the audio or change over time - whatever you can imagine.
|
|
|
|
With custom waves, you can draw the waveform (or the frequency spectrum)
|
|
wherever, whenever, and however you want; a great addition since MilkDrop
|
|
1.03, where only the built-in waveforms were possible. With custom waves
|
|
you can also write per-frame code to control the waves, and per-point code
|
|
to place every point (or line segment) on the wave exactly where you want,
|
|
and in exactly the color you want, and so on.
|
|
|
|
Remember those q1-q8 variables that were committed at the end of the preset
|
|
initialization code, then reset (to those values) at the beginning of each
|
|
frame, and then (potentially) modified in the preset per-frame code? Those
|
|
(potentially modified) values of q1-q8 - as they were at the end of the
|
|
preset's per-frame code, each frame - are piped into the custom wave & custom
|
|
shape per-frame code. So if you read 'q3' in the custom wave per-frame
|
|
code, what you're really reading is the value of 'q3' as it was left at the
|
|
end of this frame's per-frame code. Again, see the <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A> image
|
|
for a diagram of the flow of the values of the q1-q8 varibles.
|
|
|
|
For custom waves, you can modify q1-q8 and that value will get passed on
|
|
to the per-point code. If you then modify q1-q8 in the per-point code,
|
|
the modified values will pass on to the next point, much like the per-pixel
|
|
code for the preset.
|
|
|
|
There are, however, 8 additional variables available for custom waves
|
|
and shapes: <B>t1-t8</B>. These are very similar to q1-q8, but they exist only
|
|
for custom waves & shapes. Recall that q1-q8 exist so that you can carry
|
|
custom data (values) from the preset init code and per-frame code, to the
|
|
preset's per-pixel code (which uses a different pool of variables).
|
|
Likewise, t1-t8 exist so that you can pass custom values from the custom
|
|
wave/shape init code, on to the custom wave/shape per-frame code, and
|
|
then (in the case of custom waves) on to the per-point code. q1-q8 are
|
|
also used to bridge another gap: to carry values from the preset init/per-
|
|
frame code, to the custom wave/shape code. Again, see the diagram; it's
|
|
probably easier to understand than all of this explanation.
|
|
|
|
|
|
CUSTOM SHAPE PER-FRAME VARIABLES
|
|
----------------------
|
|
NAME WRITABLE? RANGE DESCRIPTION
|
|
---- --------- ----- -----------
|
|
sides yes 3-100 the default number of sides that make up the polygonal shape
|
|
thick yes 0/1 if ON, the border will be overdrawn 4X to make it thicker, bolder, and more visible
|
|
additive yes 0/1 if ON, the shape will add color to sature the image toward white; otherwise, it will replace what's there.
|
|
x yes 0..1 default x position of the shape (0..1; 0=left side, 1=right side)
|
|
y yes 0..1 default y position of the shape (0..1; 0=bottom, 1=top of screen)
|
|
rad yes 0+ default radius of the shape (0+)
|
|
ang yes 0..6.28 default rotation angle of the shape (0...2*pi)
|
|
textured yes 0/1 if ON, the shape will be textured with the image from the previous frame
|
|
tex_zoom yes >0 the portion of the previous frame's image to use with the shape
|
|
tex_ang yes 0..6.28 the angle at which to rotate the previous frame's image before applying it to the shape
|
|
r yes 0..1 default amount of red color toward the center of the shape (0..1)
|
|
g yes 0..1 default amount of green color toward the center of the shape (0..1)
|
|
b yes 0..1 default amount of blue color toward the center of the shape (0..1)
|
|
a yes 0..1 default opacity of the center of the shape; 0=transparent, 1=opaque
|
|
r2 yes 0..1 default amount of red color toward the outer edge of the shape (0..1)
|
|
g2 yes 0..1 default amount of green color toward the outer edge of the shape (0..1)
|
|
b2 yes 0..1 default amount of blue color toward the outer edge of the shape (0..1)
|
|
a2 yes 0..1 default opacity of the outer edge of the shape; 0=transparent, 1=opaque
|
|
border_r yes 0..1 default amount of red color in the shape's border (0..1)
|
|
border_g yes 0..1 default amount of green color in the shape's border (0..1)
|
|
border_b yes 0..1 default amount of blue color in the shape's border (0..1)
|
|
border_a yes 0..1 default opacity of the shape's border; 0=transparent, 1=opaque
|
|
|
|
time NO >0 retrieves the current time, in seconds, since MilkDrop started running
|
|
fps NO >0 retrieves the current framerate, in frames per second.
|
|
frame NO retrieves the number of frames of animation elapsed since the program started
|
|
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
|
|
-note that if Scroll Lock is on, 'progress' will freeze!
|
|
|
|
bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
|
|
mid NO >0 -same, but for mids (middle frequencies)
|
|
treb NO >0 -same, but for treble (high) frequencies
|
|
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
|
|
mid_att NO >0 -same, but for mids (middle frequencies)
|
|
treb_att NO >0 -same, but for treble (high) frequencies
|
|
|
|
q1 yes any }
|
|
q2 yes any }
|
|
q3 yes any } Used to carry information
|
|
q4 yes any } from the preset per-frame code
|
|
q5 yes any } to the custom shape/wave per-frame code.
|
|
q6 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
q7 yes any }
|
|
q8 yes any }
|
|
|
|
t1 yes any }
|
|
t2 yes any }
|
|
t3 yes any } Used to carry information
|
|
t4 yes any } from the custom shape init code
|
|
t5 yes any } to the custom shape per-frame code.
|
|
t6 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
t7 yes any }
|
|
t8 yes any }
|
|
|
|
|
|
CUSTOM WAVE PER-FRAME VARIABLES
|
|
---------------------
|
|
NAME WRITABLE? RANGE DESCRIPTION
|
|
---- --------- ----- -----------
|
|
r yes 0..1 base amount of red color in the wave (0..1)
|
|
g yes 0..1 base amount of green color in the wave (0..1)
|
|
b yes 0..1 base amount of blue color in the wave (0..1)
|
|
a yes 0..1 base opacity of the waveform; 0=transparent, 1=opaque
|
|
|
|
time NO >0 retrieves the current time, in seconds, since MilkDrop started running
|
|
fps NO >0 retrieves the current framerate, in frames per second.
|
|
frame NO retrieves the number of frames of animation elapsed since the program started
|
|
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
|
|
-note that if Scroll Lock is on, 'progress' will freeze!
|
|
|
|
bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
|
|
mid NO >0 -same, but for mids (middle frequencies)
|
|
treb NO >0 -same, but for treble (high) frequencies
|
|
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
|
|
mid_att NO >0 -same, but for mids (middle frequencies)
|
|
treb_att NO >0 -same, but for treble (high) frequencies
|
|
|
|
q1 yes any }
|
|
q2 yes any }
|
|
q3 yes any } Used to carry information
|
|
q4 yes any } from the preset per-frame code
|
|
q5 yes any } to the custom shape/wave per-frame code.
|
|
q6 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
q7 yes any }
|
|
q8 yes any }
|
|
|
|
t1 yes any }
|
|
t2 yes any }
|
|
t3 yes any } Used to carry information
|
|
t4 yes any } from the custom wave init code,
|
|
t5 yes any } to the custom wave per-frame code,
|
|
t6 yes any } and on to the custom wave per-point code.
|
|
t7 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
t8 yes any }
|
|
|
|
|
|
CUSTOM WAVE PER-POINT VARIABLES
|
|
---------------------
|
|
NAME WRITABLE? RANGE DESCRIPTION
|
|
---- --------- ----- -----------
|
|
x yes 0..1 the x position of this point that makes up the wave (0=left, 1=right)
|
|
y yes 0..1 the y position of this point that makes up the wave (0=bottom, 1=top)
|
|
sample no 0..1 how far along we are, through the samples that make up the waveform: 0=first sample, 0.5 = half-way through; 1=last sample.
|
|
value1 no any the value of the Left audio channel sample at this point in the waveform (or freq. spectrum).
|
|
value2 no any the value of the Right audio channel sample at this point in the waveform (or freq. spectrum).
|
|
r yes 0..1 amount of red color in this point of the wave (0..1)
|
|
g yes 0..1 amount of green color in this point of the wave (0..1)
|
|
b yes 0..1 amount of blue color in this point of the wave (0..1)
|
|
a yes 0..1 opacity of this point of the waveform; 0=transparent, 1=opaque
|
|
|
|
time NO >0 retrieves the current time, in seconds, since MilkDrop started running
|
|
fps NO >0 retrieves the current framerate, in frames per second.
|
|
frame NO retrieves the number of frames of animation elapsed since the program started
|
|
progress NO 0..1 progress through the current preset; if preset was just loaded, this is closer to 0; if preset is about to end, this is closer to 1.
|
|
-note that if Scroll Lock is on, 'progress' will freeze!
|
|
|
|
bass NO >0 retrieves the current amount of bass. 1 is normal; below ~0.7 is quiet; above ~1.3 is loud bass
|
|
mid NO >0 -same, but for mids (middle frequencies)
|
|
treb NO >0 -same, but for treble (high) frequencies
|
|
bass_att NO >0 retrieves an attenuated reading on the bass, meaning that it is damped in time and doesn't change so rapidly.
|
|
mid_att NO >0 -same, but for mids (middle frequencies)
|
|
treb_att NO >0 -same, but for treble (high) frequencies
|
|
|
|
q1 yes any }
|
|
q2 yes any }
|
|
q3 yes any } Used to carry information
|
|
q4 yes any } from the preset per-frame code
|
|
q5 yes any } to the custom wave per-frame code
|
|
q6 yes any } and on to the custom wave per-point code.
|
|
q7 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
q8 yes any }
|
|
|
|
t1 yes any }
|
|
t2 yes any }
|
|
t3 yes any } Used to carry information
|
|
t4 yes any } from the custom wave init code,
|
|
t5 yes any } to the custom wave per-frame code,
|
|
t6 yes any } and on to the custom wave per-point code.
|
|
t7 yes any } see <A HREF="q_and_t_vars.gif">q_and_t_vars.gif</A>
|
|
t8 yes any }
|
|
|
|
|
|
|
|
<A NAME="3e">
|
|
<B>e. QUALITY ASSURANCE</B>
|
|
----------------------
|
|
In order to make sure the presets you create work well on other systems,
|
|
keep the following in mind:
|
|
|
|
1. Design your presets using the default mesh size (32x24) option
|
|
from the config panel, or at least check, before you distribute them,
|
|
to make sure they look correct at the default mesh size. If your
|
|
mesh is too coarse (small), then a viewer with the default mesh size
|
|
might see unexpected "bonus" effects that you might not have intended,
|
|
and might mess up your preset. If your mesh is too fine, then a
|
|
viewer with the default might not see all the detail you intended,
|
|
and it might look bad.
|
|
|
|
2. Keep your presets fast. There's nothing to spoil the mood like
|
|
a preset popping up that chokes at 10 fps. Since division is 11
|
|
times slower than multiplication (or addition/subtraction), if you
|
|
divide a bunch of values by one other value, pre-divide that value
|
|
("inv = 1/myval;") and then multiply those other values by that
|
|
inverse. Also, never put computations in the per-pixel code that
|
|
are the same for every pixel; move these into the per-frame code,
|
|
and carry the results to the per-pixel code using the q1-q8 variables.
|
|
Remember that maxim: "If a per-pixel equation doesn't use at least
|
|
one of the variables { x, y, rad, ang }, then it should be actually
|
|
be a per-frame equation."
|
|
|
|
2. Try to design your presets in a 32-bit video mode, so that its
|
|
brightness levels are standard. The thing to really watch out
|
|
for is designing your presets in 16-bit color when the "fix pink/
|
|
white color saturation artifact" checkbox is checked. This
|
|
checkbox keeps the image extra dark to avoid color saturation,
|
|
which is only necessary on some cards, in 16-bit color. If this
|
|
is the case for you, and you write a preset, then when you run
|
|
it on another machine, it might appear insanely bright.
|
|
|
|
3. Don't underestimate the power of the 'dx' and 'dy' parameters. Some
|
|
of the best presets a based on using these. If you strip everything
|
|
out of a preset so that there's no motion at all, then you can use the
|
|
dx and dy parameters to have precise manual control over the motion.
|
|
Basically, all the other effects (zoom, warp, rot, etc.) are just
|
|
complicated abstractions; they could all be simulated by using only
|
|
{ x, y, rad, ang } and { dx, dy }.
|
|
|
|
4. If you use the 'progress' variable in a preset, make sure you
|
|
try the preset out with several values for 'Time Between Auto
|
|
Preset Changes'. The biggest thing to avoid is using something
|
|
like sin(progress), since the rate at which 'progress' increases
|
|
can vary drastically from system to system, dependong on the user's
|
|
setting for 'Time Between Auto Preset Changes'.
|
|
|
|
|
|
|
|
<A NAME="3f">
|
|
<B>f. DEBUGGING</B>
|
|
-----------------------
|
|
One feature that preset authors should definitely be aware of is the
|
|
variable monitoring feature, which lets you monitor (watch) the value
|
|
of any per-frame variable you like. First, hit the 'N' key to show
|
|
the monitor value, which will probably display zero. Then all you
|
|
have to do is add a line like this to the per-frame equations:
|
|
|
|
monitor = x;
|
|
|
|
where 'x' is the variable or expression you want to monitor. Once you
|
|
hit CTRL+ENTER to accept the changes, you should see the value of the
|
|
per-frame variable or expression in the upper-right corner of the
|
|
screen!
|
|
|
|
Once again, note that it only works for *per-frame* equations, and NOT
|
|
for per-pixel equations.
|
|
|
|
|
|
|
|
<A NAME="3g">
|
|
<B>g. FUNCTION REFERENCE</B>
|
|
-----------------------
|
|
Following is a list of the functions supported by the expression evaluator.
|
|
The list was blatently ripped from the help box of Justin Frankels' AVS
|
|
plug-in, since MilkDrop uses the expression evaluator that he wrote.
|
|
|
|
Format your expressions using a semicolon (;) to delimit between statements.
|
|
Use parenthesis ['(' and ')'] to denote precedence if you are unsure.
|
|
The following operators are available:
|
|
= : assign
|
|
+,-,/,* : plus, minus, divide, multiply
|
|
| : convert to integer, and do bitwise or
|
|
& : convert to integer, and do bitwise and
|
|
% : convert to integer, and get remainder
|
|
The following functions are available:
|
|
int(var) : returns the integer value of 'var' (rounds toward zero)
|
|
abs(var) : returns the absolute value of var
|
|
sin(var) : returns the sine of the angle var (expressed in radians)
|
|
cos(var) : returns the cosine of the angle var
|
|
tan(var) : returns the tangent of the angle var
|
|
asin(var) : returns the arcsine of var
|
|
acos(var) : returns the arccosine of var
|
|
atan(var) : returns the arctangent of var
|
|
sqr(var) : returns the square of var
|
|
sqrt(var) : returns the square root of var
|
|
pow(var,var2) : returns var to the power of var2
|
|
log(var) : returns the log base e of var
|
|
log10(var) : returns the log base 10 of var
|
|
sign(var) : returns the sign of var or 0
|
|
min(var,var2) : returns the smalest value
|
|
max(var,var2) : returns the greatest value
|
|
sigmoid(var,var2) : returns sigmoid function value of x=var (var2=constraint)
|
|
rand(var) : returns a random integer modulo 'var'; e.g. rand(4) will return 0, 1, 2, or 3.
|
|
bor(var,var2) : boolean or, returns 1 if var or var2 is != 0
|
|
bnot(var) : boolean not, returns 1 if var == 0 or 0 if var != 0
|
|
if(cond,vartrue,varfalse) : if condition is nonzero, returns valtrue, otherwise returns valfalse
|
|
equal(var,var2) : returns 1 if var = var2, else 0
|
|
above(var,var2) : returns 1 if var > var2, else 0
|
|
below(var,var2) : returns 1 if var < var2, else 0
|
|
|
|
|
|
|
|
|
|
<A HREF="#milkdrop_preset_authoring_top">return to top</A>
|
|
<A HREF="milkdrop.html">return to milkdrop.html</A>
|
|
</PRE>
|
|
</HTML> |