Accessing Parameters Data

Until now we've seen the basics of Pascal, how to create inlets-outlets for our script module, how to deal with arrays and MIDI.

Before studying some script examples and see how to process data, we need a last step: How to access to inlets data, and how to sent data to outlets.

Remember that inlets and outlets are named parameters in Usine Script.

The script language has built-in functions and procedures to read data from and write data to those parameters.Here they are.

Getting parameters data (reading inlets values)

Remember the types of parameters you can create with Usine Script:

  • ptTextField
  • ptChooseColor
  • ptMIDI
  • ptGainFader
  • ptAudio
  • ptDataField
  • ptDataFader
  • ptButton
  • ptListBox
  • ptSwitch
  • ptArray
  • ptIpAddress
  • ptSmpte
  • ...

Let's look closer at these different types:

Parameters storing single values

Those parameter store single numerical values:

ptChooseColor,
ptGainFader,
ptAudio,
ptDataField,
ptDataFader,
ptButton,
ptListBox, 
ptSwitch
...

To read the values of these parameters, you'll use the function:

function  GetValue(Param:   integer): single;

As you can see, the result returned by this function is of type single. single is the most common floating point number used in Usine Script.

Example
// Let's create a fader inlet named inA (display name 'value'):
Var inA : tParameter; 
// we declare the variable inA as a parameter
inA := createParam(ptDataFader);  
// we create the inlet, display name 'value', type datafader
SetIsOutput(inA, false); 
// inA has an inlet (no outlet)

Let's declare a variable x

 Var x : single;

To store the value of the fader 'value' to x, we simply do:

 x := GetValue(inA);
Array parameters
ptArray, ptIpAddress, ptSmpte

For these parameters you need another access function:

function  GetDataArrayValue(Param, i: integer):single;

It accepts 2 arguments:

  • Param is the parameter's name
  • i is the index

It returns a single value.

Example

Let's say we have an array input called ArrayIn. If we want to read the 4th element value we'll do:

 GetDataArrayValue(ArrayIn, 3); 
midi parameters

ptMIDI

MIDI flow is considered as an array of MIDI messages.

For example if those MIDI messages are NOTE ON message, if the MIDI inlet receive note, the array length will be 1, if the MIDI inlet receives a 4 notes chord, the array length will be 4.

To access MIDI codes you'll use the procedure:

procedure GetMIDIArrayValue(Param,I: integer; var val:TMIDI);

It accepts three arguments:

  • param is the name of the parameter we want to access
  • I integer is the index (don't forget the minus 1 since array's indexing starts from 0)
  • var val:TMIDI is the tMIDI variable to which the result will be stored
Example

Let's say we have created a MIDI input to our script, called MIDIInput.

Let's assume this input receives a 4 note chord.

Let's declare a variable of type TMIDI called MIDI1.

Var MIDI1 : TMIDI;

To store the 3rd note of the chord into MIDI1 we'll do like this:

GetMIDIArrayValue(MIDIInput, 2, MIDI1); 
String parameters

ptTextField

To read a string, just use:

function  GetStringValue(Param: integer;) : string;

It has only one argument:

  • param : integer is the name of the parameter. The result is a string.
Example

If we have a text field inlet called TextIn.

Let's create a string variable to store the text:`

 Var Text : string;

Then simply do:

 Text := GetStringValue(TextIn);

!!!!! You can check chapter 6.Strings to learn how to manipulate strings.

Important function: GetLength()

Here's a crucial function to deal with parameters:

 function  GetLength(Param:   integer):integer;

It has one argument:

  • param : integer is the name of the parameter.

It returns an integer.

This function has several purposes:

Checking if the inlet receives any data

If nothing is connected to an inlet, or if it doesn't receive any data, then Usine considers the length of the message to be 0.

If the inlet receives something then the message length is greater than 0.

So, for instance, if we have an fader inlet called inA, and we want our script to be processed only if inA receives something, we'll do:

If GetLength(InA)>0 then
Begin
// here are the instructions for processing
End;

This is very useful to save CPU resources, since Usine will just execute the GetLength function at each cycle, and execute the block of instructions only if something is present at the input.

  • Getting the length of arrays for array inlets,
  • the number of MIDI codes for MIDI inlets,
  • the length of a string for a text inlet

Let's say we have a array inlet called ArrayIn.

It can receive an array of any length.

It can be connected for instance to the array output of a Step module, or whatever.

In this case, to process the array it's crucial to know it's length, especially to do loops.

Example

Let's say we want to store the content of ArrayIn to an array variable called tab1.

You'll do this:

Var tab1 : array of single;  // we declare an array of single
Var len, i : integer; // we'll use i for the loop and len to store the array length
Len := GetLength(ArrayIn); // we store the length of ArrayIn to the variable len
For I := 0 to len-1 do //loop for each element of ArrayIn
Begin
  Tab1[i] := GetDataArrayValue(ArrayIn, i); // use the GetDataArrayValue 
                                            // function to store each of the 
                                            // elements of ArrayIn to Tab1
End;

For MIDI codes, it's the same.

It's unlikely we can guess in advance how many MIDI codes will be present at a MIDI input.

But the function GetLength will tell us.

Example

Let's say we have a MIDI inlet, called MIDIIn.

Let's create a array of MIDI codes called TabMIDI, and store all the codes entering MIDIIn to it:

Var TabMIDI : array of TMIDI; // we declare an array of MIDI codes
Var len, i: integer;
Len := GetLength(MIDIIn);
For I := 0 to Len-1 do
Begin
  GetMIDIArrayValue(MIDIIn, I, TabMIDI[i]); // note the the difference of syntax with 
                                            // the array example since GetMIDIArrayValue 
                                            // is a procedure and not a function.
End;

Setting parameters data

