/* * Carla Native Plugin API * Copyright (C) 2012-2013 Filipe Coelho * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of * the License, or any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * For a full copy of the GNU General Public License see the doc/GPL.txt file. */ #ifndef CARLA_NATIVE_H_INCLUDED #define CARLA_NATIVE_H_INCLUDED #ifdef __cplusplus extern "C" { #endif #include #include #include /*! * @defgroup CarlaNativeAPI Carla Native API * * The Carla Native API * @{ */ typedef int32_t AtomXYZ; typedef void* HostHandle; typedef void* PluginHandle; // ----------------------------------------------------------------------- // enums #define PLUGIN_API_VERSION 1 /*! * @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). /**@}*/ /*! * @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. /**@}*/ /*! * @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 PLUGIN_OPCODE_BUFFER_SIZE_CHANGED = 1, // uses value PLUGIN_OPCODE_SAMPLE_RATE_CHANGED = 2, // uses opt PLUGIN_OPCODE_OFFLINE_CHANGED = 3, // uses value (0=off, 1=on) PLUGIN_OPCODE_UI_NAME_CHANGED = 4 // uses ptr } PluginDispatcherOpcode; typedef enum { HOST_OPCODE_NULL = 0, // nothing HOST_OPCODE_SET_VOLUME = 1, // uses opt HOST_OPCODE_SET_DRYWET = 2, // uses opt HOST_OPCODE_SET_BALANCE_LEFT = 3, // uses opt HOST_OPCODE_SET_BALANCE_RIGHT = 4, // uses opt HOST_OPCODE_SET_PANNING = 5, // uses opt HOST_OPCODE_GET_PARAMETER_MIDI_CC = 6, // uses index; return answer HOST_OPCODE_SET_PARAMETER_MIDI_CC = 7, // uses index and value HOST_OPCODE_SET_PROCESS_PRECISION = 8, // uses value HOST_OPCODE_UPDATE_PARAMETER = 9, // uses index, -1 for all HOST_OPCODE_UPDATE_MIDI_PROGRAM = 10, // uses index, -1 for all; may use value for channel HOST_OPCODE_RELOAD_PARAMETERS = 11, // nothing HOST_OPCODE_RELOAD_MIDI_PROGRAMS = 12, // nothing HOST_OPCODE_RELOAD_ALL = 13, // nothing HOST_OPCODE_UI_UNAVAILABLE = 14 // nothing } HostDispatcherOpcode; // ----------------------------------------------------------------------- // base structs typedef struct { const char* label; float value; } ParameterScalePoint; typedef struct { float def; float min; float max; float step; float stepSmall; float stepLarge; } ParameterRanges; #define PARAMETER_RANGES_DEFAULT_STEP 0.01f #define PARAMETER_RANGES_DEFAULT_STEP_SMALL 0.0001f #define PARAMETER_RANGES_DEFAULT_STEP_LARGE 0.1f typedef struct { const char* hints; const char* name; const char* unit; ParameterRanges ranges; uint32_t scalePointCount; ParameterScalePoint* scalePoints; } Parameter; typedef struct { 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; const char* name; } MidiProgram; typedef struct { bool valid; int32_t bar; //!< current bar int32_t beat; //!< current beat-within-bar int32_t tick; //!< current tick-within-beat double barStartTick; float beatsPerBar; //!< time signature "numerator" float beatType; //!< time signature "denominator" double ticksPerBeat; double beatsPerMinute; } TimeInfoBBT; typedef struct { bool playing; uint64_t frame; uint64_t usecs; TimeInfoBBT bbt; } TimeInfo; // ----------------------------------------------------------------------- // HostDescriptor typedef struct { HostHandle handle; const char* resourceDir; const char* uiName; uint32_t (*get_buffer_size)(HostHandle handle); double (*get_sample_rate)(HostHandle handle); bool (*is_offline)(HostHandle handle); const TimeInfo* (*get_time_info)(HostHandle handle); 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); void (*ui_custom_data_changed)(HostHandle handle, const char* key, const char* value); void (*ui_closed)(HostHandle handle); // TODO: add some msgbox call const char* (*ui_open_file)(HostHandle handle, bool isDir, const char* title, const char* filter); const char* (*ui_save_file)(HostHandle handle, bool isDir, const char* title, const char* filter); intptr_t (*dispatcher)(HostHandle handle, HostDispatcherOpcode opcode, int32_t index, intptr_t value, void* ptr, float opt); } HostDescriptor; // ----------------------------------------------------------------------- // PluginDescriptor typedef struct _PluginDescriptor { const char* const category; const char* const hints; const char* const supports; const uint32_t audioIns; const uint32_t audioOuts; const uint32_t midiIns; const uint32_t midiOuts; const uint32_t parameterIns; const uint32_t parameterOuts; const char* const name; const char* const label; const char* const maker; const char* const copyright; PluginHandle (*instantiate)(const HostDescriptor* host); void (*cleanup)(PluginHandle handle); uint32_t (*get_parameter_count)(PluginHandle handle); 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); uint32_t (*get_midi_program_count)(PluginHandle handle); const MidiProgram* (*get_midi_program_info)(PluginHandle handle, uint32_t index); void (*set_parameter_value)(PluginHandle handle, uint32_t index, float value); void (*set_midi_program)(PluginHandle handle, uint8_t channel, uint32_t bank, uint32_t program); void (*set_custom_data)(PluginHandle handle, const char* key, const char* value); void (*ui_show)(PluginHandle handle, bool show); void (*ui_idle)(PluginHandle handle); void (*ui_set_parameter_value)(PluginHandle handle, uint32_t index, float value); void (*ui_set_midi_program)(PluginHandle handle, uint8_t channel, uint32_t bank, uint32_t program); void (*ui_set_custom_data)(PluginHandle handle, const char* key, const char* value); 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); char* (*get_state)(PluginHandle handle); void (*set_state)(PluginHandle handle, const char* data); intptr_t (*dispatcher)(PluginHandle handle, PluginDispatcherOpcode opcode, int32_t index, intptr_t value, void* ptr, float opt); } PluginDescriptor; // ----------------------------------------------------------------------- // Register plugin extern void carla_register_native_plugin(const PluginDescriptor* desc); // ----------------------------------------------------------------------- /**@}*/ #ifdef __cplusplus } // extern "C" #endif #endif // CARLA_NATIVE_H_INCLUDED