CarlaBackend.h

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_BACKEND_H_INCLUDED
#define CARLA_BACKEND_H_INCLUDED
 
#include "CarlaDefines.h"
 
#ifdef CARLA_PROPER_CPP11_SUPPORT
# include <cstdint>
#else
# include <stdint.h>
#endif
 
#define STR_MAX 0xFF
 
#ifndef CARLA_BACKEND_NAMESPACE
# define CARLA_BACKEND_NAMESPACE CarlaBackend
#endif
 
#ifdef __cplusplus
# define CARLA_BACKEND_START_NAMESPACE namespace CARLA_BACKEND_NAMESPACE {
# define CARLA_BACKEND_END_NAMESPACE }
# define CARLA_BACKEND_USE_NAMESPACE using namespace CARLA_BACKEND_NAMESPACE;
# include <algorithm>
# include <cmath>
# include <limits>
/* Start namespace */
CARLA_BACKEND_START_NAMESPACE
#endif

 
/* ------------------------------------------------------------------------------------------------------------
 * Carla Backend API (base definitions) */

static const uint MAX_DEFAULT_PLUGINS = 512;

static const uint MAX_RACK_PLUGINS = 64;

static const uint MAX_PATCHBAY_PLUGINS = 255;

static const uint MAX_DEFAULT_PARAMETERS = 200;

static const uint MAIN_CARLA_PLUGIN_ID = 0xFFFF;
 
/* ------------------------------------------------------------------------------------------------------------
 * Engine Driver Device Hints */


static const uint ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL = 0x1;

static const uint ENGINE_DRIVER_DEVICE_CAN_TRIPLE_BUFFER = 0x2;

static const uint ENGINE_DRIVER_DEVICE_VARIABLE_BUFFER_SIZE = 0x4;

static const uint ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x8;

 
/* ------------------------------------------------------------------------------------------------------------
 * Plugin Hints */


static const uint PLUGIN_IS_BRIDGE = 0x001;

static const uint PLUGIN_IS_RTSAFE = 0x002;

static const uint PLUGIN_IS_SYNTH = 0x004;

static const uint PLUGIN_HAS_CUSTOM_UI = 0x008;

static const uint PLUGIN_CAN_DRYWET = 0x010;

static const uint PLUGIN_CAN_VOLUME = 0x020;

static const uint PLUGIN_CAN_BALANCE = 0x040;

static const uint PLUGIN_CAN_PANNING = 0x080;

static const uint PLUGIN_NEEDS_FIXED_BUFFERS = 0x100;

static const uint PLUGIN_NEEDS_UI_MAIN_THREAD = 0x200;

static const uint PLUGIN_USES_MULTI_PROGS = 0x400;

static const uint PLUGIN_HAS_INLINE_DISPLAY = 0x800;

static const uint PLUGIN_HAS_CUSTOM_EMBED_UI = 0x1000;

static const uint PLUGIN_HAS_CUSTOM_UI_USING_FILE_OPEN = 0x2000;

 
/* ------------------------------------------------------------------------------------------------------------
 * Plugin Options */


static const uint PLUGIN_OPTION_FIXED_BUFFERS = 0x001;

static const uint PLUGIN_OPTION_FORCE_STEREO = 0x002;

static const uint PLUGIN_OPTION_MAP_PROGRAM_CHANGES = 0x004;

static const uint PLUGIN_OPTION_USE_CHUNKS = 0x008;

static const uint PLUGIN_OPTION_SEND_CONTROL_CHANGES = 0x010;

static const uint PLUGIN_OPTION_SEND_CHANNEL_PRESSURE = 0x020;

static const uint PLUGIN_OPTION_SEND_NOTE_AFTERTOUCH = 0x040;

static const uint PLUGIN_OPTION_SEND_PITCHBEND = 0x080;

static const uint PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100;

static const uint PLUGIN_OPTION_SEND_PROGRAM_CHANGES = 0x200;

static const uint PLUGIN_OPTION_SKIP_SENDING_NOTES = 0x400;

