This 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>\MATLABmatlab\ are 3 class directories:
...
| 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.
...
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 usage.
...
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.
| Code Block |
|---|
<designer> |
...
<module type='Examples' width='6' height='6'> |
...
<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.