1 //------------------------------------------------------------------------
4 // Category : Interfaces
5 // Filename : pluginterfaces/vst/ivsteditcontroller.h
6 // Created by : Steinberg, 09/2005
7 // Description : VST Edit Controller Interfaces
9 //-----------------------------------------------------------------------------
10 // This file is part of a Steinberg SDK. It is subject to the license terms
11 // in the LICENSE file found in the top-level directory of this distribution
12 // and at www.steinberg.net/sdklicenses.
13 // No part of the SDK, including this file, may be copied, modified, propagated,
14 // or distributed except according to the terms contained in the LICENSE file.
15 //-----------------------------------------------------------------------------
19 #include "pluginterfaces/base/ipluginbase.h"
20 #include "pluginterfaces/vst/vsttypes.h"
22 //------------------------------------------------------------------------
23 #include "pluginterfaces/base/falignpush.h"
24 //------------------------------------------------------------------------
26 //------------------------------------------------------------------------
27 /** Class Category Name for Controller Component */
28 //------------------------------------------------------------------------
29 #ifndef kVstComponentControllerClass
30 #define kVstComponentControllerClass "Component Controller Class"
33 //------------------------------------------------------------------------
38 //------------------------------------------------------------------------
41 //------------------------------------------------------------------------
42 /** Controller Parameter Info.
43 * A parameter info describes a parameter of the controller.
44 * The id must always be the same for a parameter as this uniquely identifies the parameter.
48 //------------------------------------------------------------------------
49 ParamID id
; ///< unique identifier of this parameter (named tag too)
50 String128 title
; ///< parameter title (e.g. "Volume")
51 String128 shortTitle
; ///< parameter shortTitle (e.g. "Vol")
52 String128 units
; ///< parameter unit (e.g. "dB")
53 int32 stepCount
; ///< number of discrete steps (0: continuous, 1: toggle, discrete value otherwise
54 ///< (corresponding to max - min, for example: 127 for a min = 0 and a max = 127) - see \ref vst3ParameterIntro)
55 ParamValue defaultNormalizedValue
; ///< default normalized value [0,1] (in case of discrete value: defaultNormalizedValue = defDiscreteValue / stepCount)
56 UnitID unitId
; ///< id of unit this parameter belongs to (see \ref vst3Units)
58 int32 flags
; ///< ParameterFlags (see below)
61 kNoFlags
= 0, ///< no flags wanted
62 kCanAutomate
= 1 << 0, ///< parameter can be automated
63 kIsReadOnly
= 1 << 1, ///< parameter cannot be changed from outside the plug-in (implies that kCanAutomate is NOT set)
64 kIsWrapAround
= 1 << 2, ///< attempts to set the parameter value out of the limits will result in a wrap around [SDK 3.0.2]
65 kIsList
= 1 << 3, ///< parameter should be displayed as list in generic editor or automation editing [SDK 3.1.0]
66 kIsHidden
= 1 << 4, ///< parameter should be NOT displayed and cannot be changed from outside the plug-in
67 ///< (implies that kCanAutomate is NOT set and kIsReadOnly is set) [SDK 3.7.0]
69 kIsProgramChange
= 1 << 15, ///< parameter is a program change (unitId gives info about associated unit
70 ///< - see \ref vst3ProgramLists)
71 kIsBypass
= 1 << 16 ///< special bypass parameter (only one allowed): plug-in can handle bypass
72 ///< (highly recommended to export a bypass parameter for effect plug-in)
74 //------------------------------------------------------------------------
77 //------------------------------------------------------------------------
78 /** View Types used for IEditController::createView */
79 //------------------------------------------------------------------------
81 const CString kEditor
= "editor";
84 //------------------------------------------------------------------------
85 /** Flags used for IComponentHandler::restartComponent */
88 /** The Component should be reloaded
89 * The host has to unload completely the plug-in (controller/processor) and reload it.
91 kReloadComponent
= 1 << 0,
93 /** Input / Output Bus configuration has changed
94 * The plug-in informs the host that either the bus configuration or the bus count has changed.
95 * The host has to deactivate the plug-in, asks the plug-in for its wanted new bus configurations,
96 * adapts its processing graph and reactivate the plug-in.
100 /** Multiple parameter values have changed (as result of a program change for example)
101 * The host invalidates all caches of parameter values and asks the edit controller for the current values.
103 kParamValuesChanged
= 1 << 2,
105 /** Latency has changed
106 * The plug informs the host that its latency has changed, getLatencySamples should return the new latency after setActive (true) was called
107 * The host has to deactivate and reactivate the plug-in, then afterwards the host could ask for the current latency (getLatencySamples)
108 * see IAudioProcessor::getLatencySamples
110 kLatencyChanged
= 1 << 3,
112 /** Parameter titles, default values or flags (ParameterFlags) have changed
113 * The host invalidates all caches of parameter infos and asks the edit controller for the current infos.
115 kParamTitlesChanged
= 1 << 4,
117 /** MIDI Controllers and/or Program Changes Assignments have changed
118 * The plug-in informs the host that its MIDI-CC mapping has changed (for example after a MIDI learn or new loaded preset)
119 * or if the stepCount or UnitID of a ProgramChange parameter has changed.
120 * The host has to rebuild the MIDI-CC => parameter mapping (getMidiControllerAssignment)
121 * and reread program changes parameters (stepCount and associated unitID)
123 kMidiCCAssignmentChanged
= 1 << 5,
125 /** Note Expression has changed (info, count, PhysicalUIMapping, ...)
126 * Either the note expression type info, the count of note expressions or the physical UI mapping has changed.
127 * The host invalidates all caches of note expression infos and asks the edit controller for the current ones.
128 * See INoteExpressionController, NoteExpressionTypeInfo and INoteExpressionPhysicalUIMapping
130 kNoteExpressionChanged
= 1 << 6,
132 /** Input / Output bus titles have changed
133 * The host invalidates all caches of bus titles and asks the edit controller for the current titles.
135 kIoTitlesChanged
= 1 << 7,
137 /** Prefetch support has changed
138 * The plug-in informs the host that its PrefetchSupport has changed
139 * The host has to deactivate the plug-in, calls IPrefetchableSupport::getPrefetchableSupport and reactivate the plug-in
140 * see IPrefetchableSupport
142 kPrefetchableSupportChanged
= 1 << 8,
144 /** RoutingInfo has changed
145 * The plug-in informs the host that its internal routing (relation of an event-input-channel to an audio-output-bus) has changed
146 * The host ask the plug-in for the new routing with IComponent::getRoutingInfo, \ref vst3Routing
149 kRoutingInfoChanged
= 1 << 9
152 //------------------------------------------------------------------------
153 /** Host callback interface for an edit controller: Vst::IComponentHandler
154 \ingroup vstIHost vst300
159 Allow transfer of parameter editing to component (processor) via host and support automation.
160 Cause the host to react on configuration changes (restartComponent).
162 \see \ref IEditController
164 class IComponentHandler
: public FUnknown
167 //------------------------------------------------------------------------
168 /** To be called before calling a performEdit (e.g. on mouse-click-down event).
169 This must be called in the UI-Thread context! */
170 virtual tresult PLUGIN_API
beginEdit (ParamID id
) = 0;
172 /** Called between beginEdit and endEdit to inform the handler that a given parameter has a new
173 * value. This must be called in the UI-Thread context! */
174 virtual tresult PLUGIN_API
performEdit (ParamID id
, ParamValue valueNormalized
) = 0;
176 /** To be called after calling a performEdit (e.g. on mouse-click-up event).
177 This must be called in the UI-Thread context! */
178 virtual tresult PLUGIN_API
endEdit (ParamID id
) = 0;
180 /** Instructs host to restart the component. This must be called in the UI-Thread context!
181 \param flags is a combination of RestartFlags */
182 virtual tresult PLUGIN_API
restartComponent (int32 flags
) = 0;
184 //------------------------------------------------------------------------
185 static const FUID iid
;
188 DECLARE_CLASS_IID (IComponentHandler
, 0x93A0BEA3, 0x0BD045DB, 0x8E890B0C, 0xC1E46AC6)
190 //------------------------------------------------------------------------
191 /** Extended host callback interface for an edit controller: Vst::IComponentHandler2
192 \ingroup vstIHost vst310
194 - [extends IComponentHandler]
199 - Setting dirty state of the plug-in
200 - Requesting the host to open the editor
202 The other part handles parameter group editing from the plug-in UI. It wraps a set of \ref IComponentHandler::beginEdit /
203 \ref Steinberg::Vst::IComponentHandler::performEdit / \ref Steinberg::Vst::IComponentHandler::endEdit functions (see \ref IComponentHandler)
204 which should use the same timestamp in the host when writing automation.
205 This allows for better synchronizing of multiple parameter changes at once.
207 \section IComponentHandler2Example Examples of different use cases
210 //--------------------------------------
211 // we are in the editcontroller...
212 // in case of multiple switch buttons (with associated ParamID 1 and 3)
214 hostHandler2->startGroupEdit ();
215 hostHandler->beginEdit (1);
216 hostHandler->beginEdit (3);
217 hostHandler->performEdit (1, 1.0);
218 hostHandler->performEdit (3, 0.0); // the opposite of paramID 1 for example
221 hostHandler->endEdit (1);
222 hostHandler->endEdit (3);
223 hostHandler2->finishGroupEdit ();
226 //--------------------------------------
227 // in case of multiple faders (with associated ParamID 1 and 3)
229 hostHandler2->startGroupEdit ();
230 hostHandler->beginEdit (1);
231 hostHandler->beginEdit (3);
232 hostHandler2->finishGroupEdit ();
235 hostHandler2->startGroupEdit ();
236 hostHandler->performEdit (1, x); // x the wanted value
237 hostHandler->performEdit (3, x);
238 hostHandler2->finishGroupEdit ();
241 hostHandler2->startGroupEdit ();
242 hostHandler->endEdit (1);
243 hostHandler->endEdit (3);
244 hostHandler2->finishGroupEdit ();
246 \see \ref IComponentHandler, \ref IEditController
248 class IComponentHandler2
: public FUnknown
251 //------------------------------------------------------------------------
252 /** Tells host that the plug-in is dirty (something besides parameters has changed since last save),
253 if true the host should apply a save before quitting. */
254 virtual tresult PLUGIN_API
setDirty (TBool state
) = 0;
256 /** Tells host that it should open the plug-in editor the next time it's possible.
257 You should use this instead of showing an alert and blocking the program flow (especially on loading projects). */
258 virtual tresult PLUGIN_API
requestOpenEditor (FIDString name
= ViewType::kEditor
) = 0;
260 //------------------------------------------------------------------------
261 /** Starts the group editing (call before a \ref IComponentHandler::beginEdit),
262 the host will keep the current timestamp at this call and will use it for all \ref IComponentHandler::beginEdit
263 / \ref IComponentHandler::performEdit / \ref IComponentHandler::endEdit calls until a \ref finishGroupEdit (). */
264 virtual tresult PLUGIN_API
startGroupEdit () = 0;
266 /** Finishes the group editing started by a \ref startGroupEdit (call after a \ref IComponentHandler::endEdit). */
267 virtual tresult PLUGIN_API
finishGroupEdit () = 0;
269 //------------------------------------------------------------------------
270 static const FUID iid
;
273 DECLARE_CLASS_IID (IComponentHandler2
, 0xF040B4B3, 0xA36045EC, 0xABCDC045, 0xB4D5A2CC)
275 //------------------------------------------------------------------------
276 /** Extended host callback interface for an edit controller: Vst::IComponentHandlerBusActivation
277 \ingroup vstIHost vst368
279 - [extends IComponentHandler]
283 Allows the plug-in to request the host to activate or deactivate a specific bus.
284 If the host accepts this request, it will call later on \ref IComponent::activateBus.
285 This is particularly useful for instruments with more than 1 outputs, where the user could request
286 from the plug-in UI a given output bus activation.
289 // somewhere in your code when you need to inform the host to enable a specific Bus.
290 FUnknownPtr<IComponentHandlerBusActivation> busActivation (componentHandler);
293 // here we want to activate our audio input sidechain (the 2cd input bus: index 1)
294 busActivation->requestBusActivation (kAudio, kInput, 1, true);
297 \see \ref IComponentHandler
299 class IComponentHandlerBusActivation
: public FUnknown
302 //------------------------------------------------------------------------
303 /** request the host to activate or deactivate a specific bus. */
304 virtual tresult PLUGIN_API
requestBusActivation (MediaType type
, BusDirection dir
, int32 index
,
307 //------------------------------------------------------------------------
308 static const FUID iid
;
311 DECLARE_CLASS_IID (IComponentHandlerBusActivation
, 0x067D02C1, 0x5B4E274D, 0xA92D90FD, 0x6EAF7240)
313 //------------------------------------------------------------------------
314 /** Extended host callback interface for an edit controller: Vst::IProgress
315 \ingroup vstIHost vst370
317 - [extends IComponentHandler]
321 Allows the plug-in to request the host to create a progress for some specific tasks which take
322 some time. The host can visualize the progress as read-only UI elements. For example,
323 after loading a project where a plug-in needs to load extra
324 data (e.g. samples) in a background thread, this enables the host to get and visualize the current status of the loading
325 progress and to inform the user when the loading is finished.
326 Note: During the progress, the host can unload the plug-in at any time. Make sure that the plug-in
327 supports this use case.
329 \section IProgressExample Example
332 //--------------------------------------
333 // we are in the editcontroller:
334 // as member: IProgress::ID mProgressID;
336 FUnknownPtr<IProgress> progress (componentHandler);
338 progress->start (IProgress::ProgressType::UIBackgroundTask, STR ("Load Samples..."), mProgressID);
341 myProgressValue += incProgressStep;
342 FUnknownPtr<IProgress> progress (componentHandler);
344 progress->update (mProgressID, myProgressValue);
347 FUnknownPtr<IProgress> progress (componentHandler);
349 progress->finish (mProgressID);
352 \see \ref IComponentHandler
354 class IProgress
: public FUnknown
357 //------------------------------------------------------------------------
358 enum ProgressType
: uint32
360 AsyncStateRestoration
= 0, ///< plug-in state is restored async (in a background Thread)
361 UIBackgroundTask
///< a plug-in task triggered by a UI action
366 /** Start a new progress of a given type and optional Description. outID is as ID created by the
367 * host to identify this newly created progress (for update and finish method) */
368 virtual tresult PLUGIN_API
start (ProgressType type
, const tchar
* optionalDescription
,
370 /** Update the progress value (normValue between [0, 1]) associated to the given id */
371 virtual tresult PLUGIN_API
update (ID id
, ParamValue normValue
) = 0;
372 /** Finish the progress associated to the given id */
373 virtual tresult PLUGIN_API
finish (ID id
) = 0;
375 //------------------------------------------------------------------------
376 static const FUID iid
;
379 DECLARE_CLASS_IID (IProgress
, 0x00C9DC5B, 0x9D904254, 0x91A388C8, 0xB4E91B69)
381 //------------------------------------------------------------------------
382 /** Edit controller component interface: Vst::IEditController
383 \ingroup vstIPlug vst300
388 The controller part of an effect or instrument with parameter handling (export, definition, conversion...).
389 \see \ref IComponent::getControllerClassId, \ref IMidiMapping
391 class IEditController
: public IPluginBase
394 //------------------------------------------------------------------------
395 /** Receives the component state. */
396 virtual tresult PLUGIN_API
setComponentState (IBStream
* state
) = 0;
398 /** Sets the controller state. */
399 virtual tresult PLUGIN_API
setState (IBStream
* state
) = 0;
401 /** Gets the controller state. */
402 virtual tresult PLUGIN_API
getState (IBStream
* state
) = 0;
404 // parameters -------------------------
405 /** Returns the number of parameters exported. */
406 virtual int32 PLUGIN_API
getParameterCount () = 0;
407 /** Gets for a given index the parameter information. */
408 virtual tresult PLUGIN_API
getParameterInfo (int32 paramIndex
, ParameterInfo
& info
/*out*/) = 0;
410 /** Gets for a given paramID and normalized value its associated string representation. */
411 virtual tresult PLUGIN_API
getParamStringByValue (ParamID id
, ParamValue valueNormalized
/*in*/, String128 string
/*out*/) = 0;
412 /** Gets for a given paramID and string its normalized value. */
413 virtual tresult PLUGIN_API
getParamValueByString (ParamID id
, TChar
* string
/*in*/, ParamValue
& valueNormalized
/*out*/) = 0;
415 /** Returns for a given paramID and a normalized value its plain representation
416 (for example -6 for -6dB - see \ref vst3AutomationIntro). */
417 virtual ParamValue PLUGIN_API
normalizedParamToPlain (ParamID id
, ParamValue valueNormalized
) = 0;
418 /** Returns for a given paramID and a plain value its normalized value. (see \ref vst3AutomationIntro) */
419 virtual ParamValue PLUGIN_API
plainParamToNormalized (ParamID id
, ParamValue plainValue
) = 0;
421 /** Returns the normalized value of the parameter associated to the paramID. */
422 virtual ParamValue PLUGIN_API
getParamNormalized (ParamID id
) = 0;
423 /** Sets the normalized value to the parameter associated to the paramID. The controller must never
424 pass this value-change back to the host via the IComponentHandler. It should update the according
425 GUI element(s) only!*/
426 virtual tresult PLUGIN_API
setParamNormalized (ParamID id
, ParamValue value
) = 0;
428 // handler ----------------------------
429 /** Gets from host a handler which allows the Plugin-in to communicate with the host.
430 Note: This is mandatory if the host is using the IEditController! */
431 virtual tresult PLUGIN_API
setComponentHandler (IComponentHandler
* handler
) = 0;
433 // view -------------------------------
434 /** Creates the editor view of the plug-in, currently only "editor" is supported, see \ref ViewType.
435 The life time of the editor view will never exceed the life time of this controller instance. */
436 virtual IPlugView
* PLUGIN_API
createView (FIDString name
) = 0;
438 //------------------------------------------------------------------------
439 static const FUID iid
;
442 DECLARE_CLASS_IID (IEditController
, 0xDCD7BBE3, 0x7742448D, 0xA874AACC, 0x979C759E)
444 //------------------------------------------------------------------------
448 kCircularMode
= 0, ///< Circular with jump to clicked position
449 kRelativCircularMode
, ///< Circular without jump to clicked position
450 kLinearMode
///< Linear: depending on vertical movement
453 //------------------------------------------------------------------------
454 /** \defgroup vst3typedef VST 3 Data Types */
456 //------------------------------------------------------------------------
457 /** Knob Mode Type */
458 typedef int32 KnobMode
;
461 //------------------------------------------------------------------------
462 /** Edit controller component interface extension: Vst::IEditController2
463 \ingroup vstIPlug vst310
465 - [extends IEditController]
469 Extension to allow the host to inform the plug-in about the host Knob Mode,
470 and to open the plug-in about box or help documentation.
472 \see \ref IEditController, \ref EditController
474 class IEditController2
: public FUnknown
477 /** Host could set the Knob Mode for the plug-in. Return kResultFalse means not supported mode. \see KnobModes. */
478 virtual tresult PLUGIN_API
setKnobMode (KnobMode mode
) = 0;
480 /** Host could ask to open the plug-in help (could be: opening a PDF document or link to a web page).
481 The host could call it with onlyCheck set to true for testing support of open Help.
482 Return kResultFalse means not supported function. */
483 virtual tresult PLUGIN_API
openHelp (TBool onlyCheck
) = 0;
485 /** Host could ask to open the plug-in about box.
486 The host could call it with onlyCheck set to true for testing support of open AboutBox.
487 Return kResultFalse means not supported function. */
488 virtual tresult PLUGIN_API
openAboutBox (TBool onlyCheck
) = 0;
490 //------------------------------------------------------------------------
491 static const FUID iid
;
494 DECLARE_CLASS_IID (IEditController2
, 0x7F4EFE59, 0xF3204967, 0xAC27A3AE, 0xAFB63038)
496 //------------------------------------------------------------------------
497 /** MIDI Mapping interface: Vst::IMidiMapping
498 \ingroup vstIPlug vst301
500 - [extends IEditController]
504 MIDI controllers are not transmitted directly to a VST component. MIDI as hardware protocol has
505 restrictions that can be avoided in software. Controller data in particular come along with unclear
506 and often ignored semantics. On top of this they can interfere with regular parameter automation and
507 the host is unaware of what happens in the plug-in when passing MIDI controllers directly.
509 So any functionality that is to be controlled by MIDI controllers must be exported as regular parameter.
510 The host will transform incoming MIDI controller data using this interface and transmit them as regular
511 parameter change. This allows the host to automate them in the same way as other parameters.
512 CtrlNumber can be a typical MIDI controller value extended to some others values like pitchbend or
513 aftertouch (see \ref ControllerNumbers).
514 If the mapping has changed, the plug-in must call IComponentHandler::restartComponent (kMidiCCAssignmentChanged)
515 to inform the host about this change.
517 \section IMidiMappingExample Example
520 //--------------------------------------
521 // in myeditcontroller.h
522 class MyEditController: public EditControllerEx1, public IMidiMapping
525 //---IMidiMapping---------------------------
526 tresult PLUGIN_API getMidiControllerAssignment (int32 busIndex, int16 channel, CtrlNumber midiControllerNumber, ParamID& id) SMTG_OVERRIDE;
527 //---Interface---------
528 OBJ_METHODS (MyEditController, EditControllerEx1)
530 DEF_INTERFACE (IMidiMapping)
531 END_DEFINE_INTERFACES (MyEditController)
532 REFCOUNT_METHODS (MyEditController)
535 //--------------------------------------
536 // in myeditcontroller.cpp
537 tresult PLUGIN_API MyEditController::getMidiControllerAssignment (int32 busIndex, int16 midiChannel, CtrlNumber midiControllerNumber, ParamID& tag)
539 // for my first Event bus and for MIDI channel 0 and for MIDI CC Volume only
540 if (busIndex == 0 && midiChannel == 0 && midiControllerNumber == kCtrlVolume)
550 class IMidiMapping
: public FUnknown
553 /** Gets an (preferred) associated ParamID for a given Input Event Bus index, channel and MIDI Controller.
554 * @param[in] busIndex - index of Input Event Bus
555 * @param[in] channel - channel of the bus
556 * @param[in] midiControllerNumber - see \ref ControllerNumbers for expected values (could be bigger than 127)
557 * @param[in] id - return the associated ParamID to the given midiControllerNumber
559 virtual tresult PLUGIN_API
getMidiControllerAssignment (int32 busIndex
, int16 channel
,
560 CtrlNumber midiControllerNumber
, ParamID
& id
/*out*/) = 0;
562 //------------------------------------------------------------------------
563 static const FUID iid
;
566 DECLARE_CLASS_IID (IMidiMapping
, 0xDF0FF9F7, 0x49B74669, 0xB63AB732, 0x7ADBF5E5)
568 //------------------------------------------------------------------------
569 /** Parameter Editing from host: Vst::IEditControllerHostEditing
570 \ingroup vstIPlug vst350
572 - [extends IEditController]
576 If this interface is implemented by the edit controller, and when performing edits from outside
577 the plug-in (host / remote) of a not automatable and not read-only, and not hidden flagged parameter (kind of helper parameter),
578 the host will start with a beginEditFromHost before calling setParamNormalized and end with an endEditFromHost.
579 Here the sequence that the host will call:
581 \section IEditControllerExample Example
584 //------------------------------------------------------------------------
585 plugEditController->beginEditFromHost (id);
586 plugEditController->setParamNormalized (id, value);
587 plugEditController->setParamNormalized (id, value + 0.1);
589 plugEditController->endEditFromHost (id);
592 \see \ref IEditController
594 class IEditControllerHostEditing
: public FUnknown
597 /** Called before a setParamNormalized sequence, a endEditFromHost will be call at the end of the editing action. */
598 virtual tresult PLUGIN_API
beginEditFromHost (ParamID paramID
) = 0;
600 /** Called after a beginEditFromHost and a sequence of setParamNormalized. */
601 virtual tresult PLUGIN_API
endEditFromHost (ParamID paramID
) = 0;
603 //------------------------------------------------------------------------
604 static const FUID iid
;
607 DECLARE_CLASS_IID (IEditControllerHostEditing
, 0xC1271208, 0x70594098, 0xB9DD34B3, 0x6BB0195E)
609 //------------------------------------------------------------------------
611 } // namespace Steinberg
613 //------------------------------------------------------------------------
614 #include "pluginterfaces/base/falignpop.h"
615 //------------------------------------------------------------------------