CarlaEngine.hpp

Go to the documentation of this file.

/*
 * Carla Plugin Host
 * Copyright (C) 2011-2022 Filipe Coelho <falktx@falktx.com>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * For a full copy of the GNU General Public License see the doc/GPL.txt file.
 */
 
#ifndef CARLA_ENGINE_HPP_INCLUDED
#define CARLA_ENGINE_HPP_INCLUDED
 
#include "CarlaBackend.h"
#include "CarlaPluginPtr.hpp"
 
namespace water {
class MemoryOutputStream;
class XmlDocument;
}
 
CARLA_BACKEND_START_NAMESPACE
 
// -----------------------------------------------------------------------


enum EngineType {
    kEngineTypeNull = 0,

    kEngineTypeJack = 1,

    kEngineTypeJuce = 2,

    kEngineTypeRtAudio = 3,

    kEngineTypeSDL = 4,

    kEngineTypePlugin = 5,

    kEngineTypeBridge = 6,

    kEngineTypeDummy = 7
};

enum EnginePortType {
    kEnginePortTypeNull = 0,

    kEnginePortTypeAudio = 1,

    kEnginePortTypeCV = 2,

    kEnginePortTypeEvent = 3
};

enum EngineEventType {
    kEngineEventTypeNull = 0,

    kEngineEventTypeControl = 1,

    kEngineEventTypeMidi = 2
};

enum EngineControlEventType {
    kEngineControlEventTypeNull = 0,

    kEngineControlEventTypeParameter = 1,

    kEngineControlEventTypeMidiBank = 2,

    kEngineControlEventTypeMidiProgram = 3,

    kEngineControlEventTypeAllSoundOff = 4,

    kEngineControlEventTypeAllNotesOff = 5
};

static const uint8_t kEngineEventNonMidiChannel = 0x30;
 
// -----------------------------------------------------------------------

struct CARLA_API EngineControlEvent {
    EngineControlEventType type; 
    uint16_t param;              
    int8_t   midiValue;          
    float    normalizedValue;    
    bool     handled;            

    uint8_t convertToMidiData(uint8_t channel, uint8_t data[3]) const noexcept;
};

struct CARLA_API EngineMidiEvent {
    static const uint8_t kDataSize = 4; 
 
    uint8_t port; 
    uint8_t size; 

    uint8_t        data[kDataSize];
    const uint8_t* dataExt;
};

struct CARLA_API EngineEvent {
    EngineEventType type; 
    uint32_t time;        
    uint8_t  channel;     

    union {
        EngineControlEvent ctrl;
        EngineMidiEvent midi;
    };

    void fillFromMidiData(uint8_t size, const uint8_t* data, uint8_t midiPortOffset) noexcept;
};
 
// -----------------------------------------------------------------------

struct CARLA_API EngineOptions {
    EngineProcessMode processMode;
    EngineTransportMode transportMode;
    const char* transportExtra;
 
    bool forceStereo;
    bool resetXruns;
    bool preferPluginBridges;
    bool preferUiBridges;
    bool uisAlwaysOnTop;
    bool pluginsAreStandalone;
    uint bgColor;
    uint fgColor;
    float uiScale;
 
    uint maxParameters;
    uint uiBridgesTimeout;
    uint audioBufferSize;
    uint audioSampleRate;
    bool audioTripleBuffer;
    const char* audioDriver;
    const char* audioDevice;
 
#ifndef BUILD_BRIDGE
    bool oscEnabled;
    int oscPortTCP;
    int oscPortUDP;
#endif
 
    const char* pathAudio;
    const char* pathMIDI;
 
    const char* pathLADSPA;
    const char* pathDSSI;
    const char* pathLV2;
    const char* pathVST2;
    const char* pathVST3;
    const char* pathSF2;
    const char* pathSFZ;
    const char* pathJSFX;
 
    const char* binaryDir;
    const char* resourceDir;
    const char* clientNamePrefix;
 
    bool preventBadBehaviour;
    uintptr_t frontendWinId;
 
#ifndef CARLA_OS_WIN
    struct Wine {
        const char* executable;
 
