...

• MM — cell array of audio module structures.

• DIR — base directory in which the generated files should be placed.  Files are written here and in several other subdirectories.

• LIBNAME — string specifying the name of the library.  For example, 'Advanced'.

• USESDLLS — structure specifying other module libraries that the newly built library depends upon.  A library has a dependencies when it internally utilizes a module contained in another library.  By default, USESDLLS=[] and the library is independent of others.

• GENDOC — integer indicating whether module documentation should be generated.  By default, GENDOC=0 and no documentation is generated.  If GENDOC=1, then a single document is created for the entire module library.  If GENDOC=2, then a separate document is created for each audio module.

...

Let DIR be the base directory for the audio module library and let 'Examples' be the name of the library.  awe_generate_library.m creates the following files and folders:

• <DIR>\Examples.h — Header file containing extern definitions for each module class object.  It also has macros defining the entire list of modules and all dependencies.

• <DIR>\Examples.sch — Overall schema file for the library.

• <DIR>\ExamplesSchema.cpp — Compiled schema file.

• 📁 <DIR>\Doc — Location of generated documentation

• 📁 <DIR>\Include — Location of generated module include files

• 📁 <DIR>\matlab — Location of the module m-files.  This also contains the master library make script.

• 📁 <DIR>\matlab\code — Suggested location for the inner code pieces.

• 📁 <DIR>\matlab\process — Suggested location of the MATLAB versions of the processing functions.

• 📁 <DIR>\matlab\test — Suggested location of MATLAB test scripts which validate the operation of the modules.

• 📁 <DIR>\Source – Location of the generated module source files.

• 📁 <DIR>\xml – Module XML file for AWE Designer, explained in section 3.12 get_variable.m and set_variable.m .

SchemaBuilder.exe

You'll notice this executable within the Audio Weaver Bin directory.  This executable compiles the schema information.  That is, it takes a .sch file and compiles into a .cpp file.  The .cpp file is then included in the project for building the module DLL.  SchemaBuilder.exe is automatically called by awe_generate_library.m and there is no need to call it separately.

...

The command adds the directory

• 📁 <DIR>\matlab

to the MATLAB search path; this directory has to exist.  It then optionally adds

• 📁 <DIR>\matlab\test

• 📁 <DIR>\matlab\process

if these directories exist.  In addition, the function modifies the global variable

...

For each directory, the file classids.csv is opened and examined.  The function classid_lookup.m uses internal caching to speed up the search process.

...

The ordering enforces that all scalar variables, which are initialized by the base module constructor function, are located at the start of the instance structure.  Refer to Section 4.4.1 Module Function Details for additional detailsinformation.

Overwriting Existing Source Files

...

SUBSTITUTION can be either a single string or a cell array of strings for multi-line replacements.  If you call awe_addcodemarker.m and an IDENTIFIER of the specified name already exists, then the new SUBSTITUTION string is appended as another line.  For example, the following entry located near the top of awe_module_template.c file is used to specify include files:

...

In many cases, the SUBSTITUTION string contains many lines and it is unwieldy to represent in MATLAB.  Instead, it is easier to copy the SUBSTITUTION text from another file.  If the SUBSTITUTION string has the form "Insert:filename.txt" then the text will be copied from filename.txt.  filename.txt is referenced relative to the location of the module's m-file.  You can specify subdirectories as well.  For example:

awe_addcodemarker(M, 'processFunction', ...

...

            'Insert:InnerPeakHold_Process.c');

inserts the file InnerPeakHold_Process.c located in the subdirectory "Inner".

awe_lookupcodemarker.m

The MATLAB function

STR=awe_lookupcodemarker(M, IDENTIFIER)

returns the contents of a code marker.  If IDENTIFIER is not defined, then the function returns an empty string.  The returned value STR is either a string, for simple replacements, or a cell array in the case of multi-line replacements.

awe_deletecodemarker.m

M=awe_deletecodemarker(M, IDENTIFIER)

Deletes the code marker named IDENTIFIER.

M=awe_deletecodemarker(M)

Deletes all code markers associated with a module or subsystem.

...

The template files also contain their own preprocessor directives.  These directives are similar to those used by the C preprocessor but are handled by the template substitution function.  The directives are identified by ## and only a few variations are supported.

##if 1

...

… This code will appear in the output file …

...

##endif

##if 0

… This code will NOT appear in the output file …

##endif

##if 0
… This code will NOT appear in the output file …
##endif

