Part IV/4: User-Defined Opcodes

Sections

• Introduction.
• Example. Rewrite of tutorial example with user-defined opcodes.
• Opcode Declarations. Parameters and variables.
• Opcode Statement Block. Return statements.
• Opcode Calls. Rate and width calling conventions.

Introduction

In this chapter, we describe how to write opcode definitions and how to call user-defined opcodes.

To introduce opcode definitions, we rewrite one of examples from the tutorial introduction in Part I to use several user-defined opcodes.

We describe how to declare parameters and variables in opcode definitions, and we explain opcode rate and width semantics.

Example

The right panel shows a SAOL program that generates a stereo test tone pair (the fundamental tone in one channel, the first harmonic in the other channel).

The instrument otone generates the audio signal, with the help of the user-defined a-rate opcode update and the user-defined polymorphic opcode coeff.

We begin by examining the otone instrument definition, which has a single parameter freq that sets the frequency of the test tone pair. An i-rate variable a holds the coefficient for the oscillator algorithm, and a-rate arrays s and out hold the oscillator state and instrument output respectively.

Calls to User-defined Opcodes

The code block of the instrument otone has two calls to user-defined opcodes.

In the i-rate part of the code block, the polymorphic user-defined opcode coeff converts a frequency value into the proper coefficient value for the oscillator algorithm. The definition of coeff defines its sole calling parameter as polymorphic.

In Part II/3 we presented a rule for determining the rate of a polymorphic core opcode call. The coeff call in otone also obeys this rule, which in this case indicates that coeff is i-rate because the instrument parameter freq is i-rate.

The a-rate part of the code block begins with an if statement that initializes the oscillator state vector s. An assignment statement calls the user-defined a-rate opcode update that generates the stereo audio output signal. An output statement sends this signal to output_bus to end the code block.

The opcode call to update uses three aspects of SAOL opcodes that are not used by any core opcodes.

1. Opcode parameters may be arrays. The width of the array expression in the opcode call must match the width the array in the opcode header.
2. If an opcode call uses a signal variable as a calling argument, this variable is passed by reference to the opcode, and the opcode may vary its value. In this case, the array s is passed by reference to update, which overwrites its value on each call.
3. Opcodes may return array expressions. In this case, update returns an expression of width 2, that is assigned to the array out.

   Fixed-rate Opcode Definitions

   The definition of the a-rate opcode update follows the instrument definition of otone. The definition begins with the keyword aopcode (indicating that the opcode returns an a-rate value) followed by the name of the opcode and its formal parameters.

   The update opcode has two formal parameters, an a-rate array s and an i-rate scalar a. It also has a declared a-rate variable w.

   Like core opcodes, each syntactic call to a user-defined opcode has a separate set of variables. These variables are initialized to zero during the first opcode call, and maintain their state from call to call.

   The code block of update consists of four a-rate statements. As an a-rate opcode with only a-rate statements, the rate semantics of update are easy to understand: each call to update results in the execution of all statements in the code block.

   Two statements in the code block update the state of the formal parameter s, and so the opcode only makes sense when called with a variable for the first argument (as opposed to an expression).

   The final line of update is the SAOL statement return, that generates the return value for the opcode and hands control back to the caller. In this case, the argument for return is a list of two scalar expressions, and so update returns an expression of width 2.

   A return statement always has the rate of the opcode: in the case of aopcode update, the return statement is a-rate.

   Polymorphic Opcode Definitions

   The definition of the polymorphic opcode coeff completes the program. The keyword opcode starts a polymorphic opcode definitions, and polymorphic formal parameters and signal variables are declared using the keyword xsig.

   The code block for coeff assigns the correct coefficient value to the polymorphic variable rval and then returns that value.

   Note that the assignment expression uses standard name s_rate. Opcodes may access the standard names of the instrument that calls the opcode, directly or indirectly (through a nested opcode call). However, the variables and parameters of the caller are not visible.

   Like most polymorphic opcodes, the formal parameters, variables, and all statements in the coeff opcode are polymorphic. This design approach ensures that all execution semantics of the opcode switch to the actual rate of the opcode call.

   The right panel shows a simple SASL program for driving this program, and includes an Internet link to a WAV file of the audio generated by the program.

osine.saol

global {
  outchannels 2; 
}

//
// instr otone
// plays a sine wave
// and its octave
//
// uses two user-defined
// opcodes, coeff() and
// update()
//

instr otone (freq)    
     
{

  // variable declaration

  ivar a;
  asig init;
  asig s[2], out[2];

  //***************
  // runs at i-rate 
  //***************

  a = coeff(freq);

  //***************
  // runs at a-rate 
  //***************

  if (init == 0)
    {
      init = 1;
      s[0] = 0.5;
    }

  out = update(s,a);

  output(out);

}

// 
// opcode definition
// 
// name: update
// rate: a-rate 
// width: 2
//
// expects to be passed,
// BY REFERENCE, the
// state array for the
// oscillator. opcode 
// updates state array,
// and returns a stereo
// signal, one channel 
// is the fundamental 
// tone, the other is
// the first harmonic
//

aopcode update(asig s[2], 
	       ivar a)

{
  // scales harmonic

  asig w; 

  s[0] = s[0] - a*s[1];
  s[1] = s[1] + a*s[0];

  w = 2.0;

  return(s[1], w*s[1]*s[0]);

}


// 
// opcode definition
// 
// name: coeff
// rate: polymorphic
// width: 1
// 
// 
// parameter hertz is the
// desired frequency of the
// sine wave oscillator. 
// returns the coefficient
// value that produces that
// frequency
//

opcode coeff(xsig hertz)

{
  xsig rval;
  
  rval = 2*sin(3.1415927*hertz/s_rate);
  return(rval);
}

osine.sasl

0.25 otone 4.0 1000
4.50 end

output.wav

[576,044 bytes, on the Web]

Opcode Declarations

In this section, we look at the process of declaring opcode parameters and variables in detail.

Four types of opcodes may be declared: a-rate opcodes, k-rate opcodes, i-rate opcodes, and polymorphic opcodes. The right panel shows a minimal opcode definition for each case.

The opcode keyword is followed by the name of the opcode. Opcode names must be unique, and must follow the naming rules details in Part II/1, with the exception that opcodes may share a name with a local or global variable.

Parameter Declarations

Opcodes may have zero, one, or several formal parameters, using the parameter syntax shown on the right panel. A user-defined opcode has a fixed number of parameters, set by the number of parameters in the parameter list.

A formal parameter may be scalar or array signal variable (declared using ivar, ksig, asig, and the polymorphic xsig keywords) or a wavetable (declared using the keyword table). See right panel for example parameters.

Opcode parameters declarations follow these rules:

1. A fixed-rate opcode may not have a formal parameter with a rate faster than the opcode rate, and may not have polymorphic parameters.
2. The width specifier for an array parameter may be an integer greater than zero, or the keyword inchannels or outchannels.

If the opcode is called from the global block, inchannels and outchannels code the width the input_bus or output_bus. If the opcode is called from an instrument, inchannels and outchannels code the input or output audio port width of the instrument.

Variable Declarations

All variables types that may be declared in the variable block of an instrument definition may also be used in a core opcode definition (see right panel). An opcode may not may not have signal variables with a rate faster than the opcode rate.

Polymorphic opcode signal variables must be polymorphic (declared using the xsig keyword) or a fixed rate no faster than the fastest formal parameter of the opcode. If the opcode only has polymorphic parameters, only xsig and ivar variables may be declared.

Note that imports and exports variables act only to exchange data with global block variables. Instrument variables may not be imported into an opcode, and opcode variables may not serve as targets for SASL control commands.

Like core opcodes, each syntactic opcode call to a user-defined opcode has a separate set of variables. A user-defined opcode may also be called by an oparray call, for applications where state sharing between multiple opcode calls is required.

Variables are initialized during the first opcode call, using the initialization semantics of instrument variables. Variables maintain their state from call to call.

Minimal Opcode Definitions

iopcode name() {} // i-rate
kopcode name() {} // k-rate
aopcode name() {} // a-rate
opcode  name() {} // polymorphic

Sample Parameter Lists

// no parameters

aopcode name() 


// one parameter

kopcode name(ksig x)


// several parameters

iopcode name(table a, ivar b[2])

Variable Declarations

The declaration syntax for the
following instrument variables
are also permitted in the opcode
variable block.


signal variables, including
array signal variables and imports
and/or exports signal variables.
The xsig keyword may be used
in polymorphic opcodes. See left
panel for restrictions.


oparrays constructions.


tables, including imports and/or
exports tables, and tablemaps. Tablemap
definitions may use tables defined as
opcode parameters.

When used in as array or oparray
width specifier: 

  The keyword inchannels
  codes the audio input channel
  width of the calling instrument.
  If called from the global block,
  inchannels codes the width
  of input bus.

  The keyword outchannels
  indcates the width is the number of
  audio output channels of the 
  calling instrument. If called from
  the global block, inchannels
  codes the width of input bus.

Opcode Statement Block

Earlier chapters describe the SAOL language statements that may be used in the statement block of instruments. These statements may also be used in opcodes.

In addition, opcodes may use the return statement, described on the right panel. A return statement runs at the rate of the opcode. The statement generates the return value of the opcode, and cedes control back to the caller.

Statements in fixed-rate opcodes may not be faster than the rate of the opcode. Statements in polymorphic opcodes must be polymorphic, or a fixed rate no faster than the fastest formal parameter of the opcode.

Statement Execution

Statements that have the same rate as the opcode execute every time the opcode statement block runs. Statements that are slower than the opcode rate execute following the rules below:

1. I-rate statements in a k-rate or a-rate opcode execute once, the first time the statement block executes. These i-rate statements execute before any k-rate or a-rate statements run, but after any wavetable generator initializations happen.
2. K-rate statements in an a-rate opcode execute in the first a-pass the statement block executes in an execution cycle, but do not run during subsequent a-passes in the cycle. The k-rate statements execute after any i-rate statements, but before a-rate statements.

After any slower-rate statements execute, the statements that share the rate of the opcode are executed, in order, until a return statement occurs. At that point, the return value is generated, and control flow is ceded to the caller.

If a statement block completes execution without hitting a return statement, the opcode cedes control back to the opcode. In this case, the return value is undefined.

Expressions in Statements

Expressions in statements may use the standard names, except for standard names whose rate is faster than the opcode rate. The standard names take on the value of the calling instrument.

SAOL does not support recursive opcodes, in any form. An opcode definition may not include a call to itself, or a call to another opcode that calls the original opcode, directly or indirectly.

See the right panel for special conditions that apply to certain statements in an opcode definition.

return Syntax Forms

return();
return(expr);
return(expr[,expr, ...]);

return Semantics

A return statement runs at the 
rate of the opcode.

After executing a return statement,
an opcode returns control to the 
caller.

Exprs may not have a rate faster
than the opcode. Expr may be 
scalar or have a width. A null
return statement has scalar width,
and returns an undefined value.

The sum of the widths of all exprs
is the width of the return statement.
All return statements in an opcode
must have the same width. 

If an opcode has no return statements,
it returns an undefined value of scalar
width at the end of statement block
execution.

The return value of an opcode is the
scalar or array expression value made
by concatenating the values of all
the exprs in the return statement, in
order of appearance.

instr in Opcode Definitions

If an instr statement appears in an
opcode definition, the rate of the
statement is the fastest of

-- the fastest expression in the
   statement's argument list.
-- the fastest guarding expression
   in a surrounding if-else or 
   while block.
-- the rate of the opcode 
   definition in which it resides.

extend in Opcode Definitions

If an extend statement appears in an
opcode definition, the rate of the
statement is the fastest of

-- the fastest expression in the
   statement's argument list.
-- the fastest guarding expression
   in a surrounding if-else or 
   while block.
-- the rate of the opcode 
   definition in which it resides.

Opcode Calls

In this section, we describe the process of calling a user-defined opcode. The rules in this section are a super-set of the core opcode rules described in Part II/3.

We begin by updating the five rate semantic rules for core opcodes. The first rate rule is unchanged from the first core opcode rate rule, and describes how an opcode call affects the expression that contains it:

1. To calculate the rate of an expression that includes an opcode call, treat the opcode call like a signal variable that has the rate of the opcode.

The second rule concerns the arguments for fixed-rate parameters, It also covers array formal parameters and calling by reference, two aspects of user-defined opcodes that are not used by core opcodes.

2. Each argument in an opcode call argument list matches up with its associated formal parameter in the opcode definition. For opcodes with a fixed number of parameters, the argument list must have the same number of parameters.
   1. For signal parameters, if the associated argument is an expression, the expression is evaluated, and passed by value. If an associate argument is a variable, an indexed variable, or the writable standard names MIDIctrl or params, it is passed by reference. Expressions are evaluated in the order they appear in the argument list.
   2. The width of the formal parameter must match the width of the associated argument.
   3. If a signal parameter is declared at a fixed rate, the argument must not have a faster rate.

The third rate rule defines how k-rate opcodes execute, it they are used in an a-rate statement. It is unchanged from core opcode rate rule 3.

3. If a k-rate opcode is used in an a-rate statement, it executes the first time the statement runs in the execution cycle, and its return value is stored for future use. For all subsequent opcode calls in the same execution cycle, the stored return value is reused: the opcode does not execute a second time.

The fourth rate rule defines how i-rate opcodes execute, it they are used in an i-rate or k-rate statement. It is unchanged from core opcode rate rule 4.

4. If a i-rate opcode is used in a k-rate or a-rate statement, it executes the first time the statement runs, and its return value is stored for future use. For all subsequent opcode calls during the instrument's lifetime, the stored return value is reused: the opcode does not execute a second time.

The final rule governs the rate of polymorphic opcodes. It is expanded from the core opcode version of polymorphic rate rules, which we restricted to simplify the introductory explanation of opcode semantics.

5. The rate of a rate-polymorphic opcode is the fastest of:
   1. The fixed-rate formal parameters of the opcode definition, and
   2. The arguments to the opcode call, and
   3. The fastest guard expression of an if, if-else, or while statement guarding the call, and
   4. The rate of an opcode enclosing the call.
   If none of these conditions act to set the rate of the opcode, the opcode defaults to k-rate.

Core opcode calls return a scalar value. User-defined opcodes may return an array value, whose width is determined by the width of the return statements in the opcode. The return value of the opcode takes the rate of the opcode.

Each syntactically distinct opcode call has its own set of state variables. The oparray construction, described in an earlier chapter supports applications where state sharing is necessary. User-defined opcodes may be used in oparrays, and follow the rules for opcode calls described above.

Rate Matching Errors

Statements in global

Only i-rate opcodes may be used in 
expressions used in statements in 
the global block

if and if-else

Code block(s) may not contain opcodes 
that are executed slower than the guard
statement.

while

All opcodes in the code block must
run at the rate of the guard
expression.

Summary

This section completes Part IV. of the MPEG 4 Structured Audio Book. In Part V we introduce templates, a SAOL language construct for defining a family of instr definitions.

Appendix A: Part V: Templates