source/backend/CarlaPlugin.hpp

   1 /*
   2  * Carla Plugin Host
   3  * Copyright (C) 2011-2023 Filipe Coelho <falktx@falktx.com>
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License as
   7  * published by the Free Software Foundation; either version 2 of
   8  * the License, or any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * For a full copy of the GNU General Public License see the doc/GPL.txt file.
  16  */
  17
  18 #ifndef CARLA_PLUGIN_HPP_INCLUDED
  19 #define CARLA_PLUGIN_HPP_INCLUDED
  20
  21 #include "CarlaBackend.h"
  22 #include "CarlaPluginPtr.hpp"
  23
  24 // -----------------------------------------------------------------------
  25 // Avoid including extra libs here
  26
  27 typedef struct _NativePluginDescriptor NativePluginDescriptor;
  28 struct LADSPA_RDF_Descriptor;
  29
  30 // -----------------------------------------------------------------------
  31
  32 CARLA_BACKEND_START_NAMESPACE
  33
  34 #ifdef _MSC_VER
  35 # define CARLA_PLUGIN_WARN_UNUSED_RESULT
  36 #else
  37 # define CARLA_PLUGIN_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
  38 #endif
  39
  40 // -----------------------------------------------------------------------
  41
  42 /*!
  43  * @defgroup CarlaPluginAPI Carla Plugin API
  44  *
  45  * The Carla Plugin API.
  46  * @{
  47  */
  48
  49 class CarlaEngineAudioPort;
  50 class CarlaEngineCVPort;
  51 class CarlaEngineEventPort;
  52 class CarlaEngineCVSourcePorts;
  53 class CarlaEngineBridge;
  54 struct CarlaStateSave;
  55 struct EngineEvent;
  56
  57 // -----------------------------------------------------------------------
  58
  59 /*!
  60  * Carla Backend base plugin class
  61  *
  62  * This is the base class for all available plugin types available in Carla Backend.
  63  * All virtual calls are implemented in this class as fallback (except reload and process),
  64  * so it's safe to only override needed calls.
  65  *
  66  * @see PluginType
  67  */
  68 class CARLA_API CarlaPlugin
  69 {
  70 protected:
  71     /*!
  72      * This is the constructor of the base plugin class.
  73      *
  74      * @param engine The engine which this plugin belongs to, must not be null
  75      * @param id     The 'id' of this plugin, must be between 0 and CarlaEngine::maxPluginNumber()
  76      */
  77     CarlaPlugin(CarlaEngine* engine, uint id);
  78
  79 public:
  80     /*!
  81      * This is the destructor of the base plugin class.
  82      */
  83     virtual ~CarlaPlugin();
  84
  85     // -------------------------------------------------------------------
  86     // Information (base)
  87
  88     /*!
  89      * Get the plugin's type (a subclass of CarlaPlugin).
  90      *
  91      * @note Plugin bridges will return their respective plugin type, there is no plugin type such as "bridge".
  92      *       To check if a plugin is a bridge use:
  93      * @code
  94      * if (getHints() & PLUGIN_IS_BRIDGE)
  95      *     ...
  96      * @endcode
  97      */
  98     virtual PluginType getType() const noexcept = 0;
  99
 100     /*!
 101      * Get the plugin's id (as passed in the constructor).
 102      *
 103      * @see setId()
 104      */
 105     uint getId() const noexcept;
 106
 107     /*!
 108      * Get the plugin's hints.
 109      *
 110      * @see PluginHints
 111      */
 112     uint getHints() const noexcept;
 113
 114     /*!
 115      * Get the plugin's options (currently in use).
 116      *
 117      * @see PluginOptions, getOptionsAvailable() and setOption()
 118      */
 119     uint getOptionsEnabled() const noexcept;
 120
 121     /*!
 122      * Check if the plugin is enabled.
 123      * When a plugin is disabled, it will never be processed or managed in any way.
 124      *
 125      * @see setEnabled()
 126      */
 127     bool isEnabled() const noexcept;
 128
 129     /*!
 130      * Get the plugin's internal name.
 131      * This name is unique within all plugins in an engine.
 132      *
 133      * @see getRealName() and setName()
 134      */
 135     const char* getName() const noexcept;
 136
 137     /*!
 138      * Get the currently loaded DLL filename for this plugin.
 139      * (Sound kits return their exact filename).
 140      */
 141     const char* getFilename() const noexcept;
 142
 143     /*!
 144      * Get the plugins's icon name.
 145      */
 146     const char* getIconName() const noexcept;
 147
 148     /*!
 149      * Get the plugin's category (delay, filter, synth, etc).
 150      */
 151     virtual PluginCategory getCategory() const noexcept;
 152
 153     /*!
 154      * Get the plugin's native unique Id.
 155      * May return 0 on plugin types that don't support Ids.
 156      */
 157     virtual int64_t getUniqueId() const noexcept;
 158
 159     /*!
 160      * Get the plugin's latency, in sample frames.
 161      */
 162     virtual uint32_t getLatencyInFrames() const noexcept;
 163
 164     // -------------------------------------------------------------------
 165     // Information (count)
 166
 167     /*!
 168      * Get the number of audio inputs.
 169      */
 170     uint32_t getAudioInCount() const noexcept;
 171
 172     /*!
 173      * Get the number of audio outputs.
 174      */
 175     uint32_t getAudioOutCount() const noexcept;
 176
 177     /*!
 178      * Get the number of CV inputs.
 179      */
 180     uint32_t getCVInCount() const noexcept;
 181
 182     /*!
 183      * Get the number of CV outputs.
 184      */
 185     uint32_t getCVOutCount() const noexcept;
 186
 187     /*!
 188      * Get the number of MIDI inputs.
 189      */
 190     virtual uint32_t getMidiInCount() const noexcept;
 191
 192     /*!
 193      * Get the number of MIDI outputs.
 194      */
 195     virtual uint32_t getMidiOutCount() const noexcept;
 196
 197     /*!
 198      * Get the number of parameters.
 199      * To know the number of parameter inputs and outputs separately use getParameterCountInfo() instead.
 200      */
 201     uint32_t getParameterCount() const noexcept;
 202
 203     /*!
 204      * Get the number of scalepoints for parameter @a parameterId.
 205      */
 206     virtual uint32_t getParameterScalePointCount(uint32_t parameterId) const noexcept;
 207
 208     /*!
 209      * Get the number of programs.
 210      */
 211     uint32_t getProgramCount() const noexcept;
 212
 213     /*!
 214      * Get the number of MIDI programs.
 215      */
 216     uint32_t getMidiProgramCount() const noexcept;
 217
 218     /*!
 219      * Get the number of custom data sets.
 220      */
 221     uint32_t getCustomDataCount() const noexcept;
 222
 223     // -------------------------------------------------------------------
 224     // Information (current data)
 225
 226     /*!
 227      * Get the current program number (-1 if unset).
 228      *
 229      * @see setProgram()
 230      */
 231     int32_t getCurrentProgram() const noexcept;
 232
 233     /*!
 234      * Get the current MIDI program number (-1 if unset).
 235      *
 236      * @see setMidiProgram()
 237      * @see setMidiProgramById()
 238      */
 239     int32_t getCurrentMidiProgram() const noexcept;
 240
 241     /*!
 242      * Get hints about an audio port.
 243      */
 244     virtual uint getAudioPortHints(bool isOutput, uint32_t portIndex) const noexcept;
 245
 246     /*!
 247      * Get the parameter data of @a parameterId.
 248      */
 249     const ParameterData& getParameterData(uint32_t parameterId) const noexcept;
 250
 251     /*!
 252      * Get the parameter ranges of @a parameterId.
 253      */
 254     const ParameterRanges& getParameterRanges(uint32_t parameterId) const noexcept;
 255
 256     /*!
 257      * Check if parameter @a parameterId is of output type.
 258      */
 259     bool isParameterOutput(uint32_t parameterId) const noexcept;
 260
 261     /*!
 262      * Get the MIDI program at @a index.
 263      *
 264      * @see getMidiProgramName()
 265      */
 266     const MidiProgramData& getMidiProgramData(uint32_t index) const noexcept;
 267
 268     /*!
 269      * Get the custom data set at @a index.
 270      *
 271      * @see getCustomDataCount() and setCustomData()
 272      */
 273     const CustomData& getCustomData(uint32_t index) const noexcept;
 274
 275     /*!
 276      * Get the complete plugin chunk data into @a dataPtr.
 277      *
 278      * @note Make sure to verify the plugin supports chunks before calling this function!
 279      * @return The size of the chunk or 0 if invalid.
 280      *
 281      * @see setChunkData()
 282      */
 283     virtual std::size_t getChunkData(void** dataPtr) noexcept;
 284
 285     // -------------------------------------------------------------------
 286     // Information (per-plugin data)
 287
 288     /*!
 289      * Get the plugin available options.
 290      *
 291      * @see PluginOptions, getOptions() and setOption()
 292      */
 293     virtual uint getOptionsAvailable() const noexcept;
 294
 295     /*!
 296      * Get the current parameter value of @a parameterId.
 297      */
 298     virtual float getParameterValue(uint32_t parameterId) const noexcept;
 299
 300     /*!
 301      * Get the scalepoint @a scalePointId value of the parameter @a parameterId.
 302      */
 303     virtual float getParameterScalePointValue(uint32_t parameterId, uint32_t scalePointId) const noexcept;
 304
 305     /*!
 306      * Get the plugin's label (URI for LV2 plugins).
 307      */
 308     CARLA_PLUGIN_WARN_UNUSED_RESULT
 309     virtual bool getLabel(char* strBuf) const noexcept;
 310
 311     /*!
 312      * Get the plugin's maker.
 313      */
 314     CARLA_PLUGIN_WARN_UNUSED_RESULT
 315     virtual bool getMaker(char* strBuf) const noexcept;
 316
 317     /*!
 318      * Get the plugin's copyright/license.
 319      */
 320     CARLA_PLUGIN_WARN_UNUSED_RESULT
 321     virtual bool getCopyright(char* strBuf) const noexcept;
 322
 323     /*!
 324      * Get the plugin's (real) name.
 325      *
 326      * @see getName() and setName()
 327      */
 328     CARLA_PLUGIN_WARN_UNUSED_RESULT
 329     virtual bool getRealName(char* strBuf) const noexcept;
 330
 331     /*!
 332      * Get the name of the parameter @a parameterId.
 333      */
 334     CARLA_PLUGIN_WARN_UNUSED_RESULT
 335     virtual bool getParameterName(uint32_t parameterId, char* strBuf) const noexcept;
 336
 337     /*!
 338      * Get the symbol of the parameter @a parameterId.
 339      */
 340     CARLA_PLUGIN_WARN_UNUSED_RESULT
 341     virtual bool getParameterSymbol(uint32_t parameterId, char* strBuf) const noexcept;
 342
 343     /*!
 344      * Get the custom text of the parameter @a parameterId.
 345      * @see PARAMETER_USES_CUSTOM_TEXT
 346      */
 347     CARLA_PLUGIN_WARN_UNUSED_RESULT
 348     virtual bool getParameterText(uint32_t parameterId, char* strBuf) noexcept;
 349
 350     /*!
 351      * Get the unit of the parameter @a parameterId.
 352      */
 353     CARLA_PLUGIN_WARN_UNUSED_RESULT
 354     virtual bool getParameterUnit(uint32_t parameterId, char* strBuf) const noexcept;
 355
 356     /*!
 357      * Get the comment (documentation) of the parameter @a parameterId.
 358      */
 359     CARLA_PLUGIN_WARN_UNUSED_RESULT
 360     virtual bool getParameterComment(uint32_t parameterId, char* strBuf) const noexcept;
 361
 362     /*!
 363      * Get the group name of the parameter @a parameterId.
 364      * @note The group name is prefixed by a unique symbol and ":".
 365      */
 366     CARLA_PLUGIN_WARN_UNUSED_RESULT
 367     virtual bool getParameterGroupName(uint32_t parameterId, char* strBuf) const noexcept;
 368
 369     /*!
 370      * Get the scalepoint @a scalePointId label of the parameter @a parameterId.
 371      */
 372     CARLA_PLUGIN_WARN_UNUSED_RESULT
 373     virtual bool getParameterScalePointLabel(uint32_t parameterId, uint32_t scalePointId, char* strBuf) const noexcept;
 374
 375     /*!
 376      * Get the current parameter value of @a parameterId.
 377      * @a parameterId can be negative to allow internal parameters.
 378      * @see InternalParametersIndex
 379      */
 380     float getInternalParameterValue(int32_t parameterId) const noexcept;
 381
 382     /*!
 383      * Get the name of the program at @a index.
 384      */
 385     CARLA_PLUGIN_WARN_UNUSED_RESULT
 386     bool getProgramName(uint32_t index, char* strBuf) const noexcept;
 387
 388     /*!
 389      * Get the name of the MIDI program at @a index.
 390      *
 391      * @see getMidiProgramInfo()
 392      */
 393     CARLA_PLUGIN_WARN_UNUSED_RESULT
 394     bool getMidiProgramName(uint32_t index, char* strBuf) const noexcept;
 395
 396     /*!
 397      * Get information about the plugin's parameter count.
 398      * This is used to check how many input, output and total parameters are available.
 399      *
 400      * @note Some parameters might not be input or output (ie, invalid).
 401      *
 402      * @see getParameterCount()
 403      */
 404     void getParameterCountInfo(uint32_t& ins, uint32_t& outs) const noexcept;
 405
 406     // -------------------------------------------------------------------
 407     // Set data (state)
 408
 409     /*!
 410      * Tell the plugin to prepare for save.
 411      * @param temporary Wherever we are saving into a temporary location
 412      *                  (for duplication, renaming or similar)
 413      */
 414     virtual void prepareForSave(bool temporary);
 415
 416     /*!
 417      * Reset all possible parameters.
 418      */
 419     virtual void resetParameters() noexcept;
 420
 421     /*!
 422      * Randomize all possible parameters.
 423      */
 424     virtual void randomizeParameters() noexcept;
 425
 426     /*!
 427      * Get the plugin's save state.
 428      * The plugin will automatically call prepareForSave() if requested.
 429      *
 430      * @see loadStateSave()
 431      */
 432     const CarlaStateSave& getStateSave(bool callPrepareForSave = true);
 433
 434     /*!
 435      * Get the plugin's save state.
 436      *
 437      * @see getStateSave()
 438      */
 439     void loadStateSave(const CarlaStateSave& stateSave);
 440
 441     /*!
 442      * Save the current plugin state to @a filename.
 443      *
 444      * @see loadStateFromFile()
 445      */
 446     bool saveStateToFile(const char* filename);
 447
 448     /*!
 449      * Save the plugin state from @a filename.
 450      *
 451      * @see saveStateToFile()
 452      */
 453     bool loadStateFromFile(const char* filename);
 454
 455    #ifndef CARLA_PLUGIN_ONLY_BRIDGE
 456     /*!
 457      * Export this plugin as its own LV2 plugin, using a carla wrapper around it for the LV2 functionality.
 458      */
 459     bool exportAsLV2(const char* lv2path);
 460    #endif
 461
 462     // -------------------------------------------------------------------
 463     // Set data (internal stuff)
 464
 465     /*!
 466      * Set the plugin's id to @a newId.
 467      *
 468      * @see getId()
 469      * @note RT call
 470      */
 471     virtual void setId(uint newId) noexcept;
 472
 473     /*!
 474      * Set the plugin's name to @a newName.
 475      *
 476      * @see getName() and getRealName()
 477      */
 478     virtual void setName(const char* newName);
 479
 480     /*!
 481      * Set a plugin's option.
 482      *
 483      * @see getOptions() and getOptionsAvailable()
 484      */
 485     virtual void setOption(uint option, bool yesNo, bool sendCallback);
 486
 487     /*!
 488      * Enable or disable the plugin according to @a yesNo.
 489      * When a plugin is disabled, it will never be processed or managed in any way.
 490      *
 491      * @see isEnabled()
 492      */
 493     void setEnabled(bool yesNo) noexcept;
 494
 495     /*!
 496      * Set plugin as active according to @a active.
 497      *
 498      * @param sendOsc Send message change over OSC
 499      * @param sendCallback Send message change to registered callback
 500      */
 501     void setActive(bool active, bool sendOsc, bool sendCallback) noexcept;
 502
 503 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
 504     /*!
 505      * Set the plugin's dry/wet signal value to @a value.
 506      * @a value must be between 0.0 and 1.0.
 507      *
 508      * @param sendOsc Send message change over OSC
 509      * @param sendCallback Send message change to registered callback
 510      */
 511     void setDryWet(float value, bool sendOsc, bool sendCallback) noexcept;
 512
 513     /*!
 514      * Set the plugin's output volume to @a value.
 515      * @a value must be between 0.0 and 1.27.
 516      *
 517      * @param sendOsc Send message change over OSC
 518      * @param sendCallback Send message change to registered callback
 519      */
 520     void setVolume(float value, bool sendOsc, bool sendCallback) noexcept;
 521
 522     /*!
 523      * Set the plugin's output left balance value to @a value.
 524      * @a value must be between -1.0 and 1.0.
 525      *
 526      * @param sendOsc Send message change over OSC
 527      * @param sendCallback Send message change to registered callback
 528      *
 529      * @note Pure-Stereo plugins only!
 530      */
 531     void setBalanceLeft(float value, bool sendOsc, bool sendCallback) noexcept;
 532
 533     /*!
 534      * Set the plugin's output right balance value to @a value.
 535      * @a value must be between -1.0 and 1.0.
 536      *
 537      * @param sendOsc Send message change over OSC
 538      * @param sendCallback Send message change to registered callback
 539      *
 540      * @note Pure-Stereo plugins only!
 541      */
 542     void setBalanceRight(float value, bool sendOsc, bool sendCallback) noexcept;
 543
 544     /*!
 545      * Set the plugin's output panning value to @a value.
 546      * @a value must be between -1.0 and 1.0.
 547      *
 548      * @param sendOsc Send message change over OSC
 549      * @param sendCallback Send message change to registered callback
 550      *
 551      * @note Force-Stereo plugins only!
 552      */
 553     void setPanning(float value, bool sendOsc, bool sendCallback) noexcept;
 554
 555     /*!
 556      * Overloaded functions, to be called from within RT context only.
 557      */
 558     void setDryWetRT(float value, bool sendCallbackLater) noexcept;
 559     void setVolumeRT(float value, bool sendCallbackLater) noexcept;
 560     void setBalanceLeftRT(float value, bool sendCallbackLater) noexcept;
 561     void setBalanceRightRT(float value, bool sendCallbackLater) noexcept;
 562     void setPanningRT(float value, bool sendCallbackLater) noexcept;
 563 #endif // ! BUILD_BRIDGE_ALTERNATIVE_ARCH
 564
 565     /*!
 566      * Set the plugin's midi control channel.
 567      *
 568      * @param sendOsc Send message change over OSC
 569      * @param sendCallback Send message change to registered callback
 570      */
 571     virtual void setCtrlChannel(int8_t channel, bool sendOsc, bool sendCallback) noexcept;
 572
 573     // -------------------------------------------------------------------
 574     // Set data (plugin-specific stuff)
 575
 576     /*!
 577      * Set a plugin's parameter value.
 578      *
 579      * @param parameterId The parameter to change
 580      * @param value The new parameter value, must be within the parameter's range
 581      * @param sendGui Send message change to plugin's custom GUI, if any
 582      * @param sendOsc Send message change over OSC
 583      * @param sendCallback Send message change to registered callback
 584      *
 585      * @see getParameterValue()
 586      */
 587     virtual void setParameterValue(uint32_t parameterId, float value, bool sendGui, bool sendOsc, bool sendCallback) noexcept;
 588
 589     /*!
 590      * Overloaded function, to be called from within RT context only.
 591      */
 592     virtual void setParameterValueRT(uint32_t parameterId, float value, uint32_t frameOffset, bool sendCallbackLater) noexcept;
 593
 594     /*!
 595      * Set a plugin's parameter value, including internal parameters.
 596      * @a rindex can be negative to allow internal parameters change (as defined in InternalParametersIndex).
 597      *
 598      * @see setParameterValue()
 599      * @see setActive()
 600      * @see setDryWet()
 601      * @see setVolume()
 602      * @see setBalanceLeft()
 603      * @see setBalanceRight()
 604      */
 605     void setParameterValueByRealIndex(int32_t rindex, float value, bool sendGui, bool sendOsc, bool sendCallback) noexcept;
 606
 607     /*!
 608      * Set parameter's @a parameterId MIDI channel to @a channel.
 609      * @a channel must be between 0 and 15.
 610      */
 611     virtual void setParameterMidiChannel(uint32_t parameterId, uint8_t channel, bool sendOsc, bool sendCallback) noexcept;
 612
 613     /*!
 614      * Set parameter's @a parameterId mapped control index to @a index.
 615      * @see ParameterData::mappedControlIndex
 616      */
 617     virtual void setParameterMappedControlIndex(uint32_t parameterId, int16_t index,
 618                                                 bool sendOsc, bool sendCallback, bool reconfigureNow) noexcept;
 619
 620     /*!
 621      * Set parameter's @a parameterId mapped range to @a minimum and @a maximum.
 622      */
 623     virtual void setParameterMappedRange(uint32_t parameterId, float minimum, float maximum,
 624                                          bool sendOsc, bool sendCallback) noexcept;
 625
 626     /*!
 627      * Add a custom data set.
 628      * If @a key already exists, its current value will be swapped with @a value.
 629      *
 630      * @param type Type of data used in @a value.
 631      * @param key A key identifying this data set.
 632      * @param value The value of the data set, of type @a type.
 633      * @param sendGui Send message change to plugin's custom GUI, if any
 634      *
 635      * @see getCustomDataCount() and getCustomData()
 636      */
 637     virtual void setCustomData(const char* type, const char* key, const char* value, bool sendGui);
 638
 639     /*!
 640      * Set the complete chunk data as @a data.
 641      *
 642      * @see getChunkData()
 643      *
 644      * @note Make sure to verify the plugin supports chunks before calling this function
 645      */
 646     virtual void setChunkData(const void* data, std::size_t dataSize);
 647
 648     /*!
 649      * Change the current plugin program to @a index.
 650      *
 651      * If @a index is negative the plugin's program will be considered unset.
 652      * The plugin's default parameter values will be updated when this function is called.
 653      *
 654      * @param index New program index to use
 655      * @param sendGui Send message change to plugin's custom GUI, if any
 656      * @param sendOsc Send message change over OSC
 657      * @param sendCallback Send message change to registered callback
 658      */
 659     virtual void setProgram(int32_t index, bool sendGui, bool sendOsc, bool sendCallback, bool doingInit = false) noexcept;
 660
 661     /*!
 662      * Change the current MIDI plugin program to @a index.
 663      *
 664      * If @a index is negative the plugin's program will be considered unset.
 665      * The plugin's default parameter values will be updated when this function is called.
 666      *
 667      * @param index New program index to use
 668      * @param sendGui Send message change to plugin's custom GUI, if any
 669      * @param sendOsc Send message change over OSC
 670      * @param sendCallback Send message change to registered callback
 671      */
 672     virtual void setMidiProgram(int32_t index, bool sendGui, bool sendOsc, bool sendCallback, bool doingInit = false) noexcept;
 673
 674     /*!
 675      * This is an overloaded call to setMidiProgram().
 676      * It changes the current MIDI program using @a bank and @a program values instead of index.
 677      */
 678     void setMidiProgramById(uint32_t bank, uint32_t program, bool sendGui, bool sendOsc, bool sendCallback) noexcept;
 679
 680     /*!
 681      * Overloaded functions, to be called from within RT context only.
 682      */
 683     virtual void setProgramRT(uint32_t index, bool sendCallbackLater) noexcept;
 684     virtual void setMidiProgramRT(uint32_t index, bool sendCallbackLater) noexcept;
 685
 686     // -------------------------------------------------------------------
 687     // Plugin state
 688
 689     /*!
 690      * Reload the plugin's entire state (including programs).
 691      * The plugin will be disabled during this call.
 692      */
 693     virtual void reload() = 0;
 694
 695     /*!
 696      * Reload the plugin's programs state.
 697      */
 698     virtual void reloadPrograms(bool doInit);
 699
 700     // -------------------------------------------------------------------
 701     // Plugin processing
 702
 703 protected:
 704     /*!
 705      * Plugin activate call.
 706      */
 707     virtual void activate() noexcept;
 708
 709     /*!
 710      * Plugin activate call.
 711      */
 712     virtual void deactivate() noexcept;
 713
 714 public:
 715     /*!
 716      * Plugin process call.
 717      */
 718     virtual void process(const float* const* audioIn, float** audioOut,
 719                          const float* const* cvIn, float** cvOut, uint32_t frames) = 0;
 720
 721     /*!
 722      * Tell the plugin the current buffer size changed.
 723      */
 724     virtual void bufferSizeChanged(uint32_t newBufferSize);
 725
 726     /*!
 727      * Tell the plugin the current sample rate changed.
 728      */
 729     virtual void sampleRateChanged(double newSampleRate);
 730
 731     /*!
 732      * Tell the plugin the current offline mode changed.
 733      */
 734     virtual void offlineModeChanged(bool isOffline);
 735
 736     // -------------------------------------------------------------------
 737     // Misc
 738
 739     /*!
 740      * Idle function (non-UI), called at regular intervals.
 741      * @note: This function is NOT called from the main thread.
 742      */
 743     virtual void idle();
 744
 745     /*!
 746      * Try to lock the plugin's master mutex.
 747      * @param forcedOffline When true, always locks and returns true
 748      */
 749     bool tryLock(bool forcedOffline) noexcept;
 750
 751     /*!
 752      * Unlock the plugin's master mutex.
 753      */
 754     void unlock() noexcept;
 755
 756     // -------------------------------------------------------------------
 757     // Plugin buffers
 758
 759     /*!
 760      * Initialize all RT buffers of the plugin.
 761      */
 762     virtual void initBuffers() const noexcept;
 763
 764     /*!
 765      * Delete and clear all RT buffers.
 766      */
 767     virtual void clearBuffers() noexcept;
 768
 769     // -------------------------------------------------------------------
 770     // OSC stuff
 771
 772     /*!
 773      * Handle an OSC message.
 774      * FIXME
 775      */
 776     virtual void handleOscMessage(const char* method,
 777                                   int argc,
 778                                   const void* argv,
 779                                   const char* types,
 780                                   void* msg);
 781
 782     // -------------------------------------------------------------------
 783     // MIDI events
 784
 785     /*!
 786      * Send a single midi note to be processed in the next audio callback.
 787      * A note with 0 velocity means note-off.
 788      * @note Non-RT call
 789      */
 790     void sendMidiSingleNote(uint8_t channel, uint8_t note, uint8_t velo,
 791                             bool sendGui, bool sendOsc, bool sendCallback);
 792
 793 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
 794     /*!
 795      * Send all midi notes off to the host callback.
 796      * This doesn't send the actual MIDI All-Notes-Off event, but 128 note-offs instead (IFF ctrlChannel is valid).
 797      * @note RT call
 798      */
 799     void postponeRtAllNotesOff();
 800 #endif
 801
 802     // -------------------------------------------------------------------
 803     // UI Stuff
 804
 805     /*!
 806      * Set a custom title for the plugin UI window created by Carla.
 807      */
 808     virtual void setCustomUITitle(const char* title) noexcept;
 809
 810     /*!
 811      * Show (or hide) the plugin's custom UI according to @a yesNo.
 812      * This function is always called from the main thread.
 813      */
 814     virtual void showCustomUI(bool yesNo);
 815
 816     /*!
 817      * Embed the plugin's custom UI to the system pointer @a ptr.
 818      * This function is always called from the main thread.
 819      * @note This is very experimental and subject to change at this point
 820      */
 821     virtual void* embedCustomUI(void* ptr);
 822
 823     /*!
 824      * UI idle function, called at regular intervals.
 825      * This function is only called from the main thread if PLUGIN_NEEDS_UI_MAIN_THREAD is set.
 826      * @note This function may sometimes be called even if the UI is not visible yet.
 827      */
 828     virtual void uiIdle();
 829
 830     /*!
 831      * Tell the UI a parameter has changed.
 832      * @see uiIdle
 833      */
 834     virtual void uiParameterChange(uint32_t index, float value) noexcept;
 835
 836     /*!
 837      * Tell the UI the current program has changed.
 838      * @see uiIdle
 839      */
 840     virtual void uiProgramChange(uint32_t index) noexcept;
 841
 842     /*!
 843      * Tell the UI the current midi program has changed.
 844      * @see uiIdle
 845      */
 846     virtual void uiMidiProgramChange(uint32_t index) noexcept;
 847
 848     /*!
 849      * Tell the UI a note has been pressed.
 850      * @see uiIdle
 851      */
 852     virtual void uiNoteOn(uint8_t channel, uint8_t note, uint8_t velo) noexcept;
 853
 854     /*!
 855      * Tell the UI a note has been released.
 856      * @see uiIdle
 857      */
 858     virtual void uiNoteOff(uint8_t channel, uint8_t note) noexcept;
 859
 860     // -------------------------------------------------------------------
 861     // Helper functions
 862
 863     /*!
 864      * Get the plugin's engine, as passed in the constructor.
 865      */
 866     CarlaEngine* getEngine() const noexcept;
 867
 868     /*!
 869      * Get the plugin's engine client.
 870      */
 871     CarlaEngineClient* getEngineClient() const noexcept;
 872
 873     /*!
 874      * Get a plugin's audio input port.
 875      */
 876     CarlaEngineAudioPort* getAudioInPort(uint32_t index) const noexcept;
 877
 878     /*!
 879      * Get a plugin's audio output port.
 880      */
 881     CarlaEngineAudioPort* getAudioOutPort(uint32_t index) const noexcept;
 882
 883     /*!
 884      * Get a plugin's CV input port.
 885      */
 886     CarlaEngineCVPort* getCVInPort(uint32_t index) const noexcept;
 887
 888     /*!
 889      * Get a plugin's CV output port.
 890      */
 891     CarlaEngineCVPort* getCVOutPort(uint32_t index) const noexcept;
 892
 893     /*!
 894      * Get the plugin's default event input port.
 895      */
 896     CarlaEngineEventPort* getDefaultEventInPort() const noexcept;
 897
 898     /*!
 899      * Get the plugin's default event output port.
 900      */
 901     CarlaEngineEventPort* getDefaultEventOutPort() const noexcept;
 902
 903 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
 904     /*!
 905      * Check if the plugin is interested on MIDI learn, and if so, map this event to the parameter that wants it.
 906      * Event MUST be of control type and not have been handled before.
 907      */
 908     void checkForMidiLearn(EngineEvent& event) noexcept;
 909 #endif
 910
 911     /*!
 912      * Get the plugin's type native handle.
 913      * This will be LADSPA_Handle, LV2_Handle, etc.
 914      */
 915     virtual void* getNativeHandle() const noexcept;
 916
 917     /*!
 918      * Get the plugin's type native descriptor.
 919      * This will be LADSPA_Descriptor, DSSI_Descriptor, LV2_Descriptor, AEffect, etc.
 920      */
 921     virtual const void* getNativeDescriptor() const noexcept;
 922
 923     /*!
 924      * Get the plugin UI bridge process Id.
 925      */
 926     virtual uintptr_t getUiBridgeProcessId() const noexcept;
 927
 928     // -------------------------------------------------------------------
 929
 930     /*!
 931      * Get the plugin's patchbay nodeId.
 932      * @see setPatchbayNodeId()
 933      */
 934     uint32_t getPatchbayNodeId() const noexcept;
 935
 936     /*!
 937      * Set the plugin's patchbay nodeId.
 938      * @see getPatchbayNodeId()
 939      */
 940     void setPatchbayNodeId(uint32_t nodeId) noexcept;
 941
 942     // -------------------------------------------------------------------
 943     // Plugin initializers
 944
 945     /*!
 946      * Get a plugin's binary type.
 947      * This is always BINARY_NATIVE unless the plugin is a bridge.
 948      */
 949     virtual BinaryType getBinaryType() const noexcept
 950     {
 951         return BINARY_NATIVE;
 952     }
 953
 954     /*!
 955      * Handy function required by CarlaEngine::clonePlugin().
 956      */
 957     virtual const void* getExtraStuff() const noexcept
 958     {
 959         return nullptr;
 960     }
 961
 962 #ifndef DOXYGEN
 963     struct Initializer {
 964         CarlaEngine* const engine;
 965         const uint id;
 966         const char* const filename;
 967         const char* const name;
 968         const char* const label;
 969         const int64_t uniqueId;
 970         const uint options; // see PluginOptions
 971     };
 972
 973     static CarlaPluginPtr newBridge(const Initializer& init,
 974                                     BinaryType btype, PluginType ptype,
 975                                     const char* binaryArchName, const char* bridgeBinary);
 976
 977    #ifndef CARLA_PLUGIN_ONLY_BRIDGE
 978     static CarlaPluginPtr newNative(const Initializer& init);
 979
 980     static CarlaPluginPtr newLADSPA(const Initializer& init, const LADSPA_RDF_Descriptor* rdfDescriptor);
 981     static CarlaPluginPtr newDSSI(const Initializer& init);
 982     static CarlaPluginPtr newLV2(const Initializer& init);
 983     static CarlaPluginPtr newVST2(const Initializer& init);
 984     static CarlaPluginPtr newVST3(const Initializer& init);
 985     static CarlaPluginPtr newAU(const Initializer& init);
 986     static CarlaPluginPtr newJSFX(const Initializer& init);
 987     static CarlaPluginPtr newCLAP(const Initializer& init);
 988
 989     static CarlaPluginPtr newJuce(const Initializer& init, const char* format);
 990     static CarlaPluginPtr newFluidSynth(const Initializer& init, PluginType ptype, bool use16Outs);
 991     static CarlaPluginPtr newSFZero(const Initializer& init);
 992
 993     static CarlaPluginPtr newJackApp(const Initializer& init);
 994    #endif
 995 #endif
 996
 997     // -------------------------------------------------------------------
 998
 999 protected:
1000     /*!
1001      * Internal data, for CarlaPlugin subclasses only.
1002      */
1003     struct ProtectedData;
1004     ProtectedData* const pData;
1005
1006     // -------------------------------------------------------------------
1007     // Internal helper functions
1008
1009 protected:
1010     /*!
1011      * Clone/copy files from another LV2 plugin into this one..
1012      */
1013     virtual void cloneLV2Files(const CarlaPlugin& other);
1014
1015     /*!
1016      * Call LV2 restore.
1017      * @param temporary Wherever we are saving into a temporary location
1018      *                  (for duplication, renaming or similar)
1019      */
1020     virtual void restoreLV2State(bool temporary) noexcept;
1021
1022     /*!
1023      * Allow engine to signal that plugin will be deleted soon.
1024      */
1025     virtual void prepareForDeletion() noexcept;
1026
1027     /*!
1028      * Give plugin bridges a change to update their custom data sets.
1029      */
1030     virtual void waitForBridgeSaveSignal() noexcept;
1031
1032     // -------------------------------------------------------------------
1033     // Helper classes
1034
1035     /*!
1036      * Fully disable plugin in scope and also its engine client.
1037      * May wait-block on constructor for plugin process to end.
1038      */
1039     class ScopedDisabler
1040     {
1041     public:
1042         ScopedDisabler(CarlaPlugin* plugin) noexcept;
1043         ~ScopedDisabler() noexcept;
1044
1045     private:
1046         CarlaPlugin* const fPlugin;
1047         bool fWasEnabled;
1048
1049         CARLA_PREVENT_HEAP_ALLOCATION
1050         CARLA_DECLARE_NON_COPYABLE(ScopedDisabler)
1051     };
1052
1053     /*!
1054      * Lock the plugin's own run/process call.
1055      * Plugin will still work as normal, but output only silence.
1056      * On destructor needsReset flag might be set if the plugin might have missed some events.
1057      */
1058     class ScopedSingleProcessLocker
1059     {
1060     public:
1061         ScopedSingleProcessLocker(CarlaPlugin* plugin, bool block) noexcept;
1062         ~ScopedSingleProcessLocker() noexcept;
1063
1064     private:
1065         CarlaPlugin* const fPlugin;
1066         const bool fBlock;
1067
1068         CARLA_PREVENT_HEAP_ALLOCATION
1069         CARLA_DECLARE_NON_COPYABLE(ScopedSingleProcessLocker)
1070     };
1071
1072     friend class CarlaEngine;
1073     friend class CarlaEngineBridge;
1074     CARLA_DECLARE_NON_COPYABLE(CarlaPlugin)
1075 };
1076
1077 /**@}*/
1078
1079 // -----------------------------------------------------------------------
1080
1081 CARLA_BACKEND_END_NAMESPACE
1082
1083 #endif // CARLA_PLUGIN_HPP_INCLUDED