From d30decb66a6f8c5b0fff0e09747791e96e621757 Mon Sep 17 00:00:00 2001 From: falkTX Date: Thu, 12 Sep 2013 17:32:24 +0100 Subject: [PATCH] Update native API, incomplete --- source/modules/CarlaNative.h | 145 +++++++++++++++++++++++------------ 1 file changed, 94 insertions(+), 51 deletions(-) diff --git a/source/modules/CarlaNative.h b/source/modules/CarlaNative.h index f11d926a2..8983b1cd9 100644 --- a/source/modules/CarlaNative.h +++ b/source/modules/CarlaNative.h @@ -33,56 +33,88 @@ extern "C" { * @{ */ +typedef int32_t AtomXYZ; typedef void* HostHandle; typedef void* PluginHandle; // ----------------------------------------------------------------------- // enums -typedef enum { - PLUGIN_CATEGORY_NONE = 0, //!< Null plugin category. - PLUGIN_CATEGORY_SYNTH = 1, //!< A synthesizer or generator. - PLUGIN_CATEGORY_DELAY = 2, //!< A delay or reverberator. - PLUGIN_CATEGORY_EQ = 3, //!< An equalizer. - PLUGIN_CATEGORY_FILTER = 4, //!< A filter. - PLUGIN_CATEGORY_DYNAMICS = 5, //!< A 'dynamic' plugin (amplifier, compressor, gate, etc). - PLUGIN_CATEGORY_MODULATOR = 6, //!< A 'modulator' plugin (chorus, flanger, phaser, etc). - PLUGIN_CATEGORY_UTILITY = 7, //!< An 'utility' plugin (analyzer, converter, mixer, etc). - PLUGIN_CATEGORY_OTHER = 8 //!< Misc plugin (used to check if the plugin has a category). -} PluginCategory; +#define PLUGIN_API_VERSION 1 -typedef enum { - PLUGIN_IS_RTSAFE = 1 << 0, - PLUGIN_HAS_GUI = 1 << 1, - PLUGIN_NEEDS_OPENSAVE = 1 << 2, - PLUGIN_NEEDS_SINGLE_THREAD = 1 << 3, - PLUGIN_NEEDS_FIXED_BUFFERS = 1 << 4, - PLUGIN_USES_PANNING = 1 << 5, // uses stereo balance if unset (default) - PLUGIN_USES_STATE = 1 << 6, - PLUGIN_USES_TIMEPOS = 1 << 7 -} PluginHints; +/*! + * @defgroup PluginCategories Plugin Categories + * + * A small list of pre-defined plugin categories. + * + * Plugins can use their own custom categories as well, as long as they are lowercase and contain ASCII characters only. + * Many categories can be set by using ":" in between them. + * @{ + */ +#define PLUGIN_CATEGORY_SYNTH "synth" //!< A synthesizer or generator. +#define PLUGIN_CATEGORY_DELAY "delay" //!< A delay or reverberator. +#define PLUGIN_CATEGORY_EQ "eq" //!< An equalizer. +#define PLUGIN_CATEGORY_FILTER "filter" //!< A filter. +#define PLUGIN_CATEGORY_DYNAMICS "dynamics" //!< A 'dynamic' plugin (amplifier, compressor, gate, etc). +#define PLUGIN_CATEGORY_MODULATOR "modulator" //!< A 'modulator' plugin (chorus, flanger, phaser, etc). +#define PLUGIN_CATEGORY_UTILITY "utility" //!< An 'utility' plugin (analyzer, converter, mixer, etc). +#define PLUGIN_CATEGORY_OTHER "other" //!< Misc plugin (used to check if the plugin has a category). +/**@}*/ -typedef enum { - PLUGIN_SUPPORTS_PROGRAM_CHANGES = 1 << 0, // handles MIDI programs internally instead of host-exposed/exported - PLUGIN_SUPPORTS_CONTROL_CHANGES = 1 << 1, - PLUGIN_SUPPORTS_CHANNEL_PRESSURE = 1 << 2, - PLUGIN_SUPPORTS_NOTE_AFTERTOUCH = 1 << 3, - PLUGIN_SUPPORTS_PITCHBEND = 1 << 4, - PLUGIN_SUPPORTS_ALL_SOUND_OFF = 1 << 5, - PLUGIN_SUPPORTS_EVERYTHING = (1 << 6)-1 -} PluginSupports; +/*! + * @defgroup PluginFeatures Plugin Features + * + * A list of plugin features or hints. + * + * Custom features are allowed, as long as they are lowercase and contain ASCII characters only. + * The host can decide if it can load the plugin or not based on this information. + * + * Multiple features can be set by using ":" in between them. + * @{ + */ +#define PLUGIN_FEATURE_RTSAFE "rtsafe" //!< Is hard-realtime safe. +#define PLUGIN_FEATURE_GUI "gui" //!< Provides custom UI. +#define PLUGIN_FEATURE_STATE "state" //!< Supports get_state() and set_state(). +#define PLUGIN_FEATURE_TIME "time" //!< Uses get_time_info(). +#define PLUGIN_FEATURE_WRITE_EVENT "writeevent" //!< Uses write_event(). +#define PLUGIN_FEATURE_FIXED_BUFFERS "fixedbuffers" //!< Needs fixed-size audio buffers. +#define PLUGIN_FEATURE_MONO_PANNING "monopanning" //!< Prefers mono-style panning. +#define PLUGIN_FEATURE_STEREO_BALANCE "stereobalance" //!< Prefers stereo balance. +#define PLUGIN_FEATURE_OPENSAVE "uiopensave" //!< UI uses ui_open_file() and/or ui_save_file() functions. +#define PLUGIN_FEATURE_SINGLE_THREAD "uisinglethread" //!< UI needs paramter, midi-program and custom-data changes in the main thread. +/**@}*/ -typedef enum { - PARAMETER_IS_OUTPUT = 1 << 0, - PARAMETER_IS_ENABLED = 1 << 1, - PARAMETER_IS_AUTOMABLE = 1 << 2, - PARAMETER_IS_BOOLEAN = 1 << 3, - PARAMETER_IS_INTEGER = 1 << 4, - PARAMETER_IS_LOGARITHMIC = 1 << 5, - PARAMETER_USES_SAMPLE_RATE = 1 << 6, - PARAMETER_USES_SCALEPOINTS = 1 << 7, - PARAMETER_USES_CUSTOM_TEXT = 1 << 8 -} ParameterHints; +/*! + * @defgroup PluginSupports Plugin Supports + * + * A list of plugin supported MIDI events. + * @{ + */ +#define PLUGIN_SUPPORTS_PROGRAM_CHANGES "program" //!< Handles MIDI programs internally instead of host-exposed/exported +#define PLUGIN_SUPPORTS_CONTROL_CHANGES "control" //!< Supports control changes (0xB0) +#define PLUGIN_SUPPORTS_CHANNEL_PRESSURE "pressure" //!< Supports channel pressure (0xD0) +#define PLUGIN_SUPPORTS_NOTE_AFTERTOUCH "aftertouch" //!< Supports note aftertouch (0xA0) +#define PLUGIN_SUPPORTS_PITCHBEND "pitchbend" //!< Supports pitchbend (0xE0) +#define PLUGIN_SUPPORTS_ALL_SOUND_OFF "allsoundoff" //!< Supporta all-sound-off and all-notes-off events +#define PLUGIN_SUPPORTS_EVERYTHING "program:control:pressure:aftertouch:pitchbend:allsoundoff" //!< Supports everything +/**@}*/ + +/*! + * @defgroup ParameterHints Parameter Hints + * + * List of parameter hints. + * @{ + */ +#define PARAMETER_IS_OUTPUT "output" //!< Is output; input if unset. +#define PARAMETER_IS_ENABLED "enabled" //!< Is enabled and shown by the host; can be changed if not output. +#define PARAMETER_IS_AUTOMABLE "automable" //!< Is automable; get_parameter_value() and set_parameter_value() MUST be realtime safe for this parameter. +#define PARAMETER_IS_BOOLEAN "boolean" //!< Values are boolean (always at minimum or maximum values). +#define PARAMETER_IS_INTEGER "integer" //!< Values are integer. +#define PARAMETER_IS_LOGARITHMIC "logarithmic" //!< Values are logarithmic. +#define PARAMETER_USES_SAMPLE_RATE "samplerate" //!< Needs sample-rate to work (value and ranges are multiplied by SR on usage, divided by SR on save). +#define PARAMETER_USES_SCALEPOINTS "scalepoints" //!< Uses scalepoints to define internal values in a meaningful way. +#define PARAMETER_USES_CUSTOM_TEXT "customtext" //!< Uses custom text for displaying its value. @see get_parameter_text() +/**@}*/ typedef enum { PLUGIN_OPCODE_NULL = 0, // nothing @@ -132,7 +164,7 @@ typedef struct { #define PARAMETER_RANGES_DEFAULT_STEP_LARGE 0.1f typedef struct { - ParameterHints hints; + const char* hints; const char* name; const char* unit; ParameterRanges ranges; @@ -142,12 +174,23 @@ typedef struct { } Parameter; typedef struct { - uint8_t port; - uint32_t time; - uint8_t data[4]; - uint8_t size; + AtomXYZ type; + uint32_t frame; +} Event; + +typedef struct { + Event e; + uint8_t port; + uint8_t size; + uint8_t data[4]; } MidiEvent; +typedef struct { + Event e; + uint32_t index; + float value; +} ParameterEvent; + typedef struct { uint32_t bank; uint32_t program; @@ -189,7 +232,7 @@ typedef struct { bool (*is_offline)(HostHandle handle); const TimeInfo* (*get_time_info)(HostHandle handle); - bool (*write_midi_event)(HostHandle handle, const MidiEvent* event); + bool (*write_event)(HostHandle handle, const Event* event); void (*ui_parameter_changed)(HostHandle handle, uint32_t index, float value); void (*ui_midi_program_changed)(HostHandle handle, uint8_t channel, uint32_t bank, uint32_t program); @@ -208,9 +251,9 @@ typedef struct { // PluginDescriptor typedef struct _PluginDescriptor { - const PluginCategory category; - const PluginHints hints; - const PluginSupports supports; + const char* const category; + const char* const hints; + const char* const supports; const uint32_t audioIns; const uint32_t audioOuts; const uint32_t midiIns; @@ -246,7 +289,7 @@ typedef struct _PluginDescriptor { void (*activate)(PluginHandle handle); void (*deactivate)(PluginHandle handle); - void (*process)(PluginHandle handle, float** inBuffer, float** outBuffer, uint32_t frames, const MidiEvent* midiEvents, uint32_t midiEventCount); + void (*process)(PluginHandle handle, float** inBuffer, float** outBuffer, uint32_t frames, const Event* events, uint32_t eventCount); char* (*get_state)(PluginHandle handle); void (*set_state)(PluginHandle handle, const char* data);