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.
...
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.