at

src/plugin_host/core/plugin_interface.h

@@ -0,0 +1,376 @@
+// ================================================================================================
+// Audio Backend - 插件接口基类
+// ================================================================================================
+// 描述: 定义所有插件必须实现的核心接口
+// 功能: 插件生命周期管理、音频处理、参数管理
+// ================================================================================================
+
+#pragma once
+
+#include "plugin_types.h"
+#include "audio_buffer.h"
+#include "error.h"
+#include <memory>
+#include <string>
+#include <vector>
+#include <functional>
+#include <any>
+
+namespace audio_backend::plugin_host {
+
+// ================================================================================================
+// 前向声明
+// ================================================================================================
+class PluginInfo;
+class PluginParameter;
+class PluginPreset;
+struct AudioConfig;
+
+// ================================================================================================
+// MIDI事件结构
+// ================================================================================================
+struct MidiEvent {
+    uint32_t timestamp;     // 时间戳（样本偏移）
+    uint8_t data[4];        // MIDI数据
+    uint8_t size;           // 数据大小
+    
+    MidiEvent() : timestamp(0), size(0) {
+        data[0] = data[1] = data[2] = data[3] = 0;
+    }
+    
+    MidiEvent(uint32_t ts, uint8_t d0, uint8_t d1 = 0, uint8_t d2 = 0) 
+        : timestamp(ts), size(d1 == 0 ? 1 : (d2 == 0 ? 2 : 3)) {
+        data[0] = d0;
+        data[1] = d1;
+        data[2] = d2;
+        data[3] = 0;
+    }
+    
+    // MIDI消息类型检测
+    bool is_note_on() const { return (data[0] & 0xF0) == 0x90 && data[2] > 0; }
+    bool is_note_off() const { return (data[0] & 0xF0) == 0x80 || ((data[0] & 0xF0) == 0x90 && data[2] == 0); }
+    bool is_control_change() const { return (data[0] & 0xF0) == 0xB0; }
+    bool is_program_change() const { return (data[0] & 0xF0) == 0xC0; }
+    bool is_pitch_bend() const { return (data[0] & 0xF0) == 0xE0; }
+    
+    uint8_t get_channel() const { return data[0] & 0x0F; }
+    uint8_t get_note() const { return data[1]; }
+    uint8_t get_velocity() const { return data[2]; }
+    uint8_t get_controller() const { return data[1]; }
+    uint8_t get_value() const { return data[2]; }
+};
+
+// ================================================================================================
+// 插件处理上下文
+// ================================================================================================
+struct PluginProcessContext {
+    // 时间信息
+    uint64_t sample_position = 0;          // 当前样本位置
+    double sample_rate = 44100.0;          // 采样率
+    uint32_t block_size = 512;             // 块大小
+    
+    // 传输状态
+    bool is_playing = false;               // 是否播放中
+    bool is_recording = false;             // 是否录制中
+    bool is_looping = false;               // 是否循环中
+    double tempo = 120.0;                  // 速度（BPM）
+    
+    // 小节信息
+    int32_t time_signature_numerator = 4;  // 拍号分子
+    int32_t time_signature_denominator = 4; // 拍号分母
+    double ppq_position = 0.0;             // PPQ位置
+    double bar_start_position = 0.0;       // 小节开始位置
+    
+    // 系统信息
+    uint64_t system_time = 0;              // 系统时间
+    bool is_realtime = true;               // 是否实时处理
+};
+
+// ================================================================================================
+// 插件事件监听器接口
+// ================================================================================================
+class IPluginEventListener {
+public:
+    virtual ~IPluginEventListener() = default;
+    
+    // 状态变化事件
+    virtual void on_state_changed(PluginState old_state, PluginState new_state) = 0;
+    
+    // 参数变化事件
+    virtual void on_parameter_changed(const std::string& parameter_id, const std::any& value) = 0;
+    
+    // 错误事件
+    virtual void on_error(common::ErrorCode error, const std::string& message) = 0;
+    
+    // 性能事件
+    virtual void on_performance_warning(const std::string& message) = 0;
+};
+
+// ================================================================================================
+// 插件接口基类
+// ================================================================================================
+class IPlugin {
+public:
+    virtual ~IPlugin() = default;
+    
+    // ================================================================================================
+    // 基本信息
+    // ================================================================================================
+    
+    // 获取插件信息
+    virtual std::unique_ptr<PluginInfo> get_plugin_info() const = 0;
+    
+    // 获取插件ID
+    virtual PluginId get_plugin_id() const = 0;
+    
+    // 获取插件名称
+    virtual std::string get_name() const = 0;
+    
+    // 获取供应商
+    virtual std::string get_vendor() const = 0;
+    
+    // 获取版本
+    virtual Version get_version() const = 0;
+    
+    // 获取类别
+    virtual PluginCategory get_category() const = 0;
+    
+    // 获取类型
+    virtual PluginType get_type() const = 0;
+    
+    // 获取能力
+    virtual PluginCapability get_capabilities() const = 0;
+    
+    // ================================================================================================
+    // 生命周期管理
+    // ================================================================================================
+    
+    // 初始化插件
+    virtual common::ErrorCode initialize(const engine::AudioConfig& config) = 0;
+    
+    // 关闭插件
+    virtual common::ErrorCode shutdown() = 0;
+    
+    // 激活插件
+    virtual common::ErrorCode activate() = 0;
+    
+    // 停用插件
+    virtual common::ErrorCode deactivate() = 0;
+    
+    // 暂停插件
+    virtual common::ErrorCode suspend() = 0;
+    
+    // 恢复插件
+    virtual common::ErrorCode resume() = 0;
+    
+    // 重置插件状态
+    virtual common::ErrorCode reset() = 0;
+    
+    // 获取当前状态
+    virtual PluginState get_state() const = 0;
+    
+    // ================================================================================================
+    // 音频处理
+    // ================================================================================================
+    
+    // 准备处理
+    virtual common::ErrorCode prepare_to_play(double sample_rate, uint32_t max_block_size) = 0;
+    
+    // 处理音频块
+    virtual ProcessingResult process_audio(
+        const engine::AudioBuffer& input,
+        engine::AudioBuffer& output,
+        const std::vector<MidiEvent>& midi_in,
+        std::vector<MidiEvent>& midi_out,
+        const PluginProcessContext& context) = 0;
+    
+    // 处理MIDI事件
+    virtual ProcessingResult process_midi(
+        const std::vector<MidiEvent>& midi_in,
+        std::vector<MidiEvent>& midi_out,
+        const PluginProcessContext& context) = 0;
+    
+    // 获取延迟（以样本为单位）
+    virtual uint32_t get_latency_samples() const = 0;
+    
+    // 获取尾部长度（以样本为单位）
+    virtual uint32_t get_tail_length_samples() const = 0;
+    
+    // 设置旁路状态
+    virtual common::ErrorCode set_bypass(bool bypass) = 0;
+    
+    // 获取旁路状态
+    virtual bool is_bypassed() const = 0;
+    
+    // ================================================================================================
+    // 音频配置
+    // ================================================================================================
+    
+    // 获取支持的输入声道配置
+    virtual std::vector<uint16_t> get_supported_input_channels() const = 0;
+    
+    // 获取支持的输出声道配置
+    virtual std::vector<uint16_t> get_supported_output_channels() const = 0;
+    
+    // 设置声道配置
+    virtual common::ErrorCode set_channel_configuration(uint16_t input_channels, uint16_t output_channels) = 0;
+    
+    // 获取当前声道配置
+    virtual std::pair<uint16_t, uint16_t> get_channel_configuration() const = 0;
+    
+    // ================================================================================================
+    // 参数管理
+    // ================================================================================================
+    
+    // 获取参数数量
+    virtual size_t get_parameter_count() const = 0;
+    
+    // 获取参数信息
+    virtual std::unique_ptr<PluginParameter> get_parameter_info(size_t index) const = 0;
+    
+    // 根据ID获取参数信息
+    virtual std::unique_ptr<PluginParameter> get_parameter_by_id(const std::string& parameter_id) const = 0;
+    
+    // 设置参数值
+    virtual common::ErrorCode set_parameter(const std::string& parameter_id, const std::any& value) = 0;
+    
+    // 获取参数值
+    virtual std::any get_parameter(const std::string& parameter_id) const = 0;
+    
+    // 设置参数为默认值
+    virtual common::ErrorCode reset_parameter(const std::string& parameter_id) = 0;
+    
+    // 重置所有参数
+    virtual common::ErrorCode reset_all_parameters() = 0;
+    
+    // ================================================================================================
+    // 预设管理
+    // ================================================================================================
+    
+    // 获取预设数量
+    virtual size_t get_preset_count() const = 0;
+    
+    // 获取预设信息
+    virtual std::unique_ptr<PluginPreset> get_preset_info(size_t index) const = 0;
+    
+    // 加载预设
+    virtual common::ErrorCode load_preset(const std::string& preset_id) = 0;
+    
+    // 保存预设
+    virtual common::ErrorCode save_preset(const std::string& preset_id, const std::string& name) = 0;
+    
+    // 获取当前预设ID
+    virtual std::string get_current_preset_id() const = 0;
+    
+    // ================================================================================================
+    // 状态保存和恢复
+    // ================================================================================================
+    
+    // 获取插件状态数据
+    virtual std::vector<uint8_t> get_state_data() const = 0;
+    
+    // 设置插件状态数据
+    virtual common::ErrorCode set_state_data(const std::vector<uint8_t>& data) = 0;
+    
+    // 获取状态数据大小
+    virtual size_t get_state_data_size() const = 0;
+    
+    // ================================================================================================
+    // GUI支持
+    // ================================================================================================
+    
+    // 是否有GUI
+    virtual bool has_gui() const = 0;
+    
+    // 创建GUI
+    virtual void* create_gui(void* parent_window) = 0;
+    
+    // 销毁GUI
+    virtual common::ErrorCode destroy_gui() = 0;
+    
+    // 显示/隐藏GUI
+    virtual common::ErrorCode set_gui_visible(bool visible) = 0;
+    
+    // GUI是否可见
+    virtual bool is_gui_visible() const = 0;
+    
+    // 获取GUI大小
+    virtual std::pair<uint32_t, uint32_t> get_gui_size() const = 0;
+    
+    // 设置GUI大小
+    virtual common::ErrorCode set_gui_size(uint32_t width, uint32_t height) = 0;
+    
+    // ================================================================================================
+    // 事件处理
+    // ================================================================================================
+    
+    // 设置事件监听器
+    virtual void set_event_listener(std::shared_ptr<IPluginEventListener> listener) = 0;
+    
+    // 移除事件监听器
+    virtual void remove_event_listener() = 0;
+    
+    // ================================================================================================
+    // 性能和诊断
+    // ================================================================================================
+    
+    // 获取CPU使用率（百分比）
+    virtual double get_cpu_usage() const = 0;
+    
+    // 获取内存使用量（字节）
+    virtual size_t get_memory_usage() const = 0;
+    
+    // 获取处理时间统计
+    virtual std::chrono::nanoseconds get_average_processing_time() const = 0;
+    
+    // 获取最大处理时间
+    virtual std::chrono::nanoseconds get_max_processing_time() const = 0;
+    
+    // 重置性能统计
+    virtual void reset_performance_statistics() = 0;
+    
+    // ================================================================================================
+    // 扩展功能
+    // ================================================================================================
+    
+    // 获取扩展接口（如果支持）
+    template<typename T>
+    T* get_extension() {
+        return dynamic_cast<T*>(get_extension_impl(typeid(T)));
+    }
+    
+protected:
+    // 获取扩展接口实现（子类可重写）
+    virtual void* get_extension_impl(const std::type_info& type) {
+        return nullptr;
+    }
+};
+
+// ================================================================================================
+// 插件工厂接口
+// ================================================================================================
+class IPluginFactory {
+public:
+    virtual ~IPluginFactory() = default;
+    
+    // 创建插件实例
+    virtual std::unique_ptr<IPlugin> create_plugin(const std::string& plugin_path) = 0;
+    
+    // 获取支持的插件格式
+    virtual std::vector<PluginFormat> get_supported_formats() const = 0;
+    
+    // 检查插件是否受支持
+    virtual bool is_plugin_supported(const std::string& plugin_path) const = 0;
+    
+    // 扫描插件信息（不加载）
+    virtual std::unique_ptr<PluginInfo> scan_plugin_info(const std::string& plugin_path) const = 0;
+};
+
+// ================================================================================================
+// 便捷类型别名
+// ================================================================================================
+using PluginPtr = std::unique_ptr<IPlugin>;
+using PluginFactoryPtr = std::unique_ptr<IPluginFactory>;
+using PluginEventListenerPtr = std::shared_ptr<IPluginEventListener>;
+
+} // namespace audio_backend::plugin_host