CarlaHost.h

Go to the documentation of this file.

/*
 * Carla Plugin Host
 * Copyright (C) 2011-2020 Filipe Coelho <falktx@falktx.com>
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * For a full copy of the GNU General Public License see the doc/GPL.txt file.
 */
 
#ifndef CARLA_HOST_H_INCLUDED
#define CARLA_HOST_H_INCLUDED
 
#include "CarlaBackend.h"
 
#ifdef __cplusplus
using CarlaBackend::BinaryType;
using CarlaBackend::PluginType;
using CarlaBackend::PluginCategory;
using CarlaBackend::InternalParameterIndex;
using CarlaBackend::EngineCallbackOpcode;
using CarlaBackend::NsmCallbackOpcode;
using CarlaBackend::EngineOption;
using CarlaBackend::EngineProcessMode;
using CarlaBackend::EngineTransportMode;
using CarlaBackend::FileCallbackOpcode;
using CarlaBackend::EngineCallbackFunc;
using CarlaBackend::FileCallbackFunc;
using CarlaBackend::ParameterData;
using CarlaBackend::ParameterRanges;
using CarlaBackend::MidiProgramData;
using CarlaBackend::CustomData;
using CarlaBackend::EngineDriverDeviceInfo;
using CarlaBackend::CarlaEngine;
using CarlaBackend::CarlaEngineClient;
using CarlaBackend::CarlaPlugin;
#endif
 
/* ------------------------------------------------------------------------------------------------------------
 * Carla Host API (C stuff) */
 
typedef struct _CarlaPluginInfo {
    PluginType type;
 
    PluginCategory category;
 
    uint hints;
 
    uint optionsAvailable;
 
    uint optionsEnabled;
 
    const char* filename;
 
    const char* name;
 
    const char* label;
 
    const char* maker;
 
    const char* copyright;
 
    const char* iconName;
 
    int64_t uniqueId;
 
#ifdef __cplusplus
 
    CARLA_API _CarlaPluginInfo() noexcept;
    CARLA_API ~_CarlaPluginInfo() noexcept;
    CARLA_DECLARE_NON_COPY_STRUCT(_CarlaPluginInfo)
#endif
 
} CarlaPluginInfo;
 
typedef struct _CarlaPortCountInfo {
    uint32_t ins;
 
    uint32_t outs;
 
} CarlaPortCountInfo;
 
typedef struct _CarlaParameterInfo {
    const char* name;
 
    const char* symbol;
 
    const char* unit;
 
    const char* comment;
 
    const char* groupName;
 
    uint32_t scalePointCount;
 
#ifdef __cplusplus
 
    CARLA_API _CarlaParameterInfo() noexcept;
    CARLA_API ~_CarlaParameterInfo() noexcept;
    CARLA_DECLARE_NON_COPY_STRUCT(_CarlaParameterInfo)
#endif
 
} CarlaParameterInfo;
 
typedef struct _CarlaScalePointInfo {
    float value;
 
    const char* label;
 
#ifdef __cplusplus
 
    CARLA_API _CarlaScalePointInfo() noexcept;
    CARLA_API ~_CarlaScalePointInfo() noexcept;
    CARLA_DECLARE_NON_COPY_STRUCT(_CarlaScalePointInfo)
#endif
 
} CarlaScalePointInfo;
 
typedef struct _CarlaTransportInfo {
    bool playing;
 
    uint64_t frame;
 
    int32_t bar;
 
    int32_t beat;
 
    int32_t tick;
 
    double bpm;
 
#ifdef __cplusplus
 
    CARLA_API _CarlaTransportInfo() noexcept;
 
    CARLA_API void clear() noexcept;
#endif
 
} CarlaTransportInfo;
 
typedef struct _CarlaRuntimeEngineInfo {
    float load;
 
    uint32_t xruns;
 
} CarlaRuntimeEngineInfo;
 
typedef struct {
    const char* name;
 
    uint hints;
 
    uint bufferSize;
 
    const uint32_t* bufferSizes;
 
    double sampleRate;
 
    const double* sampleRates;
 
} CarlaRuntimeEngineDriverDeviceInfo;
 
typedef struct {
    unsigned char* data;
    int width;
    int height;
    int stride;
} CarlaInlineDisplayImageSurface;
 
