Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

ivsteditcontroller.h 26KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615
  1. //------------------------------------------------------------------------
  2. // Project : VST SDK
  3. //
  4. // Category : Interfaces
  5. // Filename : pluginterfaces/vst/ivsteditcontroller.h
  6. // Created by : Steinberg, 09/2005
  7. // Description : VST Edit Controller Interfaces
  8. //
  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. //-----------------------------------------------------------------------------
  16. #pragma once
  17. #include "pluginterfaces/base/ipluginbase.h"
  18. #include "pluginterfaces/vst/vsttypes.h"
  19. //------------------------------------------------------------------------
  20. #include "pluginterfaces/base/falignpush.h"
  21. //------------------------------------------------------------------------
  22. //------------------------------------------------------------------------
  23. /** Class Category Name for Controller Component */
  24. //------------------------------------------------------------------------
  25. #ifndef kVstComponentControllerClass
  26. #define kVstComponentControllerClass "Component Controller Class"
  27. #endif
  28. //------------------------------------------------------------------------
  29. namespace Steinberg {
  30. class IPlugView;
  31. class IBStream;
  32. //------------------------------------------------------------------------
  33. namespace Vst {
  34. //------------------------------------------------------------------------
  35. /** Controller Parameter Info.
  36. * A parameter info describes a parameter of the controller.
  37. * The id must always be the same for a parameter as this uniquely identifies the parameter.
  38. */
  39. struct ParameterInfo
  40. {
  41. //------------------------------------------------------------------------
  42. ParamID id; ///< unique identifier of this parameter (named tag too)
  43. String128 title; ///< parameter title (e.g. "Volume")
  44. String128 shortTitle; ///< parameter shortTitle (e.g. "Vol")
  45. String128 units; ///< parameter unit (e.g. "dB")
  46. int32 stepCount; ///< number of discrete steps (0: continuous, 1: toggle, discrete value otherwise
  47. ///< (corresponding to max - min, for example: 127 for a min = 0 and a max = 127) - see \ref vst3ParameterIntro)
  48. ParamValue defaultNormalizedValue; ///< default normalized value [0,1] (in case of discrete value: defaultNormalizedValue = defDiscreteValue / stepCount)
  49. UnitID unitId; ///< id of unit this parameter belongs to (see \ref vst3Units)
  50. int32 flags; ///< ParameterFlags (see below)
  51. enum ParameterFlags
  52. {
  53. kNoFlags = 0, ///< no flags wanted
  54. kCanAutomate = 1 << 0, ///< parameter can be automated
  55. kIsReadOnly = 1 << 1, ///< parameter cannot be changed from outside the plug-in (implies that kCanAutomate is NOT set)
  56. kIsWrapAround = 1 << 2, ///< attempts to set the parameter value out of the limits will result in a wrap around [SDK 3.0.2]
  57. kIsList = 1 << 3, ///< parameter should be displayed as list in generic editor or automation editing [SDK 3.1.0]
  58. kIsHidden = 1 << 4, ///< parameter should be NOT displayed and cannot be changed from outside the plug-in
  59. ///< (implies that kCanAutomate is NOT set and kIsReadOnly is set) [SDK 3.7.0]
  60. kIsProgramChange = 1 << 15, ///< parameter is a program change (unitId gives info about associated unit
  61. ///< - see \ref vst3ProgramLists)
  62. kIsBypass = 1 << 16 ///< special bypass parameter (only one allowed): plug-in can handle bypass
  63. ///< (highly recommended to export a bypass parameter for effect plug-in)
  64. };
  65. //------------------------------------------------------------------------
  66. };
  67. //------------------------------------------------------------------------
  68. /** View Types used for IEditController::createView */
  69. //------------------------------------------------------------------------
  70. namespace ViewType {
  71. const CString kEditor = "editor";
  72. }
  73. //------------------------------------------------------------------------
  74. /** Flags used for IComponentHandler::restartComponent */
  75. enum RestartFlags
  76. {
  77. /** The Component should be reloaded
  78. * The host has to unload completely the plug-in (controller/processor) and reload it.
  79. * [SDK 3.0.0] */
  80. kReloadComponent = 1 << 0,
  81. /** Input / Output Bus configuration has changed
  82. * The plug-in informs the host that either the bus configuration or the bus count has changed.
  83. * The host has to deactivate the plug-in, asks the plug-in for its wanted new bus configurations,
  84. * adapts its processing graph and reactivate the plug-in.
  85. * [SDK 3.0.0] */
  86. kIoChanged = 1 << 1,
  87. /** Multiple parameter values have changed (as result of a program change for example)
  88. * The host invalidates all caches of parameter values and asks the edit controller for the current values.
  89. * [SDK 3.0.0] */
  90. kParamValuesChanged = 1 << 2,
  91. /** Latency has changed
  92. * The plug informs the host that its latency has changed, getLatencySamples should return the new latency after setActive (true) was called
  93. * The host has to deactivate and reactivate the plug-in, then afterwards the host could ask for the current latency (getLatencySamples)
  94. * see IAudioProcessor::getLatencySamples
  95. * [SDK 3.0.0] */
  96. kLatencyChanged = 1 << 3,
  97. /** Parameter titles, default values or flags (ParameterFlags) have changed
  98. * The host invalidates all caches of parameter infos and asks the edit controller for the current infos.
  99. * [SDK 3.0.0] */
  100. kParamTitlesChanged = 1 << 4,
  101. /** MIDI Controllers and/or Program Changes Assignments have changed
  102. * The plug-in informs the host that its MIDI-CC mapping has changed (for example after a MIDI learn or new loaded preset)
  103. * or if the stepCount or UnitID of a ProgramChange parameter has changed.
  104. * The host has to rebuild the MIDI-CC => parameter mapping (getMidiControllerAssignment)
  105. * and reread program changes parameters (stepCount and associated unitID)
  106. * [SDK 3.0.1] */
  107. kMidiCCAssignmentChanged = 1 << 5,
  108. /** Note Expression has changed (info, count, PhysicalUIMapping, ...)
  109. * Either the note expression type info, the count of note expressions or the physical UI mapping has changed.
  110. * The host invalidates all caches of note expression infos and asks the edit controller for the current ones.
  111. * See INoteExpressionController, NoteExpressionTypeInfo and INoteExpressionPhysicalUIMapping
  112. * [SDK 3.5.0] */
  113. kNoteExpressionChanged = 1 << 6,
  114. /** Input / Output bus titles have changed
  115. * The host invalidates all caches of bus titles and asks the edit controller for the current titles.
  116. * [SDK 3.5.0] */
  117. kIoTitlesChanged = 1 << 7,
  118. /** Prefetch support has changed
  119. * The plug-in informs the host that its PrefetchSupport has changed
  120. * The host has to deactivate the plug-in, calls IPrefetchableSupport::getPrefetchableSupport and reactivate the plug-in
  121. * see IPrefetchableSupport
  122. * [SDK 3.6.1] */
  123. kPrefetchableSupportChanged = 1 << 8,
  124. /** RoutingInfo has changed
  125. * The plug-in informs the host that its internal routing (relation of an event-input-channel to an audio-output-bus) has changed
  126. * The host ask the plug-in for the new routing with IComponent::getRoutingInfo, \ref vst3Routing
  127. * see IComponent
  128. * [SDK 3.6.6] */
  129. kRoutingInfoChanged = 1 << 9
  130. };
  131. //------------------------------------------------------------------------
  132. /** Host callback interface for an edit controller: Vst::IComponentHandler
  133. \ingroup vstIHost vst300
  134. - [host imp]
  135. - [released: 3.0.0]
  136. - [mandatory]
  137. Allow transfer of parameter editing to component (processor) via host and support automation.
  138. Cause the host to react on configuration changes (restartComponent).
  139. \see \ref IEditController
  140. */
  141. class IComponentHandler : public FUnknown
  142. {
  143. public:
  144. //------------------------------------------------------------------------
  145. /** To be called before calling a performEdit (e.g. on mouse-click-down event).
  146. This must be called in the UI-Thread context! */
  147. virtual tresult PLUGIN_API beginEdit (ParamID id) = 0;
  148. /** Called between beginEdit and endEdit to inform the handler that a given parameter has a new
  149. * value. This must be called in the UI-Thread context! */
  150. virtual tresult PLUGIN_API performEdit (ParamID id, ParamValue valueNormalized) = 0;
  151. /** To be called after calling a performEdit (e.g. on mouse-click-up event).
  152. This must be called in the UI-Thread context! */
  153. virtual tresult PLUGIN_API endEdit (ParamID id) = 0;
  154. /** Instructs host to restart the component. This must be called in the UI-Thread context!
  155. \param flags is a combination of RestartFlags */
  156. virtual tresult PLUGIN_API restartComponent (int32 flags) = 0;
  157. //------------------------------------------------------------------------
  158. static const FUID iid;
  159. };
  160. DECLARE_CLASS_IID (IComponentHandler, 0x93A0BEA3, 0x0BD045DB, 0x8E890B0C, 0xC1E46AC6)
  161. //------------------------------------------------------------------------
  162. /** Extended host callback interface for an edit controller: Vst::IComponentHandler2
  163. \ingroup vstIHost vst310
  164. - [host imp]
  165. - [extends IComponentHandler]
  166. - [released: 3.1.0]
  167. - [optional]
  168. One part handles:
  169. - Setting dirty state of the plug-in
  170. - Requesting the host to open the editor
  171. The other part handles parameter group editing from the plug-in UI. It wraps a set of \ref IComponentHandler::beginEdit /
  172. \ref Steinberg::Vst::IComponentHandler::performEdit / \ref Steinberg::Vst::IComponentHandler::endEdit functions (see \ref IComponentHandler)
  173. which should use the same timestamp in the host when writing automation.
  174. This allows for better synchronizing of multiple parameter changes at once.
  175. \section IComponentHandler2Example Examples of different use cases
  176. \code{.cpp}
  177. //--------------------------------------
  178. // we are in the editcontroller...
  179. // in case of multiple switch buttons (with associated ParamID 1 and 3)
  180. // on mouse down :
  181. hostHandler2->startGroupEdit ();
  182. hostHandler->beginEdit (1);
  183. hostHandler->beginEdit (3);
  184. hostHandler->performEdit (1, 1.0);
  185. hostHandler->performEdit (3, 0.0); // the opposite of paramID 1 for example
  186. ....
  187. // on mouse up :
  188. hostHandler->endEdit (1);
  189. hostHandler->endEdit (3);
  190. hostHandler2->finishGroupEdit ();
  191. ....
  192. ....
  193. //--------------------------------------
  194. // in case of multiple faders (with associated ParamID 1 and 3)
  195. // on mouse down :
  196. hostHandler2->startGroupEdit ();
  197. hostHandler->beginEdit (1);
  198. hostHandler->beginEdit (3);
  199. hostHandler2->finishGroupEdit ();
  200. ....
  201. // on mouse move :
  202. hostHandler2->startGroupEdit ();
  203. hostHandler->performEdit (1, x); // x the wanted value
  204. hostHandler->performEdit (3, x);
  205. hostHandler2->finishGroupEdit ();
  206. ....
  207. // on mouse up :
  208. hostHandler2->startGroupEdit ();
  209. hostHandler->endEdit (1);
  210. hostHandler->endEdit (3);
  211. hostHandler2->finishGroupEdit ();
  212. \endcode
  213. \see \ref IComponentHandler, \ref IEditController
  214. */
  215. class IComponentHandler2 : public FUnknown
  216. {
  217. public:
  218. //------------------------------------------------------------------------
  219. /** Tells host that the plug-in is dirty (something besides parameters has changed since last save),
  220. if true the host should apply a save before quitting. */
  221. virtual tresult PLUGIN_API setDirty (TBool state) = 0;
  222. /** Tells host that it should open the plug-in editor the next time it's possible.
  223. You should use this instead of showing an alert and blocking the program flow (especially on loading projects). */
  224. virtual tresult PLUGIN_API requestOpenEditor (FIDString name = ViewType::kEditor) = 0;
  225. //------------------------------------------------------------------------
  226. /** Starts the group editing (call before a \ref IComponentHandler::beginEdit),
  227. the host will keep the current timestamp at this call and will use it for all \ref IComponentHandler::beginEdit
  228. / \ref IComponentHandler::performEdit / \ref IComponentHandler::endEdit calls until a \ref finishGroupEdit (). */
  229. virtual tresult PLUGIN_API startGroupEdit () = 0;
  230. /** Finishes the group editing started by a \ref startGroupEdit (call after a \ref IComponentHandler::endEdit). */
  231. virtual tresult PLUGIN_API finishGroupEdit () = 0;
  232. //------------------------------------------------------------------------
  233. static const FUID iid;
  234. };
  235. DECLARE_CLASS_IID (IComponentHandler2, 0xF040B4B3, 0xA36045EC, 0xABCDC045, 0xB4D5A2CC)
  236. //------------------------------------------------------------------------
  237. /** Extended host callback interface for an edit controller: Vst::IComponentHandlerBusActivation
  238. \ingroup vstIHost vst368
  239. - [host imp]
  240. - [extends IComponentHandler]
  241. - [released: 3.6.8]
  242. - [optional]
  243. Allows the plug-in to request the host to activate or deactivate a specific bus.
  244. If the host accepts this request, it will call later on \ref IComponent::activateBus.
  245. This is particularly useful for instruments with more than 1 outputs, where the user could request
  246. from the plug-in UI a given output bus activation.
  247. \code{.cpp}
  248. // somewhere in your code when you need to inform the host to enable a specific Bus.
  249. FUnknownPtr<IComponentHandlerBusActivation> busActivation (componentHandler);
  250. if (busActivation)
  251. {
  252. // here we want to activate our audio input sidechain (the 2cd input bus: index 1)
  253. busActivation->requestBusActivation (kAudio, kInput, 1, true);
  254. }
  255. \endcode
  256. \see \ref IComponentHandler
  257. */
  258. class IComponentHandlerBusActivation : public FUnknown
  259. {
  260. public:
  261. //------------------------------------------------------------------------
  262. /** request the host to activate or deactivate a specific bus. */
  263. virtual tresult PLUGIN_API requestBusActivation (MediaType type, BusDirection dir, int32 index,
  264. TBool state) = 0;
  265. //------------------------------------------------------------------------
  266. static const FUID iid;
  267. };
  268. DECLARE_CLASS_IID (IComponentHandlerBusActivation, 0x067D02C1, 0x5B4E274D, 0xA92D90FD, 0x6EAF7240)
  269. //------------------------------------------------------------------------
  270. /** Extended host callback interface for an edit controller: Vst::IProgress
  271. \ingroup vstIHost vst370
  272. - [host imp]
  273. - [extends IComponentHandler]
  274. - [released: 3.7.0]
  275. - [optional]
  276. Allows the plug-in to request the host to create a progress for some specific tasks which take
  277. some time. The host can visualize the progress as read-only UI elements. For example,
  278. after loading a project where a plug-in needs to load extra
  279. data (e.g. samples) in a background thread, this enables the host to get and visualize the current status of the loading
  280. progress and to inform the user when the loading is finished.
  281. Note: During the progress, the host can unload the plug-in at any time. Make sure that the plug-in
  282. supports this use case.
  283. \section IProgressExample Example
  284. \code{.cpp}
  285. //--------------------------------------
  286. // we are in the editcontroller:
  287. // as member: IProgress::ID mProgressID;
  288. FUnknownPtr<IProgress> progress (componentHandler);
  289. if (progress)
  290. progress->start (IProgress::ProgressType::UIBackgroundTask, STR ("Load Samples..."), mProgressID);
  291. // ...
  292. myProgressValue += incProgressStep;
  293. FUnknownPtr<IProgress> progress (componentHandler);
  294. if (progress)
  295. progress->update (mProgressID, myProgressValue);
  296. // ...
  297. FUnknownPtr<IProgress> progress (componentHandler);
  298. if (progress)
  299. progress->finish (mProgressID);
  300. \endcode
  301. \see \ref IComponentHandler
  302. */
  303. class IProgress : public FUnknown
  304. {
  305. public:
  306. //------------------------------------------------------------------------
  307. enum ProgressType : uint32
  308. {
  309. AsyncStateRestoration = 0, ///< plug-in state is restored async (in a background Thread)
  310. UIBackgroundTask ///< a plug-in task triggered by a UI action
  311. };
  312. using ID = uint64;
  313. /** Start a new progress of a given type and optional Description. outID is as ID created by the
  314. * host to identify this newly created progress (for update and finish method) */
  315. virtual tresult PLUGIN_API start (ProgressType type, const tchar* optionalDescription,
  316. ID& outID) = 0;
  317. /** Update the progress value (normValue between [0, 1]) associated to the given id */
  318. virtual tresult PLUGIN_API update (ID id, ParamValue normValue) = 0;
  319. /** Finish the progress associated to the given id */
  320. virtual tresult PLUGIN_API finish (ID id) = 0;
  321. //------------------------------------------------------------------------
  322. static const FUID iid;
  323. };
  324. DECLARE_CLASS_IID (IProgress, 0x00C9DC5B, 0x9D904254, 0x91A388C8, 0xB4E91B69)
  325. //------------------------------------------------------------------------
  326. /** Edit controller component interface: Vst::IEditController
  327. \ingroup vstIPlug vst300
  328. - [plug imp]
  329. - [released: 3.0.0]
  330. - [mandatory]
  331. The controller part of an effect or instrument with parameter handling (export, definition, conversion...).
  332. \see \ref IComponent::getControllerClassId, \ref IMidiMapping
  333. */
  334. class IEditController : public IPluginBase
  335. {
  336. public:
  337. //------------------------------------------------------------------------
  338. /** Receives the component state. */
  339. virtual tresult PLUGIN_API setComponentState (IBStream* state) = 0;
  340. /** Sets the controller state. */
  341. virtual tresult PLUGIN_API setState (IBStream* state) = 0;
  342. /** Gets the controller state. */
  343. virtual tresult PLUGIN_API getState (IBStream* state) = 0;
  344. // parameters -------------------------
  345. /** Returns the number of parameters exported. */
  346. virtual int32 PLUGIN_API getParameterCount () = 0;
  347. /** Gets for a given index the parameter information. */
  348. virtual tresult PLUGIN_API getParameterInfo (int32 paramIndex, ParameterInfo& info /*out*/) = 0;
  349. /** Gets for a given paramID and normalized value its associated string representation. */
  350. virtual tresult PLUGIN_API getParamStringByValue (ParamID id, ParamValue valueNormalized /*in*/, String128 string /*out*/) = 0;
  351. /** Gets for a given paramID and string its normalized value. */
  352. virtual tresult PLUGIN_API getParamValueByString (ParamID id, TChar* string /*in*/, ParamValue& valueNormalized /*out*/) = 0;
  353. /** Returns for a given paramID and a normalized value its plain representation
  354. (for example -6 for -6dB - see \ref vst3AutomationIntro). */
  355. virtual ParamValue PLUGIN_API normalizedParamToPlain (ParamID id, ParamValue valueNormalized) = 0;
  356. /** Returns for a given paramID and a plain value its normalized value. (see \ref vst3AutomationIntro) */
  357. virtual ParamValue PLUGIN_API plainParamToNormalized (ParamID id, ParamValue plainValue) = 0;
  358. /** Returns the normalized value of the parameter associated to the paramID. */
  359. virtual ParamValue PLUGIN_API getParamNormalized (ParamID id) = 0;
  360. /** Sets the normalized value to the parameter associated to the paramID. The controller must never
  361. pass this value-change back to the host via the IComponentHandler. It should update the according
  362. GUI element(s) only!*/
  363. virtual tresult PLUGIN_API setParamNormalized (ParamID id, ParamValue value) = 0;
  364. // handler ----------------------------
  365. /** Gets from host a handler which allows the Plugin-in to communicate with the host.
  366. Note: This is mandatory if the host is using the IEditController! */
  367. virtual tresult PLUGIN_API setComponentHandler (IComponentHandler* handler) = 0;
  368. // view -------------------------------
  369. /** Creates the editor view of the plug-in, currently only "editor" is supported, see \ref ViewType.
  370. The life time of the editor view will never exceed the life time of this controller instance. */
  371. virtual IPlugView* PLUGIN_API createView (FIDString name) = 0;
  372. //------------------------------------------------------------------------
  373. static const FUID iid;
  374. };
  375. DECLARE_CLASS_IID (IEditController, 0xDCD7BBE3, 0x7742448D, 0xA874AACC, 0x979C759E)
  376. //------------------------------------------------------------------------
  377. /** Knob Mode */
  378. enum KnobModes
  379. {
  380. kCircularMode = 0, ///< Circular with jump to clicked position
  381. kRelativCircularMode, ///< Circular without jump to clicked position
  382. kLinearMode ///< Linear: depending on vertical movement
  383. };
  384. //------------------------------------------------------------------------
  385. /** \defgroup vst3typedef VST 3 Data Types */
  386. /*@{*/
  387. //------------------------------------------------------------------------
  388. /** Knob Mode Type */
  389. typedef int32 KnobMode;
  390. /*@}*/
  391. //------------------------------------------------------------------------
  392. /** Edit controller component interface extension: Vst::IEditController2
  393. \ingroup vstIPlug vst310
  394. - [plug imp]
  395. - [extends IEditController]
  396. - [released: 3.1.0]
  397. - [optional]
  398. Extension to allow the host to inform the plug-in about the host Knob Mode,
  399. and to open the plug-in about box or help documentation.
  400. \see \ref IEditController, \ref EditController
  401. */
  402. class IEditController2 : public FUnknown
  403. {
  404. public:
  405. /** Host could set the Knob Mode for the plug-in. Return kResultFalse means not supported mode. \see KnobModes. */
  406. virtual tresult PLUGIN_API setKnobMode (KnobMode mode) = 0;
  407. /** Host could ask to open the plug-in help (could be: opening a PDF document or link to a web page).
  408. The host could call it with onlyCheck set to true for testing support of open Help.
  409. Return kResultFalse means not supported function. */
  410. virtual tresult PLUGIN_API openHelp (TBool onlyCheck) = 0;
  411. /** Host could ask to open the plug-in about box.
  412. The host could call it with onlyCheck set to true for testing support of open AboutBox.
  413. Return kResultFalse means not supported function. */
  414. virtual tresult PLUGIN_API openAboutBox (TBool onlyCheck) = 0;
  415. //------------------------------------------------------------------------
  416. static const FUID iid;
  417. };
  418. DECLARE_CLASS_IID (IEditController2, 0x7F4EFE59, 0xF3204967, 0xAC27A3AE, 0xAFB63038)
  419. //------------------------------------------------------------------------
  420. /** MIDI Mapping interface: Vst::IMidiMapping
  421. \ingroup vstIPlug vst301
  422. - [plug imp]
  423. - [extends IEditController]
  424. - [released: 3.0.1]
  425. - [optional]
  426. MIDI controllers are not transmitted directly to a VST component. MIDI as hardware protocol has
  427. restrictions that can be avoided in software. Controller data in particular come along with unclear
  428. and often ignored semantics. On top of this they can interfere with regular parameter automation and
  429. the host is unaware of what happens in the plug-in when passing MIDI controllers directly.
  430. So any functionality that is to be controlled by MIDI controllers must be exported as regular parameter.
  431. The host will transform incoming MIDI controller data using this interface and transmit them as regular
  432. parameter change. This allows the host to automate them in the same way as other parameters.
  433. CtrlNumber can be a typical MIDI controller value extended to some others values like pitchbend or
  434. aftertouch (see \ref ControllerNumbers).
  435. If the mapping has changed, the plug-in must call IComponentHandler::restartComponent (kMidiCCAssignmentChanged)
  436. to inform the host about this change.
  437. \section IMidiMappingExample Example
  438. \code{.cpp}
  439. //--------------------------------------
  440. // in myeditcontroller.h
  441. class MyEditController: public EditControllerEx1, public IMidiMapping
  442. {
  443. //...
  444. //---IMidiMapping---------------------------
  445. tresult PLUGIN_API getMidiControllerAssignment (int32 busIndex, int16 channel, CtrlNumber midiControllerNumber, ParamID& id) SMTG_OVERRIDE;
  446. //---Interface---------
  447. OBJ_METHODS (MyEditController, EditControllerEx1)
  448. DEFINE_INTERFACES
  449. DEF_INTERFACE (IMidiMapping)
  450. END_DEFINE_INTERFACES (MyEditController)
  451. REFCOUNT_METHODS (MyEditController)
  452. };
  453. //--------------------------------------
  454. // in myeditcontroller.cpp
  455. tresult PLUGIN_API MyEditController::getMidiControllerAssignment (int32 busIndex, int16 midiChannel, CtrlNumber midiControllerNumber, ParamID& tag)
  456. {
  457. // for my first Event bus and for MIDI channel 0 and for MIDI CC Volume only
  458. if (busIndex == 0 && midiChannel == 0 && midiControllerNumber == kCtrlVolume)
  459. {
  460. tag = kGainId;
  461. return kResultTrue;
  462. }
  463. return kResultFalse;
  464. }
  465. \endcode
  466. */
  467. class IMidiMapping : public FUnknown
  468. {
  469. public:
  470. /** Gets an (preferred) associated ParamID for a given Input Event Bus index, channel and MIDI Controller.
  471. * @param[in] busIndex - index of Input Event Bus
  472. * @param[in] channel - channel of the bus
  473. * @param[in] midiControllerNumber - see \ref ControllerNumbers for expected values (could be bigger than 127)
  474. * @param[in] id - return the associated ParamID to the given midiControllerNumber
  475. */
  476. virtual tresult PLUGIN_API getMidiControllerAssignment (int32 busIndex, int16 channel,
  477. CtrlNumber midiControllerNumber, ParamID& id/*out*/) = 0;
  478. //------------------------------------------------------------------------
  479. static const FUID iid;
  480. };
  481. DECLARE_CLASS_IID (IMidiMapping, 0xDF0FF9F7, 0x49B74669, 0xB63AB732, 0x7ADBF5E5)
  482. //------------------------------------------------------------------------
  483. /** Parameter Editing from host: Vst::IEditControllerHostEditing
  484. \ingroup vstIPlug vst350
  485. - [plug imp]
  486. - [extends IEditController]
  487. - [released: 3.5.0]
  488. - [optional]
  489. If this interface is implemented by the edit controller, and when performing edits from outside
  490. the plug-in (host / remote) of a not automatable and not read-only, and not hidden flagged parameter (kind of helper parameter),
  491. the host will start with a beginEditFromHost before calling setParamNormalized and end with an endEditFromHost.
  492. Here the sequence that the host will call:
  493. \section IEditControllerExample Example
  494. \code{.cpp}
  495. //------------------------------------------------------------------------
  496. plugEditController->beginEditFromHost (id);
  497. plugEditController->setParamNormalized (id, value);
  498. plugEditController->setParamNormalized (id, value + 0.1);
  499. // ...
  500. plugEditController->endEditFromHost (id);
  501. \endcode
  502. \see \ref IEditController
  503. */
  504. class IEditControllerHostEditing : public FUnknown
  505. {
  506. public:
  507. /** Called before a setParamNormalized sequence, a endEditFromHost will be call at the end of the editing action. */
  508. virtual tresult PLUGIN_API beginEditFromHost (ParamID paramID) = 0;
  509. /** Called after a beginEditFromHost and a sequence of setParamNormalized. */
  510. virtual tresult PLUGIN_API endEditFromHost (ParamID paramID) = 0;
  511. //------------------------------------------------------------------------
  512. static const FUID iid;
  513. };
  514. DECLARE_CLASS_IID (IEditControllerHostEditing, 0xC1271208, 0x70594098, 0xB9DD34B3, 0x6BB0195E)
  515. //------------------------------------------------------------------------
  516. } // namespace Vst
  517. } // namespace Steinberg
  518. //------------------------------------------------------------------------
  519. #include "pluginterfaces/base/falignpop.h"
  520. //------------------------------------------------------------------------