Updating MATLAB User Scripts to 8.D.2.4/8.D.2.5+

About this guide

The internal Audio Weaver Designer MATLAB framework was refactored in Designer versions 8.D.2.4 and 8.D.2.5 to use more efficient and modern object oriented features in MATLAB. This refactoring on its own can lead to 20-30% improvements in layout build and load times, and also opens the door for further improvements in future versions.

The result of this refactoring means that from version 8.D.2.4 and onwards, AWE objects are passed by handle rather than copied by assignment in MATLAB scripts. This guide is meant to help identify when user MATLAB scripts need to be updated to function in 8.D.2.4 or 8.D.2.5 and later, and to show how to make the necessary updates.

How to Identify and Fix Issues

User MATLAB scripts created with earlier versions of Designer that rely on direct assignment to create new copies of AWE objects likely need to be edited to run successfully in Designer 8.D.2.4+. Errors generated by invalid scripts can vary but may refer to wiring errors, like missing or already existing connections between modules.

Below is an example of a MATLAB script using AWE objects that works correctly in Designer 8.D.2.3 and earlier but will result in an error in 8.D.2.4+.

function badexample()
    % This function shows an example of a script that worked with previous
    % versions of designer, but will no longer work starting at 8.D.2.4/5
    % Previously, modifications of SYS2 below would not affect GSYS.SYS.
    GSYS = load_awd('example.awd');
    
    % Make a copy of GSYS.SYS with direct assignment, then modify SYS2
    % by deleting a marker module 'M1'. SYS2 now points to GSYS.SYS
    % so modifications to SYS2 will change the original GSYS.SYS. 
    SYS2 = GSYS.SYS;
    SYS2 = delete_module(SYS2, 'M1');
    
    % This build will now complain about missing module M1 and/or bad 
    % connections when building the original system
    GSYS.SYS = build(GSYS.SYS); 
return

The error from the example above looks like this:

Error using awe_module/prebuild
AWE ERROR:Wiring error at the top-level system
AWE ERROR:Module Scaler1 input pin 'in1' is not connected

The following function uses the MATLAB copy function instead of a direct assignment to create SYS2. This function will work in Designer versions 8.D.2.4+. Using copy is backwards compatible with previous versions of Designer (8.D.2.3 and earlier), so it is always the preferred way to create new copies of AWE objects in MATLAB scripts.

function goodexample()
    GSYS = load_awd('example.awd');
    
    % Make a copy of GSYS.SYS, then modify SYS2. This will not modify the
    % original GSYS.SYS
    SYS2 = copy(GSYS.SYS);
    SYS2 = delete_module(SYS2, 'M1');
    
    % The original system is unchanged so it will still build
    GSYS.SYS = build(GSYS.SYS); 
return

Other programming paradigms are not affected by the updates in 8.D.2.4+, so only scripts of the style shown above need to be updated to use the latest versions of Designer.