typedef struct _CarlaHostHandle* CarlaHostHandle;
 
/* ------------------------------------------------------------------------------------------------------------
 * Carla Host API (C functions) */
 
CARLA_EXPORT uint carla_get_engine_driver_count(void);
 
CARLA_EXPORT const char* carla_get_engine_driver_name(uint index);
 
CARLA_EXPORT const char* const* carla_get_engine_driver_device_names(uint index);
 
CARLA_EXPORT const EngineDriverDeviceInfo* carla_get_engine_driver_device_info(uint index, const char* name);
 
CARLA_EXPORT bool carla_show_engine_driver_device_control_panel(uint index, const char* name);
 
CARLA_EXPORT CarlaHostHandle carla_standalone_host_init(void);
 
#ifdef __cplusplus
 
CARLA_EXPORT CarlaEngine* carla_get_engine_from_handle(CarlaHostHandle handle);
#endif
 
CARLA_EXPORT bool carla_engine_init(CarlaHostHandle handle, const char* driverName, const char* clientName);
 
#ifdef BUILD_BRIDGE
 
CARLA_EXPORT bool carla_engine_init_bridge(CarlaHostHandle handle,
                                           const char audioBaseName[6+1],
                                           const char rtClientBaseName[6+1],
                                           const char nonRtClientBaseName[6+1],
                                           const char nonRtServerBaseName[6+1],
                                           const char* clientName);
#endif
 
