ScriptModulationMatrix

This class provides programmatical access to the new matrix modulation system in HISE 5.0. It offers convenient methods to query modulation properties, be notified over connection events as well as programmatically perform connection changes.

In addition to these features, this class will also act as data management tool and automatically register itself to the user preset system so that all modulation connections are stored / restored in the user preset.

This class is just a simple wrapper around the functions available at different locations within HISE, so for a detailed overview of the entire matrix modulation system, please take a look at these sections:

• The Matrix Modulator module for a explanation of the (new) architecture that is powering the modulation matrix system.
• The ModulationMatrix and ModulationMatrixController floating tiles for a explanation of the available UI building blocks.

In order to use this class make sure to setup your system to work with matrix modulators:

1. Create a global modulator container and add modulation sources in there
2. Add Matrix modulators to every target that you want to modulate
3. Add / customize the floating tiles to display / edit the modulation connections
4. Create this object in the onInit callback with Engine.createModulationMatrix() and then register callbacks / perform operations on this object.

Note that this object was completely redesigned in HISE 5.0 with absolutely no attention paid to remaining backwards compatible to the API of older versions, so if you were using this object before, you will need to completely rewrite your modulation logic.

Class methods

canConnect

Checks whether the modulation connection can be made.

ScriptModulationMatrix.canConnect(String source, String target)

This method checks whether the source and target IDs are valid (= they exist) and are not connected.

• it returns true if both IDs are valid and there is no connection
• it returns false if one of the IDs are invalid or there is already a connection

Note that you don't need to call this method if you intend to call connect() , as this method performs this check internally too.

clearAllConnections

Removes all connections for the given target (or all connections if no target is specified).

ScriptModulationMatrix.clearAllConnections(String targetId)

This clears all connections for the given target ID or all connections if you pass in an empty string.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

connect

Adds (or removes) a connection from the source to the target.

ScriptModulationMatrix.connect(String sourceId, String targetId, bool addConnection)

This method allows you to programmatically connect modulators (just like using the UI functions). Calling this method connects / disconnects the given source modulator to the specified target and returns true if a connection was established. If there was already a connection or one of the IDs was invalid, it will return false.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

fromBase64

Loads the state from a previously exported Base64 string.

ScriptModulationMatrix.fromBase64(String b64)

This restores all modulation connections from a given Base64 string. Note that by default a ScriptModulationMatrix will register itself to the user preset system and automatically restore / save its connections into user presets, but this function alongside with ScriptModulationMatrix.toBase64() allows you to manually save / restore the modulation setup of your synth.

This action is fully undoable with Engine.undo() . Note that this will kill all voices and perform this operation on the scripting thread to avoid audio glitches.

getComponent

Get the component reference for the given modulation target ID.

ScriptModulationMatrix.getComponent(String targetId)

This function returns a reference to the first UI component that is assigned to a given modulation target.

Note that this does not return the ID but the component reference itself so you don't need to call Content.getComponent() afterwards.

getSourceList

Return a list of all sources.

ScriptModulationMatrix.getSourceList()

This function returns a list of all available modulation sources, which are basically just the IDs of all modulators in the global modulator container.

getTargetId

Get the target ID (either ID of the matrix modulator or matrixTargetId property) for the given component.

ScriptModulationMatrix.getTargetId(var componentOrId)

This function returns the associated target ID for the given component. The argument can be either a ID (then it will search all UI component for the first match) or a direct reference to the UI element.

This is basically the reverse function to ScriptModulationMatrix.getComponent() .

getTargetList

Return a list of all targets.

ScriptModulationMatrix.getTargetList()

This function returns a list of all available modulation targets. This will be the ID of all matrix modulators as well as all ScriptSlider components that have the matrixTargetId property set (in that case it will not return the UI component's ID but the actual value string of the matrixTargetId property).

setConnectionCallback

Set a callback that will be executed whenever the matrix state changes.

ScriptModulationMatrix.setConnectionCallback(var updateFunction)

This function will be executed whenever a connection was added or removed. It expects a function / callable object with three parameters:

1. the source ID
2. the target ID
3. whether it was added or removed.

Note that this function will be executed for every connection, so if you clear all connection at once it will be executed multiple times. So if you use a broadcaster for the notification callback make sure you enable the queue with Broadcaster.setEnableQueue() , otherwise it will only fire with the last event.

const var m = Engine.createModulationMatrix("Global Modulator Container1");

// setup a connection callback
m.setConnectionCallback(function(source, target, wasAdded)
{
	// dump the event data
	Console.print(trace({
		source: source,
		target: target,
		wasAdded: wasAdded
	}));
});

// connect the LFO to the OSC1 Gain target
// It assumes that you have set this up!
m.connect("LFO", "OSC1 Gain", true);

// Clear the connection again
m.clearAllConnections("");;

Output:

Interface: {
  "source": "LFO",
  "target": "OSC1 Gain",
  "wasAdded": true
}
Interface: {
  "source": "LFO",
  "target": "OSC1 Gain",
  "wasAdded": false
}

setCurrentlySelectedSource

Sets the currently selected source.

ScriptModulationMatrix.setCurrentlySelectedSource(String sourceId)

This method can be used to programatically change the currently selected source. Usually this is done automatically by the ModulationMatrixController , but if you are implementing a custom UI replacement for that UI component, you can use this functionality.

Note that whenever you call this function (or drag a dragger), it will automatically close all hover popups that are currently active.

setEditCallback

Set a callback that will be executed when the user clicks on "Edit connections".

ScriptModulationMatrix.setEditCallback(var menuItems, var editFunction)

This function can be used to supply additional functions in the context menu of a modulatable UI component.

This method expects two arguments:

1. A single string or an array of strings for each menu item
2. a function or callable object with two parameters that will be executed when you click on said context menu item with the zero based index of the clicked item and the associated target ID of the UI component.

If you want to find out the component that was clicked just pass that into the ScriptModulationMatrix.getComponent() method.

const var m = Engine.createModulationMatrix("Global Modulator Container1");

m.setEditCallback(["funky", "noice"], function(idx, targetId)
{
	Console.print(idx); // 0 if you click funky, 1 if you click on noice...

	Console.print("TARGET: " + targetId);
	Console.print("COMPONENT: " + this.getComponent(targetId).get("id"));
});

The use cases for this method are pretty diverse:

• you can use it to "edit the connections" by showing a matrix component with all connections of the target
• you can use it to add a "clear all connections" function for the given component (or other data management functions like custom save / restore)
• you can use it to reset the intensity values
  

setSourceSelectionCallback

Attaches a callback to be notified whenever a new modulation source is selected.

ScriptModulationMatrix.setSourceSelectionCallback(var sourceSelectionCallback)

This function can be used to attach a callback to be notified when the currently selected modulation source is changed. This is caused by one of two events:

1. You click on a dragger from a ModulationMatrixController .
2. You call ScriptModulationMatrix.setCurrentlySelectedSource() (most likely because you're reimplementing something like the modulation matrix controller with a ScriptPanel).

This can now be used for different things, eg:

• changing the layout of the hover popup that shows all modulation connections of a given UI knob
• highlighting the modulator module on your UI

The function expects a callable object with a single parameter that will be called with the ID string of the source (= the modulator's ID).

Take a look at this snippet for an example use case (showing only the currently selected modulation connection when you hover over a knob).

toBase64

Creates a Base64 string of all connections. Edit on GitHub

ScriptModulationMatrix.toBase64()