|
|
|
|
The code defining an SPUnit is contained in a special [SPU] section in a source file. The file can itself contain other sections (e.g macro or class source code).
SPU Source Section
[SPU name {arg-list} OUT {out-list}]
// {default argument assignments}
This block of code declares and defines the SPUnit identified by name, and shall be henceforth be referred to as the SPUnit source code. The declaration [SPU name {arg-list} OUT out-list] defines the interface to the outside world (i.e. its name, inputs and outputs). The other statements define the SPUnit elements (the sub-circuits of the SPUnit) and their connection to the arguments, outputs and each other. See below for details.
The signal processing language is not case sensitive (i.e. 'element1' is equivalent to 'ELEMENT1').
[SPU name {arg-list} OUT {out-list}]
SPU
The keyword SPU identifies this section as an SPUnit declaration. This is mandatory
name
The name of the SPUnit. This must be unique in the SPUnit namespace and is mandatory. Note however, that a macro and an SPUnit can have the same name.
arg-list {arg1 ... argN}
The arg-list is a list of all arguments passed to the SPUnit on instantiation (when the SPUnit is used in an S_TOOLS-STx macro file). Each argument is separated from the previous one by a blank space. The arguments provide the SPUnit with parameters. Parameters can be either number constants or strings (e.g. the name of a soundfile or a data file, the name of a wave-item, the id of a shell-item output, the output name of a value- or spu-item etc.). Connections between SPUnits and SPAtoms are established by using the outputs of an SPU item (an instantiated SPUnit) or of a value item as the arguments of another. A list of arguments is optional (i.e. an SPUnit does not necessarily have to act on input data; e.g. signal/data sources like a noise generator).
Within the SPUnit source code, the arguments can only be used in the function statements as part of an expression or in the output assignments as part of the assignment. The use and passing of arguments is subject to similar rules to the S_TOOLS-STx macros:
OUT
The keyword OUT identifies the rest of the line as outputs.
out-list {out1 ... outM}
The out-list declares the names of all the outputs. Each name is separated from the next by a space. The type of data assigned to each output is defined in the output assignments where they are connected to element outputs (see 'output assignment' below).
The names of arguments, outputs and elements must be unique within the SPUnit source code (i.e. you cannot use an argument name for an output name).
Either the argument list or the output list can be empty, but not both.
The use of feedback (i.e. the direct or indirect (through other elements) connection of an element's output with one of its input) is allowed. The following restrictions apply:
a) Feeding back can only occur within an SPUnit. It cannot be used between SPUnits at the macro level. This means that the only candidates for feedback are local elements
b) The SPUnit outputs cannot be used for feedback. This means that the element outputs used in the output statements may not be used in a feedback loop.
All outputs are calculated for SPUnit or SPAtom instances, even if they are not used.
Most SPAtoms calculate and output at every step. The exceptions are those where the output consists of more than one input step (e.g. VMERGE1) or the size of the input is only known after a number of working steps (e.g. Trigger or Logical operators). Important: When using these types of SPAtoms, one must make sure that all SPUnit outputs are calculated in the same step, since otherwise deadlocks can arise when synchronizing with other objects.
argX = valueX
This statement assigns the argument argX a default value (valueX). This value is used if no value is given for this argument on instantiation. The default value must be a number constant or a string (e.g. 5 or 'a string'). Assigning default values is optional. An argument without a default value, however, must be passed. Default values are used in reverse order. If two arguments are passed, where four have been defined, the third and fourth arguments are assigned their default values. The default values must be assigned before the argument is used (e.g. in a function statement).
elementX = typeY
A definition statement defines an SPUnit element (elementX) as a function (SPAtom or SPUnit) of a particular type (typeY). This element is local to this SPUnit (i.e. is not visible outside of the SPUnit). Any SPAtom or SPUnit can be used for typeY. All SPUnits used in the source code must be loaded before instantiating an SPU item. Once an element is defined it can be used in the function statements and output assignments.
elementX [arguments]
The function statements interconnect and 'execute' the elements. The arguments passed to the element are processed within the element and returned to the element's outputs. The element's arguments can be numerical constants, strings, the outputs from other elements, or the SPUnit's input arguments. They must be passed in the same sequence as defined in the element type's declaration. The function statements and output assignments implement the interconnection between SPUnits and SPAtoms. Elements must be defined before they can be used.
An example function statement could look like this:
ToneElem $ampl $freq $phase $nComp $srate
outX = elementY.outputZ
The output assignments determine which element outputs are made available at the SPUnit outputs (to be connected to shell items or used in other SPUnits using this SPUnit as an element). Every SPUnit output must have one output statement. An element output, however, can be assigned to more than one SPUnit output. Elements must be defined before they can be connected to outputs.