Overview

Sets parameters in other modules

Discussion

The ParamSet module takes a signal from an input wire and writes the value to an instance variable in another module. The module is useful for controlling the behavior of other modules in response to control signals or audio signals.

At instantiation time (or in Module Name and Arguments in Audio Weaver Designer), you specify the data type of the input pin and also the variable which will be written. The variable is specified as

Mod.Var

where Mod is the name of the module (in the same level of the hierarchy as the ParamSet module) and Var is the variable name. You can also specify modules that are within subsystems using

Subsystem.Mod.Var.

You can also go up in hierarchy and control modules that are in an upper system. Use a single backslash character to move up one level in the hierarchy. Use multiple backslash characters to traverse multiple levels of hierarchy. Suppose that the ParamSet module is located in:

SYS.Subsystem.ParamSet

and you want to control the variable

SYS.Scaler1.gain

Then set the Mod.Var field to

\Scaler1.gain

And finally, you can also write to individual values in arrays using the syntax

Mod.Var[index]

where index is the zero-based index of the element in the array Var to set.

The variable .setBehavior determines how often the instance variable is updated and whether the module's set function is called. setBehavior 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 possibilities:

0 = Always update. Do not call set function (useful)

1 = Always update. Call set function (not too useful)

2 = Update only when input value changes. Do not call set function (useful)

3 = Update only when input value changes. Call set function (Most useful)

4 = Update only when input value changes. Call set function immediately (not deferred)

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.

The argument executionOrder determines when the param set will actually execute in relation to the module it is controlling.

Undefined = Let the build process decide

Before = Set the parameter before the target module executes

After = Set the parameter after the target module executes

This can be confirmed by generating a .AWS file and looking at the order which the modules are added to the layout, which set the execution order.

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.

Please see the ParamSet example for specific use cases.

Type Definition

typedef struct _ModuleParamSet
{
    ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
    INT32 setBehavior;                            // Controls the behavior of the module
    void * modPtr;                                // Points to the module to set
    void * varPtr;                                // Points to the variable to set within the module instance structure
} ModuleParamSetClass;

Variables

Properties

Name	Type	Usage	isHidden	Default value	Range	Units
setBehavior	int	parameter	0	3	Unrestricted
modPtr	void *	parameter	1		Unrestricted
varPtr	void *	parameter	1		Unrestricted

Pins

Input Pins

Name: in

Description: parameter value

Data type: {float, int, fract32}

Channel range: Unrestricted

Block size range: Unrestricted

Sample rate range: Unrestricted

Complex support: Real

MATLAB Usage

File Name: param_set_module.m

M=param_set_module(NAME, DATATYPE, MODVAR, EXECUTIONORDER)
 Parameter set module.  This module can reach into the instance structure
 of other modules and set parameter values.  Arguments:
    NAME - name of the module.
    DATATYPE - string specifying the data type of the variable and this
               is also used for the data type of the input pin.  Allowable
               values are 'float', 'int', or 'fract32'.
    VARNAME - specifies the module and variable name using the form:
              'MOD.VAR' where MOD is the module name and VAR is the 
              variable name.  You can also specify internal subsystems using
              'SUBSYS.MOD.VAR'.
    EXECUTIONORDER - Determines when the ParamSet module executes relative
              to the module it is controlling.  Allowable values are:
                  'undefined' - the default.  The execution order is set
                                by the routing algorithm and can occur before
                                or after the module it is controlling.
                  'before' - forces ParamSet to execute before the module it
                            is controlling.
                  'after' - forces ParamSet to execute after the module it
                            is controlling.
               When using 'before' and 'after' you could get a build error
               indicating that no more modules can execute or there is a 
               circular dependency.

Documentation Hub [PUBLIC]

(8.D.2.6) ParamSet