| mp4-sa-> the mp4-sa book-> instrument control->in SAOL |
Sections
|
In This ChapterStatements:Standard Names: |
IntroductionIn the previous chapters in Part III, we describe the SASL and MIDI commands that create and control instrument instances. In this chapter, we describe SAOL statements that support instrument control. We describe the SAOL instr statement, that supports dynamic instance creation. An algorithmic score generator may be written directly in SAOL using this statement. We describe several SAOL standard names for status monitoring that are useful for algorithmic score generation. These standard names hold information such as the elapsed time since instantiation, and whether an instrument is scheduled to be terminated before the next k-pass. We describe several SAOL statements that let instances change their status. The turnoff statement lets an instance schedule its termination, while the extend statement lets an instance delay its termination. Finally, we present a chart that shows the complete execution timeline of a SAOL program. The timeline shows the order of events during program startup, as well as the sequencing of events during an orchestra cycle of i-pass, k-pass, and a-pass. |
|
Dynamic InstrumentsThe SAOL instr statement performs dynamic instrument instantiation, so that a parent instrument may spawn copies of a child instrument. This statement supports applications such as sequencers, arpeggiators, and algorithmic composition. The instr statement runs at the i-rate or the k-rate, and may not be used in the global block. The right panel shows the syntax for the SAOL instr statement. The statement syntax begins with the keyword instr, followed by the name of the child instrument to instantiate. The parameters are i-rate or k-rate scalar expressions that control the instantiation process. All expressions evaluate to constant values before the child instrument spawns. The dly and dur parameters control the starting time and duration for the new instance. The remaining parameters (p1, p2 ...) are the initial values for the instrument parameters of the new instance. The number of p parameters must match the number of instrument parameters in the new instance. dly and durThe dur parameter specifies how long (in scorebeats) the instance should execute before terminating. If dur has a value of -1, the instance runs indefinitely. The dly parameter specifies the length of time (in scorebeats) to delay the instantiation of the new instrument. If the dly parameter has a value less than the k-period (1/k_rate) the instrument is created as soon as the instr statement executes. The i-pass of the new instance is run immediately, and the following rules hold for the first k-pass and a-pass of the new instance:
If the dly parameter of the instr statement has a value greater than or equal to the k-period, the new instance is not created immediately. Instead, a start time (in scorebeats) is computed for the new instance, by adding the dly parameter to the current score time. The instance is created when the score time exceeds this start time. Rate SemanticsThe instr statement may be an i-rate or a k-rate statement. It is an i-rate statement unless one of these conditions hold, in which case it runs at k-rate:
The right panel shows examples of the rate semantics of the instr statement. |
Instr Statement
instr name(dly, dur [, p1, p2 ...]);
name: name of the instrument
to instantiate
dly : delay time, in scorebeats,
before instantiation.
dur : duration (in scorebeats) of
instance execution. a
value of -1 codes indefinite
execution.
p1, : values for instrument
p2, : parameters to use for
... : instantiation.
Rate Semantics
instr spawn(num) {}
instr mom() {
ivar i1, i2;
ksig k1, k2;
asig a;
// runs at i-rate
instr spawn(0, i1, i2);
// runs at k-rate
instr spawn(0, i1, k2);
// instr runs at k-rate
if (k1 > k2)
{
k1 = k1 - 1;
instr spawn(0, i1, i2);
}
// guard is a-rate
// breaks rule 2
if (a > 0)
{
a = a - 1;
instr spawn(0, i1, i2);
}
// instr is i-rate
// if is k-rate
// breaks if rule 1
if (i1 > i2)
{
k1 = k1 - 1;
instr spawn(0, i1, i2);
}
}
|
Instrument StatusFive SAOL standard names let an instance monitor its execution status. The right panel lists the full semantics for these standard names. These standard names work in instances generated using any MP4-SA technique: SASL instr lines, SAOL instr and send statements, and MIDI note-on commands.
time and itimeThe time standard name holds the creation time for the instance, measured in seconds. The itime standard name is the elapsed time since the instance was created. See the right panel for full semantics. These two names support algorithmic scores, by letting an instance track simulation time and dynamically create other instances at the appropriate times. durThe expected duration of the instance, in seconds. An indefinite duration is indicated by -1. Although this standard name is an ivar. its value changes during the life of the instance, as explained on the right panel. releasedThis standard name normally has a value of zero. If the instance is slated to be terminated at the end of the next series of a-passes, released takes on the value 1. The released standard name is often used in conjunction with the extend statement (covered later in this chapter) to add a release phase to an instance created with a definite duration. cpuloadThis standard name is intended for applications where real-time decoding is needed, such as streaming audio to a D/A converter. It tracks what percentage of system resources are currently being used, scaled to the amount of resources needed to maintain real-time operation. See the right panel for full semantics. |
ivar time;The time of instantiation for the instance. In seconds, not scorebeats. Zero seconds is start of simulation. ksig itime;The elapsed time since the instance was created. In seconds, not scorebeats. Zero seconds is the first k-pass. Note that (itime + time) is always the current absolute time. ivar dur;The intended duration (in seconds, not scorebeats) of the instrument, as set by the duration parameter in the SAOL instr statement or SASL instr command. MIDI and send instances always set dur to -1. SAOL and SASL instr commands may also set dur to -1. A -1 indicates indefinite duration. Although it is an ivar, the value changes to reflect tempo changes and the extend statement. ksig released;Set to 1 if the instrument is scheduled for termination after the last a-pass of the current cycle. Otherwise set to 0. ksig cpuload;Measures the load on the CPU that this instance in running on most often. A value of 0 indicates an idle CPU. A value of 1 indicates that the edge of real-time performance has been reached. Temporal dynamics of cpuload are decoder dependent. |
The Extend StatementAn instance may delay its termination by executing the extend statement. This statement is often run in response to the setting of the released standard name. The right panel shows the syntax for the extend statement. The statement has a single parameter delay, an i-rate or k-rate signed expression for the amount of time to extend or reduce the instance (in seconds, not scorebeats). If an instance has a scheduled termination time, executing the extend statement adds the value of delay to that termination time. If the new termination time is less than or equal to the current simulation time, the extend acts like the turnoff statement (described in the next section). If an instance has an indefinite termination time (i.e. a duration of -1) executing the extend statement sets the new termination time to be the current simulation time plus the value of delay. If delay is less than or equal to zero, the extend acts like the turnoff statement. The dur standard name is updated to reflect the execution of the extend statement. The extend statement may be an i-rate or a k-rate statement. It is an i-rate statement unless one of these conditions hold, in which case it runs at k-rate:
The extend statement may not be used in an instance created by a send statement that uses the output_bus. |
Statement Syntaxextend(delay); Example
instr lengthen() {
ksig done;
if (!done && released)
{
// runs at k-rate
extend(0.5);
done = 1;
}
}
|
The Turnoff StatementAn instance may force its own termination by executing the turnoff statement. The right panel shows the syntax of this k-rate statement. The turnoff statement is particularly useful for instances that are not scheduled for termination automatically, such as instances created with the SASL instr command and the SAOL instr statement with a duration of -1. If the turnoff statement executes during a k-pass, it schedules the instance to be terminated at the end of the following (not the current) orchestra cycle. During the next (and "final") k-pass, the released standard name has a value of 1. An extend statement execution during this k-pass would delay instance termination. The turnoff statement may not be used in an instance created by a send statement that uses the output_bus. |
Statement Syntaxturnoff; statement is k-rate Example
instr random_duration() {
// instance lasts at
// least 500 ms. and
// at most 2.5 sec
if (!released &&
(itime - 1.5 > krand(1)))
{
turnoff;
}
}
|
Decoder Execution OrderWe conclude this chapter with a table showing the order of execution of a SAOL program, shown on the right panel. The first part of the table covers the initialization of the simulation done at the start of execution. The second part of the table covers a single orchestra cycle. Orchestra cycles are continued indefinitely until the end time of the simulation is reached (set by the SASL endtime command). The third part of the table covers instance creation. The fourth part of the table covers the execution of an i-pass, k-pass, or a-pass of an instance. Links in this table refers to section of the book that explains the operation in more detail. This chapter completes Part III of the book. In Part IV, we take a comprehensive look at opcodes in SAOL. Next: Part IV: Opcodes |
I. Initial Execution Order
II. Orchestra Cycle Execution Order
III. Instance Creation Execution Order
IV. [I/A/K]-Pass Execution Order
|
| mp4-sa-> the mp4-sa book-> instrument control->in SAOL |