When the argument to ##if is 1, then the text between the ##if ##if and ##endif will appear in the generated file.  Otherwise, the text will not appear.  You can also use an identifier with an ##if statement as in

##if $myVariable$

...

Optional text

...

##endif

If you set

awe_addcodemarker(M, 'myVariable', '1')

then the optional text will appear in the generated file.  Note that $myVariable$ is being set to the string '1' not to the numeric value 1.  The template preprocessor directive also supports an else clause

##if $combineSourceFiles$

...

#include "$combinedIncludeName$"

...

##else

...

#include "$baseHFileName$"

...

##endif

Frequently Defined Code Markers

...

Allows you to specify a bypass function by name.  This is typically used in conjunction with one of the predefined bypass functions listed in Section 4.4.5.  For Bypass Function. For example,

awe_addcodemarker(M, 'bypassFunctionName', 'IOAcrossModule_Bypass');

The following logic defines the bypass function. 

1. If $bypassFunction$ is defined, then the code is placed into the generated .c file and $bypassFunctionName$ is set to awe_modClassNameBypass,

2. If $bypassFunctionName$ is defined, then this function is used for bypass behavior.  No additional code is placed into the generated .c file.

3. Otherwise, the default bypass function IOMatchUpModule_Bypass() is used.  No additional code is placed into the generated .c file.

...

Specifies the inner portion of a custom constructor function.  The function must follow the calling convention outlined in Section 4.4.1 Constructor Function.

• Simple audio modules without indirect arrays

...

• : No need to define the constructor function.  The BaseClassModule_Constructor() usually does everything needed.

• Audio modules with direct arrays

...

• : Set the .arrayHeap and .arraySizeConstructor fields of the array variables in MATLAB.  Audio Weaver will then auto generate a suitable constructor function.

• Complex modules requiring further initialization

...

• : Write a custom $constructorFunction$ or use the $postConstructorFunction$ shown below.

• Modules created out of subsystems

...

• : Audio Weaver automatically generates code for these systems.  If you need further initialization, use the

...

• $postConstructorFunction$ shown below.

$postConstructorFunction$

This code marker follows immediately after the $constructorFunction$ code marker in awe_module_template.c.  This marker allows you to add your own code in cases where Audio Weaver generates the memory allocation and instantiation code but further initialization is needed.  It is particularly useful for subsystems.

...

Defines the discussion section of the help documentation.  This has been grandfathered for backwards compatibility.  When writing new modules, set the M.docInfo.discussion field of the audio module instead.

...

Specifies the inner portion of a module's Get function.  Follows the calling convention outlined in Section 4.4.4 Get Function .

$setFunction$

Specifies the inner portion of a module's Set function.  Follows the calling convention outlined in Section 4.4.3. Set Function.

$hFileDefine$

Located near the top of the template file awe_module_template.h.  Allows you to add additional preprocessor directives (or anything else) at the start of the header file.  Example,

awe_addcodemarker(M, 'hFileDefine', '#define TRUE 1');

$hFileInclude$

Located near the top of the template file awe_module_template.h.  Allows you to include additional header files.

awe_addcodemarker(M, 'hFileInclude', '#define <stdlib.h>');

$processFunction$

Specifies the inner code for the module's processing function.  This must always be defined for modules.  For subsystems, the auto-generated should be used.  Refer to Section 4.4.2 Processing Function for a discussion of how to define this function.

...

This code marker is located immediately before the $processFunction$ marker.  It is typically used with subsystems when you want to insert your code custom code immediately prior to the auto-generated $processFunction$.

$postProcessFunction$

Similar to $preProcessFunction$ but the code here is inserted immediately after the $processFunction$.  It is typically used with subsystems when you want to insert your custom code immediately after the auto-generated $processFunction$.

$srcFileDefine$

Located near the top of the template file awe_module_template.c.  Allows you to add additional preprocessor directives (or anything else) at the start of the source file. 

...

Located near the top of the template file awe_module_template.c.  Allows you to specify additional includes included files. 

$hFileTemplate$ and $srcFileTemplate$

Audio Weaver uses the default template files specified at the start of Section 5.2 Code Markers and Template Substitution.  You can override the templates used by a particular module by setting these code markers.  There are separate markers for the header file, $hFileTemplate$, and the source file, $srcFileTemplate$.  It is handy to override these values if you want to change copyright information in the generated files.

...

The generated array constructor code is of the form:

