Versions Compared

Key

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

...

A variable in Audio Weaver represents a single scalar or array variable on the target processor.  Even if you are not developing modules, it is good to understand the @awe_variable object so that you can fully utilize variables.A variable in Audio Weaver represents a single scalar or array variable on the target processor. 

Info

Scalar is a mathematical term and refers to a variable containing only a single value, not to be confused with Audio Weaver scaler modules.

A new scalar variable is created by the call:

...

Code Block
filter = Biquad // 2nd order IIR filter

     b0: 1          // First numerator coefficient
     b1: 0          // Second numerator coefficient
     b2: 0          // Third numerator coefficient
     a1: 0          // Second denominator coefficient
     a2: 0          // Third denominator coefficient
  state: 0
          0]

...

@awe_module

This class represents a single primitive audio processing function on the target.  A module consists of the following components: a set of names, input and output pins, variables, and functions.  All of these items exist in MATLAB and many of them have duals on the target itself.

...

Class Object

To create an audio module object, call the function M=awe_module(CLASSNAME, DESCRIPTION)

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. 

After the module class is created, set the particular name of the module:

M.name='moduleName';

Note that there is a distinction between the CLASSNAME and the .name of a module.  The CLASSNAME is the unique identifier for the type of the module.  For example, there are different class names for scalers and biquad filters.  The .name identifies the module within a system and must be unique within the current level of hierarchy in the system.  At this point, we have a bare module without inputs, outputs, variables, or associated functions.  These must each be added.

We'll now look more closely at the fields within the @awe_module object.  Instead of looking at a bare module as returned by awe_module.m, we'll look at a module that is part of a system and has already been built. We'll choose the Automatic Gain Control Core module:

struct(agc_core_module)

MATLAB displays

                         name: ''

                    className: 'AGCCore'

                  description: 'Slowly varying RMS based gain computer'

                      classID: []

          constructorArgument: {}

            showArgumentPopup: 0

                  defaultName: ''

                moduleVersion: 30797

                 classVersion: 32465

                 isDeprecated: 0

           nativePCProcessing: 1

                     heapUsed: [3×1 double]

                      version: []

                 propertyInfo: [0×1 containers.Map]

                      modVars: [0×1 containers.Map]

                isInterpreted: 0

                    mfilePath: [1x62 char]

               mfileDirectory: [1x44 char]

                    mfileName: 'agc_core_module.m'

                         mode: 'active'

                 clockDivider: []

                     inputPin: {}

                    outputPin: {}

                   scratchPin: {}

               inputPinLookup: [0×1 containers.Map]

              outputPinLookup: [0×1 containers.Map]

                     variable: {}

                 variableName: {}

                      control: {}

               wireAllocation: 'distinct'

                      getFunc: []

                      setFunc: []

                enableSetFunc: 1

                  processFunc: []

                   bypassFunc: @generic_bypass

                     muteFunc: @generic_mute

                 preBuildFunc: []

                postBuildFunc: []

              testHarnessFunc: []

                  profileFunc: @profile_simple_module

                  pinInfoFunc: []

    propagateChannelNamesFunc: @generic_propagate_channel_names

           propagateDelayFunc: @generic_propagate_delay

                     isHidden: 0

                     isPreset: 1

                       isMeta: 0

                      isDebug: 0

                 metaFuncName: []

              requiredClasses: {}

             consArgPatchFunc: []

                moduleBrowser: [1×1 struct]

                textLabelFunc: []

                     textInfo: [1×1 struct]

                    shapeInfo: [1×1 struct]

                 freqRespFunc: []

           bypassFreqRespFunc: []

            prepareToSaveFunc: []

                  copyVarFunc: @generic_copy_variable_values

                  inspectFunc: []

                inspectHandle: []

              inspectPosition: []

              inspectUserData: [1×1 struct]

         numericInspectHandle: []

       numericInspectPosition: []

               freqRespHandle: []

             freqRespPosition: []

                    isTunable: 1

                         view: [1×1 struct]

                       isLive: 0

                hierarchyName: ''

                     hasFired: 0

                   targetInfo: [1×1 struct]

                       coreID: 0

                multicoreInfo: [1×1 struct]

              nProcessorGroup: 0

           allocationPriority: 0

                     objectID: []

                  objectAlias: ''

              procSIMDSupport: {}

                   codeMarker: {}

                   isTopLevel: 0

          executionDependency: {}

                      presets: [1×1 struct]

                  presetTable: [1×1 struct]

                   numPresets: 0

                      guiInfo: [1×1 struct]

                     drawInfo: [1×1 struct]

                 isControlled: 0

            controllingModule: ''

                      uccInfo: [1×1 struct]

                      docInfo: [1×1 struct]

           savePropertiesFunc: []

           loadPropertiesFunc: []

                     isLocked: 1

                        class: 'awe_module'

                  isNavigable: 1

                 passwordHash: ''

                       module: {}

                 moduleLookup: [0×1 containers.Map]

                   connection: {}

               flattenOnBuild: 1

                    isVirtual: 0

           targetSpecificInfo: [1×1 struct]

                   isPrebuilt: 0

               preProcessFunc: []

              postProcessFunc: []

                    buildFunc: []

        reusableSubsystemName: ''

                oriSubSysName: ''

                   fieldNames: {109×1 cell}

 

