Thursday, January 25, 2024
The latest version of Polymeter adds a long-overdue feature: the Modulations bar now optionally shows targets as well as sources. This can be very useful for complex modulation networks. Until now, the only way to see the modulation targets of a track was via the Graph bar, with the graph’s Scope set to Targets or Bidirectional. The Graph bar requires installing Graphviz, so users who didn’t do that had no way of viewing modulation targets at all. But even if they did have Graphviz installed, the Modulations bar is easier to use, and it’s also the obvious place to look for this information.
To use this new feature, select Show Targets in the Modulation bar’s context menu. This command toggles the visibility of the Targets pane, in other words it shows the pane if it’s hidden, or hides it if it’s showing. When the Targets pane is shown, the Modulations bar is split into two panes, separated by a draggable splitter. The window is split horizontally by default, but if you prefer a vertical split, right-click the splitter to show its context menu, and select Vertical.
You might wonder why this feature wasn’t added sooner. It’s actually a challenge to implement, because the application’s architecture has a fundamental asymmetry between modulation sources and targets. Basically the issue is that modulations are singly- rather than doubly-linked. Each track keeps a list of the tracks that modulate it, i.e. its sources, but a track does NOT keep a list of tracks that it modulates. It could, but it doesn’t, and that’s because the sequencer engine—the part of the app that actually sequences MIDI, as opposed to mere user interface code—doesn’t care about modulation targets.
When the sequencer processes a track, it asks the question: “do any other tracks modulate this track?” In other words, it looks at the track’s modulation sources, also known as modulators. The sequencer never asks the question: “what tracks does this track modulate?” The sequencer’s top-level loop completely ignores modulator tracks, because they don’t output MIDI events, by definition. Modulator tracks are only accessed while processing a non-modulator track. More formally, the sequencer iterates modulation sources, but never iterates modulation “sinks”, and this is the reason for the architectural asymmetry.
The primary constraint on the design of the Polymeter application is optimizing the sequencer to maximize speed and throughput. Doubly-linked modulations would not help the sequencer at all. A few aspects of the user interface might benefit from doubly-linked modulations, but this is outweighed by much more complicated code, and the risk of many new bugs, particularly in the area of undoing edits.
So how do we answer the question, “what tracks does this track modulate”? We need that information in order to show the modulations graph, and we also need it to show targets in the Modulations bar. It’s done by creating a special type of lookup table called a cross-reference. To build the cross-reference, we iterate all of the tracks, and for each track, iterate its modulators, if any. While doing that, we put the modulators in “buckets” that correspond to target tracks. That might sound slow, but it’s the kind of thing computers are good at. Also, that process has been greatly optimized in this version, by storing the cross-reference in a “flat” one-dimensional array. Previous versions stored the cross-reference in an array of dynamic arrays, but this incurs significant performance costs, due to the potentially large number of arrays that must be reallocated and copied as they grow.
Stress testing was done to verify that the new modulation targets cross-reference consistently improves performance (it does). The second image in this post shows the stress test in the Graph bar, rendered by Graphviz, which after many years of faithful service continues to be one of my favorite open-source software projects ever.