static const uint PLUGIN_OPTIONS_NULL = 0x10000;

 
/* ------------------------------------------------------------------------------------------------------------
 * Audio Port Hints */


static const uint AUDIO_PORT_IS_SIDECHAIN = 0x1;

 
/* ------------------------------------------------------------------------------------------------------------
 * Parameter Hints */


static const uint PARAMETER_IS_BOOLEAN = 0x001;

static const uint PARAMETER_IS_INTEGER = 0x002;

static const uint PARAMETER_IS_LOGARITHMIC = 0x004;

static const uint PARAMETER_IS_ENABLED = 0x010;

static const uint PARAMETER_IS_AUTOMATABLE = 0x020;
 
// for backwards compatibility
static const uint PARAMETER_IS_AUTOMABLE = PARAMETER_IS_AUTOMATABLE;

static const uint PARAMETER_IS_READ_ONLY = 0x040;

static const uint PARAMETER_USES_SAMPLERATE = 0x100;

static const uint PARAMETER_USES_SCALEPOINTS = 0x200;

static const uint PARAMETER_USES_CUSTOM_TEXT = 0x400;

static const uint PARAMETER_CAN_BE_CV_CONTROLLED = 0x800;

static const uint PARAMETER_IS_NOT_SAVED = 0x1000;

 
/* ------------------------------------------------------------------------------------------------------------
 * Mapped Parameter Flags */


static const uint PARAMETER_MAPPING_MIDI_DELTA = 0x001;

 
/* ------------------------------------------------------------------------------------------------------------
 * Patchbay Port Hints */


static const uint PATCHBAY_PORT_IS_INPUT = 0x01;

static const uint PATCHBAY_PORT_TYPE_AUDIO = 0x02;

static const uint PATCHBAY_PORT_TYPE_CV = 0x04;

static const uint PATCHBAY_PORT_TYPE_MIDI = 0x08;

static const uint PATCHBAY_PORT_TYPE_OSC = 0x10;

 
/* ------------------------------------------------------------------------------------------------------------
 * Patchbay Port Group Hints */


static const uint PATCHBAY_PORT_GROUP_MAIN_INPUT = 0x01;

static const uint PATCHBAY_PORT_GROUP_MAIN_OUTPUT = 0x02;

static const uint PATCHBAY_PORT_GROUP_STEREO = 0x04;

static const uint PATCHBAY_PORT_GROUP_MID_SIDE = 0x08;

 
/* ------------------------------------------------------------------------------------------------------------
 * Custom Data Types */


static const char* const CUSTOM_DATA_TYPE_BOOLEAN = "http://kxstudio.sf.net/ns/carla/boolean";

static const char* const CUSTOM_DATA_TYPE_CHUNK = "http://kxstudio.sf.net/ns/carla/chunk";

static const char* const CUSTOM_DATA_TYPE_PATH = "http://kxstudio.sf.net/ns/carla/path";

static const char* const CUSTOM_DATA_TYPE_PROPERTY = "http://kxstudio.sf.net/ns/carla/property";

static const char* const CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/string";

 
/* ------------------------------------------------------------------------------------------------------------
 * Custom Data Keys */


static const char* const CUSTOM_DATA_KEY_UI_POSITION = "CarlaUiPosition";

static const char* const CUSTOM_DATA_KEY_UI_SIZE = "CarlaUiSize";

static const char* const CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible";

 
/* ------------------------------------------------------------------------------------------------------------
 * Binary Type */

typedef enum {
    BINARY_NONE = 0,

    BINARY_POSIX32 = 1,

    BINARY_POSIX64 = 2,

    BINARY_WIN32 = 3,

    BINARY_WIN64 = 4,

    BINARY_OTHER = 5
 
} BinaryType;
 
/* ------------------------------------------------------------------------------------------------------------
 * File Type */

typedef enum {
    FILE_NONE = 0,

    FILE_AUDIO = 1,

    FILE_MIDI = 2
 
} FileType;
 
/* ------------------------------------------------------------------------------------------------------------
 * Plugin Type */

