Versions Compared

Old Version 1

changes.mady.by.user Catherine Spain

Saved on

compared with

New Version Current

changes.mady.by.user Gary Worsham

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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 in the module’s Properties panel (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.

...

Many of the fields are set when the variable was is 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 is set when the variable was is 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.targetLevel

  • size — 1x2 element vector used to represent the size of matrices, [rows columns].  For scalars, this is always [1 1].  Set when the variable was is 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 is added to the module.  Not user editable.

  • isComplex — Boolean indicating whether the variable contains complex data.  Set when the variable was is 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 is 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 at 0 when the module is instantiated and the is 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 Scalar 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 indicating whether the variable range is editable or not.

  • isTuningSymbol — Boolean indicates indicating whether the variable is real-time tunable or not.

  • classVersion — internal field indicates indicating 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 any variable that the user typically does not need to know about.  For example, allocate a 2nd order Biquad filter:

...

The first argument, CLASSNAME, is a 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.  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:

...

  • name — name of the module within the subsystem.  This is specified when the module is instantiated and cannot be changed thereafter.  Not user editable.

  • className — name of the underlying module class.  This is specified when the module is instantiated and cannot be changed thereafter.  Not user editable.

  • description — short comment indicating what the module does.  User editable.

  • classID — unique integer which identifies the module class on the target.  This value is set by the code generator and is normally blank.  Not user editable.

  • constructorArgument — list of the arguments to be passed to the module. Module must be called with all arguments while generating the code. This field is important for AWE Designer to pass arguments to module.

  • defaultName — Fixed default name of the module.

  • moduleVersion — Version of the module.

  • classVersion — Version of the module class.

  • isDeprecated — Boolean indicates whether the module is deprecated in the current version of AWE Designer.

  • isInterpreted — Boolean indicates whether the module is Interpreted or not.

  • mfilePath — full path to the m-file which instantiated the module (the one containing the call to @awe_module).  Used by the code generator.  Not user editable.

  • mfileDirectory — the directory portion of mfilePath.  Not user editable.

  • mfileName — the file name portion of mfilePath.  Not user editable.

  • mode — string indicating the current module status.  This can be either 'Active', 'Bypassed', 'Muted', or 'Inactive'.  Used internally and is not user editable.  Use the functions awe_setstatus.m and awe_getstatus.m to manipulate the module status.

  • clockDivider — integer indicating how often the module will be run within the layout.  This is currently always set to 1 (meaning run every time).  This is reserved for new Audio Weaver functionality planned in the future.  Not user editable.

  • inputPin — cell array of input pin information.  This information is set by the add_pin.m function and should not be changed.  You'll frequently access this to determine the properties of the input pins.  Each cell value contains a data structure such as:

    Code Block
    SYS.agc.core.inputPin{1}

ans = 

              type: [1x1 struct]
             usage: 'input'
              name: 'in'
       description: 'Audio input'
    referenceCount: 0
        isFeedback: 0
          drawInfo: [1x1 struct]
         wireIndex: 1

  • outputPin — similar to inputPin.  It is a cell array describing the output pins.

  • scratchPin - similar to inputPin.  It is a cell array describing the scratch pins.

  • variable — a cell array of @awe_variable objects corresponding to the variables in this module.  This array is updated by the add_variable.m function.  Not user editable.

  • variableName — a cell array of strings, one for each variable in the module.  This cell array is used to speed up variable accesses.  This array is updated by the add_variable.m command.  Not user editable.

  • control — holds internal information related to the inspector.  Not user editable.

  • wireAllocation — a string specifying how wires should be allocated for the module.  Possibilites are 'across' and 'distinct'.

  • getFunc — optional MATLAB function pointer specifying the module's get function.  This function is called whenever a variable in the module is queried.  Used very rarely.  Normally this is set to the empty matrix.

  • setFunc — optional MATLAB function pointer specifying the module's set (or control) function.

  • processFunc — optional MATLAB function pointer specifying the module's processing function.  The processing function is a MATLAB implementation of the audio processing performed by the module.

  • bypassFunc — optional MATLAB function pointer specifying the module's bypass behavior.

  • muteFunc — optional MATLAB function pointer specifying the module’s mute behavior.

  • preBuildFunc — optional MATLAB function pointer specifying the module's prebuild functionality.  The prebuild function is called prior to building the module or generating code and resolves pin types and array sizes.

  • postBuildFunc — optional MATLAB function pointer specifying the module’s postbuild functionality. Generally most of the module will have this field as empty.

  • testHarnessFunc — optional MATLAB function pointer specifying the module’s test harness script.

  • profileFunc — optional MATLAB function pointer specifying the module’s profile function.

  • isHidden — Boolean specifying whether the module should be shown when part of a subsystem.  Similar to the .isHidden field of @awe_variable objects.  User editable.

  • isPreset — Boolean that indicates whether the module will be included in generated presets.  By default, this is set to 1.  User editable.

  • isMeta — Boolean specifying whether this is a meta-module which switches out at build time.

  • metaFuncName — optional string specifying the name of the underlying module to instantiate if this is a meta module.

  • requiredClasses — This is the list of classes required for the current instantiation of the

  •  module.  For meta modules it could be a subset of requiredClassesBrowser.

  • consArgPatchFunc — Custom function to matchup older version of system with new module.

  • moduleBrowser — This is the information for displaying the module in AWE Designer GUI. It includes the image of the module in the designer module tree, search tag, name of the module in browser etc. Look for .moduleBrowser for more information.

  • textLabelFunc — Function for generating a text lablel when drawn in the AWE Designer GUI. Look at the .textLablelFunc for more information.

  • textInfo — Text label properties information.

  • shapeInfo — Is a structure which holds shape information of the module in the AWE Designer GUI. It includes the name of the SVG image used to draw on the layout, size of the module, shape of the module etc. Look at .shapeInfo for more information. Default shape information is Rectangle box with Solid lines with Black color. This can be overwritten by initializing fields in this structure.

  • freqRespFunc — Optional MATLAB function pointer for computing the frequency response of the module.

  • bypassFreqRespFunc — Frequency response function of the module in bypass mode.

  • prepareToSaveFunc — Function for clearing out internal pointers or other state that is not needed when the module is saved.

  • copyVarFunc — optional MATLAB function pointer that is called when a module’s variables need to be copied. User can over right the default generic copy variables function.

  • inspectFunc — optional MATLAB function for drawing custom inspector.

  • inspectHandle — Figure handle of the custom inspector, internal to the Audio Weaver.

  • inspectPosition — Position, [x y], of the custom inspector in MATLAB coordinates used by the “inspect” function of the Audio Weaver.

  • inspectUserData — Custom inspector persisted information.

  • numericInspectHandle — Numeric inspector handle of the module for AWE Designer.

  • numericInspectPosition — Position, [x y], of the numeric inspector of the module in MATLAB coordinates for designer.

  • freqRespHandle — Module’s frequency response handle.

  • freqRespPosition — Position, [x y], of the frequency response to be drawn in MATLAB coordinates for designer.

  • isTunable — Boolean indicating whether the variables in the module are real time tunable or not in designer.

  • View — Structure of various fields internal to Audio Weaver holds the view settings in the designer.

  • isLive —Boolean indicating whether the module has been built and is running on the target.  When a module is first instantiated, this is set to 0 and then changed to 1 by the build process.  Not user editable.

  • hierarchyName — hierarchical name of the module within the subsystem.  This is filled in during the build process.  Not user editable.

  • hasFired — Boolean field that is used internally by the routing algorithm.  Not user editable.

  • targetInfo — data structure holding target specific information.  This is filled in by the build process and is used internally for tuning.  Not user editable.

  • codeMarker — a cell array holding all of the code markers.  Code markers are used for module generation and described in Section 5.2.  Not user editable.

  • isTopLevel — Boolean set by the buid process.  A value of 1 indicates that a module is the highest level item in a system.  All modules have .isTopLevel=0; only the top-level subsystem has .isTopLevel=1.  Not user editable.

  • guiInfo — data structure used for drawing inspectors.  Some fields are user editable. See Overriding Default GUI Settings for information about creating custom inspector interfaces.

  • drawInfo — data structure used internally when creating drawings of subsystems and modules.  Not user editable.

  • docInfo — data structure containing documentation information.  This is set in the module's m-file and is used by the automated documentation generator.  Some user editable fields.  Refer to the Section 6.

  • isLocked — internal field used to accelerate references.  Not user editable.

  • class — string specifying the underlying object class.  This is always 'awe_module'.  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.

...

add_pin.m — adds an input, output, or scratch pin to an audio module object.

add_codemarker.m — adds information related to code generation.

add_control.m — exposes a single control on the inspector.

...

There is a close coupling between the module related C functions the module subfunctions on the target processor.  The table below gives a brief description of the functions available.

MATLAB Function Name

Target Function Name

 Purpose

*_module.m

*_Constructor()

Constructs an instance of a module class.  The function allocates memory for the base instance structure.  The MATLAB function sets default values while on the target default values are passed into the constructor.  Required.

.processFunc

*_Process()

Real-time processing function.  Required for C code.  Optional for MATLAB.

.setFunc

*_Set()

Implements the module's control functionality.  The function converts high-level interface parameters to lower-level derived values.  This function should be called whenever a variable in a module is modified.  Optional. 

.getFunc

*_Get()

The counterpart to the _Set() function but is used when module variables are read.  Most modules do not use this function. When a module instance variable is read, this function is first called and then the instance variable is returned.  It could be used, for example, to convert a measurement from energy to dB.

.bypassFunc

*_Bypass()

Implements the module's bypass functionality.  This is an optional function; when it is empty, a generic bypass function is used instead.

.preBuildFunc

N/A

This function exists only in MATLAB and it is called as part of the build procedure.  The prebuild function propagates pin information and may update array sizes.  The prebuild function is useful for setting variable values that depend upon the pin type.  The prebuild function is optional; if it doesn't exist, the pin type information from the module's first input pin is propagated to the output.

.freqRespFunc

 

N/A

This optional function exists only in MATLAB and it computes the frequency response of the module.

.profileFunc

 

N/A

This optional function exists only in MATLAB and it profiles the module for various settings like different block size and etc.

.textLabelFunc

 

N/A

This optional function exists only in MATLAB and it draws the text label for the AWE Designer GUI.

MATLAB Module M-File

The MATLAB m-file associated with an audio module creates and returns an instance of the module.  The typical function signature for a module m-file is

...

These commands are documented in (8.D.2.4) MATLAB Scripting API.

Internal Subsystem Functions

Each subsystem has a set of subfunctions that mirror the module functions described in 3.2.3.  Fortunately, for most subsystems, generic or generated versions of the functions can be used.  The table below describes the operation of each of the functions in the context of generated code.

MATLAB Function Name

Target Function Name

 Purpose

*_module.m

*_Constructor()

This MATLAB code must be manually written as described above.  Modules are manually added, configured, and connected.

The C code version of this function is automatically generated.  The function calls the base module constructor function and then calls the _Constructor() function for all internal modules.  The internal modules parameters are set according to their values at build time.

.processFunc

*_Process()

Audio Weaver automatically generates the MATLAB and C versions of these functions.

.setFunc

*_Set()

In all cases, this must be manually written.

.getFunc

*_Get()

In all cases, this must be manually written.

.bypassFunc

*_Bypass()

The generic function utilized by modules can also be used here.

.preBuildFunc

N/A

Not needed.  The existing pin propagation function can propagate the information through subsystems.

Top-Level Systems

Thus far, we have been using the terms system and subsystem interchangeably.  There is a slight difference, though, that you need to be aware of.  The highest level system object that is passed to the build command must be a top-level system created by the function:

...

Consider the look ahead limiter subsystem introduced in Specifying Module Constructor Arguments in Subsystems.  It can be connected to mono, stereo, or 5.1 channel signals and all of the wiring and buffer allocation will be automatically handled.  This generality allows you to design algorithms which operate on an arbitrary number of channels with little added complexity.

...

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 Audio Module Instance Structure to see the correspondence between variables in the MATLAB object and variables in the C type definition.

...