1 /* 2 * Copyright (C) 2000-2017 Paul Davis <paul@linuxaudiosystems.com> 3 * Copyright (C) 2005-2007 Taybin Rutkin <taybin@taybin.com> 4 * Copyright (C) 2006-2014 David Robillard <d@drobilla.net> 5 * Copyright (C) 2009-2012 Carl Hetherington <carl@carlh.net> 6 * Copyright (C) 2013-2019 Robin Gareus <robin@gareus.org> 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU General Public License as published by 10 * the Free Software Foundation; either version 2 of the License, or 11 * (at your option) any later version. 12 * 13 * This program is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 16 * GNU General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License along 19 * with this program; if not, write to the Free Software Foundation, Inc., 20 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 21 */ 22 23 #ifndef __ardour_plugin_h__ 24 #define __ardour_plugin_h__ 25 26 #include <boost/shared_ptr.hpp> 27 #include <set> 28 #include <string> 29 30 #include "pbd/controllable.h" 31 #include "pbd/statefuldestructible.h" 32 33 #include "ardour/buffer_set.h" 34 #include "ardour/chan_count.h" 35 #include "ardour/chan_mapping.h" 36 #include "ardour/cycles.h" 37 #include "ardour/latent.h" 38 #include "ardour/libardour_visibility.h" 39 #include "ardour/midi_ring_buffer.h" 40 #include "ardour/midi_state_tracker.h" 41 #include "ardour/parameter_descriptor.h" 42 #include "ardour/types.h" 43 #include "ardour/variant.h" 44 45 #include <map> 46 #include <set> 47 #include <vector> 48 49 namespace ARDOUR 50 { 51 class AudioEngine; 52 class Session; 53 class BufferSet; 54 class PluginInsert; 55 class Plugin; 56 class PluginInfo; 57 class AutomationControl; 58 class SessionObject; 59 60 typedef boost::shared_ptr<Plugin> PluginPtr; 61 typedef boost::shared_ptr<PluginInfo> PluginInfoPtr; 62 typedef std::list<PluginInfoPtr> PluginInfoList; 63 typedef std::set<uint32_t> PluginOutputConfiguration; 64 65 /** A plugin is an external module (usually 3rd party provided) loaded into Ardour 66 * for the purpose of digital signal processing. 67 * 68 * This class provides an abstraction for methords provided by 69 * all supported plugin standards such as presets, name, parameters etc. 70 * 71 * Plugins are not used directly in Ardour but always wrapped by a PluginInsert. 72 */ 73 class LIBARDOUR_API Plugin : public PBD::StatefulDestructible, public HasLatency 74 { 75 public: 76 Plugin (ARDOUR::AudioEngine&, ARDOUR::Session&); 77 Plugin (const Plugin&); 78 virtual ~Plugin (); 79 80 XMLNode& get_state (); 81 virtual int set_state (const XMLNode&, int version); 82 set_insert_id(PBD::ID id)83 virtual void set_insert_id (PBD::ID id) {} 84 virtual void set_state_dir (const std::string& d = "") {} 85 86 virtual std::string unique_id () const = 0; 87 virtual const char* label () const = 0; 88 virtual const char* name () const = 0; 89 virtual const char* maker () const = 0; 90 virtual uint32_t parameter_count () const = 0; 91 virtual float default_value (uint32_t port) = 0; 92 virtual float get_parameter (uint32_t which) const = 0; 93 get_docs()94 virtual std::string get_docs () const { return ""; } get_parameter_docs(uint32_t)95 virtual std::string get_parameter_docs (uint32_t /*which*/) const { return ""; } 96 97 virtual int get_parameter_descriptor (uint32_t which, ParameterDescriptor&) const = 0; 98 virtual uint32_t nth_parameter (uint32_t which, bool& ok) const = 0; 99 virtual std::string parameter_label (uint32_t which) const; 100 101 virtual void activate () = 0; 102 virtual void deactivate () = 0; flush()103 virtual void flush () 104 { 105 deactivate (); 106 activate (); 107 } 108 109 virtual std::set<Evoral::Parameter> automatable () const = 0; 110 virtual std::string describe_parameter (Evoral::Parameter) = 0; 111 virtual std::string state_node_name () const = 0; 112 print_parameter(uint32_t,std::string &)113 virtual bool print_parameter (uint32_t, std::string&) const { return false; } 114 115 virtual bool parameter_is_audio (uint32_t) const = 0; 116 virtual bool parameter_is_control (uint32_t) const = 0; 117 virtual bool parameter_is_input (uint32_t) const = 0; 118 virtual bool parameter_is_output (uint32_t) const = 0; 119 designated_bypass_port()120 virtual uint32_t designated_bypass_port () { return UINT32_MAX; } 121 122 struct LIBARDOUR_API IOPortDescription { 123 public: 124 IOPortDescription (const std::string& n, bool sc = false, std::string gn = "", uint32_t gc = 0) nameIOPortDescription125 : name (n) 126 , is_sidechain (sc) 127 , group_name (gn.empty () ? n : gn) 128 , group_channel (gc) 129 { } 130 IOPortDescriptionIOPortDescription131 IOPortDescription (const IOPortDescription& other) 132 : name (other.name) 133 , is_sidechain (other.is_sidechain) 134 , group_name (other.group_name) 135 , group_channel (other.group_channel) 136 { } 137 138 std::string name; 139 bool is_sidechain; 140 141 std::string group_name; 142 uint32_t group_channel; 143 }; 144 145 virtual IOPortDescription describe_io_port (DataType dt, bool input, uint32_t id) const; 146 virtual PluginOutputConfiguration possible_output () const; 147 set_automation_control(uint32_t,boost::shared_ptr<ARDOUR::AutomationControl>)148 virtual void set_automation_control (uint32_t /*port_index*/, boost::shared_ptr<ARDOUR::AutomationControl>) {} 149 get_scale_points(uint32_t)150 virtual boost::shared_ptr<ScalePoints> get_scale_points (uint32_t /*port_index*/) const 151 { 152 return boost::shared_ptr<ScalePoints> (); 153 } 154 signal_latency()155 samplecnt_t signal_latency () const 156 { 157 return plugin_latency (); 158 } 159 160 /** the max possible latency a plugin will have */ max_latency()161 virtual samplecnt_t max_latency () const { return 0; } 162 163 virtual int set_block_size (pframes_t nframes) = 0; requires_fixed_sized_buffers()164 virtual bool requires_fixed_sized_buffers () const { return false; } inplace_broken()165 virtual bool inplace_broken () const { return false; } connect_all_audio_outputs()166 virtual bool connect_all_audio_outputs () const { return false; } 167 168 virtual int connect_and_run (BufferSet& bufs, 169 samplepos_t start, samplepos_t end, double speed, 170 ChanMapping const& in, ChanMapping const& out, 171 pframes_t nframes, samplecnt_t offset); 172 173 174 bool write_immediate_event (Evoral::EventType event_type, size_t size, const uint8_t* buf); 175 176 void realtime_handle_transport_stopped (); 177 void realtime_locate (bool); 178 void monitoring_changed (); 179 add_slave(boost::shared_ptr<Plugin>,bool realtime)180 virtual void add_slave (boost::shared_ptr<Plugin>, bool realtime) {} remove_slave(boost::shared_ptr<Plugin>)181 virtual void remove_slave (boost::shared_ptr<Plugin>) {} 182 183 typedef struct { 184 unsigned char* data; 185 int width; 186 int height; 187 int stride; 188 } Display_Image_Surface; 189 has_inline_display()190 virtual bool has_inline_display () { return false; } inline_display_in_gui()191 virtual bool inline_display_in_gui () { return false; } render_inline_display(uint32_t,uint32_t)192 virtual Display_Image_Surface* render_inline_display (uint32_t, uint32_t) { return NULL; } 193 PBD::Signal0<void> QueueDraw; 194 has_midnam()195 virtual bool has_midnam () { return false; } read_midnam()196 virtual bool read_midnam () { return false; } midnam_model()197 virtual std::string midnam_model () { return ""; } 198 PBD::Signal0<void> UpdateMidnam; 199 PBD::Signal0<void> UpdatedMidnam; 200 knows_bank_patch()201 virtual bool knows_bank_patch () { return false; } bank_patch(uint8_t chn)202 virtual uint32_t bank_patch (uint8_t chn) { return UINT32_MAX; } 203 PBD::Signal1<void, uint8_t> BankPatchChange; 204 205 struct PresetRecord { PresetRecordPresetRecord206 PresetRecord () : valid (false) { } 207 208 PresetRecord (const std::string& u, const std::string& l, bool s = true, const std::string& d = "") uriPresetRecord209 : uri (u) 210 , label (l) 211 , description (d) 212 , user (s) 213 , valid (true) 214 { } 215 216 bool operator!= (PresetRecord const& a) const 217 { 218 return uri != a.uri || label != a.label; 219 } 220 221 std::string uri; 222 std::string label; 223 std::string description; 224 bool user; 225 bool valid; 226 }; 227 228 /** Create a new plugin-preset from the current state 229 * 230 * @param name label to use for new preset (needs to be unique) 231 * @return PresetRecord with empty URI on failure 232 */ 233 PresetRecord save_preset (std::string name); 234 void remove_preset (std::string); 235 236 /** Set parameters using a preset */ 237 virtual bool load_preset (PresetRecord); 238 void clear_preset (); 239 240 const PresetRecord* preset_by_label (const std::string&); 241 const PresetRecord* preset_by_uri (const std::string&); 242 243 std::vector<PresetRecord> get_presets (); 244 245 /** @return Last preset to be requested; the settings may have 246 * been changed since; find out with parameter_changed_since_last_preset. 247 */ last_preset()248 PresetRecord last_preset () const 249 { 250 return _last_preset; 251 } 252 parameter_changed_since_last_preset()253 bool parameter_changed_since_last_preset () const 254 { 255 return _parameter_changed_since_last_preset; 256 } 257 first_user_preset_index()258 virtual int first_user_preset_index () const { return 0; } 259 260 /** Emitted when a preset is added or removed, respectively */ 261 PBD::Signal0<void> PresetAdded; 262 PBD::Signal0<void> PresetRemoved; 263 264 /** Emitted when any preset has been changed */ 265 static PBD::Signal3<void, std::string, Plugin*, bool> PresetsChanged; 266 267 /** Emitted when a preset has been loaded */ 268 PBD::Signal0<void> PresetLoaded; 269 270 /** Emitted when a parameter is altered in a way that may have 271 * changed the settings with respect to any loaded preset. 272 */ 273 PBD::Signal0<void> PresetDirty; 274 275 /** Emitted for preset-load to set a control-port */ 276 PBD::Signal2<void, uint32_t, float> PresetPortSetValue; 277 278 /** @return true if plugin has a custom plugin GUI */ 279 virtual bool has_editor () const = 0; 280 281 /** Emitted when a parameter is altered by something outside of our 282 * control, most typically a Plugin GUI/editor 283 */ 284 PBD::Signal2<void, uint32_t, float> ParameterChangedExternally; 285 reconfigure_io(ChanCount,ChanCount,ChanCount)286 virtual bool reconfigure_io (ChanCount /*in*/, ChanCount /*aux_in*/, ChanCount /*out*/) { return true; } match_variable_io(ChanCount &,ChanCount &,ChanCount &)287 virtual bool match_variable_io (ChanCount& /*in*/, ChanCount& /*aux_in*/, ChanCount& /*out*/) { return false; } 288 289 virtual ChanCount output_streams () const; 290 virtual ChanCount input_streams () const; 291 set_info(const PluginInfoPtr info)292 virtual void set_info (const PluginInfoPtr info) { _info = info; } get_info()293 PluginInfoPtr get_info () const { return _info; } 294 set_owner(SessionObject * o)295 virtual void set_owner (SessionObject* o) { _owner = o; } owner()296 SessionObject* owner () const { return _owner; } 297 set_cycles(uint32_t c)298 void set_cycles (uint32_t c) { _cycles = c; } cycles()299 cycles_t cycles () const { return _cycles; } 300 use_for_impulse_analysis()301 void use_for_impulse_analysis () 302 { 303 _for_impulse_analysis = true; 304 } 305 engine()306 ARDOUR::AudioEngine& engine () const { return _engine; } session()307 ARDOUR::Session& session () const { return _session; } 308 309 typedef std::map<uint32_t, ParameterDescriptor> PropertyDescriptors; 310 311 /** Get a descrption of all properties supported by this plugin. 312 * 313 * Properties are distinct from parameters in that they are potentially 314 * dynamic, referred to by key, and do not correspond 1:1 with ports. 315 * 316 * For LV2 plugins, properties are implemented by sending/receiving set/get 317 * messages to/from the plugin via event ports. 318 */ get_supported_properties()319 virtual const PropertyDescriptors& get_supported_properties () const 320 { 321 static const PropertyDescriptors nothing; 322 return nothing; 323 } 324 get_property_descriptor(uint32_t id)325 virtual const ParameterDescriptor& get_property_descriptor (uint32_t id) const 326 { 327 static const ParameterDescriptor nothing; 328 return nothing; 329 } 330 331 /** Set a property from the UI. 332 * 333 * This is not UI-specific, but may only be used by one thread. If the 334 * Ardour UI is present, that is the UI thread, but otherwise, any thread 335 * except the audio thread may call this function as long as it is not 336 * called concurrently. 337 */ set_property(uint32_t key,const Variant & value)338 virtual void set_property (uint32_t key, const Variant& value) {} 339 340 /** Emit PropertyChanged for all current property values. */ announce_property_values()341 virtual void announce_property_values () {} 342 343 /** Emitted when a property is changed in the plugin. */ 344 PBD::Signal2<void, uint32_t, Variant> PropertyChanged; 345 346 PBD::Signal1<void, uint32_t> StartTouch; 347 PBD::Signal1<void, uint32_t> EndTouch; 348 349 protected: 350 friend class PluginInsert; 351 friend class Session; 352 353 /* Called when a parameter of the plugin is changed outside of this 354 * host's control (typical via a plugin's own GUI/editor) 355 */ 356 virtual void parameter_changed_externally (uint32_t which, float val); 357 358 /* should be overridden by plugin API specific derived types to 359 * actually implement changing the parameter. The derived type should 360 * call this after the change is made. 361 * 362 * @param which parameter-id 363 * @param val the raw value (plugin internal) 364 * @param when time offset of samples in current cycle (0 .. n_samples) 365 * when the event is effective. 366 */ 367 virtual void set_parameter (uint32_t which, float val, sampleoffset_t when); 368 369 /** Do the actual saving of the current plugin settings to a preset of the provided name. 370 * Should return a URI on success, or an empty string on failure. 371 */ 372 virtual std::string do_save_preset (std::string) = 0; 373 /** Do the actual removal of a preset of the provided name */ 374 virtual void do_remove_preset (std::string) = 0; 375 376 377 /** Plugin's [internal] state changed, mark preset and session 378 * as modified. 379 */ 380 void state_changed (); 381 382 ARDOUR::AudioEngine& _engine; 383 ARDOUR::Session& _session; 384 PluginInfoPtr _info; 385 uint32_t _cycles; 386 SessionObject* _owner; 387 bool _for_impulse_analysis; 388 389 std::map<std::string, PresetRecord> _presets; 390 391 private: 392 virtual samplecnt_t plugin_latency () const = 0; 393 394 /** Fill _presets with our presets */ 395 virtual void find_presets () = 0; 396 397 /** Add state to an existing XMLNode */ 398 virtual void add_state (XMLNode*) const = 0; 399 400 bool _have_presets; 401 MidiStateTracker _tracker; 402 BufferSet _pending_stop_events; 403 bool _have_pending_stop_events; 404 PresetRecord _last_preset; 405 bool _parameter_changed_since_last_preset; 406 407 PBD::ScopedConnection _preset_connection; 408 409 MidiRingBuffer<samplepos_t> _immediate_events; 410 411 void invalidate_preset_cache (std::string const&, Plugin*, bool); 412 void resolve_midi (); 413 }; 414 415 struct PluginPreset { 416 PluginInfoPtr _pip; 417 Plugin::PresetRecord _preset; 418 419 PluginPreset (PluginInfoPtr pip, const Plugin::PresetRecord* preset = NULL) _pipPluginPreset420 : _pip (pip) 421 { 422 if (preset) { 423 _preset.uri = preset->uri; 424 _preset.label = preset->label; 425 _preset.user = preset->user; 426 _preset.description = preset->description; 427 _preset.valid = preset->valid; 428 } 429 } 430 }; 431 432 typedef boost::shared_ptr<PluginPreset> PluginPresetPtr; 433 typedef std::list<PluginPresetPtr> PluginPresetList; 434 435 PluginPtr 436 find_plugin (ARDOUR::Session&, std::string unique_id, ARDOUR::PluginType); 437 438 class LIBARDOUR_API PluginInfo 439 { 440 public: PluginInfo()441 PluginInfo () 442 : multichannel_name_ambiguity (false) 443 , plugintype_name_ambiguity (false) 444 , index (0) 445 {} 446 ~PluginInfo()447 virtual ~PluginInfo () {} 448 449 std::string name; 450 std::string category; 451 std::string creator; 452 std::string path; 453 ChanCount n_inputs; 454 ChanCount n_outputs; 455 ARDOUR::PluginType type; 456 457 bool multichannel_name_ambiguity; 458 bool plugintype_name_ambiguity; 459 460 std::string unique_id; 461 462 virtual PluginPtr load (Session& session) = 0; 463 464 /* NOTE: it is possible for a plugin to be an effect AND an instrument. 465 * override these funcs as necessary to support that. */ 466 virtual bool is_effect () const; 467 virtual bool is_instrument () const; 468 virtual bool is_utility () const; // this includes things like "generators" and "midi filters" 469 virtual bool is_analyzer () const; 470 471 virtual bool needs_midi_input () const; 472 473 virtual std::vector<Plugin::PresetRecord> get_presets (bool user_only) const = 0; 474 475 /* NOTE: this block of virtual methods looks like the interface 476 * to a Processor, but Plugin does not inherit from Processor. 477 * It is therefore not required that these precisely match 478 * the interface, but it is likely that they will evolve together. */ 479 480 /* @return true if the plugin can change its inputs or outputs on demand. */ reconfigurable_io()481 virtual bool reconfigurable_io () const { return false; } 482 483 /* max [re]configurable outputs (if finite, 0 otherwise) */ max_configurable_ouputs()484 virtual uint32_t max_configurable_ouputs () const 485 { 486 return n_outputs.n_audio(); 487 } 488 489 protected: 490 friend class PluginManager; 491 uint32_t index; //< used for LADSPA, index in module 492 }; 493 494 } // namespace ARDOUR 495 496 #endif /* __ardour_plugin_h__ */ 497