More of the same

source/backend/CarlaBackend.h

@@ -274,7 +274,7 @@ const unsigned int PARAMETER_USES_CUSTOM_TEXT = 0x400;
  */
 
 /*!
- * Patchbay port is input.
+ * Patchbay port is input.\n
  * When this hint is not set, port is assumed to be output.
  */
 const unsigned int PATCHBAY_PORT_IS_INPUT = 0x1;
@@ -299,14 +299,13 @@ const unsigned int PATCHBAY_PORT_TYPE_MIDI = 0x8;
 /*!
  * @defgroup CustomDataTypes Custom Data Types
  *
- * These types define how the @param value in the CustomData struct is stored.
- * The types are valid URIs. Any non-string or non-simple type (not integral) is saved in a base64 encoded format.
- * @see CustomData
+ * These types define how the value in the CustomData struct is stored.
+ * @see CustomData::type
  * @{
  */
 
 /*!
- * Boolean string type URI.
+ * Boolean string type URI.\n
  * Only "true" and "false" are valid values.
  */
 const char* const CUSTOM_DATA_TYPE_BOOLEAN = "http://kxstudio.sf.net/ns/carla/boolean";
@@ -327,7 +326,7 @@ const char* const CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/str
  * @defgroup CustomDataKeys Custom Data Keys
  *
  * Pre-defined keys used internally in Carla.
