Scripts as Algorithm
There are four special script functions that the composition engine looks for and executes during the composition process; some, all, or none of these functions need be present.
The most important of the functions is the ‘Map’ function. The Map function in conjunction with the algorithm’s composition variable list allows you to script algorithms and map script-generated values to any composition variable.
The three other functions (BeforeCompose, Compose, and AfterCompose) are less frequently needed and will be discussed in Tutorial 3.
Example 9 - A Simple Random Algorithm
The Basic and Pascal script algorithms both display a list of available composition variables. Select the variables to assign to the script algorithm to by checking the appropriate variables in the list. Each time the composition engine requires a value for one of the ‘selected’ variables it will call the script ‘Map’ function replacing the formal arguments with the actual composition variable’s range and limit values.
Finally, to create our algorithm, we need to add the ‘Map’ function to the script and ensure that it returns a value within the MinVal – MaxVal range.
In this example script we will create a simple random algorithm by implementing the ‘Map’ function, using the randomrange(a,b) function to generate a random value within the appropriate range, and returning that value.
Do this...
Set the default project view to ‘Project Editor’ and create a new blank project.
Select the top ‘Composition’ component in the Component Pane and click on the Pascal or Basic algorithm on the ‘General’ Tab of the Algorithms Palette to add an instance of the algorithm to the project.
Select the Algorithm in the Component Pane and open its ‘property editor’ by right clicking and selecting the ‘Property Editor…’ from the pop-up menu.
Enter the following line in the Code Pane (you can ignore the comments):
(Pascal)
// returns a random value within the designated
// low-high range
//
function Map(VarID,LastVal,HighVal,LowVal,MaxVal,MinVal)
begin
result := RandomRange(LowVal, HighVal);
end;
(Basic)
- returns a random value within the designated
- low-high range
FUNCTION Map(VarID,LastVal,HighVal,LowVal,MaxVal,MinVal)
Map = RandomRange(LowVal, HighVal)
END FUNCTION
Select the pitch, duration, and volume composition variables from the ‘Composition Variable’ list to the left of the Code Pane. Close the property editor.
Click the ‘Compose’ button to generate some random notes into the project.
How it works...
Each time the composition engine needs a value for the pitch, duration, or volume composition variable (or any other selected composition variable) it executes the Map function to obtain a value.
When calling the Map function, the composition engine supplies the values:
- VarID – The composition variable identifier
- LastVal – The previous variable value
- HighVal – a specified high range value
- LowVal – a specified low range value
- MaxVal – the maximum allowed value for variable
- MinVal – the minimum allowed value for variable
The HighVal, LowVal values provide an optional window around the composition variable values to limit the amount of change from one value to the next. This ‘window’ can be ignored and the function can make use of the full allowed value range: MinVal to MaxVal. These latter values cannot be exceeded.
The RandomRange(low, high)function generates a random value between the specified low and the high values(inclusive).
Example 10 - A Simple Fractal Algorithm
We can create a simple fractal algorithm by implementing the ‘Map’ function, using the built-in MandelBrotSet object functions to generate a value, scaling that value to the appropriate range, and returning the ‘scaled’ value.
Do this…
Set the default project view to ‘Project Editor’ and create a new blank project.
Select the top ‘Composition’ component in the Component Pane and click on the Basic or Pascal algorithm on the ‘General’ Tab of the Algorithms Palette to add an instance of the algorithm to the project.
Select the Algorithm in the Component Pane and open its ‘property editor’ by right clicking and selecting the ‘Property Editor…’ from the pop-up menu.
Enter the following line in the Code Pane ( you can ignore the comments):
(Pascal)
function Map(VarID,LastVal,HighVal,LowVal,MaxVal,MinVal)
begin
result := (Mandelbrotset.Iterations /
Mandelbrotset.MaxIterations) * (HighVal –
LowVal) + LowVal;
end;
(Basic)
FUNCTION Map(VarID,LastVal,HighVal,LowVal,MaxVal,MinVal)
Map = (Mandelbrotset.Iterations / Mandelbrotset.MaxIterations) * (HighVal
- LowVal) + LowVal
END FUNCTION
Select the pitch, duration, and volume composition variables from the ‘Compositon Variable’ list to the left of the Code Pane. Close the property editor.
Click the ‘Compose’ button to generate some notes into the project.
| 
