ParamSetV2

Overview

Sets parameters in other modules

Discussion

The ParamSet V2 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 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 V2 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 V2 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.

ParamSet V2 also supports using a module's objectAlias rather than hierarchical name in the mod.Var field.

The variable .setBehavior determines how often the instance variable is updated and whether the module's set function is called. There are 5 possibilities:

0 = Always update. Do not call set function after variable update.

1 = Always update. Trigger the target module’s set function through deferred processing.

2 = Update only when input value changes. Do not call set function after variable update.

3 = Update only when input value changes. Trigger the target module’s set function through deferred processing.

4 = Update only when input value changes. Call the target module’s set function immediately after variable update.

Note that when the set function is called through deferred processing, ParamSet V2 calls its own set function through deferred processing. Then, when the set function during the deferred processing, it will call the target module’s set function immediately. This is done in order to allow the set function to be called with the target variable’s mask so that the set function only processes what is required by the change in that variable. This is a change from the original ParamSet module which called the target module’s set function through deferred processing, which always is called to execute as if all the variables have been changed leading to increased CPU usage. Deferred processing means that it’s 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 ParamSet V2 module will 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 in which the modules are added to the layout, which sets the execution order.

The input wire can have any number of channels and be any block size, however 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.

Module Pack

Standard

ClassID

classID = 248

Type Definition

typedef struct _ModuleParamSetV2
{
ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
INT32 setBehavior;                            // Controls the behavior of the module
UINT32 mask;                                  // MASK value when calling the controlled module's set function
void * modPtr;                                // Points to the module to set
void * varPtr;                                // Points to the variable to set within the module instance structure
} ModuleParamSetV2Class;

Variables

Properties

Name	Type	Usage	isHidden	Default Value	Range
setBehavior	int	parameter	0	3	Unrestricted
mask	uint	parameter	1	0	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_v2_module.m 
 M=param_set_v2_module(NAME, DATATYPE, MODVAR, EXECUTIONORDER) 
 Parameter set module.  This module can reach into the instance structure 
 of other modules and set parameter values.  This is the "v2" version of 
 this module and it uses the correct mask value when calling the controlled 
 module's Set() function.  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.