falkTX
/
Carla
mirror of https://github.com/falkTX/Carla
1
0
Fork 0
Code Releases 43 Activity
Browse Source

Update code docs

tags/1.9.4
falkTX 12 years ago
parent
09c7167c0d
commit
e3a11a11bf
4 changed files with 134 additions and 35 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +14
    -0
      doc/Carla-TODO
  2. +54
    -3
      source/backend/CarlaBackend.h
  3. +20
    -5
      source/backend/CarlaHost.h
  4. +46
    -27
      source/carla_backend.py

+ 14
- 0
doc/Carla-TODO View File

@@ -91,3 +91,17 @@ LinuxSampler:
- multi-program - multi-program
- 16outs (depends on multi-program) - 16outs (depends on multi-program)
- proper buffer-size/sample-rate change - proper buffer-size/sample-rate change

# ----------------------------------------------------------------------------
# current work

BACKEND:
- cleanup API, document everything properly (tested with doxygen)
- apply API docs to python code as well (TODO: use proper predefined pydoc style)

FRONTEND:
- fix things to new cleanup API
- share code as much as possible

OTHER:
- create tests for all utils code

+ 54
- 3
source/backend/CarlaBackend.h View File

@@ -45,6 +45,9 @@ CARLA_BACKEND_START_NAMESPACE
* @{ * @{
*/ */


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

/*! /*!
* Maximum default number of loadable plugins. * Maximum default number of loadable plugins.
*/ */
@@ -66,6 +69,9 @@ const unsigned int MAX_PATCHBAY_PLUGINS = 255;
*/ */
const unsigned int MAX_DEFAULT_PARAMETERS = 200; const unsigned int MAX_DEFAULT_PARAMETERS = 200;


// ------------------------------------------------------------------------------------------------------------
// Engine Driver Device Hints

/*! /*!
* @defgroup EngineDriverHints Engine Driver Device Hints * @defgroup EngineDriverHints Engine Driver Device Hints
* *
@@ -93,6 +99,9 @@ const unsigned int ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x4;


/** @} */ /** @} */


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

/*! /*!
* @defgroup PluginHints Plugin Hints * @defgroup PluginHints Plugin Hints
* *
@@ -145,11 +154,14 @@ const unsigned int PLUGIN_CAN_PANNING = 0x80;


/** @} */ /** @} */


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

/*! /*!
* @defgroup PluginOptions Plugin Options * @defgroup PluginOptions Plugin Options
* *
* Various plugin options. * Various plugin options.
* @see CarlaPlugin::getOptionsAvailable(), CarlaPlugin::getOptionsEnabled() and carla_get_plugin_info()
* @see CarlaPlugin::getOptionsAvailable(), CarlaPlugin::getOptionsEnabled(), carla_get_plugin_info() and carla_set_option()
* @{ * @{
*/ */


@@ -200,6 +212,9 @@ const unsigned int PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100;


/** @} */ /** @} */


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

/*! /*!
* @defgroup ParameterHints Parameter Hints * @defgroup ParameterHints Parameter Hints
* *
@@ -266,6 +281,9 @@ const unsigned int PARAMETER_USES_CUSTOM_TEXT = 0x400;


/** @} */ /** @} */


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

/*! /*!
* @defgroup PatchbayPortHints Patchbay Port Hints * @defgroup PatchbayPortHints Patchbay Port Hints
* *
@@ -296,6 +314,9 @@ const unsigned int PATCHBAY_PORT_TYPE_MIDI = 0x8;


/** @} */ /** @} */


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

/*! /*!
* @defgroup CustomDataTypes Custom Data Types * @defgroup CustomDataTypes Custom Data Types
* *
@@ -322,6 +343,9 @@ const char* const CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/str


/** @} */ /** @} */


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

/*! /*!
* @defgroup CustomDataKeys Custom Data Keys * @defgroup CustomDataKeys Custom Data Keys
* *
@@ -352,6 +376,9 @@ const char* const CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible";


/** @} */ /** @} */


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

/*! /*!
* The binary type of a plugin. * The binary type of a plugin.
*/ */
@@ -388,6 +415,9 @@ typedef enum {


} BinaryType; } BinaryType;


// ------------------------------------------------------------------------------------------------------------
// Plugin Type

/*! /*!
* Plugin type. * Plugin type.
* Some files are handled as if they were plugins. * Some files are handled as if they were plugins.
@@ -451,6 +481,9 @@ typedef enum {


} PluginType; } PluginType;


// ------------------------------------------------------------------------------------------------------------
// Plugin Category

/*! /*!
* Plugin category, which describes the functionality of a plugin. * Plugin category, which describes the functionality of a plugin.
*/ */
@@ -507,6 +540,9 @@ typedef enum {


} PluginCategory; } PluginCategory;


