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_ENGINE_HPP_INCLUDED 19 #define CARLA_ENGINE_HPP_INCLUDED 20 21 #include "CarlaBackend.h" 22 #include "CarlaPluginPtr.hpp" 23 24 namespace water { 25 class MemoryOutputStream; 26 class XmlDocument; 27 } 28 29 CARLA_BACKEND_START_NAMESPACE 30 31 // ----------------------------------------------------------------------- 32 33 /*! 34 * @defgroup CarlaEngineAPI Carla Engine API 35 * 36 * The Carla Engine API. 37 * @{ 38 */ 39 40 /*! 41 * The type of an engine. 42 */ 43 enum EngineType { 44 /*! 45 * Null engine type. 46 */ 47 kEngineTypeNull = 0, 48 49 /*! 50 * JACK engine type. 51 * Provides all processing modes. 52 */ 53 kEngineTypeJack = 1, 54 55 /*! 56 * JUCE engine type, used to provide Native Audio and MIDI support. 57 */ 58 kEngineTypeJuce = 2, 59 60 /*! 61 * RtAudio engine type, used to provide Native Audio and MIDI support. 62 */ 63 kEngineTypeRtAudio = 3, 64 65 /*! 66 * Plugin engine type, used to export the engine as a plugin. 67 */ 68 kEngineTypePlugin = 4, 69 70 /*! 71 * Bridge engine type, used in BridgePlugin class. 72 */ 73 kEngineTypeBridge = 5, 74 75 /*! 76 * Dummy engine type, does not send audio or MIDI anywhere. 77 */ 78 kEngineTypeDummy = 6 79 }; 80 81 /*! 82 * The type of an engine port. 83 */ 84 enum EnginePortType { 85 /*! 86 * Null port type. 87 */ 88 kEnginePortTypeNull = 0, 89 90 /*! 91 * Audio port type. 92 * @see CarlaEngineAudioPort 93 */ 94 kEnginePortTypeAudio = 1, 95 96 /*! 97 * CV port type. 98 * @see CarlaEngineCVPort 99 */ 100 kEnginePortTypeCV = 2, 101 102 /*! 103 * Event port type (Control or MIDI). 104 * @see CarlaEngineEventPort 105 */ 106 kEnginePortTypeEvent = 3 107 }; 108 109 /*! 110 * The type of an engine event. 111 */ 112 enum EngineEventType { 113 /*! 114 * Null port type. 115 */ 116 kEngineEventTypeNull = 0, 117 118 /*! 119 * Control event type. 120 * @see EngineControlEvent 121 */ 122 kEngineEventTypeControl = 1, 123 124 /*! 125 * MIDI event type. 126 * @see EngineMidiEvent 127 */ 128 kEngineEventTypeMidi = 2 129 }; 130 131 /*! 132 * The type of an engine control event. 133 */ 134 enum EngineControlEventType { 135 /*! 136 * Null event type. 137 */ 138 kEngineControlEventTypeNull = 0, 139 140 /*! 141 * Parameter event type. 142 * @note Value uses a normalized range of 0.0f<->1.0f. 143 */ 144 kEngineControlEventTypeParameter = 1, 145 146 /*! 147 * MIDI Bank event type. 148 */ 149 kEngineControlEventTypeMidiBank = 2, 150 151 /*! 152 * MIDI Program change event type. 153 */ 154 kEngineControlEventTypeMidiProgram = 3, 155 156 /*! 157 * All sound off event type. 158 */ 159 kEngineControlEventTypeAllSoundOff = 4, 160 161 /*! 162 * All notes off event type. 163 */ 164 kEngineControlEventTypeAllNotesOff = 5 165 }; 166 167 /*! 168 * Special value for EngineEvent channel field, indicating a non-midi parameter event. 169 */ 170 static const uint8_t kEngineEventNonMidiChannel = 0x30; 171 172 // ----------------------------------------------------------------------- 173 174 /*! 175 * Engine control event. 176 */ 177 struct CARLA_API EngineControlEvent { 178 EngineControlEventType type; //!< Control-Event type. 179 uint16_t param; //!< Parameter Id, midi bank or midi program. 180 int8_t midiValue; //!< Raw midi value, >= 0 if applicable, -1 otherwise. 181 float normalizedValue; //!< Parameter value, normalized to 0.0f<->1.0f. 182 bool handled; //!< Indicates that event was handled/received at least once. 183 184 /*! 185 * Convert this control event into MIDI data. 186 * Returns size. 187 */ 188 uint8_t convertToMidiData(uint8_t channel, uint8_t data[3]) const noexcept; 189 }; 190 191 /*! 192 * Engine MIDI event. 193 */ 194 struct CARLA_API EngineMidiEvent { 195 static const uint8_t kDataSize = 4; //!< Size of internal data 196 197 uint8_t port; //!< Port offset (usually 0) 198 uint8_t size; //!< Number of bytes used 199 200 /*! 201 * MIDI data, without channel bit. 202 * If size > kDataSize, dataExt is used (otherwise NULL). 203 */ 204 uint8_t data[kDataSize]; 205 const uint8_t* dataExt; 206 }; 207 208 /*! 209 * Engine event. 210 */ 211 struct CARLA_API EngineEvent { 212 EngineEventType type; //!< Event Type; either Control or MIDI 213 uint32_t time; //!< Time offset in frames 214 uint8_t channel; //!< Channel, used for MIDI-related events 215 216 /*! 217 * Event specific data. 218 */ 219 union { 220 EngineControlEvent ctrl; 221 EngineMidiEvent midi; 222 }; 223 224 /*! 225 * Fill this event from MIDI data. 226 */ 227 void fillFromMidiData(uint8_t size, const uint8_t* data, uint8_t midiPortOffset) noexcept; 228 }; 229 230 // ----------------------------------------------------------------------- 231 232 /*! 233 * Engine options. 234 */ 235 struct CARLA_API EngineOptions { 236 EngineProcessMode processMode; 237 EngineTransportMode transportMode; 238 const char* transportExtra; 239 240 bool forceStereo; 241 bool resetXruns; 242 bool preferPluginBridges; 243 bool preferUiBridges; 244 bool uisAlwaysOnTop; 245 bool pluginsAreStandalone; 246 uint bgColor; 247 uint fgColor; 248 float uiScale; 249 250 uint maxParameters; 251 uint uiBridgesTimeout; 252 uint audioBufferSize; 253 uint audioSampleRate; 254 bool audioTripleBuffer; 255 const char* audioDriver; 256 const char* audioDevice; 257 258 #ifndef BUILD_BRIDGE 259 bool oscEnabled; 260 int oscPortTCP; 261 int oscPortUDP; 262 #endif 263 264 const char* pathAudio; 265 const char* pathMIDI; 266 267 const char* pathLADSPA; 268 const char* pathDSSI; 269 const char* pathLV2; 270 const char* pathVST2; 271 const char* pathVST3; 272 const char* pathSF2; 273 const char* pathSFZ; 274 275 const char* binaryDir; 276 const char* resourceDir; 277 const char* clientNamePrefix; 278 279 bool preventBadBehaviour; 280 uintptr_t frontendWinId; 281 282 #ifndef CARLA_OS_WIN 283 struct Wine { 284 const char* executable; 285 286 bool autoPrefix; 287 const char* fallbackPrefix; 288 289 bool rtPrio; 290 int baseRtPrio; 291 int serverRtPrio; 292 293 Wine() noexcept; 294 ~Wine() noexcept; 295 CARLA_DECLARE_NON_COPY_STRUCT(Wine) 296 } wine; 297 #endif 298 299 #ifndef DOXYGEN 300 EngineOptions() noexcept; 301 ~EngineOptions() noexcept; 302 CARLA_DECLARE_NON_COPY_STRUCT(EngineOptions) 303 #endif 304 }; 305 306 /*! 307 * Engine BBT Time information. 308 */ 309 struct CARLA_API EngineTimeInfoBBT { 310 bool valid; 311 312 int32_t bar; //!< current bar 313 int32_t beat; //!< current beat-within-bar 314 double tick; //!< current tick-within-beat 315 double barStartTick; 316 317 float beatsPerBar; //!< time signature "numerator" 318 float beatType; //!< time signature "denominator" 319 320 double ticksPerBeat; 321 double beatsPerMinute; 322 323 /*! 324 * Clear. 325 */ 326 void clear() noexcept; 327 328 #ifndef DOXYGEN 329 EngineTimeInfoBBT() noexcept; 330 EngineTimeInfoBBT(const EngineTimeInfoBBT&) noexcept; 331 #endif 332 }; 333 334 /*! 335 * Engine Time information. 336 */ 337 struct CARLA_API EngineTimeInfo { 338 bool playing; 339 uint64_t frame; 340 uint64_t usecs; 341 EngineTimeInfoBBT bbt; 342 343 /*! 344 * Clear. 345 */ 346 void clear() noexcept; 347 348 #ifndef DOXYGEN 349 EngineTimeInfo() noexcept; 350 EngineTimeInfo(const EngineTimeInfo&) noexcept; 351 EngineTimeInfo& operator=(const EngineTimeInfo&) noexcept; 352 353 // fast comparison, doesn't check all values 354 bool compareIgnoringRollingFrames(const EngineTimeInfo& timeInfo, uint32_t maxFrames) const noexcept; 355 356 // quick operator, doesn't check all values 357 bool operator==(const EngineTimeInfo& timeInfo) const noexcept; 358 bool operator!=(const EngineTimeInfo& timeInfo) const noexcept; 359 #endif 360 }; 361 362 // ----------------------------------------------------------------------- 363 364 /*! 365 * Carla Engine port (Abstract). 366 * This is the base class for all Carla Engine ports. 367 */ 368 class CARLA_API CarlaEnginePort 369 { 370 protected: 371 /*! 372 * The constructor, protected. 373 * All constructor parameters are constant and will never change in the lifetime of the port. 374 */ 375 CarlaEnginePort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept; 376 377 public: 378 /*! 379 * The destructor. 380 */ 381 virtual ~CarlaEnginePort() noexcept; 382 383 /*! 384 * Get the type of the port, as provided by the respective subclasses. 385 */ 386 virtual EnginePortType getType() const noexcept = 0; 387 388 /*! 389 * Initialize the port's internal buffer. 390 */ 391 virtual void initBuffer() noexcept = 0; 392 393 /*! 394 * Check if this port is an input. 395 */ isInput() const396 inline bool isInput() const noexcept 397 { 398 return kIsInput; 399 } 400 401 /*! 402 * Get the index offset as passed in the constructor. 403 */ getIndexOffset() const404 inline uint32_t getIndexOffset() const noexcept 405 { 406 return kIndexOffset; 407 } 408 409 /*! 410 * Get this ports' engine client. 411 */ getEngineClient() const412 inline const CarlaEngineClient& getEngineClient() const noexcept 413 { 414 return kClient; 415 } 416 417 /*! 418 * Set a meta-data property on this port. 419 */ 420 virtual void setMetaData(const char* key, const char* value, const char* type); 421 422 #ifndef DOXYGEN 423 protected: 424 const CarlaEngineClient& kClient; 425 const bool kIsInput; 426 const uint32_t kIndexOffset; 427 428 CARLA_DECLARE_NON_COPY_CLASS(CarlaEnginePort) 429 #endif 430 }; 431 432 /*! 433 * Carla Engine Audio port. 434 */ 435 class CARLA_API CarlaEngineAudioPort : public CarlaEnginePort 436 { 437 public: 438 /*! 439 * The constructor. 440 * All constructor parameters are constant and will never change in the lifetime of the port. 441 */ 442 CarlaEngineAudioPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept; 443 444 /*! 445 * The destructor. 446 */ 447 ~CarlaEngineAudioPort() noexcept override; 448 449 /*! 450 * Get the type of the port, in this case kEnginePortTypeAudio. 451 */ getType() const452 inline EnginePortType getType() const noexcept final 453 { 454 return kEnginePortTypeAudio; 455 } 456 457 /*! 458 * Initialize the port's internal buffer. 459 */ 460 void initBuffer() noexcept override; 461 462 /*! 463 * Direct access to the port's audio buffer. 464 * May be null. 465 */ getBuffer() const466 inline float* getBuffer() const noexcept 467 { 468 return fBuffer; 469 } 470 471 #ifndef DOXYGEN 472 protected: 473 float* fBuffer; 474 475 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineAudioPort) 476 #endif 477 }; 478 479 /*! 480 * Carla Engine CV port. 481 */ 482 class CARLA_API CarlaEngineCVPort : public CarlaEnginePort 483 { 484 public: 485 /*! 486 * The constructor. 487 * All constructor parameters are constant and will never change in the lifetime of the port. 488 */ 489 CarlaEngineCVPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept; 490 491 /*! 492 * The destructor. 493 */ 494 ~CarlaEngineCVPort() noexcept override; 495 496 /*! 497 * Get the type of the port, in this case kEnginePortTypeCV. 498 */ getType() const499 inline EnginePortType getType() const noexcept final 500 { 501 return kEnginePortTypeCV; 502 } 503 504 /*! 505 * Initialize the port's internal buffer. 506 */ 507 void initBuffer() noexcept override; 508 509 /*! 510 * Direct access to the port's CV buffer. 511 * May be null. 512 */ getBuffer() const513 inline float* getBuffer() const noexcept 514 { 515 return fBuffer; 516 } 517 518 /*! 519 * Get min/max range for this CV port. 520 */ getRange(float & min,float & max) const521 inline void getRange(float& min, float& max) const noexcept 522 { 523 min = fMinimum; 524 max = fMaximum; 525 } 526 527 /*! 528 * Set min/max range for this CV port. 529 */ 530 void setRange(float min, float max) noexcept; 531 532 #ifndef DOXYGEN 533 protected: 534 float* fBuffer; 535 float fMinimum, fMaximum; 536 537 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineCVPort) 538 #endif 539 }; 540 541 /*! 542 * Carla Engine Event port. 543 */ 544 class CARLA_API CarlaEngineEventPort : public CarlaEnginePort 545 { 546 public: 547 /*! 548 * The constructor. 549 * All constructor parameters are constant and will never change in the lifetime of the port. 550 */ 551 CarlaEngineEventPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept; 552 553 /*! 554 * The destructor. 555 */ 556 ~CarlaEngineEventPort() noexcept override; 557 558 /*! 559 * Get the type of the port, in this case kEnginePortTypeEvent. 560 */ getType() const561 inline EnginePortType getType() const noexcept final 562 { 563 return kEnginePortTypeEvent; 564 } 565 566 /*! 567 * Initialize the port's internal buffer for @a engine. 568 */ 569 void initBuffer() noexcept override; 570 571 /*! 572 * Get the number of events present in the buffer. 573 * @note You must only call this for input ports. 574 */ 575 virtual uint32_t getEventCount() const noexcept; 576 577 /*! 578 * Get the event at @a index. 579 * @note You must only call this for input ports. 580 */ 581 virtual EngineEvent& getEvent(uint32_t index) const noexcept; 582 583 /*! 584 * Get the event at @a index, faster unchecked version. 585 */ 586 virtual EngineEvent& getEventUnchecked(uint32_t index) const noexcept; 587 588 /*! 589 * Write a control event into the buffer. 590 * @note You must only call this for output ports. 591 */ 592 bool writeControlEvent(uint32_t time, uint8_t channel, const EngineControlEvent& ctrl) noexcept; 593 594 /*! 595 * Write a control event into the buffer. 596 * Arguments are the same as in the EngineControlEvent struct. 597 * @note You must only call this for output ports. 598 */ 599 virtual bool writeControlEvent(uint32_t time, uint8_t channel, EngineControlEventType type, 600 uint16_t param, int8_t midiValue, float normalizedValue) noexcept; 601 602 /*! 603 * Write a MIDI event into the buffer. 604 * @note You must only call this for output ports. 605 */ 606 bool writeMidiEvent(uint32_t time, uint8_t size, const uint8_t* data) noexcept; 607 608 /*! 609 * Write a MIDI event into the buffer. 610 * @note You must only call this for output ports. 611 */ 612 bool writeMidiEvent(uint32_t time, uint8_t channel, const EngineMidiEvent& midi) noexcept; 613 614 /*! 615 * Write a MIDI event into the buffer. 616 * Arguments are the same as in the EngineMidiEvent struct. 617 * @note You must only call this for output ports. 618 */ 619 virtual bool writeMidiEvent(uint32_t time, uint8_t channel, uint8_t size, const uint8_t* data) noexcept; 620 621 #ifndef DOXYGEN 622 protected: 623 const EngineProcessMode kProcessMode; 624 EngineEvent* fBuffer; 625 friend class CarlaPluginInstance; 626 friend class CarlaEngineCVSourcePorts; 627 628 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineEventPort) 629 #endif 630 }; 631 632 // ----------------------------------------------------------------------- 633 634 /*! 635 * Carla Engine Meta CV Port. 636 * FIXME needs a better name... 637 */ 638 class CARLA_API CarlaEngineCVSourcePorts 639 { 640 public: 641 /*! 642 * The destructor. 643 */ 644 virtual ~CarlaEngineCVSourcePorts(); 645 646 /*! 647 * Add a CV port as a source of events. 648 */ 649 virtual bool addCVSource(CarlaEngineCVPort* port, uint32_t portIndexOffset, bool reconfigureNow); 650 651 /*! 652 * Remove a CV port as a source of events. 653 */ 654 virtual bool removeCVSource(uint32_t portIndexOffset); 655 656 /*! 657 * Get events and add them to an event port. 658 * FIXME needs a better name... 659 */ 660 virtual void initPortBuffers(const float* const* buffers, uint32_t frames, 661 bool sampleAccurate, CarlaEngineEventPort* eventPort); 662 663 /*! 664 * Set value range for a CV port. 665 */ 666 bool setCVSourceRange(uint32_t portIndexOffset, float minimum, float maximum); 667 668 /*! 669 * Destroy all ports. 670 */ 671 void cleanup(); 672 673 #ifndef DOXYGEN 674 protected: 675 /** @internal */ 676 struct ProtectedData; 677 ProtectedData* const pData; 678 679 /*! 680 * The constructor, protected. 681 */ 682 CarlaEngineCVSourcePorts(); 683 684 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineCVSourcePorts) 685 #endif 686 }; 687 688 // ----------------------------------------------------------------------- 689 690 /*! 691 * Carla Engine Client. 692 * Each plugin requires one client from the engine (created via CarlaEngine::addClient()). 693 * @note This is a virtual class, some engine types provide custom functionality. 694 */ 695 class CARLA_API CarlaEngineClient 696 { 697 public: 698 /*! 699 * The destructor. 700 */ 701 virtual ~CarlaEngineClient() noexcept; 702 703 /*! 704 * Activate this client. 705 * Client must be deactivated before calling this function. 706 */ 707 virtual void activate() noexcept; 708 709 /*! 710 * Deactivate this client. 711 * Client must be activated before calling this function. 712 */ 713 virtual void deactivate(bool willClose) noexcept; 714 715 /*! 716 * Check if the client is activated. 717 */ 718 virtual bool isActive() const noexcept; 719 720 /*! 721 * Check if the client is ok. 722 * Plugins will refuse to instantiate if this returns false. 723 * @note This is always true in rack and patchbay processing modes. 724 */ 725 virtual bool isOk() const noexcept; 726 727 /*! 728 * Get the current latency, in samples. 729 */ 730 virtual uint32_t getLatency() const noexcept; 731 732 /*! 733 * Change the client's latency. 734 */ 735 virtual void setLatency(uint32_t samples) noexcept; 736 737 /*! 738 * Add a new port of type @a portType. 739 * @note This function does nothing in rack processing mode since ports are static there. 740 */ 741 virtual CarlaEnginePort* addPort(EnginePortType portType, const char* name, bool isInput, uint32_t indexOffset); 742 743 /*! 744 * Remove a previously added port via addPort(). 745 */ 746 virtual bool removePort(EnginePortType portType, const char* name, bool isInput); 747 748 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 749 /*! 750 * Create an instance of CV source ports. 751 * Must be called only once per client. 752 */ 753 virtual CarlaEngineCVSourcePorts* createCVSourcePorts(); 754 #endif 755 756 /*! 757 * Get this client's engine. 758 */ 759 const CarlaEngine& getEngine() const noexcept; 760 761 /*! 762 * Get the engine's process mode. 763 */ 764 EngineProcessMode getProcessMode() const noexcept; 765 766 /*! 767 * Get port count for a type and mode. 768 */ 769 uint getPortCount(EnginePortType portType, bool isInput) const noexcept; 770 771 /*! 772 * Get an audio port name. 773 */ 774 const char* getAudioPortName(bool isInput, uint index) const noexcept; 775 776 /*! 777 * Get a CV port name. 778 */ 779 const char* getCVPortName(bool isInput, uint index) const noexcept; 780 781 /*! 782 * Get an event port name. 783 */ 784 const char* getEventPortName(bool isInput, uint index) const noexcept; 785 786 #ifndef DOXYGEN 787 protected: 788 /** @internal */ 789 struct ProtectedData; 790 ProtectedData* const pData; 791 792 /*! 793 * The constructor, protected. 794 */ 795 CarlaEngineClient(ProtectedData* pData); 796 797 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineClient) 798 #endif 799 }; 800 801 // ----------------------------------------------------------------------- 802 803 /*! 804 * Carla Engine. 805 * @note This is a virtual class for all available engine types available in Carla. 806 */ 807 class CARLA_API CarlaEngine 808 { 809 protected: 810 /*! 811 * The constructor, protected. 812 * @note This only initializes engine data, it doesn't actually start the engine. 813 */ 814 CarlaEngine(); 815 816 public: 817 /*! 818 * The destructor. 819 * The engine must have been closed before this happens. 820 */ 821 virtual ~CarlaEngine(); 822 823 // ------------------------------------------------------------------- 824 // Static calls 825 826 /*! 827 * Get the number of available engine drivers. 828 */ 829 static uint getDriverCount(); 830 831 /*! 832 * Get the name of the engine driver at @a index. 833 */ 834 static const char* getDriverName(uint index); 835 836 /*! 837 * Get the device names of the driver at @a index. 838 */ 839 static const char* const* getDriverDeviceNames(uint index); 840 841 /*! 842 * Get device information about the driver at @a index and name @a driverName. 843 */ 844 static const EngineDriverDeviceInfo* getDriverDeviceInfo(uint index, const char* driverName); 845 846 /*! 847 * Show a device custom control panel. 848 * @see ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL 849 */ 850 static bool showDriverDeviceControlPanel(uint index, const char* deviceName); 851 852 /*! 853 * Create a new engine, using driver @a driverName. 854 * Returned value must be deleted when no longer needed. 855 * @note This only initializes engine data, it doesn't actually start the engine. 856 */ 857 static CarlaEngine* newDriverByName(const char* driverName); 858 859 // ------------------------------------------------------------------- 860 // Constant values 861 862 /*! 863 * Maximum client name size. 864 */ 865 virtual uint getMaxClientNameSize() const noexcept; 866 867 /*! 868 * Maximum port name size. 869 */ 870 virtual uint getMaxPortNameSize() const noexcept; 871 872 /*! 873 * Current number of plugins loaded. 874 */ 875 uint getCurrentPluginCount() const noexcept; 876 877 /*! 878 * Maximum number of loadable plugins allowed. 879 * This function returns 0 if engine is not started. 880 */ 881 uint getMaxPluginNumber() const noexcept; 882 883 // ------------------------------------------------------------------- 884 // Virtual, per-engine type calls 885 886 /*! 887 * Initialize/start the engine, using @a clientName. 888 * When the engine is initialized, you need to call idle() at regular intervals. 889 */ 890 virtual bool init(const char* clientName) = 0; 891 892 /*! 893 * Close engine. 894 * This function always closes the engine even if it returns false. 895 * In other words, even when something goes wrong when closing the engine it still be closed nonetheless. 896 */ 897 virtual bool close(); 898 899 /*! 900 * Idle engine. 901 */ 902 virtual void idle() noexcept; 903 904 /*! 905 * Check if engine is running. 906 */ 907 virtual bool isRunning() const noexcept = 0; 908 909 /*! 910 * Check if engine is running offline (aka freewheel mode). 911 */ 912 virtual bool isOffline() const noexcept = 0; 913 914 /*! 915 * Check if engine runs on a constant buffer size value. 916 * Default implementation returns true. 917 */ 918 virtual bool usesConstantBufferSize() const noexcept; 919 920 /*! 921 * Get engine type. 922 */ 923 virtual EngineType getType() const noexcept = 0; 924 925 /*! 926 * Get the currently used driver name. 927 */ 928 virtual const char* getCurrentDriverName() const noexcept = 0; 929 930 /*! 931 * Add new engine client. 932 * @note This function must only be called within a plugin class. 933 */ 934 virtual CarlaEngineClient* addClient(CarlaPluginPtr plugin); 935 936 /*! 937 * Get the current CPU load estimated by the engine. 938 */ 939 virtual float getDSPLoad() const noexcept; 940 941 /*! 942 * Get the total number of xruns so far. 943 */ 944 virtual uint32_t getTotalXruns() const noexcept; 945 946 /*! 947 * Clear the xrun count. 948 */ 949 virtual void clearXruns() const noexcept; 950 951 /*! 952 * Dynamically change buffer size and/or sample rate while engine is running. 953 * @see ENGINE_DRIVER_DEVICE_VARIABLE_BUFFER_SIZE 954 * @see ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE 955 */ 956 virtual bool setBufferSizeAndSampleRate(uint bufferSize, double sampleRate); 957 958 /*! 959 * Show the custom control panel for the current engine device. 960 * @see ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL 961 */ 962 virtual bool showDeviceControlPanel() const noexcept; 963 964 // ------------------------------------------------------------------- 965 // Plugin management 966 967 /*! 968 * Add new plugin. 969 * @see ENGINE_CALLBACK_PLUGIN_ADDED 970 */ 971 bool addPlugin(BinaryType btype, PluginType ptype, 972 const char* filename, const char* name, const char* label, int64_t uniqueId, 973 const void* extra, uint options = PLUGIN_OPTIONS_NULL); 974 975 /*! 976 * Add new plugin, using native binary type. 977 * @see ENGINE_CALLBACK_PLUGIN_ADDED 978 */ 979 bool addPlugin(PluginType ptype, 980 const char* filename, const char* name, const char* label, int64_t uniqueId, 981 const void* extra); 982 983 /*! 984 * Remove plugin with id @a id. 985 * @see ENGINE_CALLBACK_PLUGIN_REMOVED 986 */ 987 virtual bool removePlugin(uint id); 988 989 /*! 990 * Remove all plugins. 991 */ 992 bool removeAllPlugins(); 993 994 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 995 /*! 996 * Rename plugin with id @a id to @a newName. 997 * Returns the new name, or null if the operation failed. 998 * Returned variable must be deleted if non-null. 999 * @see ENGINE_CALLBACK_PLUGIN_RENAMED 1000 */ 1001 virtual bool renamePlugin(uint id, const char* newName); 1002 1003 /*! 1004 * Clone plugin with id @a id. 1005 */ 1006 bool clonePlugin(uint id); 1007 1008 /*! 1009 * Prepare replace of plugin with id @a id. 1010 * The next call to addPlugin() will use this id, replacing the selected plugin. 1011 * @note This function requires addPlugin() to be called afterwards, as soon as possible. 1012 */ 1013 bool replacePlugin(uint id) noexcept; 1014 1015 /*! 1016 * Switch plugins with id @a idA and @a idB. 1017 */ 1018 virtual bool switchPlugins(uint idA, uint idB) noexcept; 1019 #endif 1020 1021 /*! 1022 * Set a plugin's parameter in drag/touch mode. 1023 * Usually happens from a UI when the user is moving a parameter with a mouse or similar input. 1024 * 1025 * @param parameterId The parameter to update 1026 * @param touch The new state for the parameter 1027 */ 1028 virtual void touchPluginParameter(uint id, uint32_t parameterId, bool touch) noexcept; 1029 1030 /*! 1031 * Get plugin with id @a id. 1032 */ 1033 CarlaPluginPtr getPlugin(uint id) const noexcept; 1034 1035 /*! 1036 * Get plugin with id @a id, faster unchecked version. 1037 */ 1038 CarlaPluginPtr getPluginUnchecked(uint id) const noexcept; 1039 1040 /*! 1041 * Get a unique plugin name within the engine. 1042 * Returned variable must be deleted if non-null. 1043 */ 1044 const char* getUniquePluginName(const char* name) const; 1045 1046 // ------------------------------------------------------------------- 1047 // Project management 1048 1049 /*! 1050 * Load a file of any type. 1051 * This will try to load a generic file as a plugin, 1052 * either by direct handling (SF2 and SFZ) or by using an internal plugin (like Audio and MIDI). 1053 */ 1054 bool loadFile(const char* filename); 1055 1056 /*! 1057 * Load a project file. 1058 * @note Already loaded plugins are not removed; call removeAllPlugins() first if needed. 1059 */ 1060 bool loadProject(const char* filename, bool setAsCurrentProject); 1061 1062 /*! 1063 * Save current project to a file. 1064 */ 1065 bool saveProject(const char* filename, bool setAsCurrentProject); 1066 1067 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 1068 /*! 1069 * Get the currently set project folder. 1070 * @note Valid for both standalone and plugin versions. 1071 */ 1072 virtual const char* getCurrentProjectFolder() const noexcept; 1073 1074 /*! 1075 * Get the currently set project filename. 1076 * @note Valid only for both standalone version. 1077 */ 1078 const char* getCurrentProjectFilename() const noexcept; 1079 1080 /*! 1081 * Clear the currently set project filename. 1082 */ 1083 void clearCurrentProjectFilename() noexcept; 1084 #endif 1085 1086 // ------------------------------------------------------------------- 1087 // Information (base) 1088 1089 /*! 1090 * Get the current buffer size. 1091 */ 1092 uint32_t getBufferSize() const noexcept; 1093 1094 /*! 1095 * Get the current sample rate. 1096 */ 1097 double getSampleRate() const noexcept; 1098 1099 /*! 1100 * Get the current engine name. 1101 */ 1102 const char* getName() const noexcept; 1103 1104 /*! 1105 * Get the current engine process mode. 1106 */ 1107 EngineProcessMode getProccessMode() const noexcept; 1108 1109 /*! 1110 * Get the current engine options (read-only). 1111 */ 1112 const EngineOptions& getOptions() const noexcept; 1113 1114 /*! 1115 * Get the current Time information (read-only). 1116 */ 1117 virtual EngineTimeInfo getTimeInfo() const noexcept; 1118 1119 // ------------------------------------------------------------------- 1120 // Information (peaks) 1121 1122 /*! 1123 * Get a plugin's peak values. 1124 * @note not thread-safe if pluginId == MAIN_CARLA_PLUGIN_ID 1125 */ 1126 const float* getPeaks(uint pluginId) const noexcept; 1127 1128 /*! 1129 * Get a plugin's input peak value. 1130 */ 1131 float getInputPeak(uint pluginId, bool isLeft) const noexcept; 1132 1133 /*! 1134 * Get a plugin's output peak value. 1135 */ 1136 float getOutputPeak(uint pluginId, bool isLeft) const noexcept; 1137 1138 // ------------------------------------------------------------------- 1139 // Callback 1140 1141 /*! 1142 * Call the main engine callback, if set. 1143 * May be called by plugins. 1144 */ 1145 virtual void callback(bool sendHost, bool sendOSC, 1146 EngineCallbackOpcode action, uint pluginId, 1147 int value1, int value2, int value3, float valuef, const char* valueStr) noexcept; 1148 1149 /*! 1150 * Set the main engine callback to @a func. 1151 */ 1152 void setCallback(EngineCallbackFunc func, void* ptr) noexcept; 1153 1154 // ------------------------------------------------------------------- 1155 // Callback 1156 1157 /*! 1158 * Call the file callback, if set. 1159 * May be called by plugins. 1160 */ 1161 virtual const char* runFileCallback(FileCallbackOpcode action, 1162 bool isDir, const char* title, const char* filter) noexcept; 1163 1164 /*! 1165 * Set the file callback to @a func. 1166 */ 1167 void setFileCallback(FileCallbackFunc func, void* ptr) noexcept; 1168 1169 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 1170 // ------------------------------------------------------------------- 1171 // Patchbay 1172 1173 /*! 1174 * Connect two patchbay ports. 1175 */ 1176 virtual bool patchbayConnect(bool external, 1177 uint groupA, uint portA, 1178 uint groupB, uint portB); 1179 1180 /*! 1181 * Remove a patchbay connection. 1182 */ 1183 virtual bool patchbayDisconnect(bool external, uint connectionId); 1184 1185 /*! 1186 * Set the position of a group. 1187 */ 1188 virtual bool patchbaySetGroupPos(bool sendHost, bool sendOSC, bool external, 1189 uint groupId, int x1, int y1, int x2, int y2); 1190 1191 /*! 1192 * Force the engine to resend all patchbay clients, ports and connections again. 1193 */ 1194 virtual bool patchbayRefresh(bool sendHost, bool sendOSC, bool external); 1195 #endif 1196 1197 // ------------------------------------------------------------------- 1198 // Transport 1199 1200 /*! 1201 * Start playback of the engine transport. 1202 */ 1203 virtual void transportPlay() noexcept; 1204 1205 /*! 1206 * Pause the engine transport. 1207 */ 1208 virtual void transportPause() noexcept; 1209 1210 /*! 1211 * Set the engine transport bpm to @a bpm. 1212 */ 1213 virtual void transportBPM(double bpm) noexcept; 1214 1215 /*! 1216 * Relocate the engine transport to @a frames. 1217 */ 1218 virtual void transportRelocate(uint64_t frame) noexcept; 1219 1220 // ------------------------------------------------------------------- 1221 // Error handling 1222 1223 /*! 1224 * Get last error. 1225 */ 1226 const char* getLastError() const noexcept; 1227 1228 /*! 1229 * Set last error. 1230 */ 1231 void setLastError(const char* error) const noexcept; 1232 1233 // ------------------------------------------------------------------- 1234 // Misc 1235 1236 /*! 1237 * Check if the engine is about to close. 1238 */ 1239 bool isAboutToClose() const noexcept; 1240 1241 /*! 1242 * Tell the engine it's about to close. 1243 * This is used to prevent the engine thread(s) from reactivating. 1244 * Returns true if there's no pending engine events. 1245 */ 1246 bool setAboutToClose() noexcept; 1247 1248 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 1249 /*! 1250 * TODO. 1251 */ 1252 bool isLoadingProject() const noexcept; 1253 #endif 1254 1255 /*! 1256 * Tell the engine to stop the current cancelable action. 1257 * @see ENGINE_CALLBACK_CANCELABLE_ACTION 1258 */ 1259 void setActionCanceled(bool canceled) noexcept; 1260 1261 /*! 1262 * Check wherever the last cancelable action was indeed canceled or not. 1263 */ 1264 bool wasActionCanceled() const noexcept; 1265 1266 // ------------------------------------------------------------------- 1267 // Options 1268 1269 /*! 1270 * Set the engine option @a option to @a value or @a valueStr. 1271 */ 1272 virtual void setOption(EngineOption option, int value, const char* valueStr) noexcept; 1273 1274 // ------------------------------------------------------------------- 1275 // OSC Stuff 1276 1277 #ifndef BUILD_BRIDGE 1278 /*! 1279 * Check if OSC controller is registered. 1280 */ 1281 bool isOscControlRegistered() const noexcept; 1282 1283 /*! 1284 * Get OSC TCP server path. 1285 */ 1286 const char* getOscServerPathTCP() const noexcept; 1287 1288 /*! 1289 * Get OSC UDP server path. 1290 */ 1291 const char* getOscServerPathUDP() const noexcept; 1292 #endif 1293 1294 // ------------------------------------------------------------------- 1295 1296 protected: 1297 /*! 1298 * Internal data, for CarlaEngine subclasses and friends. 1299 */ 1300 struct ProtectedData; 1301 ProtectedData* const pData; 1302 1303 /*! 1304 * Some internal classes read directly from pData or call protected functions. 1305 */ 1306 friend class CarlaEngineEventPort; 1307 friend class CarlaEngineOsc; 1308 friend class CarlaEngineThread; 1309 friend class CarlaPluginInstance; 1310 friend class EngineInternalGraph; 1311 friend class PendingRtEventsRunner; 1312 friend class ScopedActionLock; 1313 friend class ScopedEngineEnvironmentLocker; 1314 friend class ScopedThreadStopper; 1315 friend class PatchbayGraph; 1316 friend struct ExternalGraph; 1317 friend struct RackGraph; 1318 1319 // ------------------------------------------------------------------- 1320 // Internal stuff 1321 1322 /*! 1323 * Report to all plugins about buffer size change. 1324 */ 1325 void bufferSizeChanged(uint32_t newBufferSize); 1326 1327 /*! 1328 * Report to all plugins about sample rate change. 1329 * This is not supported on all plugin types, in which case they will have to be re-initiated. 1330 */ 1331 void sampleRateChanged(double newSampleRate); 1332 1333 /*! 1334 * Report to all plugins about offline mode change. 1335 */ 1336 void offlineModeChanged(bool isOffline); 1337 1338 /*! 1339 * Set a plugin (stereo) peak values. 1340 * @note RT call 1341 */ 1342 void setPluginPeaksRT(uint pluginId, float const inPeaks[2], float const outPeaks[2]) noexcept; 1343 1344 public: 1345 /*! 1346 * Common save project function for main engine and plugin. 1347 */ 1348 void saveProjectInternal(water::MemoryOutputStream& outStrm) const; 1349 1350 /*! 1351 * Common load project function for main engine and plugin. 1352 */ 1353 bool loadProjectInternal(water::XmlDocument& xmlDoc, bool alwaysLoadConnections); 1354 1355 protected: 1356 // ------------------------------------------------------------------- 1357 // Helper functions 1358 1359 /*! 1360 * Return internal data, needed for EventPorts when used in Rack, Patchbay and Bridge modes. 1361 * @note RT call 1362 */ 1363 EngineEvent* getInternalEventBuffer(bool isInput) const noexcept; 1364 1365 #ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH 1366 // ------------------------------------------------------------------- 1367 // Patchbay stuff 1368 1369 /*! 1370 * Virtual functions for handling patchbay state. 1371 * Do not free returned data. 1372 */ 1373 struct PatchbayPosition { const char* name; int x1, y1, x2, y2, pluginId; bool dealloc; }; 1374 virtual const char* const* getPatchbayConnections(bool external) const; 1375 virtual const PatchbayPosition* getPatchbayPositions(bool external, uint& count) const; 1376 virtual void restorePatchbayConnection(bool external, const char* sourcePort, const char* targetPort); 1377 // returns true if plugin name mapping found, ppos.name updated to its converted name 1378 virtual bool restorePatchbayGroupPosition(bool external, PatchbayPosition& ppos); 1379 1380 /*! 1381 * Virtual functions for handling external graph ports. 1382 */ 1383 virtual bool connectExternalGraphPort(uint, uint, const char*); 1384 virtual bool disconnectExternalGraphPort(uint, uint, const char*); 1385 #endif 1386 1387 // ------------------------------------------------------------------- 1388 1389 CARLA_DECLARE_NON_COPY_CLASS(CarlaEngine) 1390 }; 1391 1392 /**@}*/ 1393 1394 // ----------------------------------------------------------------------- 1395 1396 CARLA_BACKEND_END_NAMESPACE 1397 1398 #endif // CARLA_ENGINE_HPP_INCLUDED 1399