- * @see CustomData
+ * @see CustomData::key
  * @{
  */
 
@@ -509,7 +508,7 @@ typedef enum {
 } PluginCategory;
 
 /*!
- * Special parameters used internally in Carla.
+ * Special parameters used internally in Carla.\n
  * Plugins do not know about their existence.
  */
 typedef enum {
@@ -519,43 +518,43 @@ typedef enum {
     PARAMETER_NULL = -1,
 
     /*!
-     * Active parameter, boolean type.
+     * Active parameter, boolean type.\n
      * Default is 'false'.
      */
     PARAMETER_ACTIVE = -2,
 
     /*!
-     * Dry/Wet parameter.
+     * Dry/Wet parameter.\n
      * Range 0.0...1.0; default is 1.0.
      */
     PARAMETER_DRYWET = -3,
 
     /*!
-     * Volume parameter.
+     * Volume parameter.\n
      * Range 0.0...1.27; default is 1.0.
      */
     PARAMETER_VOLUME = -4,
 
     /*!
-     * Stereo Balance-Left parameter.
+     * Stereo Balance-Left parameter.\n
      * Range -1.0...1.0; default is -1.0.
      */
     PARAMETER_BALANCE_LEFT = -5,
 
     /*!
-     * Stereo Balance-Right parameter.
+     * Stereo Balance-Right parameter.\n
      * Range -1.0...1.0; default is 1.0.
      */
     PARAMETER_BALANCE_RIGHT = -6,
 
     /*!
-     * Mono Panning parameter.
+     * Mono Panning parameter.\n
      * Range -1.0...1.0; default is 0.0.
      */
     PARAMETER_PANNING = -7,
 
     /*!
-     * MIDI Control channel, integer type.
+     * MIDI Control channel, integer type.\n
      * Range -1...15 (-1 = off).
      */
     PARAMETER_CTRL_CHANNEL = -8,
@@ -946,7 +945,7 @@ typedef enum {
 typedef enum {
     /*!
      * Single client mode.\n
-     * Inputs and outputs are added as needed by plugins.
+     * Inputs and outputs are added dynamically as needed by plugins.
      */
     ENGINE_PROCESS_MODE_SINGLE_CLIENT = 0,
 
@@ -958,7 +957,7 @@ typedef enum {
 
     /*!
      * Single client, 'rack' mode.\n
-     * Processes plugins in order of Id, with forced stereo.
+     * Processes plugins in order of Id, with forced stereo always on.
      */
     ENGINE_PROCESS_MODE_CONTINUOUS_RACK = 2,
 
@@ -975,7 +974,7 @@ typedef enum {
 } EngineProcessMode;
 
 /*!
- * All the available transport modes
+ * Engine transport mode
  * @see ENGINE_OPTION_TRANSPORT_MODE
  */
 typedef enum {
@@ -985,7 +984,8 @@ typedef enum {
     ENGINE_TRANSPORT_MODE_INTERNAL = 0,
 
     /*!
-     * Transport from JACK, only available if driver name is "JACK".
+     * Transport from JACK.\n
+     * Only available if driver name is "JACK".
      */
     ENGINE_TRANSPORT_MODE_JACK = 1,
 
@@ -1002,40 +1002,12 @@ typedef enum {
 } EngineTransportMode;
 
 /*!
- * Opcodes sent from the backend to the frontend, asking for file related tasks.
- * Front-end MUST always block-wait for user input.
- */
-typedef enum {
-    /*!
-     * Debug.
-     * This opcode is undefined and used only for testing purposes.
-     */
-    FILE_CALLBACK_DEBUG = 0,
-
-    /*!
-     * Open file or folder.
-     */
-    FILE_CALLBACK_OPEN = 1,
-
-    /*!
-     * Save file or folder.
-     */
-    FILE_CALLBACK_SAVE = 2
-
-} FileCallbackOpcode;
-
-/*!
- * Engine callback function.
- * @see EngineCallbackType
+ * Engine callback function.\n
+ * Front-ends must never block indefinitely during a callback.
+ * @see EngineCallbackOpcode, CarlaEngine::setCallback() and carla_set_engine_callback()
  */
 typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, unsigned int pluginId, int value1, int value2, float value3, const char* valueStr);
 
-/*!
- * File callback function.
- * @see FileCallbackType
- */
-typedef const char* (*FileCallbackFunc)(void* ptr, FileCallbackOpcode action, bool isDir, const char* title, const char* filter);
-
 /*!
  * Parameter data.
  */
@@ -1058,12 +1030,12 @@ typedef struct _ParameterData {
     /*!
      *
      */
-    uint8_t  midiChannel;
+    int16_t midiCC;
 
     /*!
      *
      */
-    int16_t  midiCC;
+    uint8_t midiChannel;
 
 #ifdef __cplusplus
     /*!
@@ -1073,8 +1045,8 @@ typedef struct _ParameterData {
         : index(PARAMETER_NULL),
           rindex(-1),
           hints(0x0),
-          midiChannel(0),
-          midiCC(-1) {}
+          midiCC(-1),
+          midiChannel(0) {}
 #endif
 } ParameterData;
 

source/backend/CarlaHost.h

@@ -55,6 +55,36 @@ typedef CarlaBackend::CustomData             CarlaCustomData;
 typedef CarlaBackend::EngineDriverDeviceInfo CarlaEngineDriverDeviceInfo;
 /**@}*/
 
+/*!
+ * File callback opcodes.\n
+ * Front-ends must always block-wait for user input.
+ * @see FileCallbackFunc and carla_set_file_callback()
+ */
+typedef enum {
+    /*!
+     * Debug.
+     * This opcode is undefined and used only for testing purposes.
+     */
+    FILE_CALLBACK_DEBUG = 0,
+
+    /*!
+     * Open file or folder.
+     */
+    FILE_CALLBACK_OPEN = 1,
+
+    /*!
+     * Save file or folder.
+     */
+    FILE_CALLBACK_SAVE = 2
+
+} FileCallbackOpcode;
+
+/*!
+ * File callback function.
+ * @see FileCallbackType
+ */
+typedef const char* (*FileCallbackFunc)(void* ptr, FileCallbackOpcode action, bool isDir, const char* title, const char* filter);
+
 /*!
  * Plugin information.
  * \see carla_get_plugin_info()

source/carla_backend.py

@@ -117,7 +117,7 @@ def structToDict(struct):
     return dict((attr, getattr(struct, attr)) for attr, value in struct._fields_)
 
 # ------------------------------------------------------------------------------------------------------------
-# Carla Backend API
+# Carla Backend API (base definitions)
 
 # Maximum default number of loadable plugins.
 MAX_DEFAULT_PLUGINS = 99
@@ -478,9 +478,9 @@ ENGINE_CALLBACK_MIDI_PROGRAM_CHANGED = 10
 
 # A plugin's custom UI state has changed.
 # @param pluginId Plugin Id
-# @param value1   New state, as follows:\n
-#                  0: UI is now hidden\n
-#                  1: UI is now visible\n
+# @param value1   New state, as follows:
+#                  0: UI is now hidden
+#                  1: UI is now visible
 #                 -1: UI has crashed and should not be shown again
 ENGINE_CALLBACK_UI_STATE_CHANGED = 11
 
@@ -606,90 +606,131 @@ ENGINE_CALLBACK_ERROR = 35
 ENGINE_CALLBACK_QUIT = 36
 
 # ------------------------------------------------------------------------------------------------------------
-# Engine Options Type
-
-ENGINE_OPTION_PROCESS_NAME             = 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_UI_BRIDGES_TIMEOUT       = 8
-ENGINE_OPTION_AUDIO_NUM_PERIODS        = 9
-ENGINE_OPTION_AUDIO_BUFFER_SIZE        = 10
-ENGINE_OPTION_AUDIO_SAMPLE_RATE        = 11
-ENGINE_OPTION_AUDIO_DEVICE             = 12
-ENGINE_OPTION_PATH_RESOURCES           = 13
-ENGINE_OPTION_PATH_BRIDGE_NATIVE       = 14
-ENGINE_OPTION_PATH_BRIDGE_POSIX32      = 15
-ENGINE_OPTION_PATH_BRIDGE_POSIX64      = 16
-ENGINE_OPTION_PATH_BRIDGE_WIN32        = 17
-ENGINE_OPTION_PATH_BRIDGE_WIN64        = 18
-ENGINE_OPTION_PATH_BRIDGE_LV2_EXTERNAL = 19
-ENGINE_OPTION_PATH_BRIDGE_LV2_GTK2     = 20
-ENGINE_OPTION_PATH_BRIDGE_LV2_GTK3     = 21
-ENGINE_OPTION_PATH_BRIDGE_LV2_NTK      = 22
-ENGINE_OPTION_PATH_BRIDGE_LV2_QT4      = 23
-ENGINE_OPTION_PATH_BRIDGE_LV2_QT5      = 24
-ENGINE_OPTION_PATH_BRIDGE_LV2_COCOA    = 25
-ENGINE_OPTION_PATH_BRIDGE_LV2_WINDOWS  = 26
-ENGINE_OPTION_PATH_BRIDGE_LV2_X11      = 27
-ENGINE_OPTION_PATH_BRIDGE_VST_MAC      = 28
-ENGINE_OPTION_PATH_BRIDGE_VST_HWND     = 29
-ENGINE_OPTION_PATH_BRIDGE_VST_X11      = 30
+# Engine Option
 
-# ------------------------------------------------------------------------------------------------------------
-# Process Mode
+# Debug.
+# This option is undefined and used only for testing purposes.
+ENGINE_OPTION_DEBUG = 0
 
-PROCESS_MODE_SINGLE_CLIENT    = 0
-PROCESS_MODE_MULTIPLE_CLIENTS = 1
-PROCESS_MODE_CONTINUOUS_RACK  = 2
-PROCESS_MODE_PATCHBAY         = 3
-PROCESS_MODE_BRIDGE           = 4
+# Set the engine processing mode.
+# Default is ENGINE_PROCESS_MODE_MULTIPLE_CLIENTS on Linux and ENGINE_PROCESS_MODE_CONTINUOUS_RACK for all other OSes.
+# @see EngineProcessMode
+ENGINE_OPTION_PROCESS_MODE = 1
 
-# ------------------------------------------------------------------------------------------------------------
-# Transport Mode
+# Set the engine transport mode.
+# Default is ENGINE_TRANSPORT_MODE_JACK on Linux and ENGINE_TRANSPORT_MODE_INTERNAL for all other OSes.
+# @see EngineTransportMode
+ENGINE_OPTION_TRANSPORT_MODE = 2
+
+# Force mono plugins as stereo, by running 2 instances at the same time.
+# Default is false, but always true when process mode is ENGINE_PROCESS_MODE_CONTINUOUS_RACK.
+# @note Not supported by all plugins
+# @see PLUGIN_OPTION_FORCE_STEREO
+ENGINE_OPTION_FORCE_STEREO = 3
+
+# Use plugin bridges whenever possible.
+# Default is no, EXPERIMENTAL.
+ENGINE_OPTION_PREFER_PLUGIN_BRIDGES = 4
+
+# Use UI bridges whenever possible, otherwise UIs will be directly handled in the main backend thread.
+# Default is yes.
+ENGINE_OPTION_PREFER_UI_BRIDGES = 5
+
+# Make custom plugin UIs always-on-top.
+# Default is yes.
+ENGINE_OPTION_UIS_ALWAYS_ON_TOP = 6
+
+# Maximum number of parameters allowed.
+# Default is MAX_DEFAULT_PARAMETERS.
+ENGINE_OPTION_MAX_PARAMETERS = 7
+
+# Timeout value for how much to wait for UI bridges to respond, in milliseconds.
+# Default is 4000 (4 seconds).
+ENGINE_OPTION_UI_BRIDGES_TIMEOUT = 8
+
+# Audio number of periods.
+# Default is 2.
+ENGINE_OPTION_AUDIO_NUM_PERIODS = 9
+
+# Audio buffer size.
+# Default is 512.
+ENGINE_OPTION_AUDIO_BUFFER_SIZE = 10
+
+# Audio sample rate.
+# Default is 44100.
+ENGINE_OPTION_AUDIO_SAMPLE_RATE = 11
+
+# Audio device (within a driver).
+# Default unset.
+ENGINE_OPTION_AUDIO_DEVICE = 12
 
-TRANSPORT_MODE_INTERNAL = 0
-TRANSPORT_MODE_JACK     = 1
-TRANSPORT_MODE_PLUGIN   = 2
-TRANSPORT_MODE_BRIDGE   = 3
+# Set path to the binary files.
+# Default unset.
+# @note Must be set for plugin and UI bridges to work
+ENGINE_OPTION_PATH_BINARIES = 13
+
+# Set path to the resource files.
+# Default unset.
+# @note Must be set for some internal plugins to work
+ENGINE_OPTION_PATH_RESOURCES = 14
 
 # ------------------------------------------------------------------------------------------------------------
-# File Callback Type
+# Engine Process Mode
 
-FILE_CALLBACK_DEBUG = 0
-FILE_CALLBACK_OPEN  = 1
-FILE_CALLBACK_SAVE  = 2
+# Single client mode.
+# Inputs and outputs are added dynamically as needed by plugins.
+ENGINE_PROCESS_MODE_SINGLE_CLIENT = 0
+
+# Multiple client mode.
+# It has 1 master client + 1 client per plugin.
+ENGINE_PROCESS_MODE_MULTIPLE_CLIENTS = 1
+
+# Single client, 'rack' mode.
+# Processes plugins in order of Id, with forced stereo always on.
+ENGINE_PROCESS_MODE_CONTINUOUS_RACK = 2
+
+# Single client, 'patchbay' mode.
+ENGINE_PROCESS_MODE_PATCHBAY = 3
+
+# Special mode, used in plugin-bridges only.
+ENGINE_PROCESS_MODE_BRIDGE = 4
 
 # ------------------------------------------------------------------------------------------------------------
-# Set BINARY_NATIVE
+# Engine Transport Mode
 
-if HAIKU or LINUX or MACOS:
-    BINARY_NATIVE = BINARY_POSIX64 if kIs64bit else BINARY_POSIX32
-elif WINDOWS:
-    BINARY_NATIVE = BINARY_WIN64 if kIs64bit else BINARY_WIN32
-else:
-    BINARY_NATIVE = BINARY_OTHER
+# Internal transport mode.
+ENGINE_TRANSPORT_MODE_INTERNAL = 0
+
+# Transport from JACK.
+# Only available if driver name is "JACK".
+ENGINE_TRANSPORT_MODE_JACK = 1
+
+# Transport from host, used when Carla is a plugin.
+ENGINE_TRANSPORT_MODE_PLUGIN = 2
+
+# Special mode, used in plugin-bridges only.
+ENGINE_TRANSPORT_MODE_BRIDGE = 3
 
 # ------------------------------------------------------------------------------------------------------------
-# Backend C++ -> Python variables
+# Carla Backend API (C stuff)
 
+# Engine callback function.
+# Front-ends must never block indefinitely during a callback.
+# @see EngineCallbackOpcode and carla_set_engine_callback()
 EngineCallbackFunc = CFUNCTYPE(None, c_void_p, c_enum, c_uint, c_int, c_int, c_float, c_char_p)
-FileCallbackFunc = CFUNCTYPE(c_char_p, c_void_p, c_enum, c_bool, c_char_p, c_char_p)
 
+# Parameter data.
 class ParameterData(Structure):
     _fields_ = [
         ("type", c_enum),
         ("index", c_int32),
         ("rindex", c_int32),
         ("hints", c_uint),
-        ("midiChannel", c_uint8),
-        ("midiCC", c_int16)
+        ("midiCC", c_int16),
+        ("midiChannel", c_uint8)
     ]
 
+# Parameter ranges.
 class ParameterRanges(Structure):
     _fields_ = [
         ("def", c_float),
@@ -700,6 +741,7 @@ class ParameterRanges(Structure):
         ("stepLarge", c_float)
     ]
 
+# MIDI Program data.
 class MidiProgramData(Structure):
     _fields_ = [
         ("bank", c_uint32),
@@ -707,6 +749,7 @@ class MidiProgramData(Structure):
         ("name", c_char_p)
     ]
 
+# Custom data, for saving key:value 'dictionaries'.
 class CustomData(Structure):
     _fields_ = [
         ("type", c_char_p),
@@ -714,6 +757,7 @@ class CustomData(Structure):
         ("value", c_char_p)
     ]
 
+# Engine driver device information.
 class EngineDriverDeviceInfo(Structure):
     _fields_ = [
         ("hints", c_uint),
@@ -721,9 +765,74 @@ class EngineDriverDeviceInfo(Structure):
         ("sampleRates", POINTER(c_double))
     ]
 
+# ------------------------------------------------------------------------------------------------------------
+# Carla Backend API (Python compatible stuff)
+
+# @see ParameterData
+PyParameterData = {
+    'index': PARAMETER_NULL,
+    'rindex': -1,
+    'hints': 0x0,
+    'midiCC': -1,
+    'midiChannel': 0
+}
+
+# @see ParameterRanges
+PyParameterRanges = {
+    'def': 0.0,
+    'min': 0.0,
+    'max': 1.0,
+    'step': 0.01,
+    'stepSmall': 0.0001,
+    'stepLarge': 0.1
+}
+
+# @see MidiProgramData
+PyMidiProgramData = {
+    'bank': 0,
+    'program': 0,
+    'name': None
+}
+
+# @see CustomData
+PyCustomData = {
+    'type': None,
+    'key': None,
+    'value': None
+}
+
+# @see EngineDriverDeviceInfo
+PyEngineDriverDeviceInfo = {
+    'hints': 0x0,
+    'bufferSizes': [],
+    'sampleRates': []
+}
+
+# ------------------------------------------------------------------------------------------------------------
+# Set BINARY_NATIVE
+
+if HAIKU or LINUX or MACOS:
+    BINARY_NATIVE = BINARY_POSIX64 if kIs64bit else BINARY_POSIX32
+elif WINDOWS:
+    BINARY_NATIVE = BINARY_WIN64 if kIs64bit else BINARY_WIN32
+else:
+    BINARY_NATIVE = BINARY_OTHER
+
+# ------------------------------------------------------------------------------------------------------------
+# Backend C++ -> Python variables
+
+FileCallbackFunc = CFUNCTYPE(c_char_p, c_void_p, c_enum, c_bool, c_char_p, c_char_p)
+
 # ------------------------------------------------------------------------------------------------------------
 # Host C++ -> Python variables
 
+# ------------------------------------------------------------------------------------------------------------
+# File Callback Type
+
+FILE_CALLBACK_DEBUG = 0
+FILE_CALLBACK_OPEN  = 1
+FILE_CALLBACK_SAVE  = 2
+
 class CarlaPluginInfo(Structure):
     _fields_ = [
         ("type", c_enum),
@@ -791,36 +900,6 @@ class CarlaTransportInfo(Structure):
 # ------------------------------------------------------------------------------------------------------------
 # Python object dicts compatible with ctypes struct
 
-PyParameterData = {
-    'type': PARAMETER_NULL,
-    'index': PARAMETER_NULL,
-    'rindex': -1,
-    'hints': 0x0,
-    'midiChannel': 0,
-    'midiCC': -1
-}
-
-PyParameterRanges = {
-    'def': 0.0,
-    'min': 0.0,
-    'max': 1.0,
-    'step': 0.01,
-    'stepSmall': 0.0001,
-    'stepLarge': 0.1
-}
-
-PyMidiProgramData = {
-    'bank': 0,
-    'program': 0,
-    'name': None
-}
-
-PyCustomData = {
-    'type': None,
-    'key': None,
-    'value': None
-}
-
 PyCarlaPluginInfo = {
     'type': PLUGIN_NONE,
     'category': PLUGIN_CATEGORY_NONE,