Subcanvas Param Get

Overview

Reads back parameters from Subcanvas modules

Discussion

This module is a version of the Param Get that is able to read variables inside of a Subcanvas. The name of the Subcanvas module and the name of the internal variable are specified as module arguments. The module reads the variable in the real-time thread and writes the value to the output wire. You can optionally call the module's Get function.

The variable to read is specified in mod.var format. Both scalar and array variables can be read.

The modules uses information from the Subcanvas's AWC file to identify which variables are available to control. The AWC file contains variable names, data types, range information, and array sizes.

There is also an errorStatus variable that will be set to a negative value if an error has been encountered. errorStatus is included in the module inspector. Common errorStatus values are:

• 0 (E_SUCCESS): No error encountered.

• -26 (E_NO_LAYOUTS): The Subcanvas module does not have a valid layout running (e.g. loadNow variable is set to ‘Empty’).

• -83 (E_CLASS_NOT_SUPPORTED): The objectHandle points to a module of an unexpected classId.

For other values of errorStatus, see Bin\Assets\module\include\Errors.h for details.

Arguments

subCanvasName

Points to the Subcanvas module that the target module is in. This can be the path relative to the Subcanvas Param Get module, where '\' is used to go up a level in hierarchy, or it can be the alias name if the Subcanvas module has an objectAlias defined.

modVar

The variable to read is specified in mod.var format. The variable is specified as modName.variableName, where modName is the name of the target module as listed in the AWC file associated with the Subcanvas pointed to by subCanvasName. This name will either be the full hierarchical name of the target module, or the alias if it has an objectAlias assigned.

To read to a scalar, use modName.variableName directly. To read an array value, use modName.variableName[offset]. This module only allows you to read one value in an array, and offset (zero-indexed) must be < size of the array. If you need to read multiple array values, use the Subcanvas Array Get module.

sampleRate

The sampleRate argument specifies the sample rate for the output wire. If sampleRate is empty, then the output wire sample rate is inherited from the containing subsystem.

executionOrder

The executionOrder argument enforces the order of processing of the Subcanvas Param Get module relative to the target Subcanvas module. After means that the Subcanvas Param Get module will execute after the target Subcanvas module, and Before means that it will execute before the target Subcanvas module. The default is Undefined, which means that no execution order is enforced.

Note that this argument only functions for the Classic build engine type (see here for more information, including how to accomplish this for Hierarchical builds: Preferences and Layout | Build-Engine ).

Variables

getBehavior

The read behavior of the module is specified on the inspector in the 'Get Behavior' droplist. The target variable is read on every pump.

The options for getBehavior are as follows:

• AlwaysNoGet (0) – Always reads the value and never calls the target module's Get function.

• AlwaysDeferredGet (1) – Always reads the value and calls the target module’s Get() function from the deferred thread. The Get function will then update variables for a future read.

• AlwaysInstantGet (2) - The module's Get function is always called from the real-time thread and then the value is read. This can lead to an increase in the CPU load.

Module Get functions are used to update module variables that need adjustments to be properly observable. Few modules have Get() functions, thus the default option is ”AlwaysNoGet”.

Module Pack

Advanced

ClassID

classID = 1450

Type Definition

typedef struct _ModuleSubcanvasParamGet
{
    ModuleInstanceDescriptor instance;            // Common Audio Weaver module instance structure
    INT32 getBehavior;                            // Controls the get behavior of the module
    INT32 errorStatus;                            // Shows the current status of the module. 0 means no error. See module docs for details
    UINT32 objectHandle;                          // Integer control handle of the internal module to control
    UINT32 targetClassId;                         // Class id of the target module, used for validating access of object
    UINT32 arrayOffset;                           // When getting array values, this is the offset to write into from the start of the array
    UINT32 mask;                                  // Mask used when calling the get function
    INT32 isArray;                                // Is value to be read an array element
    void * subCanvasPtr;                          // Points to the Subcanvas module to control
} ModuleSubcanvasParamGetClass; 

Variables

Properties

Pins

Output Pins

Matlab Usage

function M = subcanvas_param_get_module(NAME, SUBCANVAS_NAME, MODVAR, SAMPLE_RATE, EXECUTION_ORDER)
% M = subcanvas_param_get_module(NAME, SUBCANVAS_NAME, MODVAR, SAMPLE_RATE, EXECUTION_ORDER)
% ParamGet module which works with the Subcanvas module.  This module reads
% internal variables from within the Subcanvas.  It works with scalar and array
% variables and gets a single value.  Arguments:
%   NAME - name of the module.
%   SUBCANVAS_NAME - name of the Subcanvas module that it is paired with.
%   MODVAR -   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'.  You can specify individual array values
%              as 'MOD.VAR[n]'.
%   SAMPLE_RATE - sample rate of the output pin, in Hz.  If this is empty, then
%               the sample rate is the block rate of the first input pin at this
%               level of hierarchy.
%   EXECUTION_ORDER - Determines when the ParamGet 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 ParamGet to execute before the module it
%                            is controlling.
%                  'after' - forces ParamGet 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.
%
% The information for the data type and array size is taken from the JSON file
% for the Subcanvas module.