ArtWonk Macro Modules

Macro Modules

Macro modules are modules that act as containers for other modules. They are helpful for organizing large patches, and they make the job of creating repeating subsections much easier because once placed in a macro, the section can be treated as a single module.

For a general description of Macro and Self modules, see the Modules page.

ArtWonk uses a highly efficient and flexible method of processing Macros; they can be nested (macros within macros) as deeply as you wish with virtually no additional burden on CPU resources. In general, it is recommended that you consider creating a macro when your modules spread out beyond the viewable screen area.

Creating a macro

To create a macro, right click on the Workspace and select "Macro/New Macro" from the pop up menu - the one with the orange ball. An empty, generic macro is created with one input and one output.

Decide what inputs and outputs you want for the macro. The modules you will be placing into the macro cannot communicate with modules outside the macro, except through its inputs and outputs, and via the Global Variable module. Click on the Property button of the Macro module, and set up the Inputs and Outputs. You can have slightly over 100 combined inputs or outputs, set with the More and Fewer buttons in the Input or Output tabs. Rename the labels and add tool tips if you like.

It is a good idea, but not required, to set up the inputs and outputs first. If you change them later, connections will be broken whenever the number of connections changes, in order to avoid connections to non existent outputs.

Once you have the Macro module shell set up, highlight the modules you want to place into the macro, and Cut them. Then enter the macro by clicking on the "@" button just to the left of the Property button. The Workspace screen will clear and you will see only the Self module, which is the mirror of the Macro module, used to communicate from within the macro to modules that are "peers" of the macro. Click on the Workspace and Paste the modules you previously had Cut. They will appear in the macro. You will see the modules now listed as a branch in the Tree view to the left of the Workspace.

All module connections made that are within the the macro are preserved, however any connections that previously connected to modules outside the macro are broken. You can re establish these connections now by using the Self inputs and outputs (which are Macro outputs and inputs), to connect to the modules you want to communicate outside the macro.

Finally, you can click on the Self "#" button to return to the previous Workspace level, where the Macro module now appears as, and should work as a regular module. To save it into the Macro library, click on the Save button in its properties. Save is only available when entering properties from the Macro, not from the Self.

Macro types

In the General tab of the Macro module Properties dialog, there is a list of several Macro types, each with a different color ball icon:

Always (orange): The generic macro type, always runs. Modules within this macro will always run, just as they would if they were outside the macro.

Change (green): Runs when the value in the 1st input changes. You are free to use this input to send a value to the inside of the macro, just as with any Macro module input. But it also has the special function of causing the macro to run the modules inside it only when it changes.

Strobe (yellow): Runs only upon Strobe in the 1st input. Since it only runs on the 0 to NZ transition of the value in the 1st input, this value will always be seen inside the macro as the NZ part of the strobe.

Loop (red): Runs continuously in a loop (repeats) the number of times set by the 1st input; if this input is 0 the module is not run. This is a very powerful type, that enables ArtWonk modules to be used as a program language, with conditional branching and looping.

To use as a loop, simply put the number of loops desired into the 1st input. When the module is run, it runs all modules inside it that number of times before giving up control to the next module.

To use as a conditional branch, use a Compare module to set the Macro module's 1st input to Compare condition output. The Loop macro will run once when the condition is True (1), and not run when it is False (0). An If, Then construction would use one Loop Macro for the If clause; and an If, Then, Else construction would use two Loop macros, with the Else clause fed by a Not module connected to the same Compare module condition output.

Clock1 & Clock2 (blue): These macros run only when the selected Loop Clock fires. Timing for the Loop Clocks can be set by the System module. Use special care when using these macro types, as they run asynchronously with the Main loop clock, and any modules that use Auto Sync, such as the Clock module, will not work correctly in them. For a full description of the Clock1 & 2 macro type, see the Run Loop page.

MIDI-A & MIDI-B (magenta): Similar to the Clock macros, but instead of running on a Clock tick, the MIDI macros run when a MIDI message is received. This bypasses the normal tick-based module execution cycle, to handle MIDI input immediately, providing a powerful means of MIDI message processing.

Modules may be set to process MIDI input from your keyboard, or any other MIDI source, immediately, and send the results on to your MIDI sound generator without any noticeable delay or lag time. This gives ArtWonk the ability to act as a super MIDI filter, probably the most advanced ever. With it, you can design your own set of real time Karma-like MIDI filters not as a factory-made rubber stamp, but as your unique signature.

Select the MIDI messages, channels and ports to respond to from the MIDI-A and MIDI-B tabs in the Macro Properties dialog. When a MIDI input is received that fits the profile, the MIDI macro will run all modules contained within it.

Unlike other macro modules which are periodic, executing on every clock tick, MIDI macro modules do not execute except when they receive a MIDI input message. Because they are aperiodic, modules that use strobe signals (non zero after a zero) will not work as expected.