        bool autoPrefix;
        const char* fallbackPrefix;
 
        bool rtPrio;
        int baseRtPrio;
        int serverRtPrio;
 
        Wine() noexcept;
        ~Wine() noexcept;
        CARLA_DECLARE_NON_COPYABLE(Wine)
    } wine;
#endif
 
#ifndef DOXYGEN
    EngineOptions() noexcept;
    ~EngineOptions() noexcept;
    CARLA_DECLARE_NON_COPYABLE(EngineOptions)
#endif
};

struct CARLA_API EngineTimeInfoBBT {
    bool valid;
 
    int32_t bar;  
    int32_t beat; 
    double  tick; 
    double  barStartTick;
 
    float beatsPerBar; 
    float beatType;    
 
    double ticksPerBeat;
    double beatsPerMinute;

    void clear() noexcept;
 
#ifndef DOXYGEN
    EngineTimeInfoBBT() noexcept;
    EngineTimeInfoBBT(const EngineTimeInfoBBT&) noexcept;
#endif
};

struct CARLA_API EngineTimeInfo {
    bool playing;
    uint64_t frame;
    uint64_t usecs;
    EngineTimeInfoBBT bbt;

    void clear() noexcept;
 
#ifndef DOXYGEN
    EngineTimeInfo() noexcept;
    EngineTimeInfo(const EngineTimeInfo&) noexcept;
    EngineTimeInfo& operator=(const EngineTimeInfo&) noexcept;
 
    // fast comparison, doesn't check all values
    bool compareIgnoringRollingFrames(const EngineTimeInfo& timeInfo, uint32_t maxFrames) const noexcept;
 
    // quick operator, doesn't check all values
    bool operator==(const EngineTimeInfo& timeInfo) const noexcept;
    bool operator!=(const EngineTimeInfo& timeInfo) const noexcept;
#endif
};
 
// -----------------------------------------------------------------------

class CARLA_API CarlaEnginePort
{
protected:
    CarlaEnginePort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept;
 
public:
    virtual ~CarlaEnginePort() noexcept;

    virtual EnginePortType getType() const noexcept = 0;

    virtual void initBuffer() noexcept = 0;

    inline bool isInput() const noexcept
    {
        return kIsInput;
    }

    inline uint32_t getIndexOffset() const noexcept
    {
        return kIndexOffset;
    }

    inline const CarlaEngineClient& getEngineClient() const noexcept
    {
        return kClient;
    }

    virtual void setMetaData(const char* key, const char* value, const char* type);
 
#ifndef DOXYGEN
protected:
    const CarlaEngineClient& kClient;
    const bool     kIsInput;
    const uint32_t kIndexOffset;
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEnginePort)
#endif
};

class CARLA_API CarlaEngineAudioPort : public CarlaEnginePort
{
public:
    CarlaEngineAudioPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept;

    ~CarlaEngineAudioPort() noexcept override;

    inline EnginePortType getType() const noexcept final
    {
        return kEnginePortTypeAudio;
    }

    void initBuffer() noexcept override;

    inline float* getBuffer() const noexcept
    {
        return fBuffer;
    }
 
#ifndef DOXYGEN
protected:
    float* fBuffer;
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngineAudioPort)
#endif
};

class CARLA_API CarlaEngineCVPort : public CarlaEnginePort
{
public:
    CarlaEngineCVPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept;

    ~CarlaEngineCVPort() noexcept override;

    inline EnginePortType getType() const noexcept final
    {
        return kEnginePortTypeCV;
    }

    void initBuffer() noexcept override;

    inline float* getBuffer() const noexcept
    {
        return fBuffer;
    }

    inline void getRange(float& min, float& max) const noexcept
    {
        min = fMinimum;
        max = fMaximum;
    }

    void setRange(float min, float max) noexcept;
 
#ifndef DOXYGEN
protected:
    float* fBuffer;
    float fMinimum, fMaximum;
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngineCVPort)
#endif
};

