Music Objects Model

The ArtSong Music Object Model defines various objects and functions that provide the interface between the script engine and ArtSong’s internal Music Component Model.

Composition Engine Hook Functions – These are functions which if defined in the FUNCTIONS section of a script will automatically be called by the composition engine.

Project, Track, Note, and MIDI Event Objects – These are the objects whose properties and methods are used from scripts to generate, edit, and select note events etc.

Escape Fractal Objects – A Julia set and Mandelbrot set object are defined that can be used from script.

Composition Engine Hook Functions

When executing scripts through the composition engine; the engine will automatically look for and call several specific procedures at particular times during the composition process. You may optionally include all or none of the following procedures in your scripts.

These procedures should be placed in a script’s FUNCTIONS section; they are only called when composing through the composition engine.

procedure BeforeCompose(Start, End): This procedure is executed once before the composition process begins. The Start and End arguments contain the starting time and ending time in TICKS for the section to be composed. This procedure is used primarily for performing any required initializations.

procedure Compose(Time): This procedure is executed for each distinct time step by the composition engine. The Time argument refers to the current composition time.

procedure AfterCompose(End): This procedure is executed once after the composition process ends. The End argument contains the ending time in TICKS for the section composed. This should be the same value as that passed as the End value in the first procedure unless the composition process is aborted.

int function Map(VarID,LastVal, HighVal, LowVal, MAXVal, MINVal): This procedure is executed each time one of the assigned composition variables needs to generate a new value. This function returns the new integer value. The arguments:

• VarID = Composition Variable ID
• LastVal = Previous value calculated for this variable
• HighVal = High range value for the current variable range
• LowVal = Low range value for the current variable range
• MAXVal = Maximum value for this variable; do not exceed this value
• MINVal = Minimum value for this variable; do not exceed this value.

Track, Note, and MIDI Event Objects

There are several ArtSong objects that can be manipulated from script. The most important are the Track and Note-Event objects but the complete list includes:

• this – refers to the current project.
• self – refers to the actual script component used to compile and execute the script. This component needs to be the ‘owner’ of all script generated Forms or Dialogs so that they will be disposed of properly when ArtSong is closed down.
• engine – refers to the composition engine.
• track – refers to a track component in the current project.
• note – refers to a note event in the current track component.
• midi – refers to a MIDI voice channel message
• constants – just some useful predefined constant values

Escape Fractal Objects

ArtSong provide two fractal scripting objects representing Mandelbrot Set and the Julia Set having the object names MandelBrotSet and JuliaSet respectively. Both have the following functions and properties.

properties

double ViewMinReal: Read/Write the minimum value for the real part of the function range

double ViewMaxReal: Read/Write the maximum value for the real part of the function range

double ViewMinImaginary: Read/Write the minimum value for the imaginary part of the function range

double ViewMaxImaginary: Read/Write the maximum value for the imaginary part of the function range

int Width: Read/Write the granularity of the real part of the function range. The range (ViewMaxReal – ViewMinReal) is divided into this number of subdivisions. Each time the function is iterated it will automatically advance. The Height and Width form a grid of cells or pixels

int Height: Read/Write the granularity of the imaginary part of the function range. The range (ViewMaxImaginary – ViewMinImaginary) is divided into this number of subdivisions. Each time the function is iterated it will automatically advance. The Height and Width form a grid of cells or pixels

bool reset: Write only – returns the internal cell/position pointer to the initial starting position

double BailOut: Read/Write the limiting function value to which the function is iterated.

int MaxIterations: Read/Write the maximum number of iterations allowed per cell.

int Iterations: Read only - returns the number of iterations to reach the BailOut value at the current position and advances position to next point.

PASCAL EXAMPLE

// to draw the mandelbrot set onto a Form Canvas
// you might do something like:
// sets the resolution of the fractal to
// match the number of pixels available in
// the form
MandelbrotSet.width := myForm.clientwidth;
MandelbrotSet.height := myForm.clientheight;
MandelbrotSet.MaxIterations := 100;
// sets the internal position to first cell (0,0)
MandelbrotSet.reset := true;
// iterates through all the cells in the height
// and width directions….
for j:= 0 to MandelbrotSet.height-1 do
begin
for i:= 0 to MandelbrotSet.width-1 do
begin
iterations := MandelbrotSet.iterations;
// do something to determine a pixel color
// based on the number of iterations….
// theColor = SOME_FUNCTION_OF(iterations)
myForm.canvas.pixels[i][j] := theColor;
end;
end;

BASIC EXAMPLE

‘ to draw the mandelbrot set onto a Form
‘ Canvas you might do something like:
MandelbrotSet.width = myForm.clientwidth
MandelbrotSet.height = myForm.clientheight
MandelbrotSet.MaxIterations = 100
MandelbrotSet.reset = true
FOR J = 0 to MandelbrotSet.height-1
FOR I = 0 to MandelbrotSet.width-1
iterations = MandelbrotSet.iterations
‘ do something to determine a pixel color
‘ based on the number of iterations….
‘ theColor = SOME_FUNCTION_OF(iterations)
myForm.canvas.pixels[i][j] = theColor
NEXT
NEXT