Getting and Setting Parameters and Arrays

About This Application Note

The Getting and Setting Parameters and Arrays Application Note describes the ParamGet, ParamSet and ArraySet modules, and their respective usage.

Wired control signals (Figure 1) such as the DC Source module, can be used to adjust parameters of modules, but this can also be accomplished with the ParamGet and ParamSet modules.

The ParamGet and ParamSet modules read and write parameters to and from existing modules in an Audio Weaver Designer layout, without the need of a wired connection.

These modules can be found in the ‘Misc’ module folder in Audio Weaver Designer’s module palette on the left-hand side of the Designer window:

Param Set Module

The ParamSet module takes a signal from an input wire and writes the incoming value to an instance variable in another module:

This module is useful for controlling the behavior of other modules in response to control signals or audio signals. This module can set parameters of any type of module, which eliminates the need to use and/or create controllable permutations of each module. The input wire can have any number of channels and any block size. The module only uses the first value in the wire and ignores all others. Internally the module uses two pointers. The first points to the base of the module being controlled. The second pointer points at the variable being written.

To set which module and variable the ParamSet module controls, right click on the ParamSet module while Audio Weaver is in Design Mode, and select ‘View Properties’ in the context menu:

The ParamSet module’s properties menu will appear at the bottom of the Audio Weaver Designer window. Navigate to the ‘Arguments’ tab to assign the desired module and variable you wish to control:

Pictured above in Figure 5, you can see two arguments for the ParamSet module:

• dataType

• modVar

The dataType argument specifies the input pin’s type of data (float, int, fract32).

The modVar argument specifies which module’s variable the ParamSet module will set. The following table describes valid modVar syntax:

Table 1: Mod.Var Syntax

The behavior of how often the instance variable is updated and whether the module’s set function is called, can be set or changed in the ‘Variables’ tab of the ParamSet module via the setBehavior variable:

The setBehavior variable presents 5 behavioral options, but behind the scenes it is a bit field:

• Bit 0 specifies whether the instance variable is always updated (=0) or only if the value on the input wire changes (=1)

• Bit 1 specifies whether the set function of the module being control is called. (=0 do not call set.  =1 call set function).

There are 5 possible bit combinations available:

Table 2: setBehavior Value Definitions

Note that in cases 1 and 3 the set function is triggered by setting the deferred bit in the module instance structure which causes the module's set function to be called as a background task. It may take tens of milliseconds before the set function is actually called and the exact timing can depend upon the CPU loading of the system. If the system is lightly loaded then there is more CPU power available for performing the deferred processing tasks. For case 4, the set function is called immediately in the real-time thread. Use with caution since this increases the CPU load.

An example layout (‘ParamSet_Example.awd’) further explaining the ParamSet module usage can be found in the ‘C:\DSP Concepts\<AWE Designer>\Examples\Module_Usage’ folder of the default Audio Weaver Designer installation path.

Param Get Module

Similar to the ParamSet module but opposite in functionality, the ParamGet module reads the value of a parameter from an existing module and outputs it on a wire for use elsewhere in the system.

Internally the module uses two pointers. The first points to the base of the module to get. The second pointer points at the variable to get within the module instance structure.

The parameter which the ParamGet module outputs is specified in the module properties. To set which module and variable the ParamGet module controls, right click on the ParamGet module while Audio Weaver is in Design Mode, and select ‘View Properties’ in the context menu:

The ParamGet module’s properties menu will appear at the bottom of the Audio Weaver Designer window. Navigate to the ‘Arguments’ tab to assign the desired module and variable you wish to control:

Pictured above in Figure 11, you can see two arguments for the ParamGet module:

• dataType

• modVar

The functionality and syntax for each variable are identical to the ParamSet module, which are described in detail above.

An example layout (‘ParamGet_Example.awd’) further explaining the ParamSet module usage can be found in the ‘C:\DSP Concepts\<AWE Designer>\Examples\Module_Usage’ folder of the default Audio Weaver Designer installation path.

Array Set & Param Set Table Modules