typedef enum {
    PLUGIN_NONE = 0,

    PLUGIN_INTERNAL = 1,

    PLUGIN_LADSPA = 2,

    PLUGIN_DSSI = 3,

    PLUGIN_LV2 = 4,

    PLUGIN_VST2 = 5,

    PLUGIN_VST3 = 6,

    PLUGIN_AU = 7,

    PLUGIN_DLS = 8,

    PLUGIN_GIG = 9,

    PLUGIN_SF2 = 10,

    PLUGIN_SFZ = 11,

    PLUGIN_JACK = 12,

    PLUGIN_JSFX = 13
 
} PluginType;
 
/* ------------------------------------------------------------------------------------------------------------
 * Plugin Category */

typedef enum {
    PLUGIN_CATEGORY_NONE = 0,

    PLUGIN_CATEGORY_SYNTH = 1,

    PLUGIN_CATEGORY_DELAY = 2,

    PLUGIN_CATEGORY_EQ = 3,

    PLUGIN_CATEGORY_FILTER = 4,

    PLUGIN_CATEGORY_DISTORTION = 5,

    PLUGIN_CATEGORY_DYNAMICS = 6,

    PLUGIN_CATEGORY_MODULATOR = 7,

    PLUGIN_CATEGORY_UTILITY = 8,

    PLUGIN_CATEGORY_OTHER = 9
 
} PluginCategory;
 
/* ------------------------------------------------------------------------------------------------------------
 * Parameter Type */

typedef enum {
    PARAMETER_UNKNOWN = 0,

    PARAMETER_INPUT = 1,

    PARAMETER_OUTPUT = 2
 
} ParameterType;
 
/* ------------------------------------------------------------------------------------------------------------
 * Internal Parameter Index */

typedef enum {
    PARAMETER_NULL = -1,
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    PARAMETER_ACTIVE = -2,

    PARAMETER_DRYWET = -3,

    PARAMETER_VOLUME = -4,

    PARAMETER_BALANCE_LEFT = -5,

    PARAMETER_BALANCE_RIGHT = -6,

    PARAMETER_PANNING = -7,

    PARAMETER_CTRL_CHANNEL = -8,
#endif

    PARAMETER_MAX = -9
 
} InternalParameterIndex;
 
/* ------------------------------------------------------------------------------------------------------------
 * Special Mapped Control Index */

typedef enum {
    CONTROL_INDEX_NONE = -1,

    CONTROL_INDEX_CV = 130,

    CONTROL_INDEX_MIDI_PITCHBEND = 131,

    CONTROL_INDEX_MIDI_LEARN = 132,

    CONTROL_INDEX_MAX_ALLOWED = CONTROL_INDEX_MIDI_LEARN
 
} SpecialMappedControlIndex;
 
/* ------------------------------------------------------------------------------------------------------------
 * Engine Callback Opcode */

