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

Misc changes

tags/1.9.4
falkTX 12 years ago
parent
da5502c7fd
commit
30fd6d7140
1 changed files with 315 additions and 56 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +315
    -56
      source/modules/CarlaNative.h

+ 315
- 56
source/modules/CarlaNative.h View File

@@ -46,7 +46,8 @@ extern "C" {
*
* 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.
* Plugins should provide at least one of these basic categories.
* THey 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.
* @{
*/
@@ -58,7 +59,7 @@ extern "C" {
#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).
/**@}*/
/** @} */

/*!
* @defgroup PluginFeatures Plugin Features
@@ -71,16 +72,87 @@ extern "C" {
* Multiple features can be set by using ":" in between them.
* @{
*/
#define PLUGIN_FEATURE_RTSAFE "rtsafe" //!< Is hard-realtime safe.
#define PLUGIN_FEATURE_IDLE "idle" //!< Needs non-realtime idle regularly. @see HOST_OPCODE_NEEDS_IDLE
#define PLUGIN_FEATURE_STATE "state" //!< Supports get_state() and set_state() functions.
#define PLUGIN_FEATURE_TIME "time" //!< Uses get_time_info() function.
#define PLUGIN_FEATURE_SEND_MSG "sendmsg" //!< Uses send_ui_msg() function.
#define PLUGIN_FEATURE_WRITE_EVENT "writeevent" //!< Uses write_event() function.
#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.
/**@}*/

/*!
* Is hard-realtime safe.
*
* Plugins with non-rtsafe parameters can be considered rtsafe,
* as long as they set parameters hints accordingly.
*
* If the plugin is hard-realtime safe and supports MIDI programs,
* it MUST ensure MIDI Program events are hard-realtime safe as well.
*
* @see PARAMETER_IS_RTSAFE
*/
#define PLUGIN_FEATURE_RTSAFE "rtsafe"

/*!
* Needs non-realtime idle() function regularly.
*
* This can be used by plugins that need a non-realtime thread to do work.
* The host will call PluginDescriptor::idle() at regular intervals.
* The plugin MUST NOT lock indefinitely.
*
* Alternatively, the plugin can ask the host for a one-shot idle(),
* by using HOST_OPCODE_NEEDS_IDLE.
*/
#define PLUGIN_FEATURE_IDLE "idle"

/*!
* Needs fixed-size audio buffers.
*
* When this feature is set, the host will always call the process() with frames equal to the current buffer size.
* The plugin should probably listen for buffer size changes.
*
* @see PLUGIN_FEATURE_BUFFER_SIZE_CHANGES, PLUGIN_OPCODE_BUFFER_SIZE_CHANGED
*/
#define PLUGIN_FEATURE_FIXED_BUFFERS "fixedbuffers"

/*!
* Supports buffer size changes on-the-fly.
*
* If unset, the host will re-initiate the plugin when the buffer size changes.
*/
#define PLUGIN_FEATURE_BUFFER_SIZE_CHANGES "buffersizechanges"

/*!
* Supports sample rate changes on-the-fly.
*
* If unset, the host will re-initiate the plugin when the sample rate changes.
*/
#define PLUGIN_FEATURE_SAMPLE_RATE_CHANGES "sampleratechanges"

/*!
* Prefers mono-style panning.
*/
#define PLUGIN_FEATURE_MONO_PANNING "monopanning"

/*!
* Prefers stereo balance.
*/
#define PLUGIN_FEATURE_STEREO_BALANCE "stereobalance"

/*!
* Supports get_state() and set_state() functions.
*/
#define PLUGIN_FEATURE_STATE "state"

/*!
* Uses get_time_info() function.
*/
#define PLUGIN_FEATURE_TIME "time"

/*!
* Uses write_event() function.
*/
#define PLUGIN_FEATURE_WRITE_EVENT "writeevent"

/*!
* Uses send_ui_msg() function.
*/
#define PLUGIN_FEATURE_SEND_MSG "sendmsg"

/** @} */

/*!
* @defgroup UiFeatures UI Features
@@ -88,15 +160,30 @@ extern "C" {
* A list of UI 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.
* The host can decide if it can load the UI or not based on this information.
*
* Multiple features can be set by using ":" in between them.
* @{
*/
#define UI_FEATURE_OPEN_SAVE "opensave" //!< Uses ui_open_file() and/or ui_save_file() functions.
#define UI_FEATURE_SEND_MSG "sendmsg" //!< Uses send_plugin_msg() function.
#define UI_FEATURE_SINGLE_THREAD "singlethread" //!< Needs parameter, midi-program and custom-data changes in the main thread.
/**@}*/

/*!
* Supports sample rate changes on-the-fly.
*
* If unset, the host will re-initiate the UI when the sample rate changes.
*/
#define UI_FEATURE_SAMPLE_RATE_CHANGES "sampleratechanges"

/*!
* Uses ui_open_file() and/or ui_save_file() functions.
*/
#define UI_FEATURE_OPEN_SAVE "opensave"

/*!
* Uses send_plugin_msg() function.
*/
#define UI_FEATURE_SEND_MSG "sendmsg"

/** @} */

/*!
* TODO - this needs a better name...
@@ -108,13 +195,49 @@ extern "C" {
* Multiple (supports) can be set by using ":" in between them.
* @{
*/
#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" //!< Supports all-sound-off and all-notes-off events
#define PLUGIN_SUPPORTS_EVERYTHING "program:control:pressure:aftertouch:pitchbend:allsoundoff" //!< Supports everything

/*!
* Handles MIDI programs internally instead of host-exposed/exported.
*
* When this is set, the host will no try to map MIDI program changes into
* plugin exported programs by sending MidiProgramEvent, but will send MidiEvent directly.
*
* @see MidiProgram, MidiProgramEvent
*/
#define PLUGIN_SUPPORTS_PROGRAM_CHANGES "program"

/*!
* Supports control changes (0xB0).
*
* @note:
* The plugin MUST NEVER change exposed parameters on its own.
* If the plugin wants to map a MIDI control change message to a parameter
* it can do so by reporting it in the meta-data, which the host will read.
*/
#define PLUGIN_SUPPORTS_CONTROL_CHANGES "control"

/*!
* Supports channel pressure (0xD0).
*/
#define PLUGIN_SUPPORTS_CHANNEL_PRESSURE "pressure"

/*!
* Supports note aftertouch (0xA0).
*/
#define PLUGIN_SUPPORTS_NOTE_AFTERTOUCH "aftertouch"

/*!
* Supports pitchbend (0xE0).
*/
#define PLUGIN_SUPPORTS_PITCHBEND "pitchbend"

/*!
* Supports all-sound-off and all-notes-off events.
*
* When this is not set, the host might want to send various note-off events to silence the plugin.
*/
#define PLUGIN_SUPPORTS_ALL_SOUND_OFF "allsoundoff"

/**@}*/

/*!
@@ -125,21 +248,84 @@ extern "C" {
* Multiple hints can be set by using ":" in between them.
* @{
*/
#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()

/*!
* Is output.
*
* If this is not set, the parameter should be considered input.
*
* Input parameters are managed by the host and changed by sending a ParameterEvent to the plugin.
* The plugin MUST NEVER change input parameters on its own.
*
* Output parameters are managed by the plugin.
* Every time their values change the plugin should .
* Because of this, any plugin that has output parameters should always set PLUGIN_FEATURE_WRITE_EVENT.
*/
#define PARAMETER_IS_OUTPUT "output"

/*!
* Is enabled.
*
* If set the host may show this parameter on its "built-in" dialog.
*/
#define PARAMETER_IS_ENABLED "enabled"

/*!
* Is hard-realtime safe.
*
* For input parameters:
* When set, the host MUST ONLY use in-process events to change this parameter.
* When not set the host MUST ONLY use PluginDescriptor::non_rt_event().
*
* For output parameters:
* When set, the plugin must send a ParameterEvent to the host every time the value changes.
* When not set the host will call PluginDescriptor::get_parameter_value(), where the plugin is allowed to lock.
*
* @see PLUGIN_FEATURE_RTSAFE
*/
#define PARAMETER_IS_RTSAFE "rtsafe"

/*!
* Values are boolean (always at minimum or maximum values).
*/
#define PARAMETER_IS_BOOLEAN "boolean"

/*!
* Values are integer.
*/
#define PARAMETER_IS_INTEGER "integer"

/*!
* Values are logarithmic.
*/
#define PARAMETER_IS_LOGARITHMIC "logarithmic"

/*!
* Needs sample rate to work.
*
* The parameter value and ranges are multiplied by sample rate on usage
* and divided by sample rate on save.
*/
#define PARAMETER_USES_SAMPLE_RATE "samplerate"

/*!
* Uses scalepoints to define internal values in a meaningful way.
*/
#define PARAMETER_USES_SCALEPOINTS "scalepoints"

/*!
* Uses custom text for displaying its value.
*
* @see get_parameter_text()
*/
#define PARAMETER_USES_CUSTOM_TEXT "customtext"

/**@}*/

/*!
* @defgroup DefaultParameterRanges Default Parameter Ranges
*
* Default ParameterRanges values.
* Default values for parameter range steps.
* @{
*/
#define PARAMETER_RANGE_DEFAULT_STEP 0.01f
@@ -152,12 +338,49 @@ extern "C" {
*
* List of supported event types.
*
* The types are mapped into MappedValue by the host.
* @see HostDescriptor::map_value()
* The types are mapped into mapped_value_t by the host.
* @see Plugin/UiHostDescriptor::map_value()
* @{
*/
#define EVENT_TYPE_MIDI "midi" //!< @see MidiEvent
#define EVENT_TYPE_PARAMETER "parameter" //!< @see ParameterEvent

/*!
* Generic MIDI event.
*
* Realtime MIDI events are always used in-process,
* while non realtime ones should be used in PluginDescriptor::non_rt_event().
*
* @see MidiEvent
*/
#define EVENT_TYPE_MIDI "midi"

/*!
* Midi program event.
*
* Used in-process only.
*
* @see MidiProgramEvent
*/
#define EVENT_TYPE_MIDI_PROGRAM "midiprogram"

/*!
* Parameter event.
*
* There are some rules for parameter events,
* please see PARAMETER_IS_RTSAFE.
*
* @see ParameterEvent
*/
#define EVENT_TYPE_PARAMETER "parameter"

/*!
* Time information event.
*
* Used in-process only.
*
* @see TimeInfoEvent
*/
#define EVENT_TYPE_PARAMETER "time"

/**@}*/

/*!
@@ -170,8 +393,8 @@ extern "C" {
* @{
*/
#define PLUGIN_OPCODE_MSG_RECEIVED "msgReceived" //!< Message received, uses ptr as char*.
#define PLUGIN_OPCODE_BUFFER_SIZE_CHANGED "bufferSizeChanged" //!< Audio buffer size changed, uses value. @see PluginHostDescriptor::get_buffer_size()
#define PLUGIN_OPCODE_SAMPLE_RATE_CHANGED "sampleRateChanged" //!< Audio sample rate changed, uses opt. @see Plugin/UiHostDescriptor::get_sample_rate()
#define PLUGIN_OPCODE_BUFFER_SIZE_CHANGED "bufferSizeChanged" //!< Audio buffer size changed, uses value, returns 1 if supported. @see PluginHostDescriptor::get_buffer_size()
#define PLUGIN_OPCODE_SAMPLE_RATE_CHANGED "sampleRateChanged" //!< Audio sample rate changed, uses opt, returns 1 if supported. @see Plugin/UiHostDescriptor::get_sample_rate()
#define PLUGIN_OPCODE_OFFLINE_CHANGED "offlineChanged" //!< Offline mode changed, uses value (0=off, 1=on). @see Plugin/UiHostDescriptor::is_offline()
#define PLUGIN_OPCODE_UI_TITLE_CHANGED "uiTitleChanged" //!< UI title changed, uses ptr. @see UiHostDescriptor::is_offline()
/**@}*/
@@ -204,11 +427,17 @@ extern "C" {
// -----------------------------------------------------------------------
// Base types

/*!
* Audio sample type.
*/
typedef float audio_sample_t;

/*!
* Host mapped value of a string.
* The value 0 is reserved as undefined.
* @see Plugin/UiHostDescriptor::map_value()
*/
typedef int32_t MappedValue;
typedef uint32_t mapped_value_t;

/*!
* Opaque plugin handle.
@@ -242,7 +471,7 @@ typedef struct {
} ParameterScalePoint;

/*!
* Paraneter ranges.
* Parameter ranges.
*/
typedef struct {
float def;
@@ -259,6 +488,7 @@ typedef struct {
typedef struct {
const char* hints; //!< @see ParameterHints
const char* name;
const char* symbol;
const char* unit;
ParameterRanges ranges;

@@ -309,8 +539,8 @@ typedef struct {
* Generic event.
*/
typedef struct {
MappedValue type; //!< Type of event. @see EventTypes
uint32_t frame; //!< Frame offset since the beginning of process()
mapped_value_t type; //!< Type of event. @see EventTypes
uint32_t frame; //!< Frame offset since the beginning of process()
} Event;

/*!
@@ -323,6 +553,23 @@ typedef struct {
uint8_t data[4];
} MidiEvent;

/*!
* MIDI Program event.
*
* This is a special type of event that tells to plugin to switch MIDI program.
* The plugin is allowed to change its parameter values, the host should request them afterwards if needed.
*
* If the plugin has PLUGIN_SUPPORTS_PROGRAM_CHANGES set, the host must never use event type.
*
* @see MidiProgram
*/
typedef struct {
Event e;
uint8_t channel; // used only in synths
uint32_t bank;
uint32_t program;
} MidiProgramEvent;

/*!
* Parameter event.
*/
@@ -332,6 +579,14 @@ typedef struct {
float value;
} ParameterEvent;

/*!
* Time information event.
*/
typedef struct {
Event e;
TimeInfoBBT bbt;
} TimeInfoEvent;

// -----------------------------------------------------------------------
// PluginHostDescriptor

@@ -339,25 +594,29 @@ typedef struct {
PluginHostHandle handle;

/*!
* Previously used plugin version, may be 0.
* Plugins might want to check this value during set_parameter_value(), set_midi_program() and set_state().
* Previously used plugin version, may be NULL.
*/
int pluginVersion;
const char* pluginVersion;

MappedValue (*map_value)(PluginHostHandle handle, const char* valueStr);
const char* (*unmap_value)(PluginHostHandle handle, MappedValue value);
// NOTE: NOT allowed during process()
mapped_value_t (*map_value)(PluginHostHandle handle, const char* valueStr);
const char* (*unmap_value)(PluginHostHandle handle, mapped_value_t value);

// NOTE: always allowed
uint32_t (*get_buffer_size)(PluginHostHandle handle);
double (*get_sample_rate)(PluginHostHandle handle);
bool (*is_offline)(PluginHostHandle handle);

// plugin must set "time" feature to use this
// NOTE: only allowed during process()
const TimeInfo* (*get_time_info)(PluginHostHandle handle);

// plugin must set "sendmsg" feature to use this
// NOTE: only allowed during idle()
bool (*send_ui_msg)(PluginHostHandle handle, const char* msg);

// plugin must set "writeevent" feature to use this
// NOTE: only allowed during process()
bool (*write_event)(PluginHostHandle handle, const Event* event);

// uses HostDispatcherOpcodes
@@ -373,8 +632,8 @@ typedef struct {
const char* resourceDir;
const char* uiTitle;

MappedValue (*map_value)(UiHostHandle handle, const char* valueStr);
const char* (*unmap_value)(UiHostHandle handle, MappedValue value);
mapped_value_t (*map_value)(UiHostHandle handle, const char* valueStr);
const char* (*unmap_value)(UiHostHandle handle, mapped_value_t value);

double (*get_sample_rate)(UiHostHandle handle);
bool (*is_offline)(UiHostHandle handle);
@@ -425,11 +684,12 @@ typedef struct _PluginDescriptor {
const Parameter* (*get_parameter_info)(PluginHandle handle, uint32_t index);
float (*get_parameter_value)(PluginHandle handle, uint32_t index);
const char* (*get_parameter_text)(PluginHandle handle, uint32_t index, float value); // only used if parameter hint "customtext" is set
void (*set_parameter_value)(PluginHandle handle, uint32_t index, float value);

uint32_t (*get_midi_program_count)(PluginHandle handle);
const MidiProgram* (*get_midi_program_info)(PluginHandle handle, uint32_t index);
void (*set_midi_program)(PluginHandle handle, uint8_t channel, uint32_t bank, uint32_t program); // channel used only in synths

// NOTE: host will never call this while process() is running
void (*non_rt_event)(PluginHandle handle, const Event* event);

// only used if "idle" feature is set, or HOST_OPCODE_NEEDS_IDLE was triggered (for one-shot).
// NOTE: although it's a non-realtime function, it will probably still not be called from the host main thread
@@ -441,7 +701,7 @@ typedef struct _PluginDescriptor {

void (*activate)(PluginHandle handle);
void (*deactivate)(PluginHandle handle);
void (*process)(PluginHandle handle, float** inBuffer, float** outBuffer, uint32_t frames, const Event* events, uint32_t eventCount);
void (*process)(PluginHandle handle, audio_sample_t** inBuffer, audio_sample_t** outBuffer, uint32_t frames, const Event* events, uint32_t eventCount);

// uses PluginDispatcherOpcodes
intptr_t (*dispatcher)(PluginHandle handle, MappedValue opcode, int32_t index, intptr_t value, void* ptr, float opt);
@@ -463,8 +723,7 @@ typedef struct {
void (*show)(UiHandle handle, bool show);
void (*idle)(UiHandle handle);

void (*set_parameter_value)(UiHandle handle, uint32_t index, float value);
void (*set_midi_program)(UiHandle handle, uint8_t channel, uint32_t bank, uint32_t program); // channel used only in synths
void (*event)(UiHandle handle, const Event* event);

intptr_t (*dispatcher)(UiHandle handle, MappedValue opcode, int32_t index, intptr_t value, void* ptr, float opt);



Write Preview
Loading…
Cancel
Save