CarlaHost.h

Go to the documentation of this file.

/*
 * Carla Plugin Host
 * Copyright (C) 2011-2022 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 CARLA_BACKEND_NAMESPACE::BinaryType;
using CARLA_BACKEND_NAMESPACE::PluginType;
using CARLA_BACKEND_NAMESPACE::PluginCategory;
using CARLA_BACKEND_NAMESPACE::InternalParameterIndex;
using CARLA_BACKEND_NAMESPACE::EngineCallbackOpcode;
using CARLA_BACKEND_NAMESPACE::NsmCallbackOpcode;
using CARLA_BACKEND_NAMESPACE::EngineOption;
using CARLA_BACKEND_NAMESPACE::EngineProcessMode;
using CARLA_BACKEND_NAMESPACE::EngineTransportMode;
using CARLA_BACKEND_NAMESPACE::FileCallbackOpcode;
using CARLA_BACKEND_NAMESPACE::EngineCallbackFunc;
using CARLA_BACKEND_NAMESPACE::FileCallbackFunc;
using CARLA_BACKEND_NAMESPACE::ParameterData;
using CARLA_BACKEND_NAMESPACE::ParameterRanges;
using CARLA_BACKEND_NAMESPACE::MidiProgramData;
using CARLA_BACKEND_NAMESPACE::CustomData;
using CARLA_BACKEND_NAMESPACE::EngineDriverDeviceInfo;
using CARLA_BACKEND_NAMESPACE::CarlaEngine;
using CARLA_BACKEND_NAMESPACE::CarlaEngineClient;
using CARLA_BACKEND_NAMESPACE::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_COPYABLE(_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_COPYABLE(_CarlaParameterInfo)
#endif
 
} CarlaParameterInfo;

typedef struct _CarlaScalePointInfo {
    float value;

    const char* label;
 
#ifdef __cplusplus
    CARLA_API _CarlaScalePointInfo() noexcept;
    CARLA_API ~_CarlaScalePointInfo() noexcept;
    CARLA_DECLARE_NON_COPYABLE(_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_API_EXPORT uint carla_get_engine_driver_count(void);

CARLA_API_EXPORT const char* carla_get_engine_driver_name(uint index);

CARLA_API_EXPORT const char* const* carla_get_engine_driver_device_names(uint index);

CARLA_API_EXPORT const EngineDriverDeviceInfo* carla_get_engine_driver_device_info(uint index, const char* name);

CARLA_API_EXPORT bool carla_show_engine_driver_device_control_panel(uint index, const char* name);

CARLA_API_EXPORT CarlaHostHandle carla_standalone_host_init(void);
 
#ifdef __cplusplus
CARLA_API_EXPORT CarlaEngine* carla_get_engine_from_handle(CarlaHostHandle handle);
#endif

CARLA_API_EXPORT bool carla_engine_init(CarlaHostHandle handle, const char* driverName, const char* clientName);
 
#ifdef BUILD_BRIDGE
CARLA_API_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_API_EXPORT bool carla_engine_close(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_engine_idle(CarlaHostHandle handle);

CARLA_API_EXPORT bool carla_is_engine_running(CarlaHostHandle handle);

CARLA_API_EXPORT const CarlaRuntimeEngineInfo* carla_get_runtime_engine_info(CarlaHostHandle handle);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT const CarlaRuntimeEngineDriverDeviceInfo* carla_get_runtime_engine_driver_device_info(CarlaHostHandle handle);

CARLA_API_EXPORT bool carla_set_engine_buffer_size_and_sample_rate(CarlaHostHandle handle, uint bufferSize, double sampleRate);

CARLA_API_EXPORT bool carla_show_engine_device_control_panel(CarlaHostHandle handle);
#endif

CARLA_API_EXPORT void carla_clear_engine_xruns(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_cancel_engine_action(CarlaHostHandle handle);

CARLA_API_EXPORT bool carla_set_engine_about_to_close(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_set_engine_callback(CarlaHostHandle handle, EngineCallbackFunc func, void* ptr);

CARLA_API_EXPORT void carla_set_engine_option(CarlaHostHandle handle, EngineOption option, int value, const char* valueStr);

CARLA_API_EXPORT void carla_set_file_callback(CarlaHostHandle handle, FileCallbackFunc func, void* ptr);

CARLA_API_EXPORT bool carla_load_file(CarlaHostHandle handle, const char* filename);

CARLA_API_EXPORT bool carla_load_project(CarlaHostHandle handle, const char* filename);

CARLA_API_EXPORT bool carla_save_project(CarlaHostHandle handle, const char* filename);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT const char* carla_get_current_project_folder(CarlaHostHandle handle);

CARLA_API_EXPORT const char* carla_get_current_project_filename(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_clear_project_filename(CarlaHostHandle handle);

CARLA_API_EXPORT bool carla_patchbay_connect(CarlaHostHandle handle, bool external, uint groupIdA, uint portIdA, uint groupIdB, uint portIdB);

CARLA_API_EXPORT bool carla_patchbay_disconnect(CarlaHostHandle handle, bool external, uint connectionId);

CARLA_API_EXPORT bool carla_patchbay_set_group_pos(CarlaHostHandle handle, bool external,
                                               uint groupId, int x1, int y1, int x2, int y2);

CARLA_API_EXPORT bool carla_patchbay_refresh(CarlaHostHandle handle, bool external);

CARLA_API_EXPORT void carla_transport_play(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_transport_pause(CarlaHostHandle handle);

CARLA_API_EXPORT void carla_transport_bpm(CarlaHostHandle handle, double bpm);

CARLA_API_EXPORT void carla_transport_relocate(CarlaHostHandle handle, uint64_t frame);

CARLA_API_EXPORT uint64_t carla_get_current_transport_frame(CarlaHostHandle handle);

CARLA_API_EXPORT const CarlaTransportInfo* carla_get_transport_info(CarlaHostHandle handle);
#endif

CARLA_API_EXPORT uint32_t carla_get_current_plugin_count(CarlaHostHandle handle);

CARLA_API_EXPORT uint32_t carla_get_max_plugin_number(CarlaHostHandle handle);

CARLA_API_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_API_EXPORT bool carla_remove_plugin(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT bool carla_remove_all_plugins(CarlaHostHandle handle);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT bool carla_rename_plugin(CarlaHostHandle handle, uint pluginId, const char* newName);

CARLA_API_EXPORT bool carla_clone_plugin(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT bool carla_replace_plugin(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT bool carla_switch_plugins(CarlaHostHandle handle, uint pluginIdA, uint pluginIdB);
#endif

CARLA_API_EXPORT bool carla_load_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);

CARLA_API_EXPORT bool carla_save_plugin_state(CarlaHostHandle handle, uint pluginId, const char* filename);

CARLA_API_EXPORT bool carla_export_plugin_lv2(CarlaHostHandle handle, uint pluginId, const char* lv2path);

CARLA_API_EXPORT const CarlaPluginInfo* carla_get_plugin_info(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_audio_port_count_info(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_midi_port_count_info(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT const CarlaPortCountInfo* carla_get_parameter_count_info(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT uint carla_get_audio_port_hints(CarlaHostHandle handle, uint pluginId, bool isOutput, uint32_t portIndex);

CARLA_API_EXPORT const CarlaParameterInfo* carla_get_parameter_info(CarlaHostHandle handle,
                                                                uint pluginId,
                                                                uint32_t parameterId);

CARLA_API_EXPORT const CarlaScalePointInfo* carla_get_parameter_scalepoint_info(CarlaHostHandle handle,
                                                                            uint pluginId,
                                                                            uint32_t parameterId,
                                                                            uint32_t scalePointId);

CARLA_API_EXPORT const ParameterData* carla_get_parameter_data(CarlaHostHandle handle,
                                                           uint pluginId,
                                                           uint32_t parameterId);

CARLA_API_EXPORT const ParameterRanges* carla_get_parameter_ranges(CarlaHostHandle handle,
                                                               uint pluginId,
                                                               uint32_t parameterId);

CARLA_API_EXPORT const MidiProgramData* carla_get_midi_program_data(CarlaHostHandle handle,
                                                                uint pluginId,
                                                                uint32_t midiProgramId);

CARLA_API_EXPORT const CustomData* carla_get_custom_data(CarlaHostHandle handle, uint pluginId, uint32_t customDataId);

CARLA_API_EXPORT const char* carla_get_custom_data_value(CarlaHostHandle handle,
                                                     uint pluginId,
                                                     const char* type,
                                                     const char* key);

CARLA_API_EXPORT const char* carla_get_chunk_data(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT uint32_t carla_get_parameter_count(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT uint32_t carla_get_program_count(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT uint32_t carla_get_midi_program_count(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT uint32_t carla_get_custom_data_count(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT const char* carla_get_parameter_text(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);

CARLA_API_EXPORT const char* carla_get_program_name(CarlaHostHandle handle, uint pluginId, uint32_t programId);

CARLA_API_EXPORT const char* carla_get_midi_program_name(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);

CARLA_API_EXPORT const char* carla_get_real_plugin_name(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT int32_t carla_get_current_program_index(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT int32_t carla_get_current_midi_program_index(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT float carla_get_default_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);

CARLA_API_EXPORT float carla_get_current_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId);

CARLA_API_EXPORT float carla_get_internal_parameter_value(CarlaHostHandle handle, uint pluginId, int32_t parameterId);

CARLA_API_EXPORT uint32_t carla_get_plugin_latency(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT const float* carla_get_peak_values(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT float carla_get_input_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);

CARLA_API_EXPORT float carla_get_output_peak_value(CarlaHostHandle handle, uint pluginId, bool isLeft);

CARLA_API_EXPORT const CarlaInlineDisplayImageSurface* carla_render_inline_display(CarlaHostHandle handle,
                                                                               uint pluginId,
                                                                               uint32_t width,
                                                                               uint32_t height);

CARLA_API_EXPORT void carla_set_active(CarlaHostHandle handle, uint pluginId, bool onOff);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT void carla_set_drywet(CarlaHostHandle handle, uint pluginId, float value);

CARLA_API_EXPORT void carla_set_volume(CarlaHostHandle handle, uint pluginId, float value);

CARLA_API_EXPORT void carla_set_balance_left(CarlaHostHandle handle, uint pluginId, float value);

CARLA_API_EXPORT void carla_set_balance_right(CarlaHostHandle handle, uint pluginId, float value);

CARLA_API_EXPORT void carla_set_panning(CarlaHostHandle handle, uint pluginId, float value);

CARLA_API_EXPORT void carla_set_ctrl_channel(CarlaHostHandle handle, uint pluginId, int8_t channel);
#endif

CARLA_API_EXPORT void carla_set_option(CarlaHostHandle handle, uint pluginId, uint option, bool yesNo);

CARLA_API_EXPORT void carla_set_parameter_value(CarlaHostHandle handle, uint pluginId, uint32_t parameterId, float value);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT void carla_set_parameter_midi_channel(CarlaHostHandle handle,
                                                   uint pluginId,
                                                   uint32_t parameterId,
                                                   uint8_t channel);

CARLA_API_EXPORT void carla_set_parameter_mapped_control_index(CarlaHostHandle handle,
                                                           uint pluginId,
                                                           uint32_t parameterId,
                                                           int16_t index);

CARLA_API_EXPORT void carla_set_parameter_mapped_range(CarlaHostHandle handle,
                                                   uint pluginId,
                                                   uint32_t parameterId,
                                                   float minimum, float maximum);

CARLA_API_EXPORT void carla_set_parameter_touch(CarlaHostHandle handle,
                                            uint pluginId,
                                            uint32_t parameterId,
                                            bool touch);
#endif

CARLA_API_EXPORT void carla_set_program(CarlaHostHandle handle, uint pluginId, uint32_t programId);

CARLA_API_EXPORT void carla_set_midi_program(CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId);

CARLA_API_EXPORT void carla_set_custom_data(CarlaHostHandle handle,
                                        uint pluginId,
                                        const char* type, const char* key, const char* value);

CARLA_API_EXPORT void carla_set_chunk_data(CarlaHostHandle handle, uint pluginId, const char* chunkData);

CARLA_API_EXPORT void carla_prepare_for_save(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT void carla_reset_parameters(CarlaHostHandle handle, uint pluginId);

CARLA_API_EXPORT void carla_randomize_parameters(CarlaHostHandle handle, uint pluginId);
 
#ifndef BUILD_BRIDGE
CARLA_API_EXPORT void carla_send_midi_note(CarlaHostHandle handle,
                                       uint pluginId,
                                       uint8_t channel, uint8_t note, uint8_t velocity);
#endif

CARLA_API_EXPORT void carla_set_custom_ui_title(CarlaHostHandle handle, uint pluginId, const char* title);

CARLA_API_EXPORT void carla_show_custom_ui(CarlaHostHandle handle, uint pluginId, bool yesNo);

CARLA_API_EXPORT void* carla_embed_custom_ui(CarlaHostHandle handle, uint pluginId, void* ptr);

CARLA_API_EXPORT uint32_t carla_get_buffer_size(CarlaHostHandle handle);

CARLA_API_EXPORT double carla_get_sample_rate(CarlaHostHandle handle);

CARLA_API_EXPORT const char* carla_get_last_error(CarlaHostHandle handle);

CARLA_API_EXPORT const char* carla_get_host_osc_url_tcp(CarlaHostHandle handle);

CARLA_API_EXPORT const char* carla_get_host_osc_url_udp(CarlaHostHandle handle);

CARLA_API_EXPORT bool carla_nsm_init(CarlaHostHandle handle, uint64_t pid, const char* executableName);

CARLA_API_EXPORT void carla_nsm_ready(CarlaHostHandle handle, NsmCallbackOpcode opcode);
 
#ifndef CARLA_UTILS_H_INCLUDED
CARLA_API_EXPORT const char* carla_get_complete_license_text(void);

CARLA_API_EXPORT const char* carla_get_juce_version(void);

CARLA_API_EXPORT const char* const* carla_get_supported_file_extensions(void);

CARLA_API_EXPORT const char* const* carla_get_supported_features(void);

CARLA_API_EXPORT const char* carla_get_library_filename(void);

CARLA_API_EXPORT const char* carla_get_library_folder(void);
#endif

 
#endif /* CARLA_HOST_H_INCLUDED */