source/backend/CarlaEngine.hpp

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