typedef enum {
    ENGINE_CALLBACK_DEBUG = 0,

    ENGINE_CALLBACK_PLUGIN_ADDED = 1,

    ENGINE_CALLBACK_PLUGIN_REMOVED = 2,

    ENGINE_CALLBACK_PLUGIN_RENAMED = 3,

    ENGINE_CALLBACK_PLUGIN_UNAVAILABLE = 4,

    ENGINE_CALLBACK_PARAMETER_VALUE_CHANGED = 5,

    ENGINE_CALLBACK_PARAMETER_DEFAULT_CHANGED = 6,
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    ENGINE_CALLBACK_PARAMETER_MAPPED_CONTROL_INDEX_CHANGED = 7,

    ENGINE_CALLBACK_PARAMETER_MIDI_CHANNEL_CHANGED = 8,

    ENGINE_CALLBACK_OPTION_CHANGED = 9,
#endif

    ENGINE_CALLBACK_PROGRAM_CHANGED = 10,

    ENGINE_CALLBACK_MIDI_PROGRAM_CHANGED = 11,

    ENGINE_CALLBACK_UI_STATE_CHANGED = 12,

    ENGINE_CALLBACK_NOTE_ON = 13,

    ENGINE_CALLBACK_NOTE_OFF = 14,

    ENGINE_CALLBACK_UPDATE = 15,

    ENGINE_CALLBACK_RELOAD_INFO = 16,

    ENGINE_CALLBACK_RELOAD_PARAMETERS = 17,

    ENGINE_CALLBACK_RELOAD_PROGRAMS = 18,

    ENGINE_CALLBACK_RELOAD_ALL = 19,
 
#ifndef BUILD_BRIDGE_ALTERNATIVE_ARCH
    ENGINE_CALLBACK_PATCHBAY_CLIENT_ADDED = 20,

    ENGINE_CALLBACK_PATCHBAY_CLIENT_REMOVED = 21,

    ENGINE_CALLBACK_PATCHBAY_CLIENT_RENAMED = 22,

    ENGINE_CALLBACK_PATCHBAY_CLIENT_DATA_CHANGED = 23,

    ENGINE_CALLBACK_PATCHBAY_PORT_ADDED = 24,

    ENGINE_CALLBACK_PATCHBAY_PORT_REMOVED = 25,

    ENGINE_CALLBACK_PATCHBAY_PORT_CHANGED = 26,

    ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED = 27,

    ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED = 28,
#endif

    ENGINE_CALLBACK_ENGINE_STARTED = 29,

    ENGINE_CALLBACK_ENGINE_STOPPED = 30,

    ENGINE_CALLBACK_PROCESS_MODE_CHANGED = 31,

    ENGINE_CALLBACK_TRANSPORT_MODE_CHANGED = 32,

    ENGINE_CALLBACK_BUFFER_SIZE_CHANGED = 33,

    ENGINE_CALLBACK_SAMPLE_RATE_CHANGED = 34,

    ENGINE_CALLBACK_CANCELABLE_ACTION = 35,

    ENGINE_CALLBACK_PROJECT_LOAD_FINISHED = 36,

    ENGINE_CALLBACK_NSM = 37,

    ENGINE_CALLBACK_IDLE = 38,

    ENGINE_CALLBACK_INFO = 39,

    ENGINE_CALLBACK_ERROR = 40,

    ENGINE_CALLBACK_QUIT = 41,

    ENGINE_CALLBACK_INLINE_DISPLAY_REDRAW = 42,

    ENGINE_CALLBACK_PATCHBAY_PORT_GROUP_ADDED = 43,

    ENGINE_CALLBACK_PATCHBAY_PORT_GROUP_REMOVED = 44,

    ENGINE_CALLBACK_PATCHBAY_PORT_GROUP_CHANGED = 45,

    ENGINE_CALLBACK_PARAMETER_MAPPED_RANGE_CHANGED = 46,

    ENGINE_CALLBACK_PATCHBAY_CLIENT_POSITION_CHANGED = 47,

    ENGINE_CALLBACK_EMBED_UI_RESIZED = 48
 
} EngineCallbackOpcode;
 
/* ------------------------------------------------------------------------------------------------------------
 * NSM Callback Opcode */

typedef enum {
    NSM_CALLBACK_INIT = 0,

    NSM_CALLBACK_ERROR = 1,

    NSM_CALLBACK_ANNOUNCE = 2,

    NSM_CALLBACK_OPEN = 3,

    NSM_CALLBACK_SAVE = 4,

    NSM_CALLBACK_SESSION_IS_LOADED = 5,

    NSM_CALLBACK_SHOW_OPTIONAL_GUI = 6,

    NSM_CALLBACK_HIDE_OPTIONAL_GUI = 7,

    NSM_CALLBACK_SET_CLIENT_NAME_ID = 8
 
} NsmCallbackOpcode;
 
/* ------------------------------------------------------------------------------------------------------------
 * Engine Option */