Setting inlet or outlet values

Here we'll use procedures (not functions since the fact to set a parameter's value can not return any result).

These procedures are quite similar to the functions used before.

You can use them either to send data to an outlet after processing, or during the init procedure to set initial values to your inlets.

Lets detail these procedures for all kinds of parameters:

Single Values parameters
ptChooseColor, ptGainFader, ptAudio, ptDataField, ptDataFader,
ptButton,ptListBox, ptSwitch

The procedure is:

 procedure SetValue(Param:   integer; val: single); 

It has two arguments:

  • Param is the name of the parameter
  • Val is the value (single).
Example

Let's say you have a data outlet called Out1. Let's send send the number 10 to out1:

 SetValue(Out1, 10);

You can also send a variable (it must be a single) or an expression:

Var x : single;
SetValue(Out1, x);
SetValue(Out1, x+2);
SetLength procedure

This procedure is the opposite of the GetLength function:

procedure SetLength(Param:   integer; val: integer);

It has two arguments:

  • Param is the name of the parameter
  • Val is the length (integer).

When the length of the message sent to a parameter is 0 then this parameter sends nothing.

If the parameter contains a value, the length is positive.

Setting the length to 0 can be a security to avoid sending or dummy messages to the outlets. You have to use SetLength when you deal with arrays or MIDI codes, all you'll see later.

Array parameters

Here the procedure is:

procedure SetDataArrayValue(Param, I: integer; val: single);

It has three arguments:

  • Param is the name of the parameter
  • i is the index (integer).
  • Val is the value (single)

--Example:--

Let's say we have an array inlet called ArrayIn, and an array outlet called ArrayOut, and we simply want to pass through an array from ArrayIn to ArrayOut.

We'll do this:

Var ArrayTemp : array of single; /array to store the data from ArrayIn
Var I, len: integer;

Len := GetLength(ArrayIn); 
// we measure the length of ArrayIn, store it to len

SetLength(ArrayOut, len); 
// we make sure ArrayOut will be the same length as ArrayIn 
//(if you don't do this it can lead to weird behaviors or errors)

For i:= 0 to len-1 do // loop for all indexes
Begin
  ArrayTemp[i] := GetDataArrayValue(ArrayIn, i); 
  // store the ith element of ArrayIn to the ith element of ArrayTemp

  SetDataArrayValue(ArrayOut, I, Arraytemp[i]); 
  // send the same element to ArrayOut
End;
midi parameters

The procedure is:

procedure SetMIDIArrayValue(Param,I: integer; val: TMIDI);

It has three arguments:

  • Param is the name of the parameter
  • i is the index (integer).
  • Val is the value (TMIDI)

It's the exact opposite of GetMIDIArrayValue.

Example

Let's say we have a MIDI output called MIDIOut.

Let's send a NOTE ON, C3, vel 95, channel1 to it:

Var MIDINote : TMIDI; // declare the note variable
MIDINote.msg := 144; // Note ON
MIDINote.data1 : =60; // C3
MIDINote.data2 := 95; //Vel 95
MIDINote.channel := 1; // Channel 1
SetMIDIArrayValue(MIDIOut, 0, MIDINote); 
// We send the note as the first element of an array (thus the index 0) to MIDIOut.
SetLength(MIDIOut, 1); 
// if you forget this nothing will be present in MIDIOut. 
//We send 1 note, so we have to specify that the length of the MIDI array we send is 1.

Warning about MIDI codes

In general when you send a MIDI code, you want it to be sent as an impulse (not continuously).

With the example above, in between each computation of the main process, the MIDIOut outlet would still contain the value MIDINote.

This can lead to errors, since it's like if MIDINote was sent at each cycle.

Thus you would be sending the note continuously.

We have to use a security, and learn the MIDI output after we've sent our note once, this means to set the length of the output to 0.

This is why we'll add following line when no MIDI message is to be sent:

 SetLength(MIDIout, 0);

Usually, when you have to process and send out MIDI data, you'll use the if then else statement:

If //(condition to process and send MIDI is true)// Then //(process and send MIDI)// Else //(Make sure you send nothing)//

Example of sending a single MIDI note
If (condition-to-process-and-send-midi-is-true) then
begin
  // Here are instructions to process MIDI
  SetMIDIArrayValue(MIDIOut, 0, MIDINote); // Store the note to MIDI out
  SetLength(MIDIOut, 1); // actually send the note
End
Else
begin
  SetLength(MIDIout, 0); // 'lose' the output, 
                         // so that the note is not isn't sent once for each cycle
End;

You'll have more examples about MIDI in MIDI tips and tricks.

Text parameters

No surprise here, the simple procedure to send a string is:

 procedure SetStringValue(Param: integer; val: string);

It has two arguments:

  • Param is the name of the parameter
  • Val is the string to send (String)
Example

We have a text field output in our script, called TextOut. Let's send the word 'hello' to it:

 SetStringValue(Textout, 'hello';

Printing to the Usine message console: trace

Sometimes you'll need to have a visual feedback of what's happening inside your script, either for debugging, to follow the status of a variable during the script, or for any other reason.

The procedures:

 procedure sTrace(S:string); 
 procedure iTrace(I:Integer); 
 procedure fTrace(F:single);

will print the string to Usine's console.

If you want to print out numerical values, use the following functions:

 IntToStr(integer); // this converts an integer to a string

 FloatToStr(Extended); // the same for floating points values.
Examples
Var x : integer;
x :=10;
itrace(x); 
//this will display the number 10 in Usine's console
Var i : integer;
Var f : single;
i :=1;
f := 2,34;
strace('i= ' + IntToStr(i) + ' f=' + FloatTostr(f));
// this will display 'i= 1 f= 2,34' in Usines's console

See also

version 3.0.141

Edit All Pages