where

 the following:

Code Block
                         name: ''
                    className: 'AGCCore'
                  description: 'Slowly varying RMS based gain computer'
                      classID: []
          constructorArgument: {}
            showArgumentPopup: 0
                  defaultName: ''
                moduleVersion: 30797
                 classVersion: 32465
                 isDeprecated: 0
           nativePCProcessing: 1
                     heapUsed: [3×1 double]
                      version: []
                 propertyInfo: [0×1 containers.Map]
                      modVars: [0×1 containers.Map]
                isInterpreted: 0
                    mfilePath: [1x62 char]
               mfileDirectory: [1x44 char]
                    mfileName: 'agc_core_module.m'
                         mode: 'active'
                 clockDivider: []
                     inputPin: {}
                    outputPin: {}
                   scratchPin: {}
               inputPinLookup: [0×1 containers.Map]
              outputPinLookup: [0×1 containers.Map]
                     variable: {}
                 variableName: {}
                      control: {}
               wireAllocation: 'distinct'
                      getFunc: []
                      setFunc: []
                enableSetFunc: 1
                  processFunc: []
                   bypassFunc: @generic_bypass
                     muteFunc: @generic_mute
                 preBuildFunc: []
                postBuildFunc: []
              testHarnessFunc: []
                  profileFunc: @profile_simple_module
                  pinInfoFunc: []
    propagateChannelNamesFunc: @generic_propagate_channel_names
           propagateDelayFunc: @generic_propagate_delay
                     isHidden: 0
                     isPreset: 1
                       isMeta: 0
                      isDebug: 0
                 metaFuncName: []
              requiredClasses: {}
             consArgPatchFunc: []
                moduleBrowser: [1×1 struct]
                textLabelFunc: []
                     textInfo: [1×1 struct]
                    shapeInfo: [1×1 struct]
                 freqRespFunc: []
           bypassFreqRespFunc: []
            prepareToSaveFunc: []
                  copyVarFunc: @generic_copy_variable_values
                  inspectFunc: []
                inspectHandle: []
              inspectPosition: []
              inspectUserData: [1×1 struct]
         numericInspectHandle: []
       numericInspectPosition: []
               freqRespHandle: []
             freqRespPosition: []
                    isTunable: 1
                         view: [1×1 struct]
                       isLive: 0
                hierarchyName: ''
                     hasFired: 0
                   targetInfo: [1×1 struct]
                       coreID: 0
                multicoreInfo: [1×1 struct]
              nProcessorGroup: 0
           allocationPriority: 0
                     objectID: []
                  objectAlias: ''
              procSIMDSupport: {}
                   codeMarker: {}
                   isTopLevel: 0
          executionDependency: {}
                      presets: [1×1 struct]
                  presetTable: [1×1 struct]
                   numPresets: 0
                      guiInfo: [1×1 struct]
                     drawInfo: [1×1 struct]
                 isControlled: 0
            controllingModule: ''
                      uccInfo: [1×1 struct]
                      docInfo: [1×1 struct]
           savePropertiesFunc: []
           loadPropertiesFunc: []
                     isLocked: 1
                        class: 'awe_module'
                  isNavigable: 1
                 passwordHash: ''
                       module: {}
                 moduleLookup: [0×1 containers.Map]
                   connection: {}
               flattenOnBuild: 1
                    isVirtual: 0
           targetSpecificInfo: [1×1 struct]
                   isPrebuilt: 0
               preProcessFunc: []
              postProcessFunc: []
                    buildFunc: []
        reusableSubsystemName: ''
                oriSubSysName: ''
                   fieldNames: {109×1 cell}

...

The above fields correspond to the following:

  • 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 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]

...

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

...

MATLAB Functions for Constructing Modules

The following functions are commonly used for constructing audio modules.  They are briefly mentioned here and are documented later on in this guide.

add_variable.m – adds a scalar variable to an audio module object.  See Section 3.6

add_array.m – adds an indirect array to an audio module object.  See Section 3.7

add_pin.m – adds an input, output, or scratch pin to an audio module object.  See Section 3.5.

add_codemarker.m – adds information related to code generation.  See Section 5.2.

add_control.m – exposes a single control on the inspector.  See the Audio Weaver Matlab API.

set_variable.m – replaces an existing module variable.  See Section 3.11

get_variable.m – extracts a variable from a module and returns an @awe_variable object.  See Section 3.11

...

       dataTypeRange: {'float'  'int'  'fract32'}

      isComplexRange: 0

...

add_pin.m
Anchor
add_pin.m
add_pin.m

Pins are added to a module by the add_pin.m function.  Each pin has an associated Pin Type as described in Section 3.4.  After creating the Pin Type, call the function

...

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

...

get_variable.m and set_variable.m
Anchor
get_variable.mandset_variable.m

...

get_variable.mandset_variable.m

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:

...