source/backend/CarlaPlugin.hpp

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