Similar to the ParamSet and ParamGet modules which act on scalar values, Audio Weaver also features modules for setting array values. At the time of this application note writing, Audio Weaver does not feature an ArrayGet module. Typically, if a user needs to know the values of an array, outputting the array to a Sink Module or a .csv satisfies any ArrayGet use cases.

Array Set Module

The ArraySet module can set array values of another module, with data from input wire.

The ArraySet module reads the data coming in from the input wire and reaches into instance structure of the target module to copy the data to the target array. The input array size must be less than or equal to the size of the target variable array size, and the input array updates the target variable starting at the first array element. If the input pin array size is less than the target array size only the number of elements from the input array are changed in the target array.

The array data structure of the target module is pointed to by the argument modVar. The modVar value for the ArraySet module is accessed via the ‘Argument’ tab of the module’s property window, which can be accessed by right clicking on the module and selecting ‘View Properties’ in the context menu, like any Audio Weaver module.

The syntax for the ArraySet module’s modVar argument follows the ParamSet and ParamGet modVar syntax outlined above in Table 1.

Unlike the ParamSet and ParamGet modules, the ArraySet module has an optional control pin that can be enabled or disabled in the ‘Arguments’ tab of the module’s properties. The control pin enables copying the input data to the modVar array when the first value of the control pin data !=0, acting as a type of trigger. If the control pin is not used, then the data is written to the target array on every execution.

Similar to the ParamSet and ParamGet modules, the ArraySet module’s ‘Variables’ tab in the Properties menu, contains an option to set the behavior of the module via the setBehavior variable:

Below is a table describing each of the ArraySet module’s setBehavior values.

Table 3: ArraySet setBehavior Values

Param Set Table Module

The ParamSet Table module is similar to the ArraySet module but offers slightly different features for different use cases. The ParamSet Table module writes the values of one column of a statically defined table to an internal array of another module. A common use case is to update the coefficients of an FIR module based on changing conditions in the system.

Let’s take a look at the ParamSet Table Module’s Properties. In the ‘Variables’ tab of the module’s Properties, we have two variables, index and setBehavior:

The setBehavior values and resultant behavior are identical to the ParamSet module’s, described above in Table 2.

The index variable specifies the current coeff column index of the coeff table defined in the ‘Array: coeff’ tab, to select which column to copy to the target module's array. This variable can be changed here in the ‘Variables’ tab of the module’s Properties and also by the integer value of the input pin.

In the ‘Arguments’ tab, we can see the following fields:

• dataType

• numRows

• numCols

• modVar

The dataType argument specifies the data type of the values in the coeffs array, defined in the module’s ‘Array:coeff’ Properties tab (float, int, fract32).

The numRows variable determines the length of each vector, and the numCols variable determines the number of vectors that can be stored in the internal table. It is the responsibility of the user to ensure that the numRows variable matches the size of the target module's array. If numRows and numCols are all = 1 then the module will assume a scalar value to write.

The modVar argument specifies the target module and array variable that the ParamSet Table module controls. The syntax is identical to the ParamSet syntax defined above in Table 1.

Skipping over the ‘Properties’ and ‘Build’ tabs, we reach the ‘Array: coeff’ tab of the ParamSet Table’s Properties menu:

As described above, this table’s dimensions are specified by the numCols and numRows variables in the ‘Arguments’ tab, and the column holding the array that gets written to the target modVar (specified in the ‘Arguments’ tab) gets set by the ParamSet Table’s input pin AND/OR the index variable specified in the ‘Variables’ tab.

The ParamSet Table module features options to either load a coeff table from a .csv file or save the current table to a .csv file:

Lastly, any time a change is made to the coeff table in the ‘Array: coeff’ tab, Audio Weaver Designer will prompt to either save or discard the changes made to the array:

Figure 22: ParamSet Table Coeff Array Save/Cancel Changes

Modules Controlled by the Get/Set Modules

Any module controlled by one of the get/set modules described in this application note, will visually change and display which module it is controlled by in the Audio Weaver Designer canvas, in text under the module. As seen below in Figure 23, the FIR1 module has a dashed outline instead of a solid border, and the text under the module indicate that it’s coeffs array variable is controlled by the CoeffTable1 module: