CarlaPlugin.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_PLUGIN_HPP_INCLUDED
#define CARLA_PLUGIN_HPP_INCLUDED
 
#include "CarlaBackend.h"
#include "CarlaPluginPtr.hpp"
 
// -----------------------------------------------------------------------
// Avoid including extra libs here
 
typedef struct _NativePluginDescriptor NativePluginDescriptor;
struct LADSPA_RDF_Descriptor;
 
// -----------------------------------------------------------------------
 
CARLA_BACKEND_START_NAMESPACE
 
#if 0
} /* Fix editor indentation */
#endif
 
// -----------------------------------------------------------------------

 
class CarlaEngineAudioPort;
class CarlaEngineCVPort;
class CarlaEngineEventPort;
class CarlaEngineCVSourcePorts;
class CarlaEngineBridge;
struct CarlaStateSave;
struct EngineEvent;
 
// -----------------------------------------------------------------------

class CARLA_API CarlaPlugin
{
protected:
    CarlaPlugin(CarlaEngine* engine, uint id);
 
public:
    virtual ~CarlaPlugin();
 
    // -------------------------------------------------------------------
    // Information (base)

    virtual PluginType getType() const noexcept = 0;

    uint getId() const noexcept;

    uint getHints() const noexcept;

    uint getOptionsEnabled() const noexcept;

    bool isEnabled() const noexcept;

    const char* getName() const noexcept;

    const char* getFilename() const noexcept;

    const char* getIconName() const noexcept;

    virtual PluginCategory getCategory() const noexcept;

    virtual int64_t getUniqueId() const noexcept;

    virtual uint32_t getLatencyInFrames() const noexcept;
 
    // -------------------------------------------------------------------
    // Information (count)

    uint32_t getAudioInCount() const noexcept;

    uint32_t getAudioOutCount() const noexcept;

    uint32_t getCVInCount() const noexcept;

    uint32_t getCVOutCount() const noexcept;

    virtual uint32_t getMidiInCount() const noexcept;

    virtual uint32_t getMidiOutCount() const noexcept;

    uint32_t getParameterCount() const noexcept;

    virtual uint32_t getParameterScalePointCount(uint32_t parameterId) const noexcept;

    uint32_t getProgramCount() const noexcept;

    uint32_t getMidiProgramCount() const noexcept;

    uint32_t getCustomDataCount() const noexcept;
 
    // -------------------------------------------------------------------
    // Information (current data)

    int32_t getCurrentProgram() const noexcept;

    int32_t getCurrentMidiProgram() const noexcept;

    virtual uint getAudioPortHints(bool isOutput, uint32_t portIndex) const noexcept;

    const ParameterData& getParameterData(uint32_t parameterId) const noexcept;

    const ParameterRanges& getParameterRanges(uint32_t parameterId) const noexcept;

    bool isParameterOutput(uint32_t parameterId) const noexcept;

    const MidiProgramData& getMidiProgramData(uint32_t index) const noexcept;

    const CustomData& getCustomData(uint32_t index) const noexcept;

    virtual std::size_t getChunkData(void** dataPtr) noexcept;
 
    // -------------------------------------------------------------------
    // Information (per-plugin data)

    virtual uint getOptionsAvailable() const noexcept;

    virtual float getParameterValue(uint32_t parameterId) const noexcept;

    virtual float getParameterScalePointValue(uint32_t parameterId, uint32_t scalePointId) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getLabel(char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getMaker(char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getCopyright(char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getRealName(char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterName(uint32_t parameterId, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterSymbol(uint32_t parameterId, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterText(uint32_t parameterId, char* strBuf) noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterUnit(uint32_t parameterId, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterComment(uint32_t parameterId, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterGroupName(uint32_t parameterId, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    virtual bool getParameterScalePointLabel(uint32_t parameterId, uint32_t scalePointId, char* strBuf) const noexcept;

    float getInternalParameterValue(int32_t parameterId) const noexcept;

    __attribute__((warn_unused_result))
    bool getProgramName(uint32_t index, char* strBuf) const noexcept;

    __attribute__((warn_unused_result))
    bool getMidiProgramName(uint32_t index, char* strBuf) const noexcept;

    void getParameterCountInfo(uint32_t& ins, uint32_t& outs) const noexcept;
 
    // -------------------------------------------------------------------
    // Set data (state)

    virtual void prepareForSave(bool temporary);

    virtual void resetParameters() noexcept;

    virtual void randomizeParameters() noexcept;

    const CarlaStateSave& getStateSave(bool callPrepareForSave = true);

    void loadStateSave(const CarlaStateSave& stateSave);

    bool saveStateToFile(const char* filename);

    bool loadStateFromFile(const char* filename);

    bool exportAsLV2(const char* lv2path);
 
    // -------------------------------------------------------------------
    // Set data (internal stuff)

    virtual void setId(uint newId) noexcept;

    virtual void setName(const char* newName);

    virtual void setOption(uint option, bool yesNo, bool sendCallback);

    void setEnabled(bool yesNo) noexcept;

    void setActive(bool active, bool sendOsc, bool sendCallback) noexcept;
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    void setDryWet(float value, bool sendOsc, bool sendCallback) noexcept;

    void setVolume(float value, bool sendOsc, bool sendCallback) noexcept;

    void setBalanceLeft(float value, bool sendOsc, bool sendCallback) noexcept;

    void setBalanceRight(float value, bool sendOsc, bool sendCallback) noexcept;

    void setPanning(float value, bool sendOsc, bool sendCallback) noexcept;

    void setDryWetRT(float value, bool sendCallbackLater) noexcept;
    void setVolumeRT(float value, bool sendCallbackLater) noexcept;
    void setBalanceLeftRT(float value, bool sendCallbackLater) noexcept;
    void setBalanceRightRT(float value, bool sendCallbackLater) noexcept;
    void setPanningRT(float value, bool sendCallbackLater) noexcept;
#endif // ! BUILD_BRIDGE_ALTERNATIVE_ARCH

    virtual void setCtrlChannel(int8_t channel, bool sendOsc, bool sendCallback) noexcept;
 
    // -------------------------------------------------------------------
    // Set data (plugin-specific stuff)

    virtual void setParameterValue(uint32_t parameterId, float value, bool sendGui, bool sendOsc, bool sendCallback) noexcept;

    virtual void setParameterValueRT(uint32_t parameterId, float value, uint32_t frameOffset, bool sendCallbackLater) noexcept;

    void setParameterValueByRealIndex(int32_t rindex, float value, bool sendGui, bool sendOsc, bool sendCallback) noexcept;

    virtual void setParameterMidiChannel(uint32_t parameterId, uint8_t channel, bool sendOsc, bool sendCallback) noexcept;

    virtual void setParameterMappedControlIndex(uint32_t parameterId, int16_t index,
                                                bool sendOsc, bool sendCallback, bool reconfigureNow) noexcept;

    virtual void setParameterMappedRange(uint32_t parameterId, float minimum, float maximum,
                                         bool sendOsc, bool sendCallback) noexcept;

    virtual void setCustomData(const char* type, const char* key, const char* value, bool sendGui);

    virtual void setChunkData(const void* data, std::size_t dataSize);

    virtual void setProgram(int32_t index, bool sendGui, bool sendOsc, bool sendCallback, bool doingInit = false) noexcept;

    virtual void setMidiProgram(int32_t index, bool sendGui, bool sendOsc, bool sendCallback, bool doingInit = false) noexcept;

    void setMidiProgramById(uint32_t bank, uint32_t program, bool sendGui, bool sendOsc, bool sendCallback) noexcept;

    virtual void setProgramRT(uint32_t index, bool sendCallbackLater) noexcept;
    virtual void setMidiProgramRT(uint32_t index, bool sendCallbackLater) noexcept;
 
    // -------------------------------------------------------------------
    // Plugin state

    virtual void reload() = 0;

    virtual void reloadPrograms(bool doInit);
 
    // -------------------------------------------------------------------
    // Plugin processing
 
protected:
    virtual void activate() noexcept;

    virtual void deactivate() noexcept;
 
public:
    virtual void process(const float* const* audioIn, float** audioOut,
                         const float* const* cvIn, float** cvOut, uint32_t frames) = 0;

    virtual void bufferSizeChanged(uint32_t newBufferSize);

    virtual void sampleRateChanged(double newSampleRate);

    virtual void offlineModeChanged(bool isOffline);
 
    // -------------------------------------------------------------------
    // Misc

    virtual void idle();

    bool tryLock(bool forcedOffline) noexcept;

    void unlock() noexcept;
 
    // -------------------------------------------------------------------
    // Plugin buffers

    virtual void initBuffers() const noexcept;

    virtual void clearBuffers() noexcept;
 
    // -------------------------------------------------------------------
    // OSC stuff

    virtual void handleOscMessage(const char* method,
                                  int argc,
                                  const void* argv,
                                  const char* types,
                                  void* msg);
 
    // -------------------------------------------------------------------
    // MIDI events

    void sendMidiSingleNote(uint8_t channel, uint8_t note, uint8_t velo,
                            bool sendGui, bool sendOsc, bool sendCallback);
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    void postponeRtAllNotesOff();
#endif
 
    // -------------------------------------------------------------------
    // UI Stuff

    virtual void setCustomUITitle(const char* title) noexcept;

    virtual void showCustomUI(bool yesNo);

    virtual void* embedCustomUI(void* ptr);

    virtual void uiIdle();

    virtual void uiParameterChange(uint32_t index, float value) noexcept;

    virtual void uiProgramChange(uint32_t index) noexcept;

    virtual void uiMidiProgramChange(uint32_t index) noexcept;

    virtual void uiNoteOn(uint8_t channel, uint8_t note, uint8_t velo) noexcept;

    virtual void uiNoteOff(uint8_t channel, uint8_t note) noexcept;
 
    // -------------------------------------------------------------------
    // Helper functions

    CarlaEngine* getEngine() const noexcept;

    CarlaEngineClient* getEngineClient() const noexcept;

    CarlaEngineAudioPort* getAudioInPort(uint32_t index) const noexcept;

    CarlaEngineAudioPort* getAudioOutPort(uint32_t index) const noexcept;

    CarlaEngineCVPort* getCVInPort(uint32_t index) const noexcept;

    CarlaEngineCVPort* getCVOutPort(uint32_t index) const noexcept;

    CarlaEngineEventPort* getDefaultEventInPort() const noexcept;

    CarlaEngineEventPort* getDefaultEventOutPort() const noexcept;
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    void checkForMidiLearn(EngineEvent& event) noexcept;
#endif

    virtual void* getNativeHandle() const noexcept;

    virtual const void* getNativeDescriptor() const noexcept;

    virtual uintptr_t getUiBridgeProcessId() const noexcept;
 
    // -------------------------------------------------------------------

    uint32_t getPatchbayNodeId() const noexcept;

    void setPatchbayNodeId(uint32_t nodeId) noexcept;
 
    // -------------------------------------------------------------------
    // Plugin initializers

    virtual BinaryType getBinaryType() const noexcept
    {
        return BINARY_NATIVE;
    }

    virtual const void* getExtraStuff() const noexcept
    {
        return nullptr;
    }
 
#ifndef DOXYGEN
    struct Initializer {
        CarlaEngine* const engine;
        const uint id;
        const char* const filename;
        const char* const name;
        const char* const label;
        const int64_t uniqueId;
        const uint options; // see PluginOptions
    };
 
    static CarlaPluginPtr newNative(const Initializer& init);
    static CarlaPluginPtr newBridge(const Initializer& init,
                                    BinaryType btype, PluginType ptype,
                                    const char* binaryArchName, const char* bridgeBinary);
 
    static CarlaPluginPtr newLADSPA(const Initializer& init, const LADSPA_RDF_Descriptor* rdfDescriptor);
    static CarlaPluginPtr newDSSI(const Initializer& init);
    static CarlaPluginPtr newLV2(const Initializer& init);
    static CarlaPluginPtr newVST2(const Initializer& init);
    static CarlaPluginPtr newVST3(const Initializer& init);
    static CarlaPluginPtr newAU(const Initializer& init);
    static CarlaPluginPtr newJSFX(const Initializer& init);
 
    static CarlaPluginPtr newJuce(const Initializer& init, const char* format);
    static CarlaPluginPtr newFluidSynth(const Initializer& init, PluginType ptype, bool use16Outs);
    static CarlaPluginPtr newSFZero(const Initializer& init);
 
    static CarlaPluginPtr newJackApp(const Initializer& init);
#endif
 
    // -------------------------------------------------------------------
 
protected:
    struct ProtectedData;
    ProtectedData* const pData;
 
    // -------------------------------------------------------------------
    // Internal helper functions
 
protected:
    virtual void cloneLV2Files(const CarlaPlugin& other);

    virtual void restoreLV2State(bool temporary) noexcept;

    virtual void prepareForDeletion() noexcept;

    virtual void waitForBridgeSaveSignal() noexcept;
 
    // -------------------------------------------------------------------
    // Helper classes

    class ScopedDisabler
    {
    public:
        ScopedDisabler(CarlaPlugin* plugin) noexcept;
        ~ScopedDisabler() noexcept;
 
    private:
        CarlaPlugin* const fPlugin;
        bool fWasEnabled;
 
        CARLA_PREVENT_HEAP_ALLOCATION
        CARLA_DECLARE_NON_COPYABLE(ScopedDisabler)
    };

    class ScopedSingleProcessLocker
    {
    public:
        ScopedSingleProcessLocker(CarlaPlugin* plugin, bool block) noexcept;
        ~ScopedSingleProcessLocker() noexcept;
 
    private:
        CarlaPlugin* const fPlugin;
        const bool fBlock;
 
        CARLA_PREVENT_HEAP_ALLOCATION
        CARLA_DECLARE_NON_COPYABLE(ScopedSingleProcessLocker)
    };
 
    friend class CarlaEngine;
    friend class CarlaEngineBridge;
    CARLA_DECLARE_NON_COPYABLE(CarlaPlugin)
};

 
// -----------------------------------------------------------------------
 
CARLA_BACKEND_END_NAMESPACE
 
#endif // CARLA_PLUGIN_HPP_INCLUDED