// ------------------------------------------------------------------------------------------------------------
// Internal Parameter Index

/*! /*!
* Special parameters used internally in Carla.\n * Special parameters used internally in Carla.\n
* Plugins do not know about their existence. * Plugins do not know about their existence.
@@ -566,6 +602,9 @@ typedef enum {


} InternalParameterIndex; } InternalParameterIndex;


// ------------------------------------------------------------------------------------------------------------
// Engine Callback Opcode

/*! /*!
* Engine callback opcodes.\n * Engine callback opcodes.\n
* Front-ends must never block indefinitely during a callback. * Front-ends must never block indefinitely during a callback.
@@ -835,6 +874,9 @@ typedef enum {


} EngineCallbackOpcode; } EngineCallbackOpcode;


// ------------------------------------------------------------------------------------------------------------
// Engine Option

/*! /*!
* Engine options. * Engine options.
* @see CarlaEngine::getOptions(), CarlaEngine::setOption() and carla_set_engine_option() * @see CarlaEngine::getOptions(), CarlaEngine::setOption() and carla_set_engine_option()
@@ -938,6 +980,9 @@ typedef enum {


} EngineOption; } EngineOption;


// ------------------------------------------------------------------------------------------------------------
// Engine Process Mode

/*! /*!
* Engine process mode. * Engine process mode.
* @see ENGINE_OPTION_PROCESS_MODE * @see ENGINE_OPTION_PROCESS_MODE
@@ -973,8 +1018,11 @@ typedef enum {


} EngineProcessMode; } EngineProcessMode;


// ------------------------------------------------------------------------------------------------------------
// Engine Transport Mode

/*! /*!
* Engine transport mode
* Engine transport mode.
* @see ENGINE_OPTION_TRANSPORT_MODE * @see ENGINE_OPTION_TRANSPORT_MODE
*/ */
typedef enum { typedef enum {
@@ -1001,12 +1049,15 @@ typedef enum {


} EngineTransportMode; } EngineTransportMode;


// ------------------------------------------------------------------------------------------------------------
// Carla Backend API (C stuff)

/*! /*!
* Engine callback function.\n * Engine callback function.\n
* Front-ends must never block indefinitely during a callback. * Front-ends must never block indefinitely during a callback.
* @see EngineCallbackOpcode, CarlaEngine::setCallback() and carla_set_engine_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);
typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, uint pluginId, int value1, int value2, float value3, const char* valueStr);


/*! /*!
* Parameter data. * Parameter data.


+ 20
- 5
source/backend/CarlaHost.h View File

@@ -51,6 +51,9 @@ using CarlaBackend::CarlaPlugin;
* @{ * @{
*/ */


// ------------------------------------------------------------------------------------------------------------
// File Callback Opcode

/*! /*!
* File callback opcodes.\n * File callback opcodes.\n
* Front-ends must always block-wait for user input. * Front-ends must always block-wait for user input.
@@ -75,6 +78,9 @@ typedef enum {


} FileCallbackOpcode; } FileCallbackOpcode;


// ------------------------------------------------------------------------------------------------------------
// Carla Host API (C stuff)

/*! /*!
* File callback function. * File callback function.
* @see FileCallbackOpcode * @see FileCallbackOpcode
@@ -463,6 +469,9 @@ typedef struct _CarlaTransportInfo {
#endif #endif
} CarlaTransportInfo; } CarlaTransportInfo;


// ------------------------------------------------------------------------------------------------------------
// Carla Host API (C functions)

/*! /*!
* Get the complete license text of used third-party code and features.\n * Get the complete license text of used third-party code and features.\n
* Returned string is in basic html format. * Returned string is in basic html format.
@@ -515,10 +524,10 @@ CARLA_EXPORT const CarlaNativePluginInfo* carla_get_internal_plugin_info(unsigne


#ifdef __cplusplus #ifdef __cplusplus
/*! /*!
* Get the currently used Host engine.
* Get the currently used engine, maybe be NULL.
* @note C++ only * @note C++ only
*/ */
CARLA_EXPORT CarlaEngine* carla_get_host_engine();
CARLA_EXPORT const CarlaEngine* carla_get_engine();
#endif #endif


/*! /*!
@@ -610,12 +619,17 @@ CARLA_EXPORT bool carla_load_project(const char* filename);
CARLA_EXPORT bool carla_save_project(const char* filename); CARLA_EXPORT bool carla_save_project(const char* filename);


/*! /*!
* Connect patchbay ports \a portA and \a portB.
* Connect two patchbay ports.
* @param portA Output port
* @param portB Input port
* @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED
*/ */
CARLA_EXPORT bool carla_patchbay_connect(int portA, int portB); CARLA_EXPORT bool carla_patchbay_connect(int portA, int portB);


/*! /*!
* Disconnect patchbay connection \a connectionId.
* Disconnect two patchbay ports.
* @param connectionId Connection Id
* @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED
*/ */
CARLA_EXPORT bool carla_patchbay_disconnect(int connectionId); CARLA_EXPORT bool carla_patchbay_disconnect(int connectionId);


@@ -635,7 +649,8 @@ CARLA_EXPORT void carla_transport_play();
CARLA_EXPORT void carla_transport_pause(); CARLA_EXPORT void carla_transport_pause();


/*! /*!
* Relocate the engine transport to \a frames.
* Relocate the engine transport to a specific frame.
* @param frames Frame to relocate to.
*/ */
CARLA_EXPORT void carla_transport_relocate(uint32_t frames); CARLA_EXPORT void carla_transport_relocate(uint32_t frames);




+ 46
- 27
source/carla_backend.py View File

@@ -134,6 +134,8 @@ MAX_DEFAULT_PARAMETERS = 200


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Engine Driver Device Hints # Engine Driver Device Hints
# Various engine driver device hints.
# @see carla_get_engine_driver_device_info()


# Engine driver device has custom control-panel. # Engine driver device has custom control-panel.
ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL = 0x1 ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL = 0x1
@@ -148,6 +150,8 @@ ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x4


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Plugin Hints # Plugin Hints
# Various plugin hints.
# @see carla_get_plugin_info()


# Plugin is a bridge. # Plugin is a bridge.
# This hint is required because "bridge" itself is not a plugin type. # This hint is required because "bridge" itself is not a plugin type.
@@ -177,6 +181,8 @@ PLUGIN_CAN_PANNING = 0x80


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Plugin Options # Plugin Options
# Various plugin options.
# @see carla_get_plugin_info() and carla_set_option()


# Use constant/fixed-size audio buffers. # Use constant/fixed-size audio buffers.
PLUGIN_OPTION_FIXED_BUFFERS = 0x001 PLUGIN_OPTION_FIXED_BUFFERS = 0x001
@@ -207,6 +213,8 @@ PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Parameter Hints # Parameter Hints
# Various parameter hints.
# @see CarlaPlugin::getParameterData() and carla_get_parameter_data()


# Parameter is input. # Parameter is input.
# When this hint is not set, parameter is assumed to be output. # When this hint is not set, parameter is assumed to be output.
@@ -245,6 +253,7 @@ PARAMETER_USES_CUSTOM_TEXT = 0x400


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Patchbay Port Hints # Patchbay Port Hints
# Various patchbay port hints.


# Patchbay port is input. # Patchbay port is input.
# When this hint is not set, port is assumed to be output. # When this hint is not set, port is assumed to be output.
@@ -261,6 +270,8 @@ PATCHBAY_PORT_TYPE_MIDI = 0x8


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Custom Data Types # Custom Data Types
# These types define how the value in the CustomData struct is stored.
# @see CustomData.type


# Boolean string type URI. # Boolean string type URI.
# Only "true" and "false" are valid values. # Only "true" and "false" are valid values.
@@ -274,6 +285,8 @@ CUSTOM_DATA_TYPE_STRING = "http://kxstudio.sf.net/ns/carla/string"


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Custom Data Keys # Custom Data Keys
# Pre-defined keys used internally in Carla.
# @see CustomData.key


# Plugin options key. # Plugin options key.
CUSTOM_DATA_KEY_PLUGIN_OPTIONS = "CarlaPluginOptions" CUSTOM_DATA_KEY_PLUGIN_OPTIONS = "CarlaPluginOptions"
@@ -289,6 +302,7 @@ CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible"


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Binary Type # Binary Type
# The binary type of a plugin.


# Null binary type. # Null binary type.
BINARY_NONE = 0 BINARY_NONE = 0
@@ -310,6 +324,8 @@ BINARY_OTHER = 5


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Plugin Type # Plugin Type
# Plugin type.
# Some files are handled as if they were plugins.


# Null plugin type. # Null plugin type.
PLUGIN_NONE = 0 PLUGIN_NONE = 0
@@ -347,6 +363,7 @@ PLUGIN_SFZ = 10


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Plugin Category # Plugin Category
# Plugin category, which describes the functionality of a plugin.


# Null plugin category. # Null plugin category.
PLUGIN_CATEGORY_NONE = 0 PLUGIN_CATEGORY_NONE = 0
@@ -379,7 +396,9 @@ PLUGIN_CATEGORY_UTILITY = 8
PLUGIN_CATEGORY_OTHER = 9 PLUGIN_CATEGORY_OTHER = 9


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Internal Parameters Index
# Internal Parameter Index
# Special parameters used internally in Carla.
# Plugins do not know about their existence.


# Null parameter. # Null parameter.
PARAMETER_NULL = -1 PARAMETER_NULL = -1
@@ -417,6 +436,9 @@ PARAMETER_MAX = -9


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Engine Callback Opcode # Engine Callback Opcode
# Engine callback opcodes.
# Front-ends must never block indefinitely during a callback.
# @see EngineCallbackFunc and carla_set_engine_callback()


# Debug. # Debug.
# This opcode is undefined and used only for testing purposes. # This opcode is undefined and used only for testing purposes.
@@ -607,6 +629,8 @@ ENGINE_CALLBACK_QUIT = 36


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Engine Option # Engine Option
# Engine options.
# @see carla_set_engine_option()


# Debug. # Debug.
# This option is undefined and used only for testing purposes. # This option is undefined and used only for testing purposes.
@@ -676,6 +700,8 @@ ENGINE_OPTION_PATH_RESOURCES = 14


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Engine Process Mode # Engine Process Mode
# Engine process mode.
# @see ENGINE_OPTION_PROCESS_MODE


# Single client mode. # Single client mode.
# Inputs and outputs are added dynamically as needed by plugins. # Inputs and outputs are added dynamically as needed by plugins.
@@ -697,6 +723,8 @@ ENGINE_PROCESS_MODE_BRIDGE = 4


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# Engine Transport Mode # Engine Transport Mode
# Engine transport mode.
# @see ENGINE_OPTION_TRANSPORT_MODE


# Internal transport mode. # Internal transport mode.
ENGINE_TRANSPORT_MODE_INTERNAL = 0 ENGINE_TRANSPORT_MODE_INTERNAL = 0
@@ -853,6 +881,9 @@ PyEngineDriverDeviceInfo = {


# ------------------------------------------------------------------------------------------------------------ # ------------------------------------------------------------------------------------------------------------
# File Callback Opcode # File Callback Opcode
# File callback opcodes.
# Front-ends must always block-wait for user input.
# @see FileCallbackFunc and carla_set_file_callback()


# Debug. # Debug.
# This opcode is undefined and used only for testing purposes. # This opcode is undefined and used only for testing purposes.
@@ -1208,27 +1239,41 @@ class Host(object):
def save_project(self, filename): def save_project(self, filename):
return bool(self.lib.carla_save_project(filename.encode("utf-8"))) return bool(self.lib.carla_save_project(filename.encode("utf-8")))


# Connect two patchbay ports.
# @param portA Output port
# @param portB Input port
# @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED
def patchbay_connect(self, portIdA, portIdB): def patchbay_connect(self, portIdA, portIdB):
return bool(self.lib.carla_patchbay_connect(portIdA, portIdB)) return bool(self.lib.carla_patchbay_connect(portIdA, portIdB))


# Disconnect two patchbay ports.
# @param connectionId Connection Id
# @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED
def patchbay_disconnect(self, connectionId): def patchbay_disconnect(self, connectionId):
return bool(self.lib.carla_patchbay_disconnect(connectionId)) return bool(self.lib.carla_patchbay_disconnect(connectionId))


# Force the engine to resend all patchbay clients, ports and connections again.
def patchbay_refresh(self): def patchbay_refresh(self):
return bool(self.lib.carla_patchbay_refresh()) return bool(self.lib.carla_patchbay_refresh())


# Start playback of the engine transport.
def transport_play(self): def transport_play(self):
self.lib.carla_transport_play() self.lib.carla_transport_play()


# Pause the engine transport.
def transport_pause(self): def transport_pause(self):
self.lib.carla_transport_pause() self.lib.carla_transport_pause()


# Relocate the engine transport to a specific frame.
# @param frames Frame to relocate to.
def transport_relocate(self, frames): def transport_relocate(self, frames):
self.lib.carla_transport_relocate(frames) self.lib.carla_transport_relocate(frames)


# Get the current transport frame.
def get_current_transport_frame(self): def get_current_transport_frame(self):
return bool(self.lib.carla_get_current_transport_frame()) return bool(self.lib.carla_get_current_transport_frame())


# Get the engine transport information.
def get_transport_info(self): def get_transport_info(self):
return structToDict(self.lib.carla_get_transport_info().contents) return structToDict(self.lib.carla_get_transport_info().contents)


@@ -1406,18 +1451,6 @@ class Host(object):
def get_sample_rate(self): def get_sample_rate(self):
return self.lib.carla_get_sample_rate() return self.lib.carla_get_sample_rate()


def nsm_announce(self, url, appName_, pid):
self.lib.carla_nsm_announce(url.encode("utf-8"), appName_.encode("utf-8"), pid)

def nsm_ready(self):
self.lib.carla_nsm_ready()

def nsm_reply_open(self):
self.lib.carla_nsm_reply_open()

def nsm_reply_save(self):
self.lib.carla_nsm_reply_save()

def _init(self, libName): def _init(self, libName):
self.lib = cdll.LoadLibrary(libName) self.lib = cdll.LoadLibrary(libName)


@@ -1669,17 +1702,3 @@ class Host(object):


self.lib.carla_get_host_osc_url_udp.argtypes = None self.lib.carla_get_host_osc_url_udp.argtypes = None
self.lib.carla_get_host_osc_url_udp.restype = c_char_p self.lib.carla_get_host_osc_url_udp.restype = c_char_p

return

self.lib.carla_nsm_announce.argtypes = [c_char_p, c_char_p, c_int]
self.lib.carla_nsm_announce.restype = None

self.lib.carla_nsm_ready.argtypes = None
self.lib.carla_nsm_ready.restype = None

self.lib.carla_nsm_reply_open.argtypes = None
self.lib.carla_nsm_reply_open.restype = None

self.lib.carla_nsm_reply_save.argtypes = None
self.lib.carla_nsm_reply_save.restype = None

Write Preview
Loading…
Cancel
Save