aax_editor.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/format/aax_model.hpp>
#include <pulp/format/plugin_descriptor.hpp>
#include <pulp/format/processor.hpp>
#include <pulp/runtime/log.hpp>
#include <pulp/state/parameter.hpp>
#include <pulp/state/store.hpp>
 
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
 
// Editor-support logic for the AAX adapter: parameter-gesture routing and the
// editor sizing contract. Both are expressed without any AAX SDK type so they
// are testable on every platform, including builds with no SDK configured. The
// thin shell that talks to `AAX_CEffectGUI` lives in `aax_effect_gui.cpp`.
//
// AAX records automation from an explicit touch/release pair: a custom editor
// must tell the host "the user grabbed this control" before writing values and
// "the user let go" afterwards. Pulp's editors already emit that intent through
// `state::Binding::begin_gesture()` / `end_gesture()`, which fan out via
// `StateStore::set_gesture_callbacks`. This router is the adapter between the
// two: it resolves a `state::ParamID` to the AAX parameter-ID string the
// EffectParameters object registered, and enforces the pairing AAX requires.
 
namespace pulp::format::aax {

inline bool param_id_for_aax_id(const PluginDefinition& definition,
                                std::string_view aax_id,
                                state::ParamID& out_id) {
    for (const auto& binding : definition.parameters) {
        if (binding.aax_id == aax_id) {
            out_id = binding.id;
            return true;
        }
    }
    return false;
}
 
// ── The parameter taper, in one place ──────────────────────────────────────
//
// AAX reaches a parameter's real value through an `AAX_ITaperDelegate<T>`; the
// adapter's delegate is these three functions over a `state::ParamRange`. They
// live here, free of AAX types, because `ParameterMirror` below has to model
// what AAX does with a write — and a second, drifting copy of this math is
// exactly how the mirror's rule came apart from the taper it was reasoning
// about. `FloatTaperDelegate` in the adapter calls straight through to these,
// so the SDK shell, the mirror, and the tests cannot disagree about the map.

inline float taper_constrain_real(const state::ParamRange& range, float value) {
    return range.denormalize(range.normalize(value));
}

inline float taper_normalized_to_real(const state::ParamRange& range, double normalized) {
    return range.denormalize(static_cast<float>(normalized));
}

inline double taper_real_to_normalized(const state::ParamRange& range, float value) {
    return range.normalize(taper_constrain_real(range, value));
}

inline float aax_value_after_write(const state::ParamRange& range, float value) {
    return taper_normalized_to_real(range, taper_real_to_normalized(range, value));
}

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

    virtual Processor* editor_processor() = 0;

    virtual state::StateStore* editor_store() = 0;

    virtual std::optional<ViewSize> editor_view_size() = 0;

    virtual const PluginDefinition& editor_definition() const = 0;

    virtual void release_editor_gestures() = 0;

    virtual void set_editor_invalidation_handler(std::function<void()> handler) {
        (void)handler;
    }
};

struct EditorSizePlan {
    uint32_t width = 0;        
    uint32_t height = 0;
    uint32_t min_width = 0;    
    uint32_t min_height = 0;
    bool resizable = false;    
    bool pin_viewport = false; 
    uint32_t design_width = 0;
    uint32_t design_height = 0;
    float aspect_ratio = 0.0f; 
};

constexpr uint32_t aax_host_dimension(uint32_t logical, float display_scale) {
    (void)display_scale;
    return logical;
}

inline EditorSizePlan plan_editor_size(const ViewSize& hints) {
    EditorSizePlan plan;
    plan.width = hints.preferred_width;
    plan.height = hints.preferred_height;
    plan.resizable = hints.min_width > 0 && hints.min_height > 0;
 
    plan.pin_viewport = should_pin_design_viewport(hints);
    if (plan.pin_viewport) {
        plan.design_width = design_viewport_width(hints);
        plan.design_height = design_viewport_height(hints);
    }
    plan.aspect_ratio = static_cast<float>(native_view_aspect_ratio(hints));
 
    // A fixed-size editor's floor is its design size: reporting a smaller one
    // would invite the host to shrink a surface that cannot reflow.
    plan.min_width = plan.resizable ? hints.min_width : plan.width;
    plan.min_height = plan.resizable ? hints.min_height : plan.height;
    return plan;
}

class ParameterIdMap {
public:
    explicit ParameterIdMap(const PluginDefinition& definition) {
        ids_.reserve(definition.parameters.size());
        for (const auto& binding : definition.parameters) {
            ids_.emplace(binding.id, binding.aax_id);
        }
    }

    const std::string* find(state::ParamID id) const {
        const auto it = ids_.find(id);
        return it == ids_.end() ? nullptr : &it->second;
    }
 
private:
    std::unordered_map<state::ParamID, std::string> ids_;
};

class ParameterMirror {
public:
    using ValueReader = std::function<bool(const char* aax_param_id, float& out_value)>;

    using ValueWriter = std::function<bool(const char* aax_param_id, float value)>;

    static constexpr std::uint32_t kCorrectionFuseLimit = 8;
 
    ParameterMirror(const PluginDefinition& definition, ValueReader reader, ValueWriter writer)
        : reader_(std::move(reader))
        , writer_(std::move(writer))
    {
        params_.reserve(definition.parameters.size());
        for (const auto& binding : definition.parameters) {
            params_.emplace(binding.id, Entry{binding.aax_id, binding.range});
        }
    }

    bool on_store_value_changed(state::ParamID id, float store_value) {
        const auto it = params_.find(id);
        if (it == params_.end()) {
            return false;  // not an AAX-registered parameter
        }
        Entry& entry = it->second;
 
        float aax_value = 0.0f;
        if (!reader_ || !reader_(entry.aax_id.c_str(), aax_value)) {
            return false;
        }
        const bool already_agrees =
            taper_real_to_normalized(entry.range, store_value) ==
            taper_real_to_normalized(entry.range, aax_value);
        const bool write_is_a_no_op =
            aax_value_after_write(entry.range, store_value) == aax_value;
        if (already_agrees || write_is_a_no_op) {
            ++suppressed_count_;
            entry.consecutive_corrections = 0;  // settled — re-arm the fuse
            return false;
        }
 
        // A new value is a new correction, however the last one ended.
        if (!entry.has_last_written || entry.last_written != store_value) {
            entry.last_written = store_value;
            entry.has_last_written = true;
            entry.consecutive_corrections = 0;
        }
 
        // The backstop. The rule above is what makes the loop terminate; this is
        // what keeps a host that breaks the rule anyway from wedging Pro Tools.
        // Stopping leaves AAX holding a value at most one taper round trip from
        // the store's — the host stays authoritative and correct to within that
        // epsilon, which is strictly better than an unbounded touch/post/release
        // stream at the host's dispatch rate. The next distinct value re-arms
        // it, so a fused parameter is not deaf for the rest of the session.
        if (entry.consecutive_corrections >= kCorrectionFuseLimit) {
            ++refused_count_;
            if (!entry.fuse_reported) {
                entry.fuse_reported = true;  // report the parameter once, not the stream
                runtime::log_error(
                    "AAX mirror: parameter '{}' did not converge after {} corrective "
                    "writes of {}; AAX holds {}. Leaving the host authoritative.",
                    entry.aax_id, kCorrectionFuseLimit, store_value, aax_value);
            }
            return false;
        }
        ++entry.consecutive_corrections;
 
        return writer_ && writer_(entry.aax_id.c_str(), store_value);
    }

    std::uint64_t suppressed_count() const { return suppressed_count_; }

    std::uint64_t refused_count() const { return refused_count_; }

    bool is_fused(state::ParamID id) const {
        const auto it = params_.find(id);
        return it != params_.end() &&
               it->second.consecutive_corrections >= kCorrectionFuseLimit;
    }
 
private:
    struct Entry {
        std::string aax_id;
        state::ParamRange range;
        float last_written = 0.0f;
        bool has_last_written = false;
        std::uint32_t consecutive_corrections = 0;
        bool fuse_reported = false;
    };
 
    std::unordered_map<state::ParamID, Entry> params_;
    ValueReader reader_;
    ValueWriter writer_;
    std::uint64_t suppressed_count_ = 0;
    std::uint64_t refused_count_ = 0;
};

class GestureRouter {
public:
    using Sink = std::function<void(const char* aax_param_id)>;
 
    GestureRouter(const PluginDefinition& definition, Sink touch, Sink release)
        : ids_(definition)
        , touch_(std::move(touch))
        , release_(std::move(release))
    {}

    bool begin(state::ParamID id) {
        const auto* aax_id = lookup(id);
        if (!aax_id) {
            ++unknown_count_;
            return false;
        }
        if (!touched_.insert(id).second) {
            return false;  // already touched — keep the record single
        }
        if (touch_) touch_(aax_id->c_str());
        return true;
    }

    bool end(state::ParamID id) {
        const auto* aax_id = lookup(id);
        if (!aax_id) {
            ++unknown_count_;
            return false;
        }
        if (touched_.erase(id) == 0) {
            return false;  // never touched — nothing to release
        }
        if (release_) release_(aax_id->c_str());
        return true;
    }

    void release_all() {
        // Copy: end() mutates touched_.
        const std::unordered_set<state::ParamID> held = touched_;
        for (const auto id : held) {
            end(id);
        }
    }

    bool is_touched(state::ParamID id) const { return touched_.count(id) != 0; }

    std::size_t touched_count() const { return touched_.size(); }

    std::uint64_t unknown_count() const { return unknown_count_; }

    const std::string* aax_id_for(state::ParamID id) const { return lookup(id); }
 
private:
    const std::string* lookup(state::ParamID id) const { return ids_.find(id); }
 
    ParameterIdMap ids_;
    Sink touch_;
    Sink release_;
    std::unordered_set<state::ParamID> touched_;
    std::uint64_t unknown_count_ = 0;
};
 
} // namespace pulp::format::aax