(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) ------------------------------------------------------------------------------