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 // This source is part of the "Auburn Sounds (Guillaume Piolat) extension to the 11 // Steinberg VST 3 Plug-in SDK". 12 // 13 // Details of that license can be found at: www.gnu.org/licenses/gpl-3.0.html 14 // 15 // Dual-licence: 16 // 17 // The "Auburn Sounds (Guillaume Piolat) extension to the Steinberg VST 3 Plug-in 18 // SDK", hereby referred to as DPLUG:VST3, is a language translation of the VST3 19 // SDK suitable for usage in Dplug. Any Licensee of a currently valid Steinberg 20 // VST 3 Plug-In SDK Licensing Agreement (version 2.2.4 or ulterior, hereby referred 21 // to as the AGREEMENT), is granted by Auburn Sounds (Guillaume Piolat) a non-exclusive, 22 // worldwide, nontransferable license during the term the AGREEMENT to use parts 23 // of DPLUG:VST3 not covered by the AGREEMENT, as if they were originally 24 // inside the Licensed Software Developer Kit mentionned in the AGREEMENT. 25 // Under this licence all conditions that apply to the Licensed Software Developer 26 // Kit also apply to DPLUG:VST3. 27 // 28 //----------------------------------------------------------------------------- 29 module dplug.vst3.ivsteditcontroller; 30 31 version(VST3): 32 33 import dplug.vst3.ftypes; 34 import dplug.vst3.ipluginbase; 35 import dplug.vst3.ibstream; 36 import dplug.vst3.iplugview; 37 38 static immutable string kVstComponentControllerClass = "Component Controller Class"; 39 40 struct ParameterInfo 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 vst3UnitsIntro) 50 51 int32 flags; ///< ParameterFlags (see below) 52 enum ParameterFlags 53 { 54 kCanAutomate = 1 << 0, ///< parameter can be automated 55 kIsReadOnly = 1 << 1, ///< parameter cannot be changed from outside (implies that kCanAutomate is false) 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 59 kIsProgramChange = 1 << 15, ///< parameter is a program change (unitId gives info about associated unit 60 ///< - see \ref vst3UnitPrograms) 61 kIsBypass = 1 << 16 ///< special bypass parameter (only one allowed): Plug-in can handle bypass 62 ///< (highly recommended to export a bypass parameter for effect Plug-in) 63 } 64 } 65 66 mixin SMTG_TYPE_SIZE_CHECK!(ParameterInfo, 792, 792, 792); 67 68 //------------------------------------------------------------------------ 69 /** View Types used for IEditController::createView */ 70 //------------------------------------------------------------------------ 71 struct ViewType 72 { 73 static immutable kEditor = "editor"; 74 } 75 76 //------------------------------------------------------------------------ 77 /** Flags used for IComponentHandler::restartComponent */ 78 //------------------------------------------------------------------------ 79 alias RestartFlags = int; 80 enum : RestartFlags 81 { 82 kReloadComponent = 1 << 0, ///< The Component should be reloaded [SDK 3.0.0] 83 kIoChanged = 1 << 1, ///< Input and/or Output Bus configuration has changed [SDK 3.0.0] 84 kParamValuesChanged = 1 << 2, ///< Multiple parameter values have changed 85 ///< (as result of a program change for example) [SDK 3.0.0] 86 kLatencyChanged = 1 << 3, ///< Latency has changed (IAudioProcessor.getLatencySamples) [SDK 3.0.0] 87 kParamTitlesChanged = 1 << 4, ///< Parameter titles or default values or flags have changed [SDK 3.0.0] 88 kMidiCCAssignmentChanged = 1 << 5, ///< MIDI Controller Assignments have changed [SDK 3.0.1] 89 kNoteExpressionChanged = 1 << 6, ///< Note Expression has changed (info, count, PhysicalUIMapping, ...) [SDK 3.5.0] 90 kIoTitlesChanged = 1 << 7, ///< Input and/or Output bus titles have changed [SDK 3.5.0] 91 kPrefetchableSupportChanged = 1 << 8, ///< Prefetch support has changed (\see IPrefetchableSupport) [SDK 3.6.1] 92 kRoutingInfoChanged = 1 << 9 ///< RoutingInfo has changed (\see IComponent) [SDK 3.6.6] 93 } 94 95 /** Host callback interface for an edit controller. 96 \ingroup vstIHost vst300 97 - [host imp] 98 - [released: 3.0.0] 99 100 Allow transfer of parameter editing to component (processor) via host and support automation. 101 Cause the host to react on configuration changes (restartComponent) 102 103 \see IEditController */ 104 interface IComponentHandler: FUnknown 105 { 106 public: 107 nothrow: 108 @nogc: 109 110 /** To be called before calling a performEdit (e.g. on mouse-click-down event). */ 111 tresult beginEdit (ParamID id); 112 113 /** Called between beginEdit and endEdit to inform the handler that a given parameter has a new value. */ 114 tresult performEdit (ParamID id, ParamValue valueNormalized); 115 116 /** To be called after calling a performEdit (e.g. on mouse-click-up event). */ 117 tresult endEdit (ParamID id); 118 119 /** Instructs host to restart the component. This should be called in the UI-Thread context! 120 \param flags is a combination of RestartFlags */ 121 tresult restartComponent (int32 flags); 122 123 __gshared immutable TUID iid = INLINE_UID(0x93A0BEA3, 0x0BD045DB, 0x8E890B0C, 0xC1E46AC6); 124 } 125 126 127 /** Edit controller component interface. 128 \ingroup vstIPlug vst300 129 - [plug imp] 130 - [released: 3.0.0] 131 132 The Controller part of an effect or instrument with parameter handling (export, definition, conversion...). 133 \see IComponent::getControllerClassId, IMidiMapping */ 134 interface IEditController: IPluginBase 135 { 136 public: 137 nothrow: 138 @nogc: 139 140 /** Receives the component state. */ 141 tresult setComponentState (IBStream state); 142 143 /** Sets the controller state. */ 144 tresult setStateController (IBStream state); // Note: renamed to disambiguate with IVstComponent.setState 145 146 /** Gets the controller state. */ 147 tresult getStateController (IBStream state); // Note: renamed to disambiguate with IVstComponent.getState 148 149 // parameters ------------------------- 150 /** Returns the number of parameters exported. */ 151 int32 getParameterCount (); 152 153 /** Gets for a given index the parameter information. */ 154 tresult getParameterInfo (int32 paramIndex, ref ParameterInfo info /*out*/); 155 156 /** Gets for a given paramID and normalized value its associated string representation. */ 157 tresult getParamStringByValue (ParamID id, ParamValue valueNormalized /*in*/, String128* string_ /*out*/); 158 159 /** Gets for a given paramID and string its normalized value. */ 160 tresult getParamValueByString (ParamID id, TChar* string_ /*in*/, ref ParamValue valueNormalized /*out*/); 161 162 /** Returns for a given paramID and a normalized value its plain representation 163 (for example 90 for 90db - see \ref vst3AutomationIntro). */ 164 ParamValue normalizedParamToPlain (ParamID id, ParamValue valueNormalized); 165 166 /** Returns for a given paramID and a plain value its normalized value. (see \ref vst3AutomationIntro) */ 167 ParamValue plainParamToNormalized (ParamID id, ParamValue plainValue); 168 169 /** Returns the normalized value of the parameter associated to the paramID. */ 170 ParamValue getParamNormalized (ParamID id); 171 172 /** Sets the normalized value to the parameter associated to the paramID. The controller must never 173 pass this value-change back to the host via the IComponentHandler. It should update the according 174 GUI element(s) only!*/ 175 tresult setParamNormalized (ParamID id, ParamValue value); 176 177 // handler ---------------------------- 178 /** Gets from host a handler. */ 179 tresult setComponentHandler (IComponentHandler handler); 180 181 // view ------------------------------- 182 /** Creates the editor view of the Plug-in, currently only "editor" is supported, see \ref ViewType. 183 The life time of the editor view will never exceed the life time of this controller instance. */ 184 IPlugView createView (FIDString name); 185 186 __gshared immutable TUID iid = INLINE_UID(0xDCD7BBE3, 0x7742448D, 0xA874AACC, 0x979C759E); 187 } 188 189 //------------------------------------------------------------------------ 190 /** Knob Mode */ 191 //------------------------------------------------------------------------ 192 alias KnobModes = int; 193 enum : KnobModes 194 { 195 kCircularMode = 0, ///< Circular with jump to clicked position 196 kRelativCircularMode, ///< Circular without jump to clicked position 197 kLinearMode ///< Linear: depending on vertical movement 198 } 199 200 alias KnobMode = int; ///< Knob Mode 201 202 203 interface IEditController2 : FUnknown 204 { 205 public: 206 nothrow: 207 @nogc: 208 209 /** Host could set the Knob Mode for the Plug-in. Return kResultFalse means not supported mode. \see KnobModes. */ 210 tresult setKnobMode (KnobMode mode); 211 212 /** Host could ask to open the Plug-in help (could be: opening a PDF document or link to a web page). 213 The host could call it with onlyCheck set to true for testing support of open Help. 214 Return kResultFalse means not supported function. */ 215 tresult openHelp (TBool onlyCheck); 216 217 /** Host could ask to open the Plug-in about box. 218 The host could call it with onlyCheck set to true for testing support of open AboutBox. 219 Return kResultFalse means not supported function. */ 220 tresult openAboutBox (TBool onlyCheck); 221 222 __gshared immutable TUID iid = INLINE_UID(0x7F4EFE59, 0xF3204967, 0xAC27A3AE, 0xAFB63038); 223 } 224 225 226 interface IMidiMapping : FUnknown 227 { 228 public: 229 nothrow: 230 @nogc: 231 /** Gets an (preferred) associated ParamID for a given Input Event Bus index, channel and MIDI Controller. 232 * @param[in] busIndex - index of Input Event Bus 233 * @param[in] channel - channel of the bus 234 * @param[in] midiControllerNumber - see \ref ControllerNumbers for expected values (could be bigger than 127) 235 * @param[in] id - return the associated ParamID to the given midiControllerNumber 236 */ 237 tresult getMidiControllerAssignment(int busIndex, short channel, 238 CtrlNumber midiControllerNumber, ref ParamID id); 239 240 __gshared immutable TUID iid = INLINE_UID(0xDF0FF9F7, 0x49B74669, 0xB63AB732, 0x7ADBF5E5); 241 }