This section page describes Audio Weaver's MATLAB functions related to module generation. Audio Weaver makes heavy use of MATLAB’s object oriented features. An object in MATLAB is a data structure with associated functions or methods. Each type of object is referred to as a class, and Audio Weaver uses separate classes to represent variable, modules, and subsystems. The class functions are stored in directories that start with the “@” symbol. Under <AWE>\matlab\ are found 3 class directories:
@awe_variable\
@awe_module\
@awe_subsystem\
It is important to understand how to use and manipulate these classes in order to properly use all of the features of Audio Weaver. We begin by describing each class and then document additional MATLAB commands used for constructing modules.
...
@awe_variable
A variable in Audio Weaver represents a single scalar [1] or array variable on the target processor. Even if you are not developing modules, it is good to understand the @awe_variable object so that you can fully utilize variables.
A variable in Audio Weaver represents a single scalar or array variable on the target processor. A new scalar variable is created by the call:
awe_variable(NAME, TYPE, VALUE, USAGE, DESCRIPTION, ISHIDDEN, ISCOMPLEX)
...
Variables in Audio Weaver have a close correspondence to variables in the C language. The arguments are:
NAME – name of the variable as a string.
TYPE – C type of the variable as a string. For example, ‘int’ or ‘float’.
VALUE – initial value of the variable.
USAGE – a string specifying how the variable is used in Audio Weaver. Possible values are:
‘const’ – the variable is initialized when the module is allocated and does not change thereafter.
‘parameter’ – the variable can be changed at run-time and is exposed as a control.
‘derived' – similar to a parameter, but the value of the variable is computed based on other parameters in the module. Derived variables are not exposed as controls.
‘state’ – the variable is set at run-time by the processing function.
DESCRIPTION – a string describing the function of the variable.
ISHIDDEN – an optional Boolean indicating whether the variable is visible (ISHIDDEN=0) or hidden (ISHIDDEN=1). By default, ISHIDDEN=0.
ISCOMPLEX – an optional Boolean indicating whether the variable is real valued (ISCOMPLEX=0) or complex (ISCOMPLEX=1). By default, ISCOMPLEX=0. Note, Audio Weaver only supports complex valued arrays, not scalars.
...
You typically do not use the The awe_variable.m function is typically not used directly. Rather, the function is automatically called when you add variables to modules or subsystems using the add_variable.m or add_array.m functions documented in Sections 3.6 and 3.7.
Only 32-bit data types are supported. Allowable types are: 'float', 'int', 'uint', 'and 'fract32'.
We now look carefully at one of the variables in the agc_example.m system. At the MATLAB prompt, type:
| Code Block |
|---|
SYS=agc_example; |
...
struct(get_variable(SYS.agc.core, 'targetLevel')) |
The get_variable.m command extracts a single variable from a module and returns the @awe_module object. (If you instead try to access SYS.agc.core.targetLevel you'll only get the value of the variable, not the actual structure.) The MATLAB struct.m command turns an object into a data structure revealing each of its internal fields. You'll see:
name: 'targetLevel'
hierarchyName:
| Code Block |
|---|
name: 'targetLevel' hierarchyName: 'agc.core.targetLevel' |
...
value: -20 |
...
size: [1 1] |
...
type: 'float' |
...
isComplex: |
...
0 range: [-50 50 0.1000] |
...
isVolatile: |
...
usage: 'parameter'
description: 'Target audio level.'
...
0 usage: 'parameter' description: 'Target audio level.' arrayHeap: 'AWE_HEAP_FAST2SLOW' |
...
memorySegment: 'AWE_MOD_FAST_ANY_DATA' |
...
arraySizeConstructor: '' |
...
constructorCode: '' |
...
guiInfo: [1x1 struct] |
...
format: '%g' |
...
units: 'dB'
isLive: 1
isHidden: 0
presets: [1x1 struct]
isArray: 0
targetInfo: [1x1 struct]
isLocked: 1
isPtr: 0
ptrExpr: ''
isRangeEditable: 1
isTuningSymbol: 0
isTextLabel: 1
isPreset: 1
isDisplayed: 1
classVersion: 29341
class: 'awe_variable'
...
units: 'dB'
isLive: 1
isHidden: 0
presets: [1x1 struct]
isArray: 0
targetInfo: [1x1 struct]
isLocked: 1
isPtr: 0
ptrExpr: ''
isRangeEditable: 1
isTuningSymbol: 0
isTextLabel: 1
isPreset: 1
isDisplayed: 1
classVersion: 29341
class: 'awe_variable'
fieldNames: {32x1 cell}
|
...
Many of the fields are set when the variable was added to the module or at build time. Some of them can be set after a module has been built.
name – string indicating the name of the variable. This was set when the variable was added to the module. Not user editable.
hierarchyName – hierarchical location of the variable in the overall system. Initially empty and then set by build.m. Not user editable.
value – current value of the variable. Although it can be read and written by the user, it is easier to access the value simply by referencing
...
SYS.agc.core.targetLevelsize – 1x2 element vector used to represent the size of matrices, [rows columns]. For scalars, this is always [1 1]. Set when the variable was added to the module or by the prebuild function. Not user editable.
type – string specifying the underlying data type of the variable. Allowable values are 'float', 'fract32', 'int', and 'uint'. Set when the variable was added to the module. Not user editable.
isComplex – Boolean indicating whether the variable contains complex data. Set when the variable was added to the module. Only arrays can be complex, not individual scalar variables. Not user editable.
range – a vector or matrix specifying the allowable range of the variable. This is used to validate variable updates and also to draw knobs and sliders. This vector uses the same format as the pin type described in Section 3.4. User editable.
usage – a string specifying how the variable is used in Audio Weaver. Set when the variable was added to the module. Not user editable. Possible values are:
‘const’ – the variable is initialized when the module is allocated and does not change thereafter.
‘parameter’ – the variable can be changed at run-time and is exposed as a control.
‘derived' – similar to a parameter, but the value of the variable is computed based on other parameters in the module. Derived variables are not exposed as controls.
‘state’ – the variable is set at run-time by the processing function.
description - a string describing the purpose or usage of the variable. User editable.
arrayHeap – used to specify array allocation information to the code generator. User editable.
memorySegment - used to specify array allocation information to the code generator. User editable.
arraySizeConstructor - used to specify array allocation information to the code generator. User editable.
constructorCode - specifies variable initialization when a module exists within a subsystem and is used by the code generator. User editable.
guiInfo – structure used to hold GUI related information. Some fields are user settable. Refer to the chapter in the Audio Weaver Matlab API that discusses creating custom inspector interfaces.
format - C formatting string used by when displaying values in the MATLAB output window. Follows the formatting convention of the printf function. User editable.
units - a string containing the underlying units of the variable. For example, ‘dB’ or ‘Hz’. This is used by documentation and on user interface panels. User editable.
isLive – Boolean variable indicating whether the variable is residing on the target (isLive = 1), or if it has not yet been built (isLive=0). This starts out equaling 0 when the module is instantiated and the set to 1 by build.m. Not user editable.
isVolatile – Boolean indicating whether the variable is changed outside of MATLAB and needs to be read from the target each time. Reading of variables from the target only occurs when isLive=1. By default, only 'const' variables have isVolatile set to 0; all others are set to 1. User editable.
isHidden – Boolean indicating whether a variable is hidden. Hidden variables are not shown when a subsystem is displayed in the MATLAB output window. However, hidden variables may still be referenced. User editable.
isPreset – Boolean indicating whether the variable is included in presets. Used by the create_preset.m function. User editable.
isArray – Boolean indicating whether the variable is a scalar or an array. Scalars values occur in the instance data structure. Arrays have pointers in the instance data structure. This field is set when the variable is first instantiated and should not be changed thereafter.
targetInfo – internal data structure used when tuning the variable at run-time. Not user editable.
fieldNames – internal cell array of field names (actually the names of the fields in this data structure). It is used to accelerate references. Not user editable.
isLocked – internal field used to accelerate references. Not user editable.
isPtr – Boolean indicating whether the variable is a pointer of type ptrExpr.
ptrExpr – string specifying the pointer type of the variable.
isRangeEditable – Boolean indicates whether the variable range is editable or not.
isTuningSymbol – Boolean indicates whether the variable is real time tunable or not.
classVersion – internal field indicates the SVN version number.
class – string specifying the underlying object class. This is always 'awe_variable'. Not user editable.
...
The .isHidden field can be used to hide variable that the user typically does not need to know about. For example, allocate a 2nd order Biquad filter:
| Code Block |
|---|
>> M=biquad_module('filter') |
...
filter = Biquad // 2nd order IIR filter |
...
...
b0: 1 // First numerator coefficient |
...
b1: 0 // Second numerator coefficient |
...
b2: 0 // Third numerator coefficient |
...
a1: 0 // Second denominator coefficient |
...
a2: 0 // Third denominator coefficient |
All 5 of the tunable filter coefficients are shown. After the filter is built, state variables are added. You can see them by typing:
| Code Block |
|---|
>> M.state |
...
ans = |
...
0 |
...
0 |
Of course, this assumes that you know that this module has a variable named .state. To show all hidden variables in the MATLAB output window, set
AWE_INFO.displayControl.showHidden=1;
Then, looking at the Biquad filter, the hidden .state variable will be shown as well:
| Code Block |
|---|
filter = Biquad // 2nd order IIR filter |
...
b0: 1 // First numerator coefficient |
...
b1: 0 // Second numerator coefficient |
...
b2: 0 // Third numerator coefficient |
...
a1: 0 // Second denominator coefficient |
...
a2: 0 // Third denominator coefficient |
...
state: 0 |
...
0] |
1.2. @awe_module
This class represents a single primitive audio processing function on the target. A module consists of the following components: a set of names, input and output pins, variables, and functions. All of these items exist in MATLAB and many of them have duals on the target itself.
...
The first argument, CLASSNAME, is string specifying the class of the module. Each module must have a unique class name, and modules on the Server are instantiated by referencing their class name[2]. The second argument, DESCRIPTION, is a short description of the function of the module. The DESCRIPTION string is used when displaying the module or requesting help.
...
● If the module has scalar pin along with pin array, then the scalar pin name must not match the bas name of a pin array.
...
add_variable.m
| Anchor | ||||
|---|---|---|---|---|
|
M=add_variable(M, VAR)
Adds a single scalar variable to an @awe_module or @awe_subsystem object and returns the updated object. Arguments:
...
Note that after a variable is added to a module, it appears as a field within the module’s structure and the name of the field equals the name of the variable. Attributes of an individual variable are referenced using the “.” structure notation. Refer to Section 2.2 to see the correspondence between variables in the MATLAB object and variables in the C type definition.
...
add_argument.m
| Anchor | ||||
|---|---|---|---|---|
|
M = add_argument(M, VAR, varargin)
...
VAR - @awe_variable object that describes the input parameter, OR use the second through N arguments to create the variable as described in the previous section.
...
add_array.m
| Anchor | ||||
|---|---|---|---|---|
|
M=add_array(M, VAR)
Adds an array to an @awe_module or @awe_subsystem object and returns the updated object. Arguments:
...
Audio Weaver is set up to handle several special cases of connections at build time. First, if an input pin has no connections, Audio Weaver inserts a source module and connects it to the unconnected input. Either a source_module.m (float) or source_fract32_module.m is added based on the first input to the system[3]. If a module has an output pin without a connection, Audio Weaver inserts a sink module based on the data type of the unconnected pin[4]
sink_module.m Floating-point data
...
If the subsystem has a direct connection from an input pin to an output pin, then a copier_module is inserted. If a module output fans out to N outputs of the subsystem, then N-1 copier modules are inserted[5].
1.12. get_variable.m and set_variable.m
...
This section focus on the module browser information related to AWE Designer. Every module must initialize the moduleBrowser and shapeInfo structure of the MATLAB module object. Below is the example settings of downsampler_example_module.m module. Refer the section 3.2 for complete information of these structures.
...
Here ‘temp’ is the name and 5 is the default max delay time.
...
[1] Scalar is a mathematical term and refers to a variable containing only a single value. Do not confuse this with a scaler which is a specific type of audio module.
[2] The function classid_lookup.m can be used to determine if a class name is already in use. Refer to Audio Weaver Module Developers Guide for more information.
[3] Audio Weaver is guessing at the type of pin that needs to be connected.
[4] This is always correct since the pin type is inherited from the module's output pin.
[5] This is required since each output of the subsystem is stored in a separate buffer.