typedef enum {
    ENGINE_OPTION_DEBUG = 0,

    ENGINE_OPTION_PROCESS_MODE = 1,

    ENGINE_OPTION_TRANSPORT_MODE = 2,

    ENGINE_OPTION_FORCE_STEREO = 3,

    ENGINE_OPTION_PREFER_PLUGIN_BRIDGES = 4,

    ENGINE_OPTION_PREFER_UI_BRIDGES = 5,

    ENGINE_OPTION_UIS_ALWAYS_ON_TOP = 6,

    ENGINE_OPTION_MAX_PARAMETERS = 7,

    ENGINE_OPTION_RESET_XRUNS = 8,

    ENGINE_OPTION_UI_BRIDGES_TIMEOUT = 9,

    ENGINE_OPTION_AUDIO_BUFFER_SIZE = 10,

    ENGINE_OPTION_AUDIO_SAMPLE_RATE = 11,

    ENGINE_OPTION_AUDIO_TRIPLE_BUFFER = 12,

    ENGINE_OPTION_AUDIO_DRIVER = 13,

    ENGINE_OPTION_AUDIO_DEVICE = 14,
 
#ifndef BUILD_BRIDGE
    ENGINE_OPTION_OSC_ENABLED = 15,

    ENGINE_OPTION_OSC_PORT_TCP = 16,

    ENGINE_OPTION_OSC_PORT_UDP = 17,
#endif

    ENGINE_OPTION_FILE_PATH = 18,

    ENGINE_OPTION_PLUGIN_PATH = 19,

    ENGINE_OPTION_PATH_BINARIES = 20,

    ENGINE_OPTION_PATH_RESOURCES = 21,

    ENGINE_OPTION_PREVENT_BAD_BEHAVIOUR = 22,

    ENGINE_OPTION_FRONTEND_BACKGROUND_COLOR = 23,

    ENGINE_OPTION_FRONTEND_FOREGROUND_COLOR = 24,

    ENGINE_OPTION_FRONTEND_UI_SCALE = 25,

    ENGINE_OPTION_FRONTEND_WIN_ID = 26,
 
#if !defined(BUILD_BRIDGE_ALTERNATIVE_ARCH) && !defined(CARLA_OS_WIN)
    ENGINE_OPTION_WINE_EXECUTABLE = 27,

    ENGINE_OPTION_WINE_AUTO_PREFIX = 28,

    ENGINE_OPTION_WINE_FALLBACK_PREFIX = 29,

    ENGINE_OPTION_WINE_RT_PRIO_ENABLED = 30,

    ENGINE_OPTION_WINE_BASE_RT_PRIO = 31,

    ENGINE_OPTION_WINE_SERVER_RT_PRIO = 32,
#endif
 
#ifndef BUILD_BRIDGE
    ENGINE_OPTION_DEBUG_CONSOLE_OUTPUT = 33,
#endif

    ENGINE_OPTION_CLIENT_NAME_PREFIX = 34,

    ENGINE_OPTION_PLUGINS_ARE_STANDALONE = 35
 
} EngineOption;
 
/* ------------------------------------------------------------------------------------------------------------
 * Engine Process Mode */

typedef enum {
    ENGINE_PROCESS_MODE_SINGLE_CLIENT = 0,

    ENGINE_PROCESS_MODE_MULTIPLE_CLIENTS = 1,

    ENGINE_PROCESS_MODE_CONTINUOUS_RACK = 2,

    ENGINE_PROCESS_MODE_PATCHBAY = 3,

    ENGINE_PROCESS_MODE_BRIDGE = 4
 
} EngineProcessMode;
 
/* ------------------------------------------------------------------------------------------------------------
 * Engine Transport Mode */

typedef enum {
    ENGINE_TRANSPORT_MODE_DISABLED = 0,

    ENGINE_TRANSPORT_MODE_INTERNAL = 1,

    ENGINE_TRANSPORT_MODE_JACK = 2,

    ENGINE_TRANSPORT_MODE_PLUGIN = 3,

    ENGINE_TRANSPORT_MODE_BRIDGE = 4
 
} EngineTransportMode;
 
/* ------------------------------------------------------------------------------------------------------------
 * File Callback Opcode */

