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