class CARLA_API CarlaEngineEventPort : public CarlaEnginePort
{
public:
    CarlaEngineEventPort(const CarlaEngineClient& client, bool isInputPort, uint32_t indexOffset) noexcept;

    ~CarlaEngineEventPort() noexcept override;

    inline EnginePortType getType() const noexcept final
    {
        return kEnginePortTypeEvent;
    }

    void initBuffer() noexcept override;

    virtual uint32_t getEventCount() const noexcept;

    virtual EngineEvent& getEvent(uint32_t index) const noexcept;

    virtual EngineEvent& getEventUnchecked(uint32_t index) const noexcept;

    bool writeControlEvent(uint32_t time, uint8_t channel, const EngineControlEvent& ctrl) noexcept;

    virtual bool writeControlEvent(uint32_t time, uint8_t channel, EngineControlEventType type,
                                   uint16_t param, int8_t midiValue, float normalizedValue) noexcept;

    bool writeMidiEvent(uint32_t time, uint8_t size, const uint8_t* data) noexcept;

    bool writeMidiEvent(uint32_t time, uint8_t channel, const EngineMidiEvent& midi) noexcept;

    virtual bool writeMidiEvent(uint32_t time, uint8_t channel, uint8_t size, const uint8_t* data) noexcept;
 
#ifndef DOXYGEN
protected:
    const EngineProcessMode kProcessMode;
    EngineEvent* fBuffer;
    friend class CarlaPluginInstance;
    friend class CarlaEngineCVSourcePorts;
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngineEventPort)
#endif
};
 
// -----------------------------------------------------------------------

class CARLA_API CarlaEngineCVSourcePorts
{
public:
    virtual ~CarlaEngineCVSourcePorts();

    virtual bool addCVSource(CarlaEngineCVPort* port, uint32_t portIndexOffset, bool reconfigureNow);

    virtual bool removeCVSource(uint32_t portIndexOffset);

    virtual void initPortBuffers(const float* const* buffers, uint32_t frames,
                                 bool sampleAccurate, CarlaEngineEventPort* eventPort);

    bool setCVSourceRange(uint32_t portIndexOffset, float minimum, float maximum);

    void cleanup();
 
#ifndef DOXYGEN
protected:
    struct ProtectedData;
    ProtectedData* const pData;

    CarlaEngineCVSourcePorts();
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngineCVSourcePorts)
#endif
};
 
// -----------------------------------------------------------------------

class CARLA_API CarlaEngineClient
{
public:
    virtual ~CarlaEngineClient() noexcept;

    virtual void activate() noexcept;

    virtual void deactivate(bool willClose) noexcept;

    virtual bool isActive() const noexcept;

    virtual bool isOk() const noexcept;

    virtual uint32_t getLatency() const noexcept;

    virtual void setLatency(uint32_t samples) noexcept;

    virtual CarlaEnginePort* addPort(EnginePortType portType, const char* name, bool isInput, uint32_t indexOffset);

    virtual bool removePort(EnginePortType portType, const char* name, bool isInput);
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    virtual CarlaEngineCVSourcePorts* createCVSourcePorts();
#endif

    const CarlaEngine& getEngine() const noexcept;

    EngineProcessMode getProcessMode() const noexcept;

    uint getPortCount(EnginePortType portType, bool isInput) const noexcept;

    const char* getAudioPortName(bool isInput, uint index) const noexcept;

    const char* getCVPortName(bool isInput, uint index) const noexcept;

    const char* getEventPortName(bool isInput, uint index) const noexcept;
 
#ifndef DOXYGEN
protected:
    struct ProtectedData;
    ProtectedData* const pData;

    CarlaEngineClient(ProtectedData* pData);
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngineClient)
#endif
};
 
// -----------------------------------------------------------------------

class CARLA_API CarlaEngine
{
protected:
    CarlaEngine();
 
public:
    virtual ~CarlaEngine();
 
    // -------------------------------------------------------------------
    // Static calls

    static uint getDriverCount();

    static const char* getDriverName(uint index);

    static const char* const* getDriverDeviceNames(uint index);

    static const EngineDriverDeviceInfo* getDriverDeviceInfo(uint index, const char* driverName);

    static bool showDriverDeviceControlPanel(uint index, const char* deviceName);

    static CarlaEngine* newDriverByName(const char* driverName);
 
    // -------------------------------------------------------------------
    // Constant values

    virtual uint getMaxClientNameSize() const noexcept;

    virtual uint getMaxPortNameSize() const noexcept;

    uint getCurrentPluginCount() const noexcept;

    uint getMaxPluginNumber() const noexcept;
 
    // -------------------------------------------------------------------
    // Virtual, per-engine type calls

    virtual bool init(const char* clientName) = 0;

    virtual bool close();

    virtual void idle() noexcept;

    virtual bool isRunning() const noexcept = 0;

    virtual bool isOffline() const noexcept = 0;

    virtual bool usesConstantBufferSize() const noexcept;

    virtual EngineType getType() const noexcept = 0;

    virtual const char* getCurrentDriverName() const noexcept = 0;

    virtual CarlaEngineClient* addClient(CarlaPluginPtr plugin);

    virtual float getDSPLoad() const noexcept;

    virtual uint32_t getTotalXruns() const noexcept;

    virtual void clearXruns() const noexcept;

    virtual bool setBufferSizeAndSampleRate(uint bufferSize, double sampleRate);

    virtual bool showDeviceControlPanel() const noexcept;
 
    // -------------------------------------------------------------------
    // Plugin management

    bool addPlugin(BinaryType btype, PluginType ptype,
                   const char* filename, const char* name, const char* label, int64_t uniqueId,
                   const void* extra, uint options = PLUGIN_OPTIONS_NULL);

    bool addPlugin(PluginType ptype,
                   const char* filename, const char* name, const char* label, int64_t uniqueId,
                   const void* extra);

    virtual bool removePlugin(uint id);

    bool removeAllPlugins();
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    virtual bool renamePlugin(uint id, const char* newName);

    bool clonePlugin(uint id);

    bool replacePlugin(uint id) noexcept;

    virtual bool switchPlugins(uint idA, uint idB) noexcept;
#endif

    virtual void touchPluginParameter(uint id, uint32_t parameterId, bool touch) noexcept;

    CarlaPluginPtr getPlugin(uint id) const noexcept;

    CarlaPluginPtr getPluginUnchecked(uint id) const noexcept;

    const char* getUniquePluginName(const char* name) const;
 
    // -------------------------------------------------------------------
    // Project management

    bool loadFile(const char* filename);

    bool loadProject(const char* filename, bool setAsCurrentProject);

    bool saveProject(const char* filename, bool setAsCurrentProject);
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    virtual const char* getCurrentProjectFolder() const noexcept;

    const char* getCurrentProjectFilename() const noexcept;

    void clearCurrentProjectFilename() noexcept;
#endif
 
    // -------------------------------------------------------------------
    // Information (base)

    uint32_t getBufferSize() const noexcept;

    double getSampleRate() const noexcept;

    const char* getName() const noexcept;

    EngineProcessMode getProccessMode() const noexcept;

    const EngineOptions& getOptions() const noexcept;

    virtual EngineTimeInfo getTimeInfo() const noexcept;
 
    // -------------------------------------------------------------------
    // Information (peaks)

    const float* getPeaks(uint pluginId) const noexcept;

    float getInputPeak(uint pluginId, bool isLeft) const noexcept;

    float getOutputPeak(uint pluginId, bool isLeft) const noexcept;
 
    // -------------------------------------------------------------------
    // Callback

    virtual void callback(bool sendHost, bool sendOSC,
                          EngineCallbackOpcode action, uint pluginId,
                          int value1, int value2, int value3, float valuef, const char* valueStr) noexcept;

    void setCallback(EngineCallbackFunc func, void* ptr) noexcept;
 
    // -------------------------------------------------------------------
    // Callback

    virtual const char* runFileCallback(FileCallbackOpcode action,
                                        bool isDir, const char* title, const char* filter) noexcept;

