1 //----------------------------------------------------------------------------- 2 // LICENSE 3 // (c) 2005, Steinberg Media Technologies GmbH, All Rights Reserved 4 // (c) 2018, Guillaume Piolat (contact@auburnsounds.com) 5 //----------------------------------------------------------------------------- 6 // 7 // This Software Development Kit is licensed under the terms of the General 8 // Public License (GPL) Version 3. 9 // 10 // Details of that license can be found at: www.gnu.org/licenses/gpl-3.0.html 11 //----------------------------------------------------------------------------- 12 module dplug.vst3.ivsteditcontroller; 13 14 version(VST3): 15 16 import dplug.vst3.ftypes; 17 import dplug.vst3.ipluginbase; 18 import dplug.vst3.ibstream; 19 import dplug.vst3.iplugview; 20 21 static immutable string kVstComponentControllerClass = "Component Controller Class"; 22 23 struct ParameterInfo 24 { 25 ParamID id; ///< unique identifier of this parameter (named tag too) 26 String128 title; ///< parameter title (e.g. "Volume") 27 String128 shortTitle; ///< parameter shortTitle (e.g. "Vol") 28 String128 units; ///< parameter unit (e.g. "dB") 29 int32 stepCount; ///< number of discrete steps (0: continuous, 1: toggle, discrete value otherwise 30 ///< (corresponding to max - min, for example: 127 for a min = 0 and a max = 127) - see \ref vst3parameterIntro) 31 ParamValue defaultNormalizedValue; ///< default normalized value [0,1] (in case of discrete value: defaultNormalizedValue = defDiscreteValue / stepCount) 32 UnitID unitId; ///< id of unit this parameter belongs to (see \ref vst3UnitsIntro) 33 34 int32 flags; ///< ParameterFlags (see below) 35 enum ParameterFlags 36 { 37 kCanAutomate = 1 << 0, ///< parameter can be automated 38 kIsReadOnly = 1 << 1, ///< parameter cannot be changed from outside (implies that kCanAutomate is false) 39 kIsWrapAround = 1 << 2, ///< attempts to set the parameter value out of the limits will result in a wrap around [SDK 3.0.2] 40 kIsList = 1 << 3, ///< parameter should be displayed as list in generic editor or automation editing [SDK 3.1.0] 41 42 kIsProgramChange = 1 << 15, ///< parameter is a program change (unitId gives info about associated unit 43 ///< - see \ref vst3UnitPrograms) 44 kIsBypass = 1 << 16 ///< special bypass parameter (only one allowed): Plug-in can handle bypass 45 ///< (highly recommended to export a bypass parameter for effect Plug-in) 46 } 47 } 48 49 mixin SMTG_TYPE_SIZE_CHECK!(ParameterInfo, 792, 792, 792); 50 51 //------------------------------------------------------------------------ 52 /** View Types used for IEditController::createView */ 53 //------------------------------------------------------------------------ 54 struct ViewType 55 { 56 static immutable kEditor = "editor"; 57 } 58 59 //------------------------------------------------------------------------ 60 /** Flags used for IComponentHandler::restartComponent */ 61 //------------------------------------------------------------------------ 62 alias RestartFlags = int; 63 enum : RestartFlags 64 { 65 kReloadComponent = 1 << 0, ///< The Component should be reloaded [SDK 3.0.0] 66 kIoChanged = 1 << 1, ///< Input and/or Output Bus configuration has changed [SDK 3.0.0] 67 kParamValuesChanged = 1 << 2, ///< Multiple parameter values have changed 68 ///< (as result of a program change for example) [SDK 3.0.0] 69 kLatencyChanged = 1 << 3, ///< Latency has changed (IAudioProcessor.getLatencySamples) [SDK 3.0.0] 70 kParamTitlesChanged = 1 << 4, ///< Parameter titles or default values or flags have changed [SDK 3.0.0] 71 kMidiCCAssignmentChanged = 1 << 5, ///< MIDI Controller Assignments have changed [SDK 3.0.1] 72 kNoteExpressionChanged = 1 << 6, ///< Note Expression has changed (info, count, PhysicalUIMapping, ...) [SDK 3.5.0] 73 kIoTitlesChanged = 1 << 7, ///< Input and/or Output bus titles have changed [SDK 3.5.0] 74 kPrefetchableSupportChanged = 1 << 8, ///< Prefetch support has changed (\see IPrefetchableSupport) [SDK 3.6.1] 75 kRoutingInfoChanged = 1 << 9 ///< RoutingInfo has changed (\see IComponent) [SDK 3.6.6] 76 } 77 78 /** Host callback interface for an edit controller. 79 \ingroup vstIHost vst300 80 - [host imp] 81 - [released: 3.0.0] 82 83 Allow transfer of parameter editing to component (processor) via host and support automation. 84 Cause the host to react on configuration changes (restartComponent) 85 86 \see IEditController */ 87 interface IComponentHandler: FUnknown 88 { 89 public: 90 nothrow: 91 @nogc: 92 93 /** To be called before calling a performEdit (e.g. on mouse-click-down event). */ 94 tresult beginEdit (ParamID id); 95 96 /** Called between beginEdit and endEdit to inform the handler that a given parameter has a new value. */ 97 tresult performEdit (ParamID id, ParamValue valueNormalized); 98 99 /** To be called after calling a performEdit (e.g. on mouse-click-up event). */ 100 tresult endEdit (ParamID id); 101 102 /** Instructs host to restart the component. This should be called in the UI-Thread context! 103 \param flags is a combination of RestartFlags */ 104 tresult restartComponent (int32 flags); 105 106 __gshared immutable TUID iid = INLINE_UID(0x93A0BEA3, 0x0BD045DB, 0x8E890B0C, 0xC1E46AC6); 107 } 108 109 110 /** Edit controller component interface. 111 \ingroup vstIPlug vst300 112 - [plug imp] 113 - [released: 3.0.0] 114 115 The Controller part of an effect or instrument with parameter handling (export, definition, conversion...). 116 \see IComponent::getControllerClassId, IMidiMapping */ 117 interface IEditController: IPluginBase 118 { 119 public: 120 nothrow: 121 @nogc: 122 123 /** Receives the component state. */ 124 tresult setComponentState (IBStream state); 125 126 /** Sets the controller state. */ 127 tresult setStateController (IBStream state); // Note: renamed to disambiguate with IVstComponent.setState 128 129 /** Gets the controller state. */ 130 tresult getStateController (IBStream state); // Note: renamed to disambiguate with IVstComponent.getState 131 132 // parameters ------------------------- 133 /** Returns the number of parameters exported. */ 134 int32 getParameterCount (); 135 136 /** Gets for a given index the parameter information. */ 137 tresult getParameterInfo (int32 paramIndex, ref ParameterInfo info /*out*/); 138 139 /** Gets for a given paramID and normalized value its associated string representation. */ 140 tresult getParamStringByValue (ParamID id, ParamValue valueNormalized /*in*/, String128* string_ /*out*/); 141 142 /** Gets for a given paramID and string its normalized value. */ 143 tresult getParamValueByString (ParamID id, TChar* string_ /*in*/, ref ParamValue valueNormalized /*out*/); 144 145 /** Returns for a given paramID and a normalized value its plain representation 146 (for example 90 for 90db - see \ref vst3AutomationIntro). */ 147 ParamValue normalizedParamToPlain (ParamID id, ParamValue valueNormalized); 148 149 /** Returns for a given paramID and a plain value its normalized value. (see \ref vst3AutomationIntro) */ 150 ParamValue plainParamToNormalized (ParamID id, ParamValue plainValue); 151 152 /** Returns the normalized value of the parameter associated to the paramID. */ 153 ParamValue getParamNormalized (ParamID id); 154 155 /** Sets the normalized value to the parameter associated to the paramID. The controller must never 156 pass this value-change back to the host via the IComponentHandler. It should update the according 157 GUI element(s) only!*/ 158 tresult setParamNormalized (ParamID id, ParamValue value); 159 160 // handler ---------------------------- 161 /** Gets from host a handler. */ 162 tresult setComponentHandler (IComponentHandler handler); 163 164 // view ------------------------------- 165 /** Creates the editor view of the Plug-in, currently only "editor" is supported, see \ref ViewType. 166 The life time of the editor view will never exceed the life time of this controller instance. */ 167 IPlugView createView (FIDString name); 168 169 __gshared immutable TUID iid = INLINE_UID(0xDCD7BBE3, 0x7742448D, 0xA874AACC, 0x979C759E); 170 } 171 172 //------------------------------------------------------------------------ 173 /** Knob Mode */ 174 //------------------------------------------------------------------------ 175 alias KnobModes = int; 176 enum : KnobModes 177 { 178 kCircularMode = 0, ///< Circular with jump to clicked position 179 kRelativCircularMode, ///< Circular without jump to clicked position 180 kLinearMode ///< Linear: depending on vertical movement 181 } 182 183 alias KnobMode = int; ///< Knob Mode 184 185 186 interface IEditController2 : FUnknown 187 { 188 public: 189 nothrow: 190 @nogc: 191 192 /** Host could set the Knob Mode for the Plug-in. Return kResultFalse means not supported mode. \see KnobModes. */ 193 tresult setKnobMode (KnobMode mode); 194 195 /** Host could ask to open the Plug-in help (could be: opening a PDF document or link to a web page). 196 The host could call it with onlyCheck set to true for testing support of open Help. 197 Return kResultFalse means not supported function. */ 198 tresult openHelp (TBool onlyCheck); 199 200 /** Host could ask to open the Plug-in about box. 201 The host could call it with onlyCheck set to true for testing support of open AboutBox. 202 Return kResultFalse means not supported function. */ 203 tresult openAboutBox (TBool onlyCheck); 204 205 __gshared immutable TUID iid = INLINE_UID(0x7F4EFE59, 0xF3204967, 0xAC27A3AE, 0xAFB63038); 206 }