Controller

Every declared parameter is held as an atomic double, which the audio thread reads and writes without waiting, and as an Elements value_model<double>, which a control links to. Both start at the parameter’s initial value.

When the host moves a parameter, the value lands in the atomic through set_parameter, and the adapter asks the host for a main-thread callback. There, update_models brings the models up to date, and the controls follow. It assigns only the models whose value has actually changed. A model assignment always notifies, so assigning all of them would redraw the whole editor on every callback, and a value the host echoes back mid gesture would fight the control the user is dragging.

The other direction starts in the editor. A control’s binding calls edit_parameter, which stores the atomic, sets the model and passes the edit on to the edit_sink the plugin installed, which queues it for the host. The audio thread drains that queue without blocking, so an edit never holds up either side.

A parameter is addressed by its index in the list parameters() returns. The id belongs to the host and to the state; the adapter translates between the two. See parameter.

The state is one JSON object, and it is the same thing whether the host is saving a session or the plugin is saving a preset:

plugin is info().id and keeps a state written by another plugin out. version is info().state_version, so a plugin can tell an old layout of its values from the current one. A state written by a later version than the plugin knows is refused rather than misread.

params carries every parameter. A value is found by id, and failing that by name, so a plugin may add, remove, reorder or rename its parameters and an old state still loads. An entry the plugin no longer has is skipped, and a parameter the state does not carry takes its default. Values are clamped into the parameter’s range on the way in.

view holds the editor’s zoom and preset the preset the panel shows. Both belong to the session rather than to the sound, so save_preset leaves them out, and with them the parameters marked dont_save.

A preset is a named state. Factory presets come with the plugin, in factory_presets.json among its resources; user presets live in a presets.json of the user’s own, in a directory named after the plugin’s vendor and name:

Both files are one JSON object of preset name to state, and both are read on first use, so a plugin with no presets pays nothing. Presets keep their files' order: the factory ones as the plugin lists them, a cartridge’s 32 voices in the cartridge’s order, say, and the user’s in the order they were added, a new one at the end.

The names the plugin ships are the plugin’s. save_preset refuses one, rather than leave a preset that loads as the user’s while the list calls it factory and nothing in the editor will delete it. Only user presets can be saved or deleted.

The preset shown is the name the state was last loaded from or saved as, and whether any parameter has moved since, by the panel or by the host. Both ride in the state, so a session comes back showing what it was saved with. Naming a preset starts it unedited, and a preset file carries neither.

Nothing here has to be wired. The standard header along the top of the editor lists the presets, loads the one chosen, saves and deletes, and shows the current name with a * when it has been edited, all of it through the controller.

The list is fixed for the life of the plugin, so it is returned from a static array. The index of a parameter in it is how the plugin’s own code addresses it, and the enum that names those indices belongs next to the array. The delay example declares two:

get_parameter and changes are the calls the audio thread makes. They read atomics and never wait. The rest are main thread.

changes is how the plugin knows to call the processor's parameters_changed: it compares the count before each run of frames. Setting a parameter to the value it already holds is no change.

The template forms hand the value over as the type the parameter was declared with, which is what a plugin actually works in. A controller usually wraps each one in an accessor of its own, as anna_5 does:

A Debug build asserts that the type asked for matches the kind the parameter was declared with. Where a parameter’s units and the plugin’s are not the same thing, the accessor is where they are reconciled:

set_parameter is what the host’s own changes arrive through, so a controller that wants to know when a parameter moves overrides it and calls the base. The call comes from the audio thread while the plugin is processing, so an override must not block or allocate there. Loading a state or a preset goes through it too.

update_models is called on the main thread after the host has changed anything, and by state once a state is loaded. It assigns only the models whose value has changed.

These are what the editor changes a parameter through, on the main thread. A presenter's bind calls all three: the two gesture calls bracket a drag, so the host records it as one move rather than a scatter of values, and edit_parameter carries each value as the control passes through it. A plugin binds its controls and calls none of this itself.

edit_parameter is virtual, so a controller that has to act on an edit from the editor, and not on a change from the host, overrides this one rather than set_parameter.

The three go out through the edit_sink the plugin installed. That is plugin, which queues them and passes them to the host from the audio thread when that takes no wait, so the editor never blocks on the host.

These are how a state finds its way back to the current parameters, by id first and then by name. A plugin rarely needs them, since it knows its own indices.

The host calls save_state and load_state through the adapter, which wraps the host’s own stream as a q_plug::ostream or istream, two virtuals wide. A plugin does not call these.

A refused state changes nothing. A state that is taken sets every parameter, those it carries and those it does not, then the zoom and the preset, then calls load_extra and update_models.

The zoom is kept here, with the state, so a session comes back at the zoom it was saved at. The presenter reads it when the editor opens and writes it when the user zooms; a plugin has no reason to touch it. A preset does not carry it.

load_preset tells the host every saved value, as an edit of its own. Taking the state alone would only set the values, which is right when it is the host that is loading, but a preset chosen in the editor is the plugin’s own edit: unannounced, the host’s automation would still hold the values the preset replaced.

save_preset does not name the preset it just wrote. Naming it is a separate step, so the caller decides whether the panel should follow. The header’s Save dialog does both:

add_presets is for states from elsewhere, many at once: a synth that imports a cartridge of 32 voices adds them in one write rather than 32, and they appear in the menu in the order given. Dexter does this with the DX7 cartridges dropped on it:

A plugin with more to keep than its parameters overrides these. Everything a parameter covers is already saved, so this is for what is not a parameter. version is the state_version the state was written with, so a plugin can read an older layout of its own.

Both are called on the main thread, save_extra at the end of state() and load_extra after the parameters are set and before the models are brought up to date. Keep to keys of the plugin’s own; plugin, version, params, view and preset are taken.

plugin calls init once, on the main thread, before anything else runs. It cannot happen in the constructor, since parameters() is virtual. A test that stands a controller up without a plugin calls it from a derived class with a sink of its own.