From e3a11a11bf51b8ec5d8f523457c118f1386d9ab0 Mon Sep 17 00:00:00 2001 From: falkTX Date: Thu, 19 Dec 2013 19:48:13 +0000 Subject: [PATCH] Update code docs --- doc/Carla-TODO | 14 +++++++ source/backend/CarlaBackend.h | 57 +++++++++++++++++++++++++-- source/backend/CarlaHost.h | 25 +++++++++--- source/carla_backend.py | 73 ++++++++++++++++++++++------------- 4 files changed, 134 insertions(+), 35 deletions(-) diff --git a/doc/Carla-TODO b/doc/Carla-TODO index d9ecb8556..87a2b8aaa 100644 --- a/doc/Carla-TODO +++ b/doc/Carla-TODO @@ -91,3 +91,17 @@ LinuxSampler: - multi-program - 16outs (depends on multi-program) - 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 diff --git a/source/backend/CarlaBackend.h b/source/backend/CarlaBackend.h index 8da986c55..82effa129 100644 --- a/source/backend/CarlaBackend.h +++ b/source/backend/CarlaBackend.h @@ -45,6 +45,9 @@ CARLA_BACKEND_START_NAMESPACE * @{ */ +// ------------------------------------------------------------------------------------------------------------ +// Carla Backend API (base definitions) + /*! * Maximum default number of loadable plugins. */ @@ -66,6 +69,9 @@ const unsigned int MAX_PATCHBAY_PLUGINS = 255; */ const unsigned int MAX_DEFAULT_PARAMETERS = 200; +// ------------------------------------------------------------------------------------------------------------ +// 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 * @@ -145,11 +154,14 @@ const unsigned int PLUGIN_CAN_PANNING = 0x80; /** @} */ +// ------------------------------------------------------------------------------------------------------------ +// Plugin Options + /*! * @defgroup PluginOptions 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 * @@ -266,6 +281,9 @@ const unsigned int PARAMETER_USES_CUSTOM_TEXT = 0x400; /** @} */ +// ------------------------------------------------------------------------------------------------------------ +// 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 * @@ -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 * @@ -352,6 +376,9 @@ const char* const CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible"; /** @} */ +// ------------------------------------------------------------------------------------------------------------ +// Binary Type + /*! * The binary type of a plugin. */ @@ -388,6 +415,9 @@ typedef enum { } BinaryType; +// ------------------------------------------------------------------------------------------------------------ +// Plugin Type + /*! * Plugin type. * Some files are handled as if they were plugins. @@ -451,6 +481,9 @@ typedef enum { } PluginType; +// ------------------------------------------------------------------------------------------------------------ +// Plugin Category + /*! * Plugin category, which describes the functionality of a plugin. */ @@ -507,6 +540,9 @@ typedef enum { } PluginCategory; +// ------------------------------------------------------------------------------------------------------------ +// Internal Parameter Index + /*! * Special parameters used internally in Carla.\n * Plugins do not know about their existence. @@ -566,6 +602,9 @@ typedef enum { } InternalParameterIndex; +// ------------------------------------------------------------------------------------------------------------ +// Engine Callback Opcode + /*! * Engine callback opcodes.\n * Front-ends must never block indefinitely during a callback. @@ -835,6 +874,9 @@ typedef enum { } EngineCallbackOpcode; +// ------------------------------------------------------------------------------------------------------------ +// Engine Option + /*! * Engine options. * @see CarlaEngine::getOptions(), CarlaEngine::setOption() and carla_set_engine_option() @@ -938,6 +980,9 @@ typedef enum { } EngineOption; +// ------------------------------------------------------------------------------------------------------------ +// Engine Process Mode + /*! * Engine process mode. * @see ENGINE_OPTION_PROCESS_MODE @@ -973,8 +1018,11 @@ typedef enum { } EngineProcessMode; +// ------------------------------------------------------------------------------------------------------------ +// Engine Transport Mode + /*! - * Engine transport mode + * Engine transport mode. * @see ENGINE_OPTION_TRANSPORT_MODE */ typedef enum { @@ -1001,12 +1049,15 @@ typedef enum { } EngineTransportMode; +// ------------------------------------------------------------------------------------------------------------ +// Carla Backend API (C stuff) + /*! * 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); +typedef void (*EngineCallbackFunc)(void* ptr, EngineCallbackOpcode action, uint pluginId, int value1, int value2, float value3, const char* valueStr); /*! * Parameter data. diff --git a/source/backend/CarlaHost.h b/source/backend/CarlaHost.h index eaa1b11e2..03fcfa8c4 100644 --- a/source/backend/CarlaHost.h +++ b/source/backend/CarlaHost.h @@ -51,6 +51,9 @@ using CarlaBackend::CarlaPlugin; * @{ */ +// ------------------------------------------------------------------------------------------------------------ +// File Callback Opcode + /*! * File callback opcodes.\n * Front-ends must always block-wait for user input. @@ -75,6 +78,9 @@ typedef enum { } FileCallbackOpcode; +// ------------------------------------------------------------------------------------------------------------ +// Carla Host API (C stuff) + /*! * File callback function. * @see FileCallbackOpcode @@ -463,6 +469,9 @@ typedef struct _CarlaTransportInfo { #endif } CarlaTransportInfo; +// ------------------------------------------------------------------------------------------------------------ +// Carla Host API (C functions) + /*! * Get the complete license text of used third-party code and features.\n * Returned string is in basic html format. @@ -515,10 +524,10 @@ CARLA_EXPORT const CarlaNativePluginInfo* carla_get_internal_plugin_info(unsigne #ifdef __cplusplus /*! - * Get the currently used Host engine. + * Get the currently used engine, maybe be NULL. * @note C++ only */ -CARLA_EXPORT CarlaEngine* carla_get_host_engine(); +CARLA_EXPORT const CarlaEngine* carla_get_engine(); #endif /*! @@ -610,12 +619,17 @@ CARLA_EXPORT bool carla_load_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); /*! - * 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); @@ -635,7 +649,8 @@ CARLA_EXPORT void carla_transport_play(); 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); diff --git a/source/carla_backend.py b/source/carla_backend.py index b61457edd..dfcdaa8e9 100644 --- a/source/carla_backend.py +++ b/source/carla_backend.py @@ -134,6 +134,8 @@ MAX_DEFAULT_PARAMETERS = 200 # ------------------------------------------------------------------------------------------------------------ # 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_CONTROL_PANEL = 0x1 @@ -148,6 +150,8 @@ ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE = 0x4 # ------------------------------------------------------------------------------------------------------------ # Plugin Hints +# Various plugin hints. +# @see carla_get_plugin_info() # Plugin is a bridge. # This hint is required because "bridge" itself is not a plugin type. @@ -177,6 +181,8 @@ PLUGIN_CAN_PANNING = 0x80 # ------------------------------------------------------------------------------------------------------------ # Plugin Options +# Various plugin options. +# @see carla_get_plugin_info() and carla_set_option() # Use constant/fixed-size audio buffers. PLUGIN_OPTION_FIXED_BUFFERS = 0x001 @@ -207,6 +213,8 @@ PLUGIN_OPTION_SEND_ALL_SOUND_OFF = 0x100 # ------------------------------------------------------------------------------------------------------------ # Parameter Hints +# Various parameter hints. +# @see CarlaPlugin::getParameterData() and carla_get_parameter_data() # Parameter is input. # When this hint is not set, parameter is assumed to be output. @@ -245,6 +253,7 @@ PARAMETER_USES_CUSTOM_TEXT = 0x400 # ------------------------------------------------------------------------------------------------------------ # Patchbay Port Hints +# Various patchbay port hints. # Patchbay port is input. # When this hint is not set, port is assumed to be output. @@ -261,6 +270,8 @@ PATCHBAY_PORT_TYPE_MIDI = 0x8 # ------------------------------------------------------------------------------------------------------------ # Custom Data Types +# These types define how the value in the CustomData struct is stored. +# @see CustomData.type # Boolean string type URI. # 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 +# Pre-defined keys used internally in Carla. +# @see CustomData.key # Plugin options key. CUSTOM_DATA_KEY_PLUGIN_OPTIONS = "CarlaPluginOptions" @@ -289,6 +302,7 @@ CUSTOM_DATA_KEY_UI_VISIBLE = "CarlaUiVisible" # ------------------------------------------------------------------------------------------------------------ # Binary Type +# The binary type of a plugin. # Null binary type. BINARY_NONE = 0 @@ -310,6 +324,8 @@ BINARY_OTHER = 5 # ------------------------------------------------------------------------------------------------------------ # Plugin Type +# Plugin type. +# Some files are handled as if they were plugins. # Null plugin type. PLUGIN_NONE = 0 @@ -347,6 +363,7 @@ PLUGIN_SFZ = 10 # ------------------------------------------------------------------------------------------------------------ # Plugin Category +# Plugin category, which describes the functionality of a plugin. # Null plugin category. PLUGIN_CATEGORY_NONE = 0 @@ -379,7 +396,9 @@ PLUGIN_CATEGORY_UTILITY = 8 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. PARAMETER_NULL = -1 @@ -417,6 +436,9 @@ PARAMETER_MAX = -9 # ------------------------------------------------------------------------------------------------------------ # Engine Callback Opcode +# Engine callback opcodes. +# Front-ends must never block indefinitely during a callback. +# @see EngineCallbackFunc and carla_set_engine_callback() # Debug. # This opcode is undefined and used only for testing purposes. @@ -607,6 +629,8 @@ ENGINE_CALLBACK_QUIT = 36 # ------------------------------------------------------------------------------------------------------------ # Engine Option +# Engine options. +# @see carla_set_engine_option() # Debug. # 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. +# @see ENGINE_OPTION_PROCESS_MODE # Single client mode. # 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. +# @see ENGINE_OPTION_TRANSPORT_MODE # Internal transport mode. ENGINE_TRANSPORT_MODE_INTERNAL = 0 @@ -853,6 +881,9 @@ PyEngineDriverDeviceInfo = { # ------------------------------------------------------------------------------------------------------------ # File Callback Opcode +# File callback opcodes. +# Front-ends must always block-wait for user input. +# @see FileCallbackFunc and carla_set_file_callback() # Debug. # This opcode is undefined and used only for testing purposes. @@ -1208,27 +1239,41 @@ class Host(object): def save_project(self, filename): 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): 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): return bool(self.lib.carla_patchbay_disconnect(connectionId)) + # Force the engine to resend all patchbay clients, ports and connections again. def patchbay_refresh(self): return bool(self.lib.carla_patchbay_refresh()) + # Start playback of the engine transport. def transport_play(self): self.lib.carla_transport_play() + # Pause the engine transport. def transport_pause(self): self.lib.carla_transport_pause() + # Relocate the engine transport to a specific frame. + # @param frames Frame to relocate to. def transport_relocate(self, frames): self.lib.carla_transport_relocate(frames) + # Get the current transport frame. def get_current_transport_frame(self): return bool(self.lib.carla_get_current_transport_frame()) + # Get the engine transport information. def get_transport_info(self): return structToDict(self.lib.carla_get_transport_info().contents) @@ -1406,18 +1451,6 @@ class Host(object): def get_sample_rate(self): 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): 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.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