...
| Code Block |
|---|
name: 'targetLevel'
hierarchyName: 'agc.core.targetLevel'
value: -20
size: [1 1]
type: 'float'
isComplex: 0
range: [-50 50 0.1000]
isVolatile: 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'
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 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 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.
Note: The function classid_lookup.m can be used to determine if a class name is already in use. Refer to Specifying Class IDs for more information.
After the module class is created, set the particular name of the module:
...
for each input, output, or scratch pin you want to add.
...
The arguments are as follows:
...
Adds a single scalar variable to an @awe_module or @awe_subsystem object and returns the updated object. Arguments
...
The arguments are as follows:
M — @awe_module or @awe_subsystem object to which to add the variable
VAR — @awe_variable object returned by
awe_variable.m
...
Adds an input argument descriptor to the module/subsystem object. These are not accessible via the . operator, but are kept in the constructorArguments container. Arguments are variables used at construction time for operations such as: sizing internal arrays based on something other than channels / blockSize and disabling or enabling additional pins. For constructor arguments to be available in the structure they should be tracked by an additional ‘const’ module variable added using add_variable().
...
The arguments are as follows:
M — @awe_module or @awe_subsystem object to which to add the argument
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.
...
Adds an array to an @awe_module or @awe_subsystem object and returns the updated object. Arguments
...
The arguments are as follows:
M — @awe_module or @awe_subsystem object to which to add the array
VAR — @awe_variable object.
...
Adds a pointer variable to an Audio Weaver module. A pointer variable is used to point to a data structure which is defined outside of the module itself. Use pointers, for example, to point a data structure used by a third party algorithm. When you add a pointer to an Audio Weaver module, the pointer variable is added to the module’s instance structure but memory for it is not allocated. You must separately allocate memory for the pointer using custom code in the module’s constructor function.
...
ArgumentsThe arguments are as follows:
M - @awe_module object to which to add the pointer variable.
NAME — name of the pointer variable. Must be a valid C variable name.
CTYPE — type definition which will be used by the variable. For example, ‘void *’ or ‘SparseItem *’. This string is used directly as the pointer type in the instance structure.
USAGE — how the variable is used. As before, this can be ‘parameter’, ‘state’, ‘derived’, or ‘const’.
DESCRIPTION — optional short description string.
ISHIDDEN — optional Boolean which hides the variable from standard Matlab MATLAB usage.
...
Note: you will not be able to examine the contents of pointer variables from MatlabMATLAB, since Matlab is unaware of the data type of the variable.
...
Modules are added to subsystems one at a time using the function
add_module(SYS, MOD)
The first argument is the subsystem while the second argument is the module (or subsystem) to add. Once a module is added to a subsystem, it appears as a field within the object SYS. The name of the field is determined by the module's name. Modules can be added to subsystems in any order. The run-time execution order is determined by the routing algorithm.
As modules are added to the subsystem, they are appended to the .module field. You can use standard MATLAB programming syntax to access this information. For example, to determine the number of modules in a subsystem:
count=length(SYS.module);
Or, to print out the names of all of the modules in a subsystem:
| Code Block |
|---|
for i=1:length(SYS.module) |
...
fprintf(1, '%s\n', SYS.module{i}.name); |
...
end |
connect.m
Creates a connection between two pins in a subsystem. The general form is:
connect(SYS, SRCPIN, DSTPIN);
where SRCPIN and DSTPIN specify the source and destination pins, respectively. Pins are specified as strings to the connect.m command using the syntax:
moduleName.pinName
Consider the system shown below and contained within multiplexor_example.m.
...
To connect the output of the sine generator1 to the second input of the multiplexor, use the command:
connect(SYS, 'sine1.out', 'mult.in2');
The module names "sine1" and "mult" are obvious because they were specified when the modules were created. The pins names may not be obvious since they appear within the module's constructor function. To determine the names of a module's pins, you can either utilize the detailed help function awe_help (recommended)
awe_help multiplexor_smoothed_module
...
or have MATLAB draw the module
| Code Block |
|---|
M=multiplexor_smoothed_module('foo'); |
...
draw(M) |
...
Several short cuts shortcuts exists to simplify use of the connect.m command.:
If the module has only a single input or output pin, then you need only specify the module name; the pin name is assumed. Since the sine wave generator module in the multiplexor example has only a single output pin, the example above reduces to:
connect(SYS, 'sine1', 'mult.in2');Inputs and outputs to the subsystem are specified by the empty string. Thus,
connect(SYS, '', 'mult.in1');
connects the input of the system to the first input of the multiplexor. Similarly,connect(SYS, 'mult', '');
connects the output of the multiplexor to the output of the system.By default, the connect command performs rudimentary error checking. The function verifies that the named modules and pins exist within the subsystem. At build time, however, exhaustive checking of all connections is done. Audio Weaver verifies that all connections are made to compatible input and output pins (using the range information within the pin type). You can enable this exhaustive checking when a connection is made by supplying a 4th argument:
connect(SYS, 'mult', '', 1)
This is useful when debugging wiring failures that are revealed at build time.
Output pins are permitted to fan out to an arbitrary number of input pins. Input pins, however, can only have a single connection.
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](Audio Weaver is guessing at the type of pin that needs to be connected). 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
. This is always correct since the pin type is inherited from the module's output pin.
| Code Block |
|---|
sink_module.m Floating-point data sink_fract32_module.m Fixed-point data |
...
= sink_int_module.m Integer 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]. This is required since each output of the subsystem is stored in a separate buffer.
get_variable.m and set_variable.m
| Anchor | ||||
|---|---|---|---|---|
|
Extract and assign individual @awe_variable objects within an audio module. This is needed because of the object-oriented nature of the Audio Weaver interface. When accessing a variable "var" within a module "M", as in:
M.var
Audio Weaver returns the value of the variable, not the variable object itself. If you wish to gain access to the actual variable object, use the call:
V=get_variable(M, NAME)
where:
M — the @awe_module object.
NAME — a string specifying the name of the variable.
The function returns an @awe_variable object. For example, the following code gets the underlying @awe_variable object for the "gain" variable of a smoothed scaler module:
| Code Block |
|---|
M=scaler_smoothed_module('scaler'); |
...
V=get_variable(M, 'gain'); |
Similary, the set_variable.m command can be used to replace an existing variable with a given @awe_variable object. "Replace" is used because the variable must already exist within the audio module. The syntax for this command is:
M=set_variable(M, NAME, VAR)
where:
M — the @awe_module object.
NAME — a string specifying the name of the variable.
VAR - @awe_variable object.
The get_variable.m and set_variable.m functions are rarely used in practice. You can always access the internal fields of a @awe_variable object even when it is part of an audio module. For example, to access the "range" field of the variable "gain", use:
range=M.gain.range;
Note: get_variable.m and set_variable.m also apply to @awe_subsystem objects.
Module for AWE Designer
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.
| Code Block |
|---|
M.moduleBrowser.path = 'Examples'; |
...
M.moduleBrowser.image = '../images/E.bmp'; |
...
M.moduleBrowser.searchTags = 'decimation'; |
...
M.shapeInfo.svgImage = '../../images/DownSampler.svg'; |
...
M.shapeInfo.size = [6 6]; |
.path — is the folder name in the AWE Designer browser tree.
.image — is the module browser image file to be used to display the module in AWE Designer browser tree. If no image file is empty, then the default image file will be used by the Designer.
.searchTags — is the string to search in the Designer search filed to find the module.
.svgImage — is the module shape image file to be used by the designer to draw the shape in the layout area when the module is drag and dropped in the layout area. If this field is empty then the default rectangle shape is used by the Designer. If an invalid SVG image is provided, an error will be logged in the Bin/Assets/logs/general.log file. See the Audio Weaver Logging Guide for
...
details.
.size — is the shape size in the Designer layout area.
When the module is generated by executing the make script, for example make_examples.m, the XML file is generated which is used by the AWE Designer. XML file holds the complete information about the module to AWE Designer, like browser image file path, svg image file path for module shape, help document path, module arguments and other settings for AWE Designer. The information in XML file is extracted from the module file from the moduleBrowser and shapeInfo fields. Below is the example XML file of downsampler_example_module.m module.
<designer>
...
| Code Block |
|---|
<designer> <module type='Examples' width='6' height='6'> |
...
<browsername>Downsampler Example</browsername>
<legend></legend>
...
<browsername>Downsampler Example</browsername> <legend></legend> <image>../images/E.bmp</image> |
...
<svgimage>../../images/DownSampler.svg</svgimage> |
...
<targetclasses>ModuleDownsamplerExample</targetclasses> |
...
<datatype>float,fract32,int</datatype> |
...
<searchtags>decimation</searchtags> |
...
<mfile>downsampler_example_module</mfile> |
...
<helpfile>../Doc/DownsamplerExample.html</helpfile> |
...
<examples></examples> |
...
<property propsheet = 'Build Settings' name='allocationPriority' type='int' value='0' min = '0'/> |
...
<property propsheet = 'Build Settings' name='objectID' type='int' value='' min = '1'/> |
...
<property propsheet = 'Build Settings' name='clockDivider' type='int' value='' isValueEditable='0'/> |
...
<property propsheet = 'Build Settings' name='isTunable' type='bool' value='1' min = '0'/> |
...
<property propsheet = 'Variables' name='D' description='Decimation factor. |
...
1 out of every D samples is output' type='int' min='1' max='1024' step='1' isRangeEditable='1' value='2' format='%g' hide='1' isComplex='0'/> |
...
<property propsheet = 'Arguments' name='D' description='Decimation factor' type='int' |
...
value='2' format='%g' /> |
...
<pin name='in' legend='in' usage='input' pos='left' show='0' hide='0' |
...
/> |
...
<pin name='out' legend='out' usage='output' pos='right' show='0' hide='0' |
...
/> |
...
Downsampler (or decimator) - keeps 1 out of every D |
...
samples <shape color='#000000' fill='#ffffff' style='0'> |
...
<poly>
...
<poly> <point x='0' y='0' /> |
...
<point x='0' y='6' /> |
...
<point x='6' y='6' |
...
/> <point x='6' y='0' /> |
...
</poly> |
...
</shape> |
...
</module> |
...
</designer> |
Every module must be instantiated in the make script with complete arguments. Otherwise the arguments related information will not be extracted in to XML file and AWE Designer won’t have access to arguments. For example downsampler_example_module.m require two arguments, NAME and D (decimation factor). It must be instantiated as
MM{end+1}=downsampler_example_module('temp', 2); % 100% instantiation
in the make_example.m script. Here ‘temp’ is the name and 2 is the default decimation factor. Similarly lah_limiter_example_module.m require two arguments, NAME and MAXDELAY. This must be instantiated as
MM{end+1}=lah_limiter_example_module('temp', 5); % 100% instantiation
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.