    void setFileCallback(FileCallbackFunc func, void* ptr) noexcept;
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    // -------------------------------------------------------------------
    // Patchbay

    virtual bool patchbayConnect(bool external,
                                 uint groupA, uint portA,
                                 uint groupB, uint portB);

    virtual bool patchbayDisconnect(bool external, uint connectionId);

    virtual bool patchbaySetGroupPos(bool sendHost, bool sendOSC, bool external,
                                     uint groupId, int x1, int y1, int x2, int y2);

    virtual bool patchbayRefresh(bool sendHost, bool sendOSC, bool external);
#endif
 
    // -------------------------------------------------------------------
    // Transport

    virtual void transportPlay() noexcept;

    virtual void transportPause() noexcept;

    virtual void transportBPM(double bpm) noexcept;

    virtual void transportRelocate(uint64_t frame) noexcept;
 
    // -------------------------------------------------------------------
    // Error handling

    const char* getLastError() const noexcept;

    void setLastError(const char* error) const noexcept;
 
    // -------------------------------------------------------------------
    // Misc

    bool isAboutToClose() const noexcept;

    bool setAboutToClose() noexcept;
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    bool isLoadingProject() const noexcept;
#endif

    void setActionCanceled(bool canceled) noexcept;

    bool wasActionCanceled() const noexcept;
 
    // -------------------------------------------------------------------
    // Options

    virtual void setOption(EngineOption option, int value, const char* valueStr) noexcept;
 
    // -------------------------------------------------------------------
    // OSC Stuff
 
#ifndef BUILD_BRIDGE
    bool isOscControlRegistered() const noexcept;

    const char* getOscServerPathTCP() const noexcept;

    const char* getOscServerPathUDP() const noexcept;
#endif
 
    // -------------------------------------------------------------------
 
protected:
    struct ProtectedData;
    ProtectedData* const pData;

    friend class CarlaEngineEventPort;
    friend class CarlaEngineOsc;
    friend class CarlaEngineRunner;
    friend class CarlaPluginInstance;
    friend class EngineInternalGraph;
    friend class PendingRtEventsRunner;
    friend class ScopedActionLock;
    friend class ScopedEngineEnvironmentLocker;
    friend class ScopedRunnerStopper;
    friend class PatchbayGraph;
    friend struct ExternalGraph;
    friend struct RackGraph;
 
    // -------------------------------------------------------------------
    // Internal stuff

    void bufferSizeChanged(uint32_t newBufferSize);

    void sampleRateChanged(double newSampleRate);

    void offlineModeChanged(bool isOffline);

    void setPluginPeaksRT(uint pluginId, float const inPeaks[2], float const outPeaks[2]) noexcept;
 
public:
    void saveProjectInternal(water::MemoryOutputStream& outStrm) const;

    bool loadProjectInternal(water::XmlDocument& xmlDoc, bool alwaysLoadConnections);
 
protected:
    // -------------------------------------------------------------------
    // Helper functions

    EngineEvent* getInternalEventBuffer(bool isInput) const noexcept;
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    // -------------------------------------------------------------------
    // Patchbay stuff

    struct PatchbayPosition { const char* name; int x1, y1, x2, y2, pluginId; bool dealloc; };
    virtual const char* const* getPatchbayConnections(bool external) const;
    virtual const PatchbayPosition* getPatchbayPositions(bool external, uint& count) const;
    virtual void restorePatchbayConnection(bool external, const char* sourcePort, const char* targetPort);
    // returns true if plugin name mapping found, ppos.name updated to its converted name
    virtual bool restorePatchbayGroupPosition(bool external, PatchbayPosition& ppos);

    virtual bool connectExternalGraphPort(uint, uint, const char*);
    virtual bool disconnectExternalGraphPort(uint, uint, const char*);
#endif
 
    // -------------------------------------------------------------------
 
    CARLA_DECLARE_NON_COPYABLE(CarlaEngine)
};

 
// -----------------------------------------------------------------------
 
CARLA_BACKEND_END_NAMESPACE
 
#endif // CARLA_ENGINE_HPP_INCLUDED