forge_param_descriptor.hpp

Go to the documentation of this file.

#pragma once
 
// Semantic descriptors for Forge-exposed catalog parameters.
//
// CustomNodeBakedParam carries the numeric contract an audio graph needs: id,
// range, default. An agent choosing a node needs more than that — what the
// parameter is called, what it is measured in, whether it steps between named
// states, and what it does. That vocabulary lived downstream and had to be kept
// in sync by hand; a descriptor moves it next to the DSP it describes.
//
// Descriptors deliberately carry NO range or default. Those come from the baked
// node at export time, so a descriptor cannot drift out of agreement with the
// DSP it annotates — there is only ever one copy of a number.
 
#include <pulp/state/parameter.hpp>
 
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace pulp::host {

enum class ForgeParamKind { continuous, stepped };

enum class ForgeParamCurve { linear, logarithmic };

struct ForgeParamChoice {
    std::string_view token;
    std::string_view label;
    float value = 0.0f;
    std::vector<std::string_view> realization_modes;
 
    ForgeParamChoice() = default;
    ForgeParamChoice(std::string_view token_in, std::string_view label_in, float value_in,
                     std::vector<std::string_view> modes_in = {})
        : token(token_in), label(label_in), value(value_in),
          realization_modes(std::move(modes_in)) {}
};

struct ForgeAxisValue {
    std::string_view token;
    std::string_view label;
    float value = 0.0f;
};
 
struct ForgeParamDescriptor {
    std::string_view key;
    state::ParamID id = 0;
    std::string_view label;
    std::string_view unit;
    std::string_view description;
    ForgeParamKind kind = ForgeParamKind::continuous;
    ForgeParamCurve curve = ForgeParamCurve::linear;
    std::vector<ForgeParamChoice> choices;
    std::vector<std::string_view> realization_modes;
 
    ForgeParamDescriptor() = default;
    ForgeParamDescriptor(std::string_view key_in, state::ParamID id_in, std::string_view label_in,
                         std::string_view unit_in, std::string_view description_in,
                         ForgeParamKind kind_in, ForgeParamCurve curve_in,
                         std::vector<ForgeParamChoice> choices_in = {},
                         std::vector<std::string_view> modes_in = {})
        : key(key_in), id(id_in), label(label_in), unit(unit_in), description(description_in),
          kind(kind_in), curve(curve_in), choices(std::move(choices_in)),
          realization_modes(std::move(modes_in)) {}
};

struct ForgeRealizationAxis {
    std::string_view key;
    std::string_view label;
    std::string_view description;
    std::vector<ForgeAxisValue> values;
};

struct ForgeRealizationSetting {
    std::string_view axis;
    std::string_view value;
};

struct ForgeRealization {
    std::string mode;
    std::string type_id;
    std::vector<ForgeRealizationSetting> settings;
 
    ForgeRealization() = default;
    ForgeRealization(std::string_view mode_in, std::string_view type_id_in,
                     std::vector<ForgeRealizationSetting> settings_in = {})
        : mode(mode_in), type_id(type_id_in), settings(std::move(settings_in)) {}
};
 
struct ForgeNodeDescriptor {
    std::string_view key;
    std::string_view label;
    std::string_view description;
    std::vector<ForgeRealizationAxis> axes;
    std::vector<ForgeRealization> realizations;
    std::vector<ForgeParamDescriptor> params;
};

inline const ForgeParamDescriptor* find_param(const ForgeNodeDescriptor& node,
                                              std::string_view key) noexcept {
    for (const auto& param : node.params)
        if (param.key == key)
            return &param;
    return nullptr;
}

inline bool param_applies(const ForgeParamDescriptor& param, std::string_view mode) noexcept {
    if (param.realization_modes.empty())
        return true;
    for (const auto& allowed : param.realization_modes)
        if (allowed == mode)
            return true;
    return false;
}
 
inline bool choice_applies(const ForgeParamChoice& choice, std::string_view mode) noexcept {
    if (choice.realization_modes.empty())
        return true;
    for (const auto& allowed : choice.realization_modes)
        if (allowed == mode)
            return true;
    return false;
}
 
}  // namespace pulp::host