source/includes/CarlaNative.h

   1 /*
   2  * Carla Native Plugin API
   3  * Copyright (C) 2012-2023 Filipe Coelho <falktx@falktx.com>
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License as
   7  * published by the Free Software Foundation; either version 2 of
   8  * the License, or any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * For a full copy of the GNU General Public License see the doc/GPL.txt file.
  16  */
  17
  18 #ifndef CARLA_NATIVE_H_INCLUDED
  19 #define CARLA_NATIVE_H_INCLUDED
  20
  21 #include "CarlaDefines.h"
  22 #include <stddef.h>
  23 #include <stdint.h>
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /*!
  30  * @defgroup CarlaNativeAPI Carla Native API
  31  *
  32  * The Carla Native API
  33  * @{
  34  */
  35
  36 typedef void* NativeHostHandle;
  37 typedef void* NativePluginHandle;
  38
  39 /* ------------------------------------------------------------------------------------------------------------
  40  * enums */
  41
  42 typedef enum {
  43     NATIVE_PLUGIN_CATEGORY_NONE       = 0, /** Null plugin category.                                     */
  44     NATIVE_PLUGIN_CATEGORY_SYNTH      = 1, /** A synthesizer or generator.                               */
  45     NATIVE_PLUGIN_CATEGORY_DELAY      = 2, /** A delay or reverberator.                                  */
  46     NATIVE_PLUGIN_CATEGORY_EQ         = 3, /** An equalizer.                                             */
  47     NATIVE_PLUGIN_CATEGORY_FILTER     = 4, /** A filter.                                                 */
  48     NATIVE_PLUGIN_CATEGORY_DISTORTION = 5, /** A distortion plugin.                                      */
  49     NATIVE_PLUGIN_CATEGORY_DYNAMICS   = 6, /** A 'dynamic' plugin (amplifier, compressor, gate, etc).    */
  50     NATIVE_PLUGIN_CATEGORY_MODULATOR  = 7, /** A 'modulator' plugin (chorus, flanger, phaser, etc).      */
  51     NATIVE_PLUGIN_CATEGORY_UTILITY    = 8, /** An 'utility' plugin (analyzer, converter, mixer, etc).    */
  52     NATIVE_PLUGIN_CATEGORY_OTHER      = 9  /** Misc plugin (used to check if the plugin has a category). */
  53 } NativePluginCategory;
  54
  55 typedef enum {
  56     NATIVE_PLUGIN_IS_RTSAFE            = 1 <<  0,
  57     NATIVE_PLUGIN_IS_SYNTH             = 1 <<  1,
  58     NATIVE_PLUGIN_HAS_UI               = 1 <<  2,
  59     NATIVE_PLUGIN_NEEDS_FIXED_BUFFERS  = 1 <<  3,
  60     NATIVE_PLUGIN_NEEDS_UI_MAIN_THREAD = 1 <<  4,
  61     NATIVE_PLUGIN_NEEDS_UI_OPEN_SAVE   = 1 <<  6,
  62     NATIVE_PLUGIN_USES_MULTI_PROGS     = 1 <<  7, /** has 1 program per midi channel         */
  63     NATIVE_PLUGIN_USES_PANNING         = 1 <<  8, /** uses stereo balance if unset (default) */
  64     NATIVE_PLUGIN_USES_STATE           = 1 <<  9,
  65     NATIVE_PLUGIN_USES_TIME            = 1 << 10,
  66     NATIVE_PLUGIN_USES_PARENT_ID       = 1 << 11, /** can set transient hint to parent       */
  67     NATIVE_PLUGIN_HAS_INLINE_DISPLAY   = 1 << 12,
  68     NATIVE_PLUGIN_USES_CONTROL_VOLTAGE = 1 << 13,
  69     NATIVE_PLUGIN_REQUESTS_IDLE        = 1 << 15,
  70     NATIVE_PLUGIN_USES_UI_SIZE         = 1 << 16
  71 } NativePluginHints;
  72
  73 typedef enum {
  74     NATIVE_PLUGIN_SUPPORTS_NOTHING          = 0,
  75     NATIVE_PLUGIN_SUPPORTS_PROGRAM_CHANGES  = 1 << 0, /** handles MIDI programs internally instead of host-exposed/exported */
  76     NATIVE_PLUGIN_SUPPORTS_CONTROL_CHANGES  = 1 << 1,
  77     NATIVE_PLUGIN_SUPPORTS_CHANNEL_PRESSURE = 1 << 2,
  78     NATIVE_PLUGIN_SUPPORTS_NOTE_AFTERTOUCH  = 1 << 3,
  79     NATIVE_PLUGIN_SUPPORTS_PITCHBEND        = 1 << 4,
  80     NATIVE_PLUGIN_SUPPORTS_ALL_SOUND_OFF    = 1 << 5,
  81     NATIVE_PLUGIN_SUPPORTS_EVERYTHING       = (1 << 6)-1
  82 } NativePluginSupports;
  83
  84 typedef enum {
  85     NATIVE_PARAMETER_DESIGNATION_NONE = 0,
  86     NATIVE_PARAMETER_DESIGNATION_ENABLED
  87 } NativeParameterDesignations;
  88
  89 typedef enum {
  90     NATIVE_PARAMETER_IS_OUTPUT        = 1 << 0,
  91     NATIVE_PARAMETER_IS_ENABLED       = 1 << 1,
  92     NATIVE_PARAMETER_IS_AUTOMATABLE   = 1 << 2,
  93     NATIVE_PARAMETER_IS_AUTOMABLE     = NATIVE_PARAMETER_IS_AUTOMATABLE, // there was a typo..
  94     NATIVE_PARAMETER_IS_BOOLEAN       = 1 << 3,
  95     NATIVE_PARAMETER_IS_INTEGER       = 1 << 4,
  96     NATIVE_PARAMETER_IS_LOGARITHMIC   = 1 << 5,
  97     NATIVE_PARAMETER_USES_SAMPLE_RATE = 1 << 6,
  98     NATIVE_PARAMETER_USES_SCALEPOINTS = 1 << 7,
  99     NATIVE_PARAMETER_USES_DESIGNATION = 1 << 8
 100 } NativeParameterHints;
 101
 102 typedef enum {
 103     NATIVE_PLUGIN_OPCODE_NULL                = 0, /** nothing                   */
 104     NATIVE_PLUGIN_OPCODE_BUFFER_SIZE_CHANGED = 1, /** uses value                */
 105     NATIVE_PLUGIN_OPCODE_SAMPLE_RATE_CHANGED = 2, /** uses opt                  */
 106     NATIVE_PLUGIN_OPCODE_OFFLINE_CHANGED     = 3, /** uses value (0=off, 1=on)  */
 107     NATIVE_PLUGIN_OPCODE_UI_NAME_CHANGED     = 4, /** uses ptr                  */
 108     NATIVE_PLUGIN_OPCODE_GET_INTERNAL_HANDLE = 5, /** nothing                   */
 109     NATIVE_PLUGIN_OPCODE_IDLE                = 6, /** nothing                   */
 110     NATIVE_PLUGIN_OPCODE_UI_MIDI_EVENT       = 7, /** uses ptr                  */
 111     NATIVE_PLUGIN_OPCODE_HOST_USES_EMBED     = 8, /** nothing                   */
 112     NATIVE_PLUGIN_OPCODE_HOST_OPTION         = 9  /** uses index, value and ptr */
 113 } NativePluginDispatcherOpcode;
 114
 115 typedef enum {
 116     NATIVE_HOST_OPCODE_NULL                  = 0,  /** nothing                                           */
 117     NATIVE_HOST_OPCODE_UPDATE_PARAMETER      = 1,  /** uses index, -1 for all                            */
 118     NATIVE_HOST_OPCODE_UPDATE_MIDI_PROGRAM   = 2,  /** uses index, -1 for all; may use value for channel */
 119     NATIVE_HOST_OPCODE_RELOAD_PARAMETERS     = 3,  /** nothing                                           */
 120     NATIVE_HOST_OPCODE_RELOAD_MIDI_PROGRAMS  = 4,  /** nothing                                           */
 121     NATIVE_HOST_OPCODE_RELOAD_ALL            = 5,  /** nothing                                           */
 122     NATIVE_HOST_OPCODE_UI_UNAVAILABLE        = 6,  /** nothing                                           */
 123     NATIVE_HOST_OPCODE_HOST_IDLE             = 7,  /** nothing                                           */
 124     NATIVE_HOST_OPCODE_INTERNAL_PLUGIN       = 8,  /** nothing                                           */
 125     NATIVE_HOST_OPCODE_QUEUE_INLINE_DISPLAY  = 9,  /** nothing                                           */
 126     NATIVE_HOST_OPCODE_UI_TOUCH_PARAMETER    = 10, /** uses index, value as bool                         */
 127     NATIVE_HOST_OPCODE_REQUEST_IDLE          = 11, /** nothing                                           */
 128     NATIVE_HOST_OPCODE_GET_FILE_PATH         = 12, /** uses ptr as string for file type                  */
 129     NATIVE_HOST_OPCODE_UI_RESIZE             = 13, /** uses index and value                              */
 130     NATIVE_HOST_OPCODE_PREVIEW_BUFFER_DATA   = 14  /** uses index as type, value as size, and ptr        */
 131 } NativeHostDispatcherOpcode;
 132
 133 /* ------------------------------------------------------------------------------------------------------------
 134  * base structs */
 135
 136 typedef struct {
 137     const char* label;
 138     float value;
 139 } NativeParameterScalePoint;
 140
 141 typedef struct {
 142     float def;
 143     float min;
 144     float max;
 145     float step;
 146     float stepSmall;
 147     float stepLarge;
 148 } NativeParameterRanges;
 149
 150 #define PARAMETER_RANGES_DEFAULT_STEP       0.01f
 151 #define PARAMETER_RANGES_DEFAULT_STEP_SMALL 0.0001f
 152 #define PARAMETER_RANGES_DEFAULT_STEP_LARGE 0.1f
 153
 154 typedef struct {
 155     NativeParameterHints hints;
 156     const char* name;
 157     const char* unit;
 158     NativeParameterRanges ranges;
 159
 160     uint32_t scalePointCount;
 161     const NativeParameterScalePoint* scalePoints;
 162
 163     const char* comment;
 164     const char* groupName;
 165
 166     uint designation;
 167 } NativeParameter;
 168
 169 typedef struct {
 170     uint32_t time;
 171     uint8_t  port;
 172     uint8_t  size;
 173     uint8_t  data[4];
 174 } NativeMidiEvent;
 175
 176 typedef struct {
 177     uint32_t bank;
 178     uint32_t program;
 179     const char* name;
 180 } NativeMidiProgram;
 181
 182 typedef struct {
 183     bool valid;
 184
 185     int32_t bar;  /** current bar              */
 186     int32_t beat; /** current beat-within-bar  */
 187     double  tick; /** current tick-within-beat */
 188     double  barStartTick;
 189
 190     float beatsPerBar; /** time signature "numerator"  */
 191     float beatType;    /** time signature "denominator" */
 192
 193     double ticksPerBeat;
 194     double beatsPerMinute;
 195 } NativeTimeInfoBBT;
 196
 197 typedef struct {
 198     bool playing;
 199     uint64_t frame;
 200     uint64_t usecs;
 201     NativeTimeInfoBBT bbt;
 202 } NativeTimeInfo;
 203
 204 typedef struct {
 205     unsigned char* data;
 206     int width;
 207     int height;
 208     int stride;
 209 } NativeInlineDisplayImageSurface;
 210
 211 typedef struct {
 212     float minimum, maximum;
 213 } NativePortRange;
 214
 215 /* ------------------------------------------------------------------------------------------------------------
 216  * HostDescriptor */
 217
 218 typedef struct {
 219     NativeHostHandle handle;
 220     const char* resourceDir;
 221     const char* uiName;
 222     uintptr_t   uiParentId;
 223
 224     uint32_t (*get_buffer_size)(NativeHostHandle handle);
 225     double   (*get_sample_rate)(NativeHostHandle handle);
 226     bool     (*is_offline)(NativeHostHandle handle);
 227
 228     const NativeTimeInfo* (*get_time_info)(NativeHostHandle handle);
 229     bool                  (*write_midi_event)(NativeHostHandle handle, const NativeMidiEvent* event);
 230
 231     void (*ui_parameter_changed)(NativeHostHandle handle, uint32_t index, float value);
 232     void (*ui_midi_program_changed)(NativeHostHandle handle, uint8_t channel, uint32_t bank, uint32_t program);
 233     void (*ui_custom_data_changed)(NativeHostHandle handle, const char* key, const char* value);
 234     void (*ui_closed)(NativeHostHandle handle);
 235
 236     const char* (*ui_open_file)(NativeHostHandle handle, bool isDir, const char* title, const char* filter);
 237     const char* (*ui_save_file)(NativeHostHandle handle, bool isDir, const char* title, const char* filter);
 238
 239     intptr_t (*dispatcher)(NativeHostHandle handle,
 240                            NativeHostDispatcherOpcode opcode, int32_t index, intptr_t value, void* ptr, float opt);
 241
 242 } NativeHostDescriptor;
 243
 244 /* ------------------------------------------------------------------------------------------------------------
 245  * PluginDescriptor */
 246
 247 typedef struct _NativePluginDescriptor {
 248     const NativePluginCategory category;
 249     const NativePluginHints hints;
 250     const NativePluginSupports supports;
 251     const uint32_t audioIns;
 252     const uint32_t audioOuts;
 253     const uint32_t midiIns;
 254     const uint32_t midiOuts;
 255     const uint32_t paramIns;
 256     const uint32_t paramOuts;
 257     const char* const name;
 258     const char* const label;
 259     const char* const maker;
 260     const char* const copyright;
 261
 262     NativePluginHandle (*instantiate)(const NativeHostDescriptor* host);
 263     void               (*cleanup)(NativePluginHandle handle);
 264
 265     uint32_t               (*get_parameter_count)(NativePluginHandle handle);
 266     const NativeParameter* (*get_parameter_info)(NativePluginHandle handle, uint32_t index);
 267     float                  (*get_parameter_value)(NativePluginHandle handle, uint32_t index);
 268
 269     uint32_t                 (*get_midi_program_count)(NativePluginHandle handle);
 270     const NativeMidiProgram* (*get_midi_program_info)(NativePluginHandle handle, uint32_t index);
 271
 272     void (*set_parameter_value)(NativePluginHandle handle, uint32_t index, float value);
 273     void (*set_midi_program)(NativePluginHandle handle, uint8_t channel, uint32_t bank, uint32_t program);
 274     void (*set_custom_data)(NativePluginHandle handle, const char* key, const char* value);
 275
 276     void (*ui_show)(NativePluginHandle handle, bool show);
 277     void (*ui_idle)(NativePluginHandle handle);
 278
 279     void (*ui_set_parameter_value)(NativePluginHandle handle, uint32_t index, float value);
 280     void (*ui_set_midi_program)(NativePluginHandle handle, uint8_t channel, uint32_t bank, uint32_t program);
 281     void (*ui_set_custom_data)(NativePluginHandle handle, const char* key, const char* value);
 282
 283     void (*activate)(NativePluginHandle handle);
 284     void (*deactivate)(NativePluginHandle handle);
 285
 286     /* FIXME for v3.0, use const for the input buffer */
 287     void (*process)(NativePluginHandle handle,
 288                     float** inBuffer, float** outBuffer, uint32_t frames,
 289                     const NativeMidiEvent* midiEvents, uint32_t midiEventCount);
 290
 291     char* (*get_state)(NativePluginHandle handle);
 292     void  (*set_state)(NativePluginHandle handle, const char* data);
 293
 294     intptr_t (*dispatcher)(NativePluginHandle handle,
 295                            NativePluginDispatcherOpcode opcode, int32_t index, intptr_t value, void* ptr, float opt);
 296
 297     /* placed at the end for backwards compatibility. only valid if NATIVE_PLUGIN_HAS_INLINE_DISPLAY is set */
 298     const NativeInlineDisplayImageSurface* (*render_inline_display)(NativePluginHandle handle,
 299                                                                     uint32_t width, uint32_t height);
 300
 301     /* placed at the end for backwards compatibility. only valid if NATIVE_PLUGIN_USES_CONTROL_VOLTAGE is set */
 302     const uint32_t cvIns;
 303     const uint32_t cvOuts;
 304     const char* (*get_buffer_port_name)(NativePluginHandle handle, uint32_t index, bool isOutput);
 305     const NativePortRange* (*get_buffer_port_range)(NativePluginHandle handle, uint32_t index, bool isOutput);
 306
 307     /* placed at the end for backwards compatibility. only valid if NATIVE_PLUGIN_USES_UI_SIZE is set */
 308     uint16_t ui_width, ui_height;
 309
 310 } NativePluginDescriptor;
 311
 312 /* ------------------------------------------------------------------------------------------------------------
 313  * Register plugin */
 314
 315 /** Implemented by host */
 316 extern void carla_register_native_plugin(const NativePluginDescriptor* desc);
 317
 318 /** Called once on host init */
 319 void carla_register_all_native_plugins(void);
 320
 321 /** Get meta-data only */
 322 CARLA_API_EXPORT
 323 const NativePluginDescriptor* carla_get_native_plugins_data(uint32_t* count);
 324
 325 /* ------------------------------------------------------------------------------------------------------------ */
 326
 327 /**@}*/
 328
 329 #ifdef __cplusplus
 330 } /* extern "C" */
 331 #endif
 332
 333 #endif /* CARLA_NATIVE_H_INCLUDED */