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