if ((S->ARRAYVAR = (TYPE *) awe_fwMalloc(SIZE, HEAP, retVal)) == 0)

...

{

...

{
    // Error code is in *retVal

...

    return 0;

...

}

whereWhere:

• ARRAYVAR

...

• — is the name of the variable

• TYPE

...

• — is the type of the module (either float, fract32, or int)

• SIZE

...

• — is a user specified string

• HEAP

...

• — is a user specified string.

ARRAYVAR and TYPE are already known to MATLAB.  SIZE and HEAP must be separately specified as C code to embed into the generated code.  The string SIZE is specified in MATLAB by setting field .arraySizeConstructor field of the array variable.  Similarly, HEAP is specified by setting the .arrayHeap field of the array variable.  For an example, see the Peak Hold module in Section 7Module.2

Specifying Module Constructor Arguments in Subsystems

Anchor
SpecifyingModuleConstructorArgumentsinSubsystems SpecifyingModuleConstructorArgumentsinSubsystems

...

To get around this problem, Audio Weaver allows you to specify a piece of C code which overrides the default numeric initializer for an internal module variable.  The C code is written to the .constructorCode field of the variable.  For an example, refer to the look ahead limiter example of Section 0. Look Ahead Limiter Module. 

Avoiding Wire Allocation Problems with Subsystems

This issue also applies to the case of compiling subsystems to form new module classes.  If your subsystem has .flattenOnBuild=1 (which means that it is not compiled), then you can ignore this section.  This  This problem arises because Audio Weaver modules can operate on an arbitrary number of channels.  In  In certain circumstances, the routing algorithm incorrectly allocates wire buffers during code generation such that audio processing crashes at run-time.  In these cases, you need to be careful how you specify default channel counts and block sizes within modules.   The look ahead limiter example of Section 7.4 Look Ahead Limiter Module demonstrates the problem and presents a solution.

unique_classes.m

C=unique_classes(SYS)

where

• SYS

...

• — @awe_subsystem object.

Returns a list of all the unique module and subsystem classes found within subsystem SYS.  The function recursively searches through the system and identifies individual modules and subsystems.  The return result C is a cell array of strings. If called without any output arguments, the function displays the class list to the MATLAB output window.  The class name of the input SYS is not included in the C.  This function is useful for dependency checking.

[C, M]=unique_classes(SYS)

An optional second output receives a cell array of the actual modules/subsystems listed in C.

SYS can also be a cell array of subsystems.  In this case, the function returns the overall set of unique classes needed to create all of the systems in SYS.

[C, M]=unique_classes(SYS CLIST)

An optional Boolean argument CLIST specifies that the list of unique module classes should be displayed in a manner appropriate for inclusion in the TargetInfo.h file.

For example, to determine all of the unique module classes needed for the agc_example, type:

>> SYS=agc_example;

...

>> unique_classes(SYS)

...

Unique classes within the subsystem of class: test

...

AGC

...

AGCCore

...

AGCMultiplier

...

Meter

...

ScalerDB

If you want to build a target with only the modules required for the agc_example, you would set CLIST=1.  The following C code is then printed to the output window:

extern const ModClassModule awe_modAGCClass;

...

extern const ModClassModule awe_modAGCCoreClass;

...

extern const ModClassModule awe_modAGCMultiplierClass;

...

extern const ModClassModule awe_modMeterClass;

...

extern const ModClassModule awe_modScalerDBClass;

...

#define LISTOFCLASSOBJECTS \

 
#define LISTOFCLASSOBJECTS \
&awe_modAGCClass, \

...

&awe_modAGCCoreClass, \

...

&awe_modAGCMultiplierClass, \

...

&awe_modMeterClass, \

...

&awe_modScalerDBClass

This text can be pasted directly into TargetInfo.h.

awe_generate_module.m

M=awe_generate_module(M, DIRECTORY, WRITEFILES)

Internal function used by awe_generate_library.m.  In some cases, such as when generating documentation, you may want to call this function directly.  Arguments:

• M

...

• — @awe_module object.

• DIRECTORY

...

• — directory in which the generated files should be written to.  By default, this is set to MATLAB's current working directory (returned by the pwd command).

• WRITEFILES

...

• — an optional Boolean argument which specifies whether the generated files should actually be written.  If you set WRITEFILES=0, then the module M will be updated with code markers, but no output files will be written.  Use WRITEFILES=0 when generating documentation as described in

...

• Generating Documentation.