typedef enum {
    FILE_CALLBACK_DEBUG = 0,

    FILE_CALLBACK_OPEN = 1,

    FILE_CALLBACK_SAVE = 2
 
} FileCallbackOpcode;
 
/* ------------------------------------------------------------------------------------------------------------
 * Patchbay Icon */

enum PatchbayIcon {
    PATCHBAY_ICON_APPLICATION = 0,

    PATCHBAY_ICON_PLUGIN = 1,

    PATCHBAY_ICON_HARDWARE = 2,

    PATCHBAY_ICON_CARLA = 3,

    PATCHBAY_ICON_DISTRHO = 4,

    PATCHBAY_ICON_FILE = 5
};
 
/* ------------------------------------------------------------------------------------------------------------
 * Carla Backend API (C stuff) */

typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, uint pluginId,
                                   int value1, int value2, int value3,
                                   float valuef, const char* valueStr);

typedef const char* (*FileCallbackFunc)(void* ptr, FileCallbackOpcode action, bool isDir, const char* title, const char* filter);

typedef struct {
    ParameterType type;

    uint hints;

    int32_t index;

    int32_t rindex;

    uint8_t midiChannel;

    int16_t mappedControlIndex;

    float mappedMinimum;

    float mappedMaximum;

    uint mappedFlags;
 
} ParameterData;

typedef struct _ParameterRanges {
    float def;

    float min;

    float max;

    float step;

    float stepSmall;

    float stepLarge;
 
#ifdef __cplusplus
    void fixDefault() noexcept
    {
        fixValue(def);
    }

    void fixValue(float& value) const noexcept
    {
        if (value < min)
            value = min;
        else if (value > max)
            value = max;
    }

    const float& getFixedValue(const float& value) const noexcept
    {
        if (value <= min)
            return min;
        if (value >= max)
            return max;
        return value;
    }

    float getNormalizedValue(const float& value) const noexcept
    {
        const float normValue((value - min) / (max - min));
 
        if (normValue <= 0.0f)
            return 0.0f;
        if (normValue >= 1.0f)
            return 1.0f;
        return normValue;
    }

    float getFixedAndNormalizedValue(const float& value) const noexcept
    {
        if (value <= min)
            return 0.0f;
        if (value >= max)
            return 1.0f;
 
        const float normValue((value - min) / (max - min));
 
        if (normValue <= 0.0f)
            return 0.0f;
        if (normValue >= 1.0f)
            return 1.0f;
 
        return normValue;
    }

    float getUnnormalizedValue(const float& value) const noexcept
    {
        if (value <= 0.0f)
            return min;
        if (value >= 1.0f)
            return max;
 
        return value * (max - min) + min;
    }

    float getUnnormalizedLogValue(const float& value) const noexcept
    {
        if (value <= 0.0f)
            return min;
        if (value >= 1.0f)
            return max;
 
        float rmin = min;
 
        if (std::abs(min) < std::numeric_limits<float>::epsilon())
            rmin = 0.00001f;
 
        return rmin * std::pow(max/rmin, value);
    }
#endif /* __cplusplus */
 
} ParameterRanges;

typedef struct {
    uint32_t bank;

    uint32_t program;

    const char* name;
 
} MidiProgramData;

typedef struct _CustomData {
    const char* type;

    const char* key;

    const char* value;
 
#ifdef __cplusplus
    bool isValid() const noexcept
    {
        if (type  == nullptr || type[0] == '\0') return false;
        if (key   == nullptr || key [0] == '\0') return false;
        if (value == nullptr)                    return false;
        return true;
    }
#endif /* __cplusplus */
 
} CustomData;

typedef struct {
    uint hints;

    const uint32_t* bufferSizes;

    const double* sampleRates;
 
} EngineDriverDeviceInfo;

 
#ifdef __cplusplus
/* Forward declarations of commonly used Carla classes */
class CarlaEngine;
class CarlaEngineClient;
class CarlaEngineCVSourcePorts;
class CarlaPlugin;
/* End namespace */
CARLA_BACKEND_END_NAMESPACE
#endif
 
#endif /* CARLA_BACKEND_H_INCLUDED */