editor_host.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/format/editor_host_kind.hpp>
#include <pulp/format/plugin_descriptor.hpp>
#include <pulp/state/parameter.hpp>
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <unordered_map>
#include <utility>
#include <vector>
 
namespace pulp::state {
class StateStore;
}
 
namespace pulp::format {
 
class Processor;
 
// ── Parameters ───────────────────────────────────────────────────────────────

class ParamSubscription {
  public:
    ParamSubscription() = default;
    explicit ParamSubscription(std::function<void()> cancel) noexcept
        : cancel_(std::move(cancel)) {}
    ParamSubscription(ParamSubscription&& other) noexcept
        : cancel_(std::exchange(other.cancel_, {})) {}
    ParamSubscription& operator=(ParamSubscription&& other) noexcept {
        if (this != &other) {
            reset();
            cancel_ = std::exchange(other.cancel_, {});
        }
        return *this;
    }
    ParamSubscription(const ParamSubscription&) = delete;
    ParamSubscription& operator=(const ParamSubscription&) = delete;
    ~ParamSubscription() {
        reset();
    }

    void reset() noexcept {
        if (auto cancel = std::exchange(cancel_, {}))
            cancel();
    }
 
    explicit operator bool() const noexcept {
        return static_cast<bool>(cancel_);
    }
 
  private:
    std::function<void()> cancel_;
};

class ParamPort {
  public:
    using Listener = std::function<void(state::ParamID id, float plain_value)>;
 
    virtual ~ParamPort() = default;

    virtual std::span<const state::ParamInfo> params() const = 0;
    virtual const state::ParamInfo* info(state::ParamID id) const = 0;
    virtual float get(state::ParamID id) const = 0;

    virtual void begin(state::ParamID id) = 0;
    virtual void set(state::ParamID id, float plain_value) = 0;
    virtual void end(state::ParamID id) = 0;

    [[nodiscard]] virtual ParamSubscription add_listener(Listener listener) = 0;

    float get_normalized(state::ParamID id) const {
        const auto* i = info(id);
        return i ? i->range.normalize(get(id)) : 0.0f;
    }

    void set_normalized(state::ParamID id, float normalized) {
        if (const auto* i = info(id))
            set(id, i->range.denormalize(normalized));
    }
};

class StateStoreParamPort final : public ParamPort {
  public:
    explicit StateStoreParamPort(state::StateStore& store);
    ~StateStoreParamPort() override;
 
    StateStoreParamPort(const StateStoreParamPort&) = delete;
    StateStoreParamPort& operator=(const StateStoreParamPort&) = delete;
 
    std::span<const state::ParamInfo> params() const override;
    const state::ParamInfo* info(state::ParamID id) const override;
    float get(state::ParamID id) const override;
    void begin(state::ParamID id) override;
    void set(state::ParamID id, float plain_value) override;
    void end(state::ParamID id) override;
    [[nodiscard]] ParamSubscription add_listener(Listener listener) override;

    void release_all();

    void disconnect();
    bool connected() const;

    int open_gestures(state::ParamID id) const;
 
  private:
    struct Link;
    std::shared_ptr<Link> link_;
};
 
// ── Visual data ──────────────────────────────────────────────────────────────

enum class VisualChannelShape : std::uint8_t {
    scalar = 0, 
    meter = 1,  
    vector = 2, 
    events = 3, 
};

struct VisualChannelInfo {
    std::string_view name; 
    std::string_view unit; 
    VisualChannelShape shape = VisualChannelShape::scalar;
    float neutral = 0.0f;
};

struct VisualEvent {
    std::uint32_t frame_index = 0; 
    float value = 0.0f;            
};

class VisualPort {
  public:
    virtual ~VisualPort() = default;
 
    virtual std::size_t channel_count() const noexcept = 0;
    virtual VisualChannelInfo channel(std::size_t index) const noexcept = 0;

    virtual bool read_scalar(std::size_t index, float& value) noexcept = 0;
    virtual std::size_t read_meter(std::size_t index, std::span<float> rms,
                                   std::span<float> peak) noexcept = 0;
    virtual std::size_t read_vector(std::size_t index, std::span<float> samples) noexcept = 0;
    virtual std::size_t read_events(std::size_t index, std::span<VisualEvent> events) noexcept = 0;
    virtual std::uint32_t publish_count(std::size_t index) const noexcept = 0;

    std::optional<std::size_t> find(std::string_view name,
                                    VisualChannelShape shape) const noexcept {
        for (std::size_t i = 0, n = channel_count(); i < n; ++i) {
            const auto c = channel(i);
            if (c.shape == shape && c.name == name)
                return i;
        }
        return std::nullopt;
    }
};
 
// ── Native windows, sizes and keys ───────────────────────────────────────────

enum class EditorRole : std::uint8_t {
    editor = 0,    
    inspector = 1, 
    settings = 2,  
};

enum class NativeParentKind : std::uint8_t {
    none = 0,         
    cocoa_view = 1,   
    uikit_view = 2,   
    win32_window = 3, 
    x11_window = 4,   
};

struct NativeParent {
    NativeParentKind kind = NativeParentKind::none;
    void* handle = nullptr;      
    std::uint64_t window_id = 0; 
};

struct EditorSize {
    std::uint32_t width = 0;
    std::uint32_t height = 0;
    double scale = 1.0;
};

enum class EditorKey : std::uint16_t {
    none = 0,
    space = 1,
    enter = 2,
    tab = 3,
    backspace = 4,
    escape = 5,
    delete_forward = 6,
    left = 7,
    right = 8,
    up = 9,
    down = 10,
    home = 11,
    end = 12,
    page_up = 13,
    page_down = 14,
};

enum EditorKeyModifier : std::uint8_t {
    editor_modifier_shift = 1u << 0,
    editor_modifier_control = 1u << 1,
    editor_modifier_alt = 1u << 2,     
    editor_modifier_command = 1u << 3, 
};

struct EditorKeyEvent {
    EditorKey key = EditorKey::none;
    char32_t character = 0;     
    std::uint8_t modifiers = 0; 
    bool is_down = true;        
    bool is_repeat = false;     
};

enum class KeyDisposition : std::uint8_t {
    forward = 0,  
    consumed = 1, 
};
 
// ── Editor ───────────────────────────────────────────────────────────────────

class EditorAutomation {
  public:
    virtual ~EditorAutomation() = default;

    virtual bool capture_png(std::vector<std::uint8_t>& /*png*/) {
        return false;
    }

    virtual bool inject_input(std::string_view /*request_json*/, std::string& error) {
        error = "input injection is not supported by this editor";
        return false;
    }

    virtual bool observe(std::string_view /*query_json*/, std::string& /*reply_json*/) {
        return false;
    }
};

class Editor {
  public:
    virtual ~Editor() = default;

    virtual bool supports_parent(NativeParentKind kind) const = 0;

    virtual bool attach(const NativeParent& parent) = 0;

    virtual void detach() = 0;

    virtual void invalidate() = 0;

    virtual EditorSize size() const = 0;

    virtual bool set_size(const EditorSize& size) = 0;

    virtual ViewSize size_hints() const {
        const auto s = size();
        ViewSize hints;
        hints.preferred_width = s.width;
        hints.preferred_height = s.height;
        return hints;
    }

    virtual EditorSize adjust_size(const EditorSize& proposed) const {
        return proposed;
    }

    virtual void idle() {}

    virtual void visibility_changed(bool /*visible*/) {}

    virtual void focus_changed(bool /*focused*/) {}

    virtual KeyDisposition offer_key(const EditorKeyEvent& /*event*/) {
        return KeyDisposition::forward;
    }

    virtual void parameter_highlight(state::ParamID /*id*/, bool /*highlighted*/,
                                     std::uint32_t /*color_rgb*/) {}

    virtual EditorAutomation* automation() {
        return nullptr;
    }
};
 
// ── Host context ─────────────────────────────────────────────────────────────

enum class HostAction : std::uint16_t {
    mark_state_dirty = 0,
    parameter_context_menu = 1,
    close_editor = 2,
};

struct HostActionRequest {
    HostAction action = HostAction::mark_state_dirty;
    state::ParamID param = 0;
    float x = 0.0f;
    float y = 0.0f;
};

class EditorContext {
  public:
    virtual ~EditorContext() = default;

    virtual ParamPort& params() = 0;

    virtual VisualPort* visuals() = 0;

    virtual bool request_resize(const EditorSize& size) = 0;

    virtual bool host_action(const HostActionRequest& request) = 0;

    virtual EditorHostKind host_kind() const = 0;

    virtual void* query_extension(std::string_view /*id*/) {
        return nullptr;
    }
};
 
// ── Factory ──────────────────────────────────────────────────────────────────

class EditorFactory {
  public:
    virtual ~EditorFactory() = default;

    virtual bool supports(EditorRole role) const = 0;

    virtual std::unique_ptr<Editor> create(Processor& processor, EditorContext& context,
                                           EditorRole role) = 0;

    virtual void prewarm() {}
};
 
} // namespace pulp::format