(Stu(t(ter)))
INTRODUCTION
------------
Stutter is a very simple language used to define the move, waveform,
particle and colormap functions. The grammar of the language is
very simple. All operators are of the form
(operator argument ...)
Each of the arguments can (usually) be one of
A literal only numeric values are supported, and all
numerics a floating point numbers.
e.g. 1.0 23.92
A variable a variable is referenced by '$name' where
the name can be any alpha chacater followed
by any combination of alpha-numeric characters
e.g. $x $Volume $Y3
Stutter now supports a simple array type. There
is a maximum number of 1024 elements in a an
array. An array is accessed by as follows
[$name element]
Note that the '$' must be present. The element
may be any argument type. Only the integer
component of the element is used. Arrays can
be used anywhere that variables can.
A operator most arguments can also be the return values
of another operator
e.g. (operator (operator arg) arg)
It is required that you define a number of functions in your scripts
that are run at appropriate times. For example, all of the types
of script should have an init function, which is used for setting
up relevant variables and settings for the main function. An example
of an init function would be
(declare init
(set $RandomX (- (rnd 2.0) 1.0))
(set $RandomY (- (rnd 2.0) 1.0))
)
To read and understand 'stutter' code it is best to work from the inner
most levels out. So, in this example the inner most function is
(rnd 2.0)
This returns a random number between 0.0 and 2.0
The next level out is
(- (rnd 2.0) 1.0)
which means subtract 1.0 from the random number (in the range 0.0 to 2.0)
The outer layer is
(set $RandomX (- (rnd 2.0) 1.0))
which sets the value of the variable $RandomX to the number we have just
worked out.
You'll noticde that the whole function is within a (declare init ..).
This is how you declare functions. There is no way to run your own
functions at this point, so you will only need to create the functions
that are requried for each type of script.
While the language may seem confusing it is simple to learn and its strange
layout allows for simple and fast compiling and running of these scripts.
FUNCTION LIST
-------------
The following functions are available
Mathematical Operators:
These are the arithmetic functions, as well as trigonometric
and other standard mathematical functions. All angles in
trigonometrical functions are in radians (a full circle is
2 * PI radians)
Function Usage Notes
-------- ----------------------- --------------------------------------
+ (+ arg1 arg2 ...) Returns arg1 + arg2. If more arguments
are supplied, they are also added.
- (- arg1 arg2) Returns arg1 - arg2
* (* arg1 arg2 ...) Returns arg1 * arg2. If more arguments
are supplied they are also multiplied.
/ (/ arg1 arg2) Returns arg1 / arg2. If arg2 == 0 then
returns 0.
mod (mod arg1 arg2) Returns the remainder of arg1 / arg2
% (% arg1 arg2) Synonym for mod
abs (abs arg1) Returns the absolute value of arg1
trunc (trunc arg1) Returns the non-decimal part of arg1
sign (sign arg1) If arg1 >= 0 returns 1.0 otherwise -1.0
pos (pos arg1) If arg1 >= 0 returns arg1 otherwise 0.0
neg (neg arg1) Return the negative of arg1. Note that
this is NOT similar to the pos function.
Equivalent to (- 0 arg1).
sqrt (sqrt arg1) Returns the square root of arg1
log (log arg1) Returns the log of arg1
exp (exp arg1) Returns the exp of arg1
pow (pow arg1 arg2) Returns arg1 raised to the power of arg2
sin (sin arg1) Returns the sin of arg1
cos (cos arg1) Returns the cos of arg1
tan (tan arg1) Returns the tan of arg1
atan (atan arg1 arg2) Returns the arctangent of arg2 / arg1.
Correctly handles arg1 = 0.
rnd (rnd [arg1 [arg2]]) Return a random number between arg1
and arg2. If arg2 is missing, then
return a number between 0 and arg1,
if neither are present return a number
between 0 and 1.
wrap (wrap arg1 [arg2 Wraps arg1 in the range a to b where
[arg3]]) a=arg2 and b=arg3 if both supplied
a=0.0 and b=arg2 if one supplied
a=0.0 and b=1.0
clamp (clamp arg1 [arg2 With a and b the same as for wrap,
[arg3]]) if arg1 < a return a, if arg1 > b
return b otherwise return arg1
Logical Operators:
The logical operators duplicate the boolean functions of many
languages. Because stutter only supports floating point numbers,
a value of 1.0 is used for True and 0.0 for False. In the use
of logical values any non zero value is considered to be True.
Function Usage Notes
-------- ----------------------- --------------------------------------
&& (&& arg1 arg2 ...) True if both arg1 and arg2 are nonzero
If more arguments are added, they must
also be non-zero. Only enough args
are evaluated to find the first zero
value, otherwise all are evaluated.
|| (|| arg1 arg2 ...) True if either arg1 or arg2 is nonzero
If more arguments are added, they may
also be non-zero. Only enough args
are evaluated to find the first
non-zero value, otherwise all are
evaluated.
! (! arg1) True if arg1 is zero
== (== arg1 arg2) True if arg1 and arg2 are equal
!= (!= arg1 arg2) True if arg1 is not equal to arg2
< (< arg1 arg2) True if arg1 is less than arg2
<= (<= arg1 arg2) True if arg1 is less than or equal
to arg2
> (> arg1 arg2) True if arg1 is greater than arg2
>= (>= arg1 arg2) True if arg1 is greater than or equal
to arg2
Bitwise Operators:
Although all variables in stutter are floating point, a small amount
of support for bitwise operators is available. The decimal part of
the arguments are stripped off and the bitwise operation is applied
to the integer part of the arguments.
Function Usage Notes
-------- ----------------------- --------------------------------------
& (& arg1 arg2 ...) Return the bitwise AND of arg1 and arg2
If more arguments are supplied they
are AND'ed as well.
| (| arg1 arg2 ...) Return the bitwise OR of arg1 and arg2
If more arguments are supplied they
are OR'ed as well.
<< (<< arg1 arg2) Left shift the integer value arg1 by
arg2 bits.
>> (>> arg1 arg2) Right shift the integer value arg1 by
arg2 bits
Variable Handling:
These operators are special in that one or more of the arguments
must be variables.
Function Usage Notes
-------- ----------------------- --------------------------------------
set (set $v arg1) Set the value of variable $v to arg1
= (= $v arg1) Synonym for set
polar (polar $v1 $v2 arg1 Convert arg1 and arg2, which are X and
arg2) Y coordinates to polar coordinates and
store them in the variables $v1 and $v2
which are radius and angle (theta)
respectively. The value of this
function is the value of $v1
cart (cart $v1 $v2 arg1 Convert arg1 and arg2, which are radius
arg2) and theta in polar coordinates, to
cartesian (X, Y) coordinates and store
in the variables $v1 and $v2 which are
the X and Y coordinates. The value of
this function is the value of $v1
+= (+= $v arg1) This is equivalent to (= $v (+ $v arg1))
-= (-= $v arg1) This is equivalent to (= $v (- $v arg1))
*= (*= $v arg1) This is equivalent to (= $v (* $v arg1))
/= (/= $v arg1) This is equivalent to (= $v (/ $v arg1))
%= (%= $v arg1) This is equivalent to (= $v (% $v arg1))
Execution Flow:
These functions allow help with the flow of functions.
Function Usage Notes
-------- ----------------------- --------------------------------------
declare (delcare name [arg Declare a function for use by the
...]) program. The arguments are evaluated
in turn. No value is returned from a
declare statement. It can only be the
outermost level of any statement and
is also the only valid outermost level.
block (block [arg ...]) Evaluate the arguments in order. The
return value is value of the last
argument.
if (if arg1 arg2 [arg3]) If the value of arg1 is considered to
be True (i.e arg1 != 0), then evaluate
arg2, otherwise evaluate arg3 if it is
supplied. The return value whichever
argument (arg2 or arg3) is evaluated,
or 0 if none.
loop (loop $v1 arg1 arg2 Evalute arg3 for each integer value
arg3 between arg1 and arg2 (inclusive).
The value of $v1 is set to the current
loop value for each iteration. The
values of arg1 and arg2 are set at
the beginning of the loop and are not
continually evaulated.
while (while arg1 arg2) So long as arg1 is nonzero, evaluate
arg2.
case (case val A case statement is similar to that
[tst0 arg0 in many languages, and is equivalent
tst1 arg1 ...] to a number of if statements. The
[argN]) value of 'val' is compared to each
of the tst0, tst1, etc values and
if they are equal, the value of the
matching arg is returned, otherwise
the value of argN (the final arg on
the end of the case statement) is
returned. If that is not present a
value of 0 is returned if nothing
matches.
Audio Data Functions:
These allow you to get audio data at the current time. They
should only be used in colormap, waveform and particle functions.
Function Usage Notes
-------- ----------------------- --------------------------------------
lSpect (lspect arg1) Return the spectrum intensity at the
frequency mapped by arg1. Arg1 should
be in the range 0 to 1. The data is
for the left channel. The return value
is in the range 0 to 1.
rSpect (rspect arg1) As with lspect except that the data is
from the right channel.
lWave (lwave arg1) Return the wave value (range of -1 to 1)
at the point specified by arg1 (which
is in the range of 0 to 1). The data
is from the left channel.
rWave (rwave arg1) As with lwave except that the ata is
from the right channel.
3D Functions:
To help speed up 3D calculations a little, there are a small number
of 3D routines available.
Note: the 3dSetup and 3dRotate routines are designed for use when
many points are being rotated through the same angles. It is
expected that the 3dSetup be called once for many calls to the
3dRotate function. If you wish to rotate a single point you
should probably script that explicitly.
Function Usage Notes
-------- ----------------------- --------------------------------------
3dSetup (3dSetup arg1 arg2 Setup a rotation matrix with arg1,
arg3) arg2 and arg3 being the X, Y, and Z
rotation values respectively. This
function should be called before the
3dRotate function is called, it does
precalculation for when you are
rotating many points through the same
angles.
3dRotate (3dRotate $v1 $v2 $v3 Rotate the points arg1, arg2 and arg3,
arg1 arg2 arg3) which are (X,Y,Z) through the rotation
setup with 3dSetup and store the values
in ($v1,$v2,$v3)
SPECIAL VARIABLES AND FUNCTIONS
-------------------------------
In each script there are a number of variables that have special meaning.
Some of these can be set by the script to determine behaviour - this is
usually done within the init function. Others are set before functions
are called as effectively the passed arguments to the function.
==============================================================================
Colormaps
==============================================================================
Function: init
Variables Supplied: none
Variables Returned: none
Called: Called when the colormap is about to be called for
the first time.
------------------------------------------------------------------------------
Function: color
Variables Supplied: $Time time (in seconds) - see $UseTime and
$RelativeTime, below
$Value the color value (in the range from
0 to 1. 0 is considered the background
color and 1 the 'brightest'.
$LeftPeak, A measure of the average volume of
$RightPeak, the whole waveform. The left and
$MidPeak right channels as well as the average
of the two, is supplied
$LeftBass, The bass and treble portions of the
$RightBass, left, right and average channels are
$MidBass, soon to be available, but currently
$LeftTreble, are set to zero.
$RightTreble,
$MidTreble
Variabkes Returned: $H, $S, $V Hue, Saturation and Intensity
of the color, each in a range of 0
to 1. Only used if $UseHSV is True.
$R, $G, $B Red, Green and Blue portions of the
color, each in a range of 0 to 1.
Only used if $UseHSV is not True.
Called: Whenever a color is required. Will be called once
for each color in the colormap (256 colors)
when the colormap is first installed. If $UseTime
is true then it will be called for each color in
the colormap before each frame is displayed.
------------------------------------------------------------------------------
Special Variable: $UseHSV If True the HSV values rather than
RGB values are used to determine the
colors
------------------------------------------------------------------------------
Special Variable: $UseTime If True then the colormap is assumed
to change over time and is regenerated
each frame with an updated $Time
variable
------------------------------------------------------------------------------
Special Variable: $RelativeTime If True then the $Time variable sent
is relative to a zero time when the
colormap was first called, otherwise
it is system time.
------------------------------------------------------------------------------
Special Variable: $PI The value of PI (3.14159265358979323)
------------------------------------------------------------------------------
==============================================================================
Movemaps
==============================================================================
Function: init
Variables Supplied: none
Variables Returned: none
Called: Called when the movemap is about to be called for
the first time.
------------------------------------------------------------------------------
Function: move
Variables Supplied: $X X coordinate in the range -1 to 1
$Y Y coordinate in the range -1 to 1
$Radius Radius from polar coordinates (if
$RequireRadius is True)
$Theta Theta from polar coordinates (if
$RequireTheta is True)
Variables Returned: $SrcX, $SrcY The X and Y coordinates to source the
new color for the $x, $y point from.
Only used if $UsePolar is not True
$SrcRadius, The Radius and Theta coordinates to
$SrcTheta source the new color for the $radius
$theta point from. Only used if
$UsePolar is True.
Called: Once per $x, $y on the current screen.
------------------------------------------------------------------------------
Special Variable: $RequireRadius If True then when the move function is
called, the radius of the (X, Y) point
is calculated and supplied in $Radius
------------------------------------------------------------------------------
Special Variable: $RequireTheta If True then when the move function is
called, the theta of the (X, Y) point
is calculated and supplied in $Theta
------------------------------------------------------------------------------
Special Variable: $UsePolar If True then the $SrcRadius and
$SrcTheta values are used instead of
$SrcX and $SrcY. If set True in the
init function then $RequireRadius and
$RequireTheta are also set to True.
------------------------------------------------------------------------------
Special Variable: $UseAspect If True then the X, Y range from
(-1,-1) to (1,1) defines the smallest
square to fit all the screen otherwise
the shape is a rectangle to exactly
fit the screen.
------------------------------------------------------------------------------
Special Variable: $PI The value of PI (3.14159265358979323)
------------------------------------------------------------------------------
==============================================================================
Waveforms
==============================================================================
Function: init
Variables Supplied: none
Variables Returned: $NumPaths The number of separate waveforms to
draw. There can be a maximum of 16
paths. The value defaults to 1
Called: Called when the waveform is about to be called for
the first time.
------------------------------------------------------------------------------
Function: newline
Variables Supplied: $Time time (in seconds) - see $UseTime and
$RelativeTime, below
$LeftPeak, A measure of the average volume of
$RightPeak, the whole waveform. The left and
$MidPeak right channels as well as the average
of the two, is supplied
$LeftBass, The bass and treble portions of the
$RightBass, left, right and average channels are
$MidBass, soon to be available, but currently
$LeftTreble, are set to zero.
$RightTreble,
$MidTreble
Variables Returned: none
Called: Called once before the beginning of a new waveform
for each frame.
------------------------------------------------------------------------------
Function: waveform
Variables Supplied: $Time, These are the same as in the newline
$Leftpeak, function.
$RightPeak,
$MidPeak,
$LeftBass,
$RightBass,
$MidBass,
$LeftTreble,
$RightTreble,
$MidTreble
$Step The stage in the waveform we are. This
is in the range 0 to 1.
$Left, $Right, The waveform data for the left and
$Mid right channel, as well as the average.
Variables Returned: $X0, $Y0, For each path (from 0 to $NumPaths - 1)
$X1, $Y1, ... you need to supply the X and Y points
for the waveform at this step.
$Fade0, $Fade1, The color to draw the line in. See
... the special variables below.
Called: Once for each step (see $NumSteps below) in the
waveform. Each call is expected to work out the x
and y coordinates for each of the paths.
------------------------------------------------------------------------------
Special Variable: $NumPaths The number of separate waveform paths
to display.
------------------------------------------------------------------------------
Special Variable: $NumSteps The number of steps along the
waveform. The default value is 256.
The data supplied is limited to 512
pieces of data, so the maximum value
for $NumSteps is 512. Minimum 2.
------------------------------------------------------------------------------
Special Variable: $Loop0, For each of the paths if the $Loopn
$Loop1, ... is True, then a line is draw from the
last point back to the first point,
to make a looped waveform.
------------------------------------------------------------------------------
Special Variable: $NoLines0, If True, for each of the paths, then
$NoLines1, rather than draw lines just do points
... for the waveform display.
------------------------------------------------------------------------------
Special Variable: $Fade0, How much, in a range of 0 to 1, to
$Fade1 fade the newly drawn waveform data
... by. A value of zero draws the waveform
in the brightest color entry, while
a value of 1 draws in the background
color.
------------------------------------------------------------------------------
Special Variable: $RelativeTime If True then the $Time variable sent
is relative to a zero time when the
waveform was first called, otherwise
it is system time.
------------------------------------------------------------------------------
Special Variable: $UseAspect If True then the X, Y range from
(-1,-1) to (1,1) defines the smallest
square to fit all the screen otherwise
the shape is a rectangle to exactly
fit the screen.
------------------------------------------------------------------------------
Special Variable: $useBlendType Set the method by which the color
is drawn. A blend type of 0 will
set the pixel to the color specified,
a type of 1 will add the value to the
current pixel, and a value of 2 will
only set the pixel if the new color
is 'brighter' than current one.
------------------------------------------------------------------------------
Special Variable: $PI The value of PI (3.14159265358979323)
------------------------------------------------------------------------------
==============================================================================
Particles
==============================================================================
Function: init
Variables Supplied: none
Variables Returned: $NumParticles The number of particles to be drawn.
The particle function will be called
once for each of these, with the value
of $Particle set to each integer
value from 0 to $NumParticles - 1 in
turn.
Called: Called when the particle is about to be called for
the first time.
------------------------------------------------------------------------------
Function: newframe
Variables Supplied: $Time time (in seconds) - see $UseTime and
$RelativeTime, below
$LeftPeak, A measure of the average volume of
$RightPeak, the whole waveform. The left and
$MidPeak right channels as well as the average
of the two, is supplied
$LeftBass, The bass and treble portions of the
$RightBass, left, right and average channels are
$MidBass, soon to be available, but currently
$LeftTreble, are set to zero.
$RightTreble,
$MidTreble
Variables Returned: none
Called: Called once before the beginning of a new frame.
------------------------------------------------------------------------------
Function: particle
Variables Supplied: $Time, These are the same as in the newline
$Leftpeak, function.
$RightPeak,
$MidPeak,
$LeftBass,
$RightBass,
$MidBass,
$LeftTreble,
$RightTreble,
$MidTreble
$Particle This is the current particle number.
It is between 0 and $NumParticles - 1,
inclusive.
Variables Returned: $X, $Y The X and Y values for this particle
$Xend, $Yend The end X and Y values if the style
requires two points.
$Size The size of the particle. The value
for the size should probably be in
the range of .01 to 1.0. Anything
larger than 1.0 is quite large.
$Style This value determines the style of
particle type to draw. Currently
the following types are supported
1 A circle, using the size.
2 A line between ($x,$y) and
($Xend,$Yend). $size is
ignored.
Any other value is treated as type
1.
$Fade The color to draw the particle in. See
the special variables below.
Called: Once for each particle in the range 0 to
$NumParticles - 1. Each call is expected to work out
the x and y coordinates and size of its particle.
------------------------------------------------------------------------------
Special Variable: $NumParticles The number of particles to display.
There is one call to the particle
function for each particle for each
frame.
------------------------------------------------------------------------------
Special Variable: $Fade How much, in a range of 0 to 1, to
fade the newly drawn particle by.
A value of zero draws the particle
in the brightest color entry, while
a value of 1 draws in the background
color.
------------------------------------------------------------------------------
Special Variable: $RelativeTime If True then the $Time variable sent
is relative to a zero time when the
waveform was first called, otherwise
it is system time.
------------------------------------------------------------------------------
Special Variable: $UseAspect If True then the X, Y range from
(-1,-1) to (1,1) defines the smallest
square to fit all the screen otherwise
the shape is a rectangle to exactly
fit the screen.
------------------------------------------------------------------------------
Special Variable: $useBlendType Set the method by which the color
is drawn. A blend type of 0 will
set the pixel to the color specified,
a type of 1 will add the value to the
current pixel, and a value of 2 will
only set the pixel if the new color
is 'brighter' than current one.
------------------------------------------------------------------------------
Special Variable: $PI The value of PI (3.14159265358979323)
------------------------------------------------------------------------------