CARLA_EXPORT bool carla_engine_close(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_engine_idle(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_is_engine_running(CarlaHostHandle handle);
 
CARLA_EXPORT const CarlaRuntimeEngineInfo* carla_get_runtime_engine_info(CarlaHostHandle handle);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT const CarlaRuntimeEngineDriverDeviceInfo* carla_get_runtime_engine_driver_device_info(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_set_engine_buffer_size_and_sample_rate(CarlaHostHandle handle, uint bufferSize, double sampleRate);
 
CARLA_EXPORT bool carla_show_engine_device_control_panel(CarlaHostHandle handle);
#endif
 
CARLA_EXPORT void carla_clear_engine_xruns(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_cancel_engine_action(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_set_engine_about_to_close(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_set_engine_callback(CarlaHostHandle handle, EngineCallbackFunc func, void* ptr);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT void carla_set_engine_option(CarlaHostHandle handle, EngineOption option, int value, const char* valueStr);
#endif
 
CARLA_EXPORT void carla_set_file_callback(CarlaHostHandle handle, FileCallbackFunc func, void* ptr);
 
CARLA_EXPORT bool carla_load_file(CarlaHostHandle handle, const char* filename);
 
CARLA_EXPORT bool carla_load_project(CarlaHostHandle handle, const char* filename);
 
CARLA_EXPORT bool carla_save_project(CarlaHostHandle handle, const char* filename);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT const char* carla_get_current_project_folder(CarlaHostHandle handle);
 
CARLA_EXPORT const char* carla_get_current_project_filename(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_clear_project_filename(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_patchbay_connect(CarlaHostHandle handle, bool external, uint groupIdA, uint portIdA, uint groupIdB, uint portIdB);
 
CARLA_EXPORT bool carla_patchbay_disconnect(CarlaHostHandle handle, bool external, uint connectionId);
 
CARLA_EXPORT bool carla_patchbay_set_group_pos(CarlaHostHandle handle, bool external,
                                               uint groupId, int x1, int y1, int x2, int y2);
 
CARLA_EXPORT bool carla_patchbay_refresh(CarlaHostHandle handle, bool external);
 
CARLA_EXPORT void carla_transport_play(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_transport_pause(CarlaHostHandle handle);
 
CARLA_EXPORT void carla_transport_bpm(CarlaHostHandle handle, double bpm);
 
CARLA_EXPORT void carla_transport_relocate(CarlaHostHandle handle, uint64_t frame);
 
CARLA_EXPORT uint64_t carla_get_current_transport_frame(CarlaHostHandle handle);
 
CARLA_EXPORT const CarlaTransportInfo* carla_get_transport_info(CarlaHostHandle handle);
#endif
 
CARLA_EXPORT uint32_t carla_get_current_plugin_count(CarlaHostHandle handle);
 
CARLA_EXPORT uint32_t carla_get_max_plugin_number(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_add_plugin(CarlaHostHandle handle,
                                   BinaryType btype, PluginType ptype,
                                   const char* filename, const char* name, const char* label, int64_t uniqueId,
                                   const void* extraPtr, uint options);
 
CARLA_EXPORT bool carla_remove_plugin(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT bool carla_remove_all_plugins(CarlaHostHandle handle);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT bool carla_rename_plugin(CarlaHostHandle handle, uint pluginId, const char* newName);
 
CARLA_EXPORT bool carla_clone_plugin(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT bool carla_replace_plugin(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT bool carla_switch_plugins(CarlaHostHandle handle, uint pluginIdA, uint pluginIdB);
#endif
 
CARLA_EXPORT bool carla_load_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);
 
CARLA_EXPORT bool carla_save_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);
 
CARLA_EXPORT bool carla_export_plugin_lv2(CarlaHostHandle handle, uint pluginId, const char* lv2path);
 
CARLA_EXPORT const CarlaPluginInfo* carla_get_plugin_info(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT const CarlaPortCountInfo* carla_get_audio_port_count_info(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT const CarlaPortCountInfo* carla_get_midi_port_count_info(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT const CarlaPortCountInfo* carla_get_parameter_count_info(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT const CarlaParameterInfo* carla_get_parameter_info(CarlaHostHandle handle,
                                                                uint pluginId,
                                                                uint32_t parameterId);
 
CARLA_EXPORT const CarlaScalePointInfo* carla_get_parameter_scalepoint_info(CarlaHostHandle handle,
                                                                            uint pluginId,
                                                                            uint32_t parameterId,
                                                                            uint32_t scalePointId);
 
CARLA_EXPORT const ParameterData* carla_get_parameter_data(CarlaHostHandle handle,
                                                           uint pluginId,
                                                           uint32_t parameterId);
 
CARLA_EXPORT const ParameterRanges* carla_get_parameter_ranges(CarlaHostHandle handle,
                                                               uint pluginId,
                                                               uint32_t parameterId);
 
CARLA_EXPORT const MidiProgramData* carla_get_midi_program_data(CarlaHostHandle handle,
                                                                uint pluginId,
                                                                uint32_t midiProgramId);
 
CARLA_EXPORT const CustomData* carla_get_custom_data(CarlaHostHandle handle, uint pluginId, uint32_t customDataId);
 
CARLA_EXPORT const char* carla_get_custom_data_value(CarlaHostHandle handle,
                                                     uint pluginId,
                                                     const char* type,
                                                     const char* key);
 
CARLA_EXPORT const char* carla_get_chunk_data(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT uint32_t carla_get_parameter_count(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT uint32_t carla_get_program_count(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT uint32_t carla_get_midi_program_count(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT uint32_t carla_get_custom_data_count(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT const char* carla_get_parameter_text(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 
CARLA_EXPORT const char* carla_get_program_name(CarlaHostHandle handle, uint pluginId, uint32_t programId);
 
CARLA_EXPORT const char* carla_get_midi_program_name(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);
 
CARLA_EXPORT const char* carla_get_real_plugin_name(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT int32_t carla_get_current_program_index(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT int32_t carla_get_current_midi_program_index(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT float carla_get_default_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 
CARLA_EXPORT float carla_get_current_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);
 
CARLA_EXPORT float carla_get_internal_parameter_value(CarlaHostHandle handle, uint pluginId, int32_t parameterId);
 
CARLA_EXPORT const float* carla_get_peak_values(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT float carla_get_input_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);
 
CARLA_EXPORT float carla_get_output_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);
 
CARLA_EXPORT const CarlaInlineDisplayImageSurface* carla_render_inline_display(CarlaHostHandle handle,
                                                                               uint pluginId,
                                                                               uint32_t width,
                                                                               uint32_t height);
 
CARLA_EXPORT void carla_set_active(CarlaHostHandle handle, uint pluginId, bool onOff);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT void carla_set_drywet(CarlaHostHandle handle, uint pluginId, float value);
 
CARLA_EXPORT void carla_set_volume(CarlaHostHandle handle, uint pluginId, float value);
 
CARLA_EXPORT void carla_set_balance_left(CarlaHostHandle handle, uint pluginId, float value);
 
CARLA_EXPORT void carla_set_balance_right(CarlaHostHandle handle, uint pluginId, float value);
 
CARLA_EXPORT void carla_set_panning(CarlaHostHandle handle, uint pluginId, float value);
 
CARLA_EXPORT void carla_set_ctrl_channel(CarlaHostHandle handle, uint pluginId, int8_t channel);
#endif
 
CARLA_EXPORT void carla_set_option(CarlaHostHandle handle, uint pluginId, uint option, bool yesNo);
 
CARLA_EXPORT void carla_set_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId, float value);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT void carla_set_parameter_midi_channel(CarlaHostHandle handle,
                                                   uint pluginId,
                                                   uint32_t parameterId,
                                                   uint8_t channel);
 
CARLA_EXPORT void carla_set_parameter_mapped_control_index(CarlaHostHandle handle,
                                                           uint pluginId,
                                                           uint32_t parameterId,
                                                           int16_t index);
 
CARLA_EXPORT void carla_set_parameter_mapped_range(CarlaHostHandle handle,
                                                   uint pluginId,
                                                   uint32_t parameterId,
                                                   float minimum, float maximum);
 
CARLA_EXPORT void carla_set_parameter_touch(CarlaHostHandle handle,
                                            uint pluginId,
                                            uint32_t parameterId,
                                            bool touch);
#endif
 
CARLA_EXPORT void carla_set_program(CarlaHostHandle handle, uint pluginId, uint32_t programId);
 
CARLA_EXPORT void carla_set_midi_program(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);
 
CARLA_EXPORT void carla_set_custom_data(CarlaHostHandle handle,
                                        uint pluginId,
                                        const char* type, const char* key, const char* value);
 
CARLA_EXPORT void carla_set_chunk_data(CarlaHostHandle handle, uint pluginId, const char* chunkData);
 
CARLA_EXPORT void carla_prepare_for_save(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT void carla_reset_parameters(CarlaHostHandle handle, uint pluginId);
 
CARLA_EXPORT void carla_randomize_parameters(CarlaHostHandle handle, uint pluginId);
 
#ifndef BUILD_BRIDGE
 
CARLA_EXPORT void carla_send_midi_note(CarlaHostHandle handle,
                                       uint pluginId,
                                       uint8_t channel, uint8_t note, uint8_t velocity);
#endif
 
CARLA_EXPORT void carla_set_custom_ui_title(CarlaHostHandle handle, uint pluginId, const char* title);
 
CARLA_EXPORT void carla_show_custom_ui(CarlaHostHandle handle, uint pluginId, bool yesNo);
 
CARLA_EXPORT void* carla_embed_custom_ui(CarlaHostHandle handle, uint pluginId, void* ptr);
 
CARLA_EXPORT uint32_t carla_get_buffer_size(CarlaHostHandle handle);
 
CARLA_EXPORT double carla_get_sample_rate(CarlaHostHandle handle);
 
CARLA_EXPORT const char* carla_get_last_error(CarlaHostHandle handle);
 
CARLA_EXPORT const char* carla_get_host_osc_url_tcp(CarlaHostHandle handle);
 
CARLA_EXPORT const char* carla_get_host_osc_url_udp(CarlaHostHandle handle);
 
CARLA_EXPORT bool carla_nsm_init(CarlaHostHandle handle, uint64_t pid, const char* executableName);
 
CARLA_EXPORT void carla_nsm_ready(CarlaHostHandle handle, NsmCallbackOpcode opcode);
 
#ifndef CARLA_UTILS_H_INCLUDED
 
CARLA_EXPORT const char* carla_get_complete_license_text(void);
 
CARLA_EXPORT const char* carla_get_juce_version(void);
 
CARLA_EXPORT const char* const* carla_get_supported_file_extensions(void);
 
CARLA_EXPORT const char* const* carla_get_supported_features(void);
 
CARLA_EXPORT const char* carla_get_library_filename(void);
 
CARLA_EXPORT const char* carla_get_library_folder(void);
#endif
 
#endif /* CARLA_HOST_H_INCLUDED */