source/backend/CarlaHost.h

   1 // SPDX-FileCopyrightText: 2011-2024 Filipe Coelho <falktx@falktx.com>
   2 // SPDX-License-Identifier: GPL-2.0-or-later
   3
   4 #ifndef CARLA_HOST_H_INCLUDED
   5 #define CARLA_HOST_H_INCLUDED
   6
   7 #include "CarlaBackend.h"
   8
   9 #ifdef __cplusplus
  10 using CARLA_BACKEND_NAMESPACE::BinaryType;
  11 using CARLA_BACKEND_NAMESPACE::PluginType;
  12 using CARLA_BACKEND_NAMESPACE::PluginCategory;
  13 using CARLA_BACKEND_NAMESPACE::InternalParameterIndex;
  14 using CARLA_BACKEND_NAMESPACE::EngineCallbackOpcode;
  15 using CARLA_BACKEND_NAMESPACE::NsmCallbackOpcode;
  16 using CARLA_BACKEND_NAMESPACE::EngineOption;
  17 using CARLA_BACKEND_NAMESPACE::EngineProcessMode;
  18 using CARLA_BACKEND_NAMESPACE::EngineTransportMode;
  19 using CARLA_BACKEND_NAMESPACE::FileCallbackOpcode;
  20 using CARLA_BACKEND_NAMESPACE::EngineCallbackFunc;
  21 using CARLA_BACKEND_NAMESPACE::FileCallbackFunc;
  22 using CARLA_BACKEND_NAMESPACE::ParameterData;
  23 using CARLA_BACKEND_NAMESPACE::ParameterRanges;
  24 using CARLA_BACKEND_NAMESPACE::MidiProgramData;
  25 using CARLA_BACKEND_NAMESPACE::CustomData;
  26 using CARLA_BACKEND_NAMESPACE::EngineDriverDeviceInfo;
  27 using CARLA_BACKEND_NAMESPACE::CarlaEngine;
  28 using CARLA_BACKEND_NAMESPACE::CarlaEngineClient;
  29 using CARLA_BACKEND_NAMESPACE::CarlaPlugin;
  30 #endif
  31
  32 /*!
  33  * @defgroup CarlaHostAPI Carla Host API
  34  *
  35  * The Carla Host API.
  36  *
  37  * This API makes it possible to use the Carla Backend in a standalone host application..
  38  *
  39  * None of the returned values in this API calls need to be deleted or free'd.
  40  * When a function fails (returns false or NULL), use carla_get_last_error() to find out what went wrong.
  41  * @{
  42  */
  43
  44 /* ------------------------------------------------------------------------------------------------------------
  45  * Carla Host API (C stuff) */
  46
  47 /*!
  48  * Information about a loaded plugin.
  49  * @see carla_get_plugin_info()
  50  */
  51 typedef struct _CarlaPluginInfo {
  52     /*!
  53      * Plugin type.
  54      */
  55     PluginType type;
  56
  57     /*!
  58      * Plugin category.
  59      */
  60     PluginCategory category;
  61
  62     /*!
  63      * Plugin hints.
  64      * @see PluginHints
  65      */
  66     uint hints;
  67
  68     /*!
  69      * Plugin options available for the user to change.
  70      * @see PluginOptions
  71      */
  72     uint optionsAvailable;
  73
  74     /*!
  75      * Plugin options currently enabled.
  76      * Some options are enabled but not available, which means they will always be on.
  77      * @see PluginOptions
  78      */
  79     uint optionsEnabled;
  80
  81     /*!
  82      * Plugin filename.
  83      * This can be the plugin binary or resource file.
  84      */
  85     const char* filename;
  86
  87     /*!
  88      * Plugin name.
  89      * This name is unique within a Carla instance.
  90      * @see carla_get_real_plugin_name()
  91      */
  92     const char* name;
  93
  94     /*!
  95      * Plugin label or URI.
  96      */
  97     const char* label;
  98
  99     /*!
 100      * Plugin author/maker.
 101      */
 102     const char* maker;
 103
 104     /*!
 105      * Plugin copyright/license.
 106      */
 107     const char* copyright;
 108
 109     /*!
 110      * Icon name for this plugin, in lowercase.
 111      * Default is "plugin".
 112      */
 113     const char* iconName;
 114
 115     /*!
 116      * Plugin unique Id.
 117      * This Id is dependent on the plugin type and may sometimes be 0.
 118      */
 119     int64_t uniqueId;
 120
 121 #ifdef __cplusplus
 122     /*!
 123      * C++ constructor and destructor.
 124      */
 125     CARLA_API _CarlaPluginInfo() noexcept;
 126     CARLA_API ~_CarlaPluginInfo() noexcept;
 127     CARLA_DECLARE_NON_COPYABLE(_CarlaPluginInfo)
 128 #endif
 129
 130 } CarlaPluginInfo;
 131
 132 /*!
 133  * Port count information, used for Audio and MIDI ports and parameters.
 134  * @see carla_get_audio_port_count_info()
 135  * @see carla_get_midi_port_count_info()
 136  * @see carla_get_parameter_count_info()
 137  */
 138 typedef struct _CarlaPortCountInfo {
 139     /*!
 140      * Number of inputs.
 141      */
 142     uint32_t ins;
 143
 144     /*!
 145      * Number of outputs.
 146      */
 147     uint32_t outs;
 148
 149 } CarlaPortCountInfo;
 150
 151 /*!
 152  * Parameter information.
 153  * @see carla_get_parameter_info()
 154  */
 155 typedef struct _CarlaParameterInfo {
 156     /*!
 157      * Parameter name.
 158      */
 159     const char* name;
 160
 161     /*!
 162      * Parameter symbol.
 163      */
 164     const char* symbol;
 165
 166     /*!
 167      * Parameter unit.
 168      */
 169     const char* unit;
 170
 171     /*!
 172      * Parameter comment / documentation.
 173      */
 174     const char* comment;
 175
 176     /*!
 177      * Parameter group name, prefixed by a unique symbol and ":".
 178      */
 179     const char* groupName;
 180
 181     /*!
 182      * Number of scale points.
 183      * @see CarlaScalePointInfo
 184      */
 185     uint32_t scalePointCount;
 186
 187 #ifdef __cplusplus
 188     /*!
 189      * C++ constructor and destructor.
 190      */
 191     CARLA_API _CarlaParameterInfo() noexcept;
 192     CARLA_API ~_CarlaParameterInfo() noexcept;
 193     CARLA_DECLARE_NON_COPYABLE(_CarlaParameterInfo)
 194 #endif
 195
 196 } CarlaParameterInfo;
 197
 198 /*!
 199  * Parameter scale point information.
 200  * @see carla_get_parameter_scalepoint_info()
 201  */
 202 typedef struct _CarlaScalePointInfo {
 203     /*!
 204      * Scale point value.
 205      */
 206     float value;
 207
 208     /*!
 209      * Scale point label.
 210      */
 211     const char* label;
 212
 213 #ifdef __cplusplus
 214     /*!
 215      * C++ constructor and destructor.
 216      */
 217     CARLA_API _CarlaScalePointInfo() noexcept;
 218     CARLA_API ~_CarlaScalePointInfo() noexcept;
 219     CARLA_DECLARE_NON_COPYABLE(_CarlaScalePointInfo)
 220 #endif
 221
 222 } CarlaScalePointInfo;
 223
 224 /*!
 225  * Transport information.
 226  * @see carla_get_transport_info()
 227  */
 228 typedef struct _CarlaTransportInfo {
 229     /*!
 230      * Wherever transport is playing.
 231      */
 232     bool playing;
 233
 234     /*!
 235      * Current transport frame.
 236      */
 237     uint64_t frame;
 238
 239     /*!
 240      * Bar.
 241      */
 242     int32_t bar;
 243
 244     /*!
 245      * Beat.
 246      */
 247     int32_t beat;
 248
 249     /*!
 250      * Tick.
 251      */
 252     int32_t tick;
 253
 254     /*!
 255      * Beats per minute.
 256      */
 257     double bpm;
 258
 259 #ifdef __cplusplus
 260     /*!
 261      * C++ constructor.
 262      */
 263     CARLA_API _CarlaTransportInfo() noexcept;
 264
 265     /*!
 266      * Clear struct contents.
 267      */
 268     CARLA_API void clear() noexcept;
 269 #endif
 270
 271 } CarlaTransportInfo;
 272
 273 /*!
 274  * Runtime engine information.
 275  */
 276 typedef struct _CarlaRuntimeEngineInfo {
 277     /*!
 278      * DSP load.
 279      */
 280     float load;
 281
 282     /*!
 283      * Number of xruns.
 284      */
 285     uint32_t xruns;
 286
 287 } CarlaRuntimeEngineInfo;
 288
 289 /*!
 290  * Runtime engine driver device information.
 291  */
 292 typedef struct {
 293     /*!
 294      * Name of the driver device.
 295      */
 296     const char* name;
 297
 298     /*!
 299      * This driver device hints.
 300      * @see EngineDriverHints
 301      */
 302     uint hints;
 303
 304     /*!
 305      * Current buffer size.
 306      */
 307     uint bufferSize;
 308
 309     /*!
 310      * Available buffer sizes.
 311      * Terminated with 0.
 312      */
 313     const uint32_t* bufferSizes;
 314
 315     /*!
 316      * Current sample rate.
 317      */
 318     double sampleRate;
 319
 320     /*!
 321      * Available sample rates.
 322      * Terminated with 0.0.
 323      */
 324     const double* sampleRates;
 325
 326 } CarlaRuntimeEngineDriverDeviceInfo;
 327
 328 /*!
 329  * Image data for LV2 inline display API.
 330  * raw image pixmap format is ARGB32,
 331  */
 332 typedef struct {
 333     unsigned char* data;
 334     int width;
 335     int height;
 336     int stride;
 337 } CarlaInlineDisplayImageSurface;
 338
 339 /*! Opaque data type for CarlaHost API calls */
 340 typedef struct _CarlaHostHandle* CarlaHostHandle;
 341
 342 /* ------------------------------------------------------------------------------------------------------------
 343  * Carla Host API (C functions) */
 344
 345 /*!
 346  * Get how many engine drivers are available.
 347  */
 348 CARLA_API_EXPORT uint carla_get_engine_driver_count(void);
 349
 350 /*!
 351  * Get an engine driver name.
 352  * @param index Driver index
 353  */
 354 CARLA_API_EXPORT const char* carla_get_engine_driver_name(uint index);
 355
 356 /*!
 357  * Get the device names of an engine driver.
 358  * @param index Driver index
 359  */
 360 CARLA_API_EXPORT const char* const* carla_get_engine_driver_device_names(uint index);
 361
 362 /*!
 363  * Get information about a device driver.
 364  * @param index Driver index
 365  * @param name  Device name
 366  */
 367 CARLA_API_EXPORT const EngineDriverDeviceInfo* carla_get_engine_driver_device_info(uint index, const char* name);
 368
 369 /*!
 370  * Show a device custom control panel.
 371  * @see ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL
 372  * @param index Driver index
 373  * @param name  Device name
 374  */
 375 CARLA_API_EXPORT bool carla_show_engine_driver_device_control_panel(uint index, const char* name);
 376
 377 /*!
 378  * Create a global host handle for standalone application usage.
 379  */
 380 CARLA_API_EXPORT CarlaHostHandle carla_standalone_host_init(void);
 381
 382 #ifdef __cplusplus
 383 /*!
 384  * Get the currently used engine, may be NULL.
 385  * @note C++ only
 386  */
 387 CARLA_API_EXPORT CarlaEngine* carla_get_engine_from_handle(CarlaHostHandle handle);
 388 #endif
 389
 390 /*!
 391  * Initialize the engine.
 392  * Make sure to call carla_engine_idle() at regular intervals afterwards.
 393  * @param driverName Driver to use
 394  * @param clientName Engine master client name
 395  */
 396 CARLA_API_EXPORT bool carla_engine_init(CarlaHostHandle handle, const char* driverName, const char* clientName);
 397
 398 #ifdef BUILD_BRIDGE
 399 /*!
 400  * Initialize the engine in bridged mode.
 401  */
 402 CARLA_API_EXPORT bool carla_engine_init_bridge(CarlaHostHandle handle,
 403                                                const char audioBaseName[6+1],
 404                                                const char rtClientBaseName[6+1],
 405                                                const char nonRtClientBaseName[6+1],
 406                                                const char nonRtServerBaseName[6+1],
 407                                                const char* clientName);
 408 #endif
 409
 410 /*!
 411  * Close the engine.
 412  * This function always closes the engine even if it returns false.
 413  * In other words, even when something goes wrong when closing the engine it still be closed nonetheless.
 414  */
 415 CARLA_API_EXPORT bool carla_engine_close(CarlaHostHandle handle);
 416
 417 /*!
 418  * Idle the engine.
 419  * Do not call this if the engine is not running.
 420  */
 421 CARLA_API_EXPORT void carla_engine_idle(CarlaHostHandle handle);
 422
 423 /*!
 424  * Check if the engine is running.
 425  */
 426 CARLA_API_EXPORT bool carla_is_engine_running(CarlaHostHandle handle);
 427
 428 /*!
 429  * Get information about the currently running engine.
 430  */
 431 CARLA_API_EXPORT const CarlaRuntimeEngineInfo* carla_get_runtime_engine_info(CarlaHostHandle handle);
 432
 433 #ifndef BUILD_BRIDGE
 434 /*!
 435  * Get information about the currently running engine driver device.
 436  */
 437 CARLA_API_EXPORT const CarlaRuntimeEngineDriverDeviceInfo* carla_get_runtime_engine_driver_device_info(CarlaHostHandle handle);
 438
 439 /*!
 440  * Dynamically change buffer size and/or sample rate while engine is running.
 441  * @see ENGINE_DRIVER_DEVICE_VARIABLE_BUFFER_SIZE
 442  * @see ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE
 443  */
 444 CARLA_API_EXPORT bool carla_set_engine_buffer_size_and_sample_rate(CarlaHostHandle handle,
 445                                                                    uint bufferSize, double sampleRate);
 446
 447 /*!
 448  * Show the custom control panel for the current engine device.
 449  * @see ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL
 450  */
 451 CARLA_API_EXPORT bool carla_show_engine_device_control_panel(CarlaHostHandle handle);
 452 #endif
 453
 454 /*!
 455  * Clear the xrun count on the engine, so that the next time carla_get_runtime_engine_info() is called, it returns 0.
 456  */
 457 CARLA_API_EXPORT void carla_clear_engine_xruns(CarlaHostHandle handle);
 458
 459 /*!
 460  * Tell the engine to stop the current cancelable action.
 461  * @see ENGINE_CALLBACK_CANCELABLE_ACTION
 462  */
 463 CARLA_API_EXPORT void carla_cancel_engine_action(CarlaHostHandle handle);
 464
 465 /*!
 466  * Tell the engine it's about to close.
 467  * This is used to prevent the engine thread(s) from reactivating.
 468  * Returns true if there's no pending engine events.
 469  */
 470 CARLA_API_EXPORT bool carla_set_engine_about_to_close(CarlaHostHandle handle);
 471
 472 /*!
 473  * Set the engine callback function.
 474  * @param func Callback function
 475  * @param ptr  Callback pointer
 476  */
 477 CARLA_API_EXPORT void carla_set_engine_callback(CarlaHostHandle handle, EngineCallbackFunc func, void* ptr);
 478
 479 /*!
 480  * Set an engine option.
 481  * @param option   Option
 482  * @param value    Value as number
 483  * @param valueStr Value as string
 484  */
 485 CARLA_API_EXPORT void carla_set_engine_option(CarlaHostHandle handle,
 486                                               EngineOption option, int value, const char* valueStr);
 487
 488 /*!
 489  * Set the file callback function.
 490  * @param func Callback function
 491  * @param ptr  Callback pointer
 492  */
 493 CARLA_API_EXPORT void carla_set_file_callback(CarlaHostHandle handle, FileCallbackFunc func, void* ptr);
 494
 495 /*!
 496  * Load a file of any type.
 497  * This will try to load a generic file as a plugin,
 498  * either by direct handling (SF2 and SFZ) or by using an internal plugin (like Audio and MIDI).
 499  * @see carla_get_supported_file_extensions()
 500  */
 501 CARLA_API_EXPORT bool carla_load_file(CarlaHostHandle handle, const char* filename);
 502
 503 /*!
 504  * Load a Carla project file.
 505  * @note Currently loaded plugins are not removed; call carla_remove_all_plugins() first if needed.
 506  */
 507 CARLA_API_EXPORT bool carla_load_project(CarlaHostHandle handle, const char* filename);
 508
 509 /*!
 510  * Save current project to a file.
 511  */
 512 CARLA_API_EXPORT bool carla_save_project(CarlaHostHandle handle, const char* filename);
 513
 514 #ifndef BUILD_BRIDGE
 515 /*!
 516   * Get the currently set project folder.
 517   * @note Valid for both standalone and plugin versions.
 518  */
 519 CARLA_API_EXPORT const char* carla_get_current_project_folder(CarlaHostHandle handle);
 520
 521 /*!
 522  * Get the currently set project filename.
 523  * @note Valid only for standalone version.
 524  */
 525 CARLA_API_EXPORT const char* carla_get_current_project_filename(CarlaHostHandle handle);
 526
 527 /*!
 528  * Clear the currently set project filename.
 529  */
 530 CARLA_API_EXPORT void carla_clear_project_filename(CarlaHostHandle handle);
 531
 532 /*!
 533  * Connect two patchbay ports.
 534  * @param groupIdA Output (source) group
 535  * @param portIdA  Output (source) port
 536  * @param groupIdB Input (target) group
 537  * @param portIdB  Input (target) port
 538  * @note The group corresponds to the client Id received in the engine callback
 539  * for ENGINE_CALLBACK_PATCHBAY_PORT_ADDED.
 540  * @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED
 541  */
 542 CARLA_API_EXPORT bool carla_patchbay_connect(CarlaHostHandle handle,
 543                                              bool external, uint groupIdA, uint portIdA, uint groupIdB, uint portIdB);
 544
 545 /*!
 546  * Disconnect two patchbay ports.
 547  * @param connectionId Connection Id
 548  * @see ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED
 549  */
 550 CARLA_API_EXPORT bool carla_patchbay_disconnect(CarlaHostHandle handle, bool external, uint connectionId);
 551
 552 /*!
 553  * Set the position of a group.
 554  * This is purely cached and saved in the project file, Carla backend does nothing with the value.
 555  * When loading a project, callbacks are used to inform of the previously saved positions.
 556  * @see ENGINE_CALLBACK_PATCHBAY_CLIENT_POSITION_CHANGED
 557  */
 558 CARLA_API_EXPORT bool carla_patchbay_set_group_pos(CarlaHostHandle handle,
 559                                                    bool external, uint groupId, int x1, int y1, int x2, int y2);
 560
 561 /*!
 562  * Force the engine to resend all patchbay clients, ports and connections again.
 563  * @param external Wherever to show external/hardware ports instead of internal ones.
 564  *                 Only valid in patchbay engine mode, other modes will ignore this.
 565  */
 566 CARLA_API_EXPORT bool carla_patchbay_refresh(CarlaHostHandle handle, bool external);
 567
 568 /*!
 569  * Start playback of the engine transport.
 570  */
 571 CARLA_API_EXPORT void carla_transport_play(CarlaHostHandle handle);
 572
 573 /*!
 574  * Pause the engine transport.
 575  */
 576 CARLA_API_EXPORT void carla_transport_pause(CarlaHostHandle handle);
 577
 578 /*!
 579  * Set the engine transport bpm.
 580  */
 581 CARLA_API_EXPORT void carla_transport_bpm(CarlaHostHandle handle, double bpm);
 582
 583 /*!
 584  * Relocate the engine transport to a specific frame.
 585  */
 586 CARLA_API_EXPORT void carla_transport_relocate(CarlaHostHandle handle, uint64_t frame);
 587
 588 /*!
 589  * Get the current transport frame.
 590  */
 591 CARLA_API_EXPORT uint64_t carla_get_current_transport_frame(CarlaHostHandle handle);
 592
 593 /*!
 594  * Get the engine transport information.
 595  */
 596 CARLA_API_EXPORT const CarlaTransportInfo* carla_get_transport_info(CarlaHostHandle handle);
 597 #endif
 598
 599 /*!
 600  * Current number of plugins loaded.
 601  */
 602 CARLA_API_EXPORT uint32_t carla_get_current_plugin_count(CarlaHostHandle handle);
 603
 604 /*!
 605  * Maximum number of loadable plugins allowed.
 606  * Returns 0 if engine is not started.
 607  */
 608 CARLA_API_EXPORT uint32_t carla_get_max_plugin_number(CarlaHostHandle handle);
 609
 610 /*!
 611  * Add a new plugin.
 612  * If you don't know the binary type use the BINARY_NATIVE macro.
 613  * @param btype    Binary type
 614  * @param ptype    Plugin type
 615  * @param filename Filename, if applicable
 616  * @param name     Name of the plugin, can be NULL
 617  * @param label    Plugin label, if applicable
 618  * @param uniqueId Plugin unique Id, if applicable
 619  * @param extraPtr Extra pointer, defined per plugin type
 620  * @param options  Initial plugin options
 621  */
 622 CARLA_API_EXPORT bool carla_add_plugin(CarlaHostHandle handle,
 623                                        BinaryType btype, PluginType ptype,
 624                                        const char* filename, const char* name, const char* label, int64_t uniqueId,
 625                                        const void* extraPtr, uint options);
 626
 627 /*!
 628  * Remove one plugin.
 629  * @param pluginId Plugin to remove.
 630  */
 631 CARLA_API_EXPORT bool carla_remove_plugin(CarlaHostHandle handle, uint pluginId);
 632
 633 /*!
 634  * Remove all plugins.
 635  */
 636 CARLA_API_EXPORT bool carla_remove_all_plugins(CarlaHostHandle handle);
 637
 638 #ifndef BUILD_BRIDGE
 639 /*!
 640  * Rename a plugin.
 641  * Returns the new name, or NULL if the operation failed.
 642  * @param pluginId Plugin to rename
 643  * @param newName  New plugin name
 644  */
 645 CARLA_API_EXPORT bool carla_rename_plugin(CarlaHostHandle handle, uint pluginId, const char* newName);
 646
 647 /*!
 648  * Clone a plugin.
 649  * @param pluginId Plugin to clone
 650  */
 651 CARLA_API_EXPORT bool carla_clone_plugin(CarlaHostHandle handle, uint pluginId);
 652
 653 /*!
 654  * Prepare replace of a plugin.
 655  * The next call to carla_add_plugin() will use this id, replacing the current plugin.
 656  * @param pluginId Plugin to replace
 657  * @note This function requires carla_add_plugin() to be called afterwards *as soon as possible*.
 658  */
 659 CARLA_API_EXPORT bool carla_replace_plugin(CarlaHostHandle handle, uint pluginId);
 660
 661 /*!
 662  * Switch two plugins positions.
 663  * @param pluginIdA Plugin A
 664  * @param pluginIdB Plugin B
 665  */
 666 CARLA_API_EXPORT bool carla_switch_plugins(CarlaHostHandle handle, uint pluginIdA, uint pluginIdB);
 667 #endif
 668
 669 /*!
 670  * Load a plugin state.
 671  * @param pluginId Plugin
 672  * @param filename Path to plugin state
 673  * @see carla_save_plugin_state()
 674  */
 675 CARLA_API_EXPORT bool carla_load_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);
 676
 677 /*!
 678  * Save a plugin state.
 679  * @param pluginId Plugin
 680  * @param filename Path to plugin state
 681  * @see carla_load_plugin_state()
 682  */
 683 CARLA_API_EXPORT bool carla_save_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);
 684
 685 /*!
 686  * Export plugin as LV2.
 687  * @param pluginId Plugin
 688  * @param lv2path Path to lv2 plugin folder
 689  */
 690 CARLA_API_EXPORT bool carla_export_plugin_lv2(CarlaHostHandle handle, uint pluginId, const char* lv2path);
 691
 692 /*!
 693  * Get information from a plugin.
 694  * @param pluginId Plugin
 695  */
 696 CARLA_API_EXPORT const CarlaPluginInfo* carla_get_plugin_info(CarlaHostHandle handle, uint pluginId);
 697
 698 /*!
 699  * Get audio port count information from a plugin.
 700  * @param pluginId Plugin
 701  */
 702 CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_audio_port_count_info(CarlaHostHandle handle, uint pluginId);
 703
 704 /*!
 705  * Get MIDI port count information from a plugin.
 706  * @param pluginId Plugin
 707  */
 708 CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_midi_port_count_info(CarlaHostHandle handle, uint pluginId);
 709
 710 /*!
 711  * Get parameter count information from a plugin.
 712  * @param pluginId Plugin
 713  */
 714 CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_parameter_count_info(CarlaHostHandle handle, uint pluginId);
 715
 716 /*!
 717  * Get hints about an audio port.
 718  * @param pluginId  Plugin
 719  * @param isOutput  Whether port is output, input otherwise
 720  * @param portIndex Port index, related to input or output
 721  */
 722 CARLA_API_EXPORT uint carla_get_audio_port_hints(CarlaHostHandle handle, uint pluginId, bool isOutput, uint32_t portIndex);
 723
 724 /*!
 725  * Get parameter information from a plugin.
 726  * @param pluginId    Plugin
 727  * @param parameterId Parameter index
 728  * @see carla_get_parameter_count()
 729  */
 730 CARLA_API_EXPORT const CarlaParameterInfo* carla_get_parameter_info(CarlaHostHandle handle,
 731                                                                     uint pluginId,
 732                                                                     uint32_t parameterId);
 733
 734 /*!
 735  * Get parameter scale point information from a plugin.
 736  * @param pluginId     Plugin
 737  * @param parameterId  Parameter index
 738  * @param scalePointId Parameter scale-point index
 739  * @see CarlaParameterInfo::scalePointCount
 740  */
 741 CARLA_API_EXPORT const CarlaScalePointInfo* carla_get_parameter_scalepoint_info(CarlaHostHandle handle,
 742                                                                                 uint pluginId,
 743                                                                                 uint32_t parameterId,
 744                                                                                 uint32_t scalePointId);
 745
 746 /*!
 747  * Get a plugin's parameter data.
 748  * @param pluginId    Plugin
 749  * @param parameterId Parameter index
 750  * @see carla_get_parameter_count()
 751  */
 752 CARLA_API_EXPORT const ParameterData* carla_get_parameter_data(CarlaHostHandle handle,
 753                                                                uint pluginId, uint32_t parameterId);
 754
 755 /*!
 756  * Get a plugin's parameter ranges.
 757  * @param pluginId    Plugin
 758  * @param parameterId Parameter index
 759  * @see carla_get_parameter_count()
 760  */
 761 CARLA_API_EXPORT const ParameterRanges* carla_get_parameter_ranges(CarlaHostHandle handle,
 762                                                                    uint pluginId, uint32_t parameterId);
 763
 764 /*!
 765  * Get a plugin's MIDI program data.
 766  * @param pluginId      Plugin
 767  * @param midiProgramId MIDI Program index
 768  * @see carla_get_midi_program_count()
 769  */
 770 CARLA_API_EXPORT const MidiProgramData* carla_get_midi_program_data(CarlaHostHandle handle,
 771                                                                     uint pluginId, uint32_t midiProgramId);
 772
 773 /*!
 774  * Get a plugin's custom data, using index.
 775  * @param pluginId     Plugin
 776  * @param customDataId Custom data index
 777  * @see carla_get_custom_data_count()
 778  */
 779 CARLA_API_EXPORT const CustomData* carla_get_custom_data(CarlaHostHandle handle, uint pluginId, uint32_t customDataId);
 780
 781 /*!
 782  * Get a plugin's custom data value, using type and key.
 783  * @param pluginId Plugin
 784  * @param type     Custom data type
 785  * @param key      Custom data key
 786  * @see carla_get_custom_data_count()
 787  */
 788 CARLA_API_EXPORT const char* carla_get_custom_data_value(CarlaHostHandle handle,
 789                                                          uint pluginId, const char* type, const char* key);
 790
 791 /*!
 792  * Get a plugin's chunk data.
 793  * @param pluginId Plugin
 794  * @see PLUGIN_OPTION_USE_CHUNKS and carla_set_chunk_data()
 795  */
 796 CARLA_API_EXPORT const char* carla_get_chunk_data(CarlaHostHandle handle, uint pluginId);
 797
 798 /*!
 799  * Get how many parameters a plugin has.
 800  * @param pluginId Plugin
 801  */
 802 CARLA_API_EXPORT uint32_t carla_get_parameter_count(CarlaHostHandle handle, uint pluginId);
 803
 804 /*!
 805  * Get how many programs a plugin has.
 806  * @param pluginId Plugin
 807  * @see carla_get_program_name()
 808  */
 809 CARLA_API_EXPORT uint32_t carla_get_program_count(CarlaHostHandle handle, uint pluginId);
 810
 811 /*!
 812  * Get how many MIDI programs a plugin has.
 813  * @param pluginId Plugin
 814  * @see carla_get_midi_program_name() and carla_get_midi_program_data()
 815  */
 816 CARLA_API_EXPORT uint32_t carla_get_midi_program_count(CarlaHostHandle handle, uint pluginId);
 817
 818 /*!
 819  * Get how many custom data sets a plugin has.
 820  * @param pluginId Plugin
 821  * @see carla_get_custom_data()
 822  */
 823 CARLA_API_EXPORT uint32_t carla_get_custom_data_count(CarlaHostHandle handle, uint pluginId);
 824
 825 /*!
 826  * Get a plugin's parameter text (custom display of internal values).
 827  * @param pluginId    Plugin
 828  * @param parameterId Parameter index
 829  * @see PARAMETER_USES_CUSTOM_TEXT
 830  */
 831 CARLA_API_EXPORT const char* carla_get_parameter_text(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 832
 833 /*!
 834  * Get a plugin's program name.
 835  * @param pluginId  Plugin
 836  * @param programId Program index
 837  * @see carla_get_program_count()
 838  */
 839 CARLA_API_EXPORT const char* carla_get_program_name(CarlaHostHandle handle, uint pluginId, uint32_t programId);
 840
 841 /*!
 842  * Get a plugin's MIDI program name.
 843  * @param pluginId      Plugin
 844  * @param midiProgramId MIDI Program index
 845  * @see carla_get_midi_program_count()
 846  */
 847 CARLA_API_EXPORT const char* carla_get_midi_program_name(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);
 848
 849 /*!
 850  * Get a plugin's real name.
 851  * This is the name the plugin uses to identify itself; may not be unique.
 852  * @param pluginId Plugin
 853  */
 854 CARLA_API_EXPORT const char* carla_get_real_plugin_name(CarlaHostHandle handle, uint pluginId);
 855
 856 /*!
 857  * Get a plugin's program index.
 858  * @param pluginId Plugin
 859  */
 860 CARLA_API_EXPORT int32_t carla_get_current_program_index(CarlaHostHandle handle, uint pluginId);
 861
 862 /*!
 863  * Get a plugin's midi program index.
 864  * @param pluginId Plugin
 865  */
 866 CARLA_API_EXPORT int32_t carla_get_current_midi_program_index(CarlaHostHandle handle, uint pluginId);
 867
 868 /*!
 869  * Get a plugin's default parameter value.
 870  * @param pluginId    Plugin
 871  * @param parameterId Parameter index
 872  */
 873 CARLA_API_EXPORT float carla_get_default_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 874
 875 /*!
 876  * Get a plugin's current parameter value.
 877  * @param pluginId    Plugin
 878  * @param parameterId Parameter index
 879  */
 880 CARLA_API_EXPORT float carla_get_current_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 881
 882 /*!
 883  * Get a plugin's internal parameter value.
 884  * @param pluginId    Plugin
 885  * @param parameterId Parameter index, maybe be negative
 886  * @see InternalParameterIndex
 887  */
 888 CARLA_API_EXPORT float carla_get_internal_parameter_value(CarlaHostHandle handle, uint pluginId, int32_t parameterId);
 889
 890 /*!
 891  * Get a plugin's internal latency, in samples.
 892  * @param pluginId    Plugin
 893  * @see InternalParameterIndex
 894  */
 895 CARLA_API_EXPORT uint32_t carla_get_plugin_latency(CarlaHostHandle handle, uint pluginId);
 896
 897 /*!
 898  * Get a plugin's peak values.
 899  * @param pluginId Plugin
 900  */
 901 CARLA_API_EXPORT const float* carla_get_peak_values(CarlaHostHandle handle, uint pluginId);
 902
 903 /*!
 904  * Get a plugin's input peak value.
 905  * @param pluginId Plugin
 906  * @param isLeft   Wherever to get the left/mono value, otherwise right.
 907  */
 908 CARLA_API_EXPORT float carla_get_input_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);
 909
 910 /*!
 911  * Get a plugin's output peak value.
 912  * @param pluginId Plugin
 913  * @param isLeft   Wherever to get the left/mono value, otherwise right.
 914  */
 915 CARLA_API_EXPORT float carla_get_output_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);
 916
 917 /*!
 918  * Render a plugin's inline display.
 919  * @param pluginId Plugin
 920  */
 921 CARLA_API_EXPORT const CarlaInlineDisplayImageSurface* carla_render_inline_display(CarlaHostHandle handle,
 922                                                                                    uint pluginId,
 923                                                                                    uint32_t width,
 924                                                                                    uint32_t height);
 925
 926 /*!
 927  * Enable or disable a plugin.
 928  * @param pluginId Plugin
 929  * @param onOff    New active state
 930  */
 931 CARLA_API_EXPORT void carla_set_active(CarlaHostHandle handle, uint pluginId, bool onOff);
 932
 933 #ifndef BUILD_BRIDGE
 934 /*!
 935  * Change a plugin's internal dry/wet.
 936  * @param pluginId Plugin
 937  * @param value    New dry/wet value
 938  */
 939 CARLA_API_EXPORT void carla_set_drywet(CarlaHostHandle handle, uint pluginId, float value);
 940
 941 /*!
 942  * Change a plugin's internal volume.
 943  * @param pluginId Plugin
 944  * @param value    New volume
 945  */
 946 CARLA_API_EXPORT void carla_set_volume(CarlaHostHandle handle, uint pluginId, float value);
 947
 948 /*!
 949  * Change a plugin's internal stereo balance, left channel.
 950  * @param pluginId Plugin
 951  * @param value    New value
 952  */
 953 CARLA_API_EXPORT void carla_set_balance_left(CarlaHostHandle handle, uint pluginId, float value);
 954
 955 /*!
 956  * Change a plugin's internal stereo balance, right channel.
 957  * @param pluginId Plugin
 958  * @param value    New value
 959  */
 960 CARLA_API_EXPORT void carla_set_balance_right(CarlaHostHandle handle, uint pluginId, float value);
 961
 962 /*!
 963  * Change a plugin's internal mono panning value.
 964  * @param pluginId Plugin
 965  * @param value    New value
 966  */
 967 CARLA_API_EXPORT void carla_set_panning(CarlaHostHandle handle, uint pluginId, float value);
 968
 969 /*!
 970  * Change a plugin's internal control channel.
 971  * @param pluginId Plugin
 972  * @param channel  New channel
 973  */
 974 CARLA_API_EXPORT void carla_set_ctrl_channel(CarlaHostHandle handle, uint pluginId, int8_t channel);
 975 #endif
 976
 977 /*!
 978  * Enable a plugin's option.
 979  * @param pluginId Plugin
 980  * @param option   An option from PluginOptions
 981  * @param yesNo    New enabled state
 982  */
 983 CARLA_API_EXPORT void carla_set_option(CarlaHostHandle handle, uint pluginId, uint option, bool yesNo);
 984
 985 /*!
 986  * Change a plugin's parameter value.
 987  * @param pluginId    Plugin
 988  * @param parameterId Parameter index
 989  * @param value       New value
 990  */
 991 CARLA_API_EXPORT void carla_set_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId, float value);
 992
 993 #ifndef BUILD_BRIDGE
 994 /*!
 995  * Change a plugin's parameter MIDI channel.
 996  * @param pluginId    Plugin
 997  * @param parameterId Parameter index
 998  * @param channel     New MIDI channel
 999  */
1000 CARLA_API_EXPORT void carla_set_parameter_midi_channel(CarlaHostHandle handle,
1001                                                        uint pluginId, uint32_t parameterId, uint8_t channel);
1002
1003 /*!
1004  * Change a plugin's parameter mapped control index.
1005  * @param pluginId    Plugin
1006  * @param parameterId Parameter index
1007  * @param cc          New control index
1008  */
1009 CARLA_API_EXPORT void carla_set_parameter_mapped_control_index(CarlaHostHandle handle,
1010                                                                uint pluginId, uint32_t parameterId, int16_t index);
1011
1012 /*!
1013  * Change a plugin's parameter mapped range.
1014  * @param pluginId    Plugin
1015  * @param parameterId Parameter index
1016  * @param minimum     New mapped minimum
1017  * @param maximum     New mapped maximum
1018  */
1019 CARLA_API_EXPORT void carla_set_parameter_mapped_range(CarlaHostHandle handle,
1020                                                        uint pluginId, uint32_t parameterId, float minimum, float maximum);
1021
1022 /*!
1023  * Change a plugin's parameter in drag/touch mode state.
1024  * Usually happens from a UI when the user is moving a parameter with a mouse or similar input.
1025  * @param pluginId    Plugin
1026  * @param parameterId Parameter index
1027  * @param touch       New state
1028  */
1029 CARLA_API_EXPORT void carla_set_parameter_touch(CarlaHostHandle handle,
1030                                                 uint pluginId, uint32_t parameterId, bool touch);
1031 #endif
1032
1033 /*!
1034  * Change a plugin's current program.
1035  * @param pluginId  Plugin
1036  * @param programId New program
1037  */
1038 CARLA_API_EXPORT void carla_set_program(CarlaHostHandle handle, uint pluginId, uint32_t programId);
1039
1040 /*!
1041  * Change a plugin's current MIDI program.
1042  * @param pluginId      Plugin
1043  * @param midiProgramId New value
1044  */
1045 CARLA_API_EXPORT void carla_set_midi_program(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);
1046
1047 /*!
1048  * Set a plugin's custom data set.
1049  * @param pluginId Plugin
1050  * @param type     Type
1051  * @param key      Key
1052  * @param value    New value
1053  * @see CustomDataTypes and CustomDataKeys
1054  */
1055 CARLA_API_EXPORT void carla_set_custom_data(CarlaHostHandle handle,
1056                                             uint pluginId, const char* type, const char* key, const char* value);
1057
1058 /*!
1059  * Set a plugin's chunk data.
1060  * @param pluginId  Plugin
1061  * @param chunkData New chunk data
1062  * @see PLUGIN_OPTION_USE_CHUNKS and carla_get_chunk_data()
1063  */
1064 CARLA_API_EXPORT void carla_set_chunk_data(CarlaHostHandle handle, uint pluginId, const char* chunkData);
1065
1066 /*!
1067  * Tell a plugin to prepare for save.
1068  * This should be called before saving custom data sets.
1069  * @param pluginId Plugin
1070  */
1071 CARLA_API_EXPORT void carla_prepare_for_save(CarlaHostHandle handle, uint pluginId);
1072
1073 /*!
1074  * Reset all plugin's parameters.
1075  * @param pluginId Plugin
1076  */
1077 CARLA_API_EXPORT void carla_reset_parameters(CarlaHostHandle handle, uint pluginId);
1078
1079 /*!
1080  * Randomize all plugin's parameters.
1081  * @param pluginId Plugin
1082  */
1083 CARLA_API_EXPORT void carla_randomize_parameters(CarlaHostHandle handle, uint pluginId);
1084
1085 #ifndef BUILD_BRIDGE
1086 /*!
1087  * Send a single note of a plugin.
1088  * If velocity is 0, note-off is sent; note-on otherwise.
1089  * @param pluginId Plugin
1090  * @param channel  Note channel
1091  * @param note     Note pitch
1092  * @param velocity Note velocity
1093  */
1094 CARLA_API_EXPORT void carla_send_midi_note(CarlaHostHandle handle,
1095                                            uint pluginId, uint8_t channel, uint8_t note, uint8_t velocity);
1096 #endif
1097
1098 /*!
1099  * Set a custom title for the plugin UI window created by Carla.
1100  */
1101 CARLA_API_EXPORT void carla_set_custom_ui_title(CarlaHostHandle handle, uint pluginId, const char* title);
1102
1103 /*!
1104  * Tell a plugin to show its own custom UI.
1105  * @param pluginId Plugin
1106  * @param yesNo    New UI state, visible or not
1107  * @see PLUGIN_HAS_CUSTOM_UI
1108  */
1109 CARLA_API_EXPORT void carla_show_custom_ui(CarlaHostHandle handle, uint pluginId, bool yesNo);
1110
1111 /*!
1112   * Embed the plugin's custom UI to the system pointer @a ptr.
1113   * This function is always called from the main thread.
1114   * @note This is very experimental and subject to change at this point
1115   */
1116 CARLA_API_EXPORT void* carla_embed_custom_ui(CarlaHostHandle handle, uint pluginId, void* ptr);
1117
1118 /*!
1119  * Get the current engine buffer size.
1120  */
1121 CARLA_API_EXPORT uint32_t carla_get_buffer_size(CarlaHostHandle handle);
1122
1123 /*!
1124  * Get the current engine sample rate.
1125  */
1126 CARLA_API_EXPORT double carla_get_sample_rate(CarlaHostHandle handle);
1127
1128 /*!
1129  * Get the last error.
1130  */
1131 CARLA_API_EXPORT const char* carla_get_last_error(CarlaHostHandle handle);
1132
1133 /*!
1134  * Get the current engine OSC URL (TCP).
1135  */
1136 CARLA_API_EXPORT const char* carla_get_host_osc_url_tcp(CarlaHostHandle handle);
1137
1138 /*!
1139  * Get the current engine OSC URL (UDP).
1140  */
1141 CARLA_API_EXPORT const char* carla_get_host_osc_url_udp(CarlaHostHandle handle);
1142
1143 /*!
1144  * Initialize NSM (that is, announce ourselves to it).
1145  * Must be called as early as possible in the program's lifecycle.
1146  * Returns true if NSM is available and initialized correctly.
1147  */
1148 CARLA_API_EXPORT bool carla_nsm_init(CarlaHostHandle handle, uint64_t pid, const char* executableName);
1149
1150 /*!
1151  * Respond to an NSM callback.
1152  */
1153 CARLA_API_EXPORT void carla_nsm_ready(CarlaHostHandle handle, NsmCallbackOpcode opcode);
1154
1155 #ifndef CARLA_UTILS_H_INCLUDED
1156 /*!
1157  * Get the complete license text of used third-party code and features.
1158  * Returned string is in basic html format.
1159  */
1160 CARLA_API_EXPORT const char* carla_get_complete_license_text(void);
1161
1162 /*!
1163  * Get the list of supported file extensions in carla_load_file().
1164  */
1165 CARLA_API_EXPORT const char* const* carla_get_supported_file_extensions(void);
1166
1167 /*!
1168  * Get the list of supported features in the current Carla build.
1169  */
1170 CARLA_API_EXPORT const char* const* carla_get_supported_features(void);
1171
1172 /*!
1173  * Get the absolute filename of this carla library.
1174  */
1175 CARLA_API_EXPORT const char* carla_get_library_filename(void);
1176
1177 /*!
1178  * Get the folder where this carla library resides.
1179  */
1180 CARLA_API_EXPORT const char* carla_get_library_folder(void);
1181 #endif
1182
1183 /** @} */
1184
1185 #endif /* CARLA_HOST_H_INCLUDED */