Instr Variables

Signal variable declarations in SAOL instrs occur after the open curly-brace of the instr preamble. The first SAOL statement in the instr marks the end of the variable declaration section: declarations and statements cannot be interspersed.

Each declared variable and parameter in an instr must have a unique name. Signal variables hold 32-bit floating point values and are initialized to zero.

Scalars

The simplest variable declaration consists of a rate identifier (ivar for i-rate, ksig for k-rate, or asig for a-rate), a name, and a semicolon (see right panel for examples). These variables are scalars, and have width 1. Multiple variables can be declared on the same line, separated by commas.

Legal Declarations

instr foo () {

ivar a;
ksig b,c;
asig d;

b = a;

}

Illegal Declarations

instr foo () {

ivar a;  // legal
asig d;  // legal 

a = 1;

ksig b; // illegal: must precede a = 1;

b = a;

}

Arrays

Array declarations build on this syntax, by adding an open bracket, a width specifier and a closed bracket. Arrays and scalars may share the same declaration line. The width specifier, that sets the width of the array, is usually numeric (an integer greater than zero).

Alternatively, the keyword inchannels or outchannels may serve as a width specifier. In an instr, arrays declared with the width specifier inchannels take the width of the audio input presented to the instrument. Arrays declared with the width specifier outchannels take the width of the audio data written by output statements in the instr. In Part II/5 we describe how to determine these widths for an instr.

Legal Array Declarations

ivar a[3];
ksig b,c[2];
asig d[inchannels],f[outchannels];

Illegal Array Declarations

ivar a[0];   // illegal: must be >= 1
ksig c[2.0]; // illegal: must be integer

Imports and Exports

Both scalar and array global variables may be imported or exported into an instr. The rate and width of the global and instr variables must be the same. Since globals may not be asig, neither may imported or exported instr declarations. See the right panel for examples.

If an instr variable is declared with imports, then at the start of the i-pass (for ivars) or at the start of each k-pass (for ksigs), the value of the global variable is copied into the instr variable.

If an instr variable is declared with exports, then at the end of the i-pass following instr instantiation (for ivars) or at the end of each k-pass (for ksigs), the final value of the instr variable is copied into the global variable.

If both imports and exports are used, both behaviors described above happen.

Legal imports and exports

global {
ivar a, c;
ksig b[3];
}

instr example () {

imports ivar a;
exports ivar c;
imports exports ksig b[3];

}

Illegal imports and exports

global {
ivar a;
}

instr example () {

imports ivar a[2]; // illegal: size mismatch
imports ksig a;    // illegal: rate mismatch
}

Imports for SASL

If an instr signal variable is declared using the imports keyword, but no global variable of the same name exists in the global block, the import semantics described in the previous section do not apply.

Instead, the imports keyword signifies that a variable may be targeted by a SASL labelled control command. This SASL command writes a new value into a ksig variable of an instr instance at the start of a k-pass.

Only scalar ksig variables may be used in this construction, and only imports may be used in the declaration, not exports.

An example in the tutorial in Part I shows this usage of the imports keyword in detail. A later section of this book explains SASL control statements in detail.

Imports for SASL:

See tutorial example.

Global Variables

Global signal variables are scalar or array variables declared in a global block of a SAOL program. Global signal variables may be declared ivar or ksig but not asig. The imports and exports keywords may not be used with global variables. Apart from these differences, global declarations share the same syntax as instr declarations.

Global variable names must be unique among all the global variables.

Array declarations may use the keywords inchannels or outchannels as width specifiers. For global arrays, these keywords indicate that the array should take the same width as the the input_bus or output_bus, respectively. These system buses are dedicated to external audio input and output, and are described in detail in Part II/5.

Distributed Global Blocks

The MP4-SA standard states that only one global block may exist in a SAOL program. This restriction makes it difficult to develop modular SAOL libraries.

Sfront relaxes this rule, and permits many global blocks in a SAOL program. To create MP4 files that comply with the standard, sfront collapses all global blocks into a single large global block when encoding .mp4 files.

startup

Global variables hold 32-bit floating-point numbers initialized to zero. To initialize global variable to non-zero values, define an instr named startup and assign initialization values to the global variables in its code block (using imports and exports to access the global variables).

This method works because the SAOL instr execution rules ensure that if the instr startup is defined, it is instanced and run at i-rate as part of the start up sequence of a SAOL program, before the first k-cycle begins.

In addition, by default the startup instrument executes first in each execution cycle, so that k-rate global variables may also be initialized. See Part II/5 for more details on the startup instrument.

Legal Global Declarations

global {

ivar a;
ksig b[2],c;
ivar d[outchannels];
ksig e[inchannels];

}

Illegal Global Declarations

global {  // all lines below are illegal

asig a;         // a-rate globals not allowed 
imports ksig c; // imports globals not allowed 
exports ksig c; // exports globals not allowed 
ivar d[0];      // width 0 not allowed

}

Standard Names

Standard names are read-only variables that hold system information. The panel on the right lists the SAOL standard names and the declaration each would have if it were a normal variable.

This book describes most standard names in chapters related to their function. The list on the right panel includes links to the parts of chapters on buses, MIDI control, SAOL instrument control, and MPEG 4 integration that describe the standard names related to these topics.

Two standard names are general purpose in nature, and we explain them now. The ivar standard name k_rate holds the k-rate of the SAOL program, and the ivar standard name s_rate holds the a-rate of the SAOL program.

SAOL programs often compute constant values based on the value of k_rate and s_rate. The sfront distribution includes a library of SAOL utilities, called Slib, that defines a set of useful constants derived from k_rate and s_rate.

Standard Names

Described in this section

ivar k_rate;
ivar s_rate;

For buses: see Part II/5

ivar inchan;
ivar outchan;
asig input[inchannels];
ivar inGroup[inchannels];

For MIDI: see Part III/2

ivar preset;
ivar channel;
ksig MIDIctrl[128];
ksig MIDItouch;
ksig MIDIbend;

For instr control: see Part III/3

ivar dur;
ksig itime;
ksig released;
ivar time;
ksig cpuload;

For AudioBIFS: see Sfront manual

imports ksig position[3];
ksig direction[3];
ksig listenerPosition[3];
ksig listenerDirection[3];
ksig minFront;
ksig maxFront;
ksig minBack;
ksig maxBack;
imports exports ksig params[128];

Global Parameters

Global parameters may be used to change system constants in SAOL. Global parameters are set in the global block, using the syntax shown in the right panel. Each global parameter may only be set once.

Unlike instr parameters, global parameters may not be used as variables in SAOL expressions. Use the standard name related to the global parameter instead.

There are five global parameters. The parameters inchannels and outchannels concern the special buses input_bus and output_bus and are explained in Part II/5. The parameter interp concerns wavetables and is explained in Part II/4.

The last two global parameters, srate and krate, set the a-rate and k-rate of the system. The srate parameter may be set to an integer in the range 4000 Hz to 96000 Hz.

The krate parameter may be set to an integer in the range 1 Hz to the audio sampling rate.

The k-rate of a SAOL program defaults to 100 Hz. The a-rate of a SAOL program defaults to 32,000 Hz. (but see this exception if processing external audio input).

If krate does not evenly divide into srate, the k-rate of the SAOL program is the first integer larger than krate which does evenly divide srate.

Syntax

globals {

srate 48000; // note: no = 

}

The Global Parameters

Described in this section

srate
krate

For buses: see Part II/5

inchannel
outchannel

For wavetables: see Part II/4

interp

Next section: Part II/2: Expressions and Statements

Instr Variables

Signal variable declarations in SAOL instrs occur after the open curly-brace of the instr preamble. The first SAOL statement in the instr marks the end of the variable declaration section: declarations and statements cannot be interspersed.

Each declared variable and parameter in an instr must have a unique name. Signal variables hold 32-bit floating point values and are initialized to zero.

Scalars

The simplest variable declaration consists of a rate identifier (ivar for i-rate, ksig for k-rate, or asig for a-rate), a name, and a semicolon (see right panel for examples). These variables are scalars, and have width 1. Multiple variables can be declared on the same line, separated by commas.

Legal Declarations

instr foo () {

ivar a;
ksig b,c;
asig d;

b = a;

}

Illegal Declarations

instr foo () {

ivar a;  // legal
asig d;  // legal 

a = 1;

ksig b; // illegal: must precede a = 1;

b = a;

}

Arrays

Array declarations build on this syntax, by adding an open bracket, a width specifier and a closed bracket. Arrays and scalars may share the same declaration line. The width specifier, that sets the width of the array, is usually numeric (an integer greater than zero).

Alternatively, the keyword inchannels or outchannels may serve as a width specifier. In an instr, arrays declared with the width specifier inchannels take the width of the audio input presented to the instrument. Arrays declared with the width specifier outchannels take the width of the audio data written by output statements in the instr. In Part II/5 we describe how to determine these widths for an instr.

Legal Array Declarations

ivar a[3];
ksig b,c[2];
asig d[inchannels],f[outchannels];

Illegal Array Declarations

ivar a[0];   // illegal: must be >= 1
ksig c[2.0]; // illegal: must be integer

Imports and Exports

Both scalar and array global variables may be imported or exported into an instr. The rate and width of the global and instr variables must be the same. Since globals may not be asig, neither may imported or exported instr declarations. See the right panel for examples.

If an instr variable is declared with imports, then at the start of the i-pass (for ivars) or at the start of each k-pass (for ksigs), the value of the global variable is copied into the instr variable.

If an instr variable is declared with exports, then at the end of the i-pass following instr instantiation (for ivars) or at the end of each k-pass (for ksigs), the final value of the instr variable is copied into the global variable.

If both imports and exports are used, both behaviors described above happen.

Legal imports and exports

global {
ivar a, c;
ksig b[3];
}

instr example () {

imports ivar a;
exports ivar c;
imports exports ksig b[3];

}

Illegal imports and exports

global {
ivar a;
}

instr example () {

imports ivar a[2]; // illegal: size mismatch
imports ksig a;    // illegal: rate mismatch
}

Imports for SASL

If an instr signal variable is declared using the imports keyword, but no global variable of the same name exists in the global block, the import semantics described in the previous section do not apply.

Instead, the imports keyword signifies that a variable may be targeted by a SASL labelled control command. This SASL command writes a new value into a ksig variable of an instr instance at the start of a k-pass.

Only scalar ksig variables may be used in this construction, and only imports may be used in the declaration, not exports.

An example in the tutorial in Part I shows this usage of the imports keyword in detail. A later section of this book explains SASL control statements in detail.

Imports for SASL:

See tutorial example.

Global Variables

Global signal variables are scalar or array variables declared in a global block of a SAOL program. Global signal variables may be declared ivar or ksig but not asig. The imports and exports keywords may not be used with global variables. Apart from these differences, global declarations share the same syntax as instr declarations.

Global variable names must be unique among all the global variables.

Array declarations may use the keywords inchannels or outchannels as width specifiers. For global arrays, these keywords indicate that the array should take the same width as the the input_bus or output_bus, respectively. These system buses are dedicated to external audio input and output, and are described in detail in Part II/5.

Distributed Global Blocks

The MP4-SA standard states that only one global block may exist in a SAOL program. This restriction makes it difficult to develop modular SAOL libraries.

Sfront relaxes this rule, and permits many global blocks in a SAOL program. To create MP4 files that comply with the standard, sfront collapses all global blocks into a single large global block when encoding .mp4 files.

startup

Global variables hold 32-bit floating-point numbers initialized to zero. To initialize global variable to non-zero values, define an instr named startup and assign initialization values to the global variables in its code block (using imports and exports to access the global variables).

This method works because the SAOL instr execution rules ensure that if the instr startup is defined, it is instanced and run at i-rate as part of the start up sequence of a SAOL program, before the first k-cycle begins.

In addition, by default the startup instrument executes first in each execution cycle, so that k-rate global variables may also be initialized. See Part II/5 for more details on the startup instrument.

Legal Global Declarations

global {

ivar a;
ksig b[2],c;
ivar d[outchannels];
ksig e[inchannels];

}

Illegal Global Declarations

global {  // all lines below are illegal

asig a;         // a-rate globals not allowed 
imports ksig c; // imports globals not allowed 
exports ksig c; // exports globals not allowed 
ivar d[0];      // width 0 not allowed

}