The MP4-SA Book: Part IV/4: User-Defined Opcodes
Description: User-defined opcodes in the SAOL language of MPEG 4 Structured Audio.
Keywords: MP4-SA, opcodes, user-defined opcodes, user, user defined opcodes, return, polymorphic opcodes, xsig, iopcode, kopcode, aopcode, opcode

### From The MPEG-4 Structured Audio Book by John Lazzaro and John Wawrzynek.

# 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. | ## Language Elements: aopcode iopcode kopcode opcode return xsig

## 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. 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. 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. 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: A fixed-rate opcode may not have a formal parameter with a rate faster than the opcode rate, and may not have polymorphic parameters. 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: 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. 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: 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. 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. 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. The width of the formal parameter must match the width of the associated argument. 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. 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. 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. The rate of a rate-polymorphic opcode is the fastest of: The fixed-rate formal parameters of the opcode definition, and The arguments to the opcode call, and The fastest guard expression of an if, if-else, or while statement guarding the call, and 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 |

Copyright 1999 John Lazzaro and John Wawrzynek.