Bridge.hpp

Go to the documentation of this file.

#pragma once
 
#include "Primitives/Mapped.hpp"
 
namespace MayaFlux::Core {
class Window;
}
 
namespace MayaFlux::Vruta {
class TaskScheduler;
}
 
namespace MayaFlux::Buffers {
class BufferManager;
class ShaderProcessor;
class AudioWriteProcessor;
class DataWriteProcessor;
class FormaBindingsProcessor;
}
 
namespace MayaFlux::Nodes {
class Node;
class Constant;
}
 
namespace MayaFlux::Portal::Forma {
 
/**
 * @class Bridge
 * @brief Two-way binding orchestrator for Forma elements.
 *
 * One Bridge instance serves the full application. It owns all inbound
 * GraphicsRoutine tasks and all outbound FormaBindingsProcessor instances.
 * Layer and Context are created via the Forma free functions and passed in
 * — Bridge does not own or create them.
 *
 * Inbound (what drives an element's MappedState each frame):
 *   - bind(id, Node)     — reads Node::get_last_output() via GraphicsRoutine
 *   - bind(id, lambda)   — calls std::function<float()> via GraphicsRoutine
 *
 * Outbound (where the element's value goes each frame):
 *   - write(id, ShaderProcessor, offset) — push constant staging
 *   - write(id, descriptor_name, ...)    — descriptor binding
 *   - write(id, AudioWriteProcessor)     — audio buffer
 *   - write(id, DataWriteProcessor)      — vertex buffer
 *   - write(id, Constant)                — node graph value carrier
 *
 * All overloads also accept shared_ptr<MappedState<T>> in place of the
 * element id. These resolve to the state->id.
 * duplicated logic.
 *
 * Usage:
 * @code
 * auto [layer, ctx] = Forma::create_layer(window, "hud", event_manager);
 * auto el = Forma::create_element<float>(*layer, window, bm, geom, 0.5f);
 *
 * Bridge bridge(scheduler, buffer_manager);
 * bridge.bind(el.state, envelope);
 * bridge.write(el.state, compute_proc, offsetof(PC, cutoff));
 *
 * ctx->on_press(el.element.id, IO::MouseButtons::LEFT,
 *     [](uint32_t, glm::vec2){});
 * @endcode
 */
class MAYAFLUX_API Bridge {
public:
    Bridge(
        Vruta::TaskScheduler& scheduler,
        Buffers::BufferManager& buffer_manager);
 
    ~Bridge();
 
    Bridge(const Bridge&) = delete;
    Bridge& operator=(const Bridge&) = delete;
    Bridge(Bridge&&) = delete;
    Bridge& operator=(Bridge&&) = delete;
 
    // =========================================================================
    // Inbound — id overloads (primary implementation)
    // =========================================================================
 
    /**
     * @brief Drive element value from a Node's output each frame.
     *
     * Spawns a GraphicsRoutine that reads node->get_last_output() every tick,
     * applies @p project, and writes into the element's MappedState.
     * Node must be processed externally (EXTERNAL mode read).
     * Replaces any existing inbound binding on this element.
     *
     * @param id      Element id (from Layer::add / Mapped::element.id).
     * @param node    Node to read from.
     * @param project Optional double -> float projection. Identity if empty.
     */
    void bind(uint32_t id,
        std::shared_ptr<Nodes::Node> node,
        std::function<float(double)> project = {});
 
    /**
     * @brief Drive element value from an arbitrary per-frame callable.
     *
     * Spawns a GraphicsRoutine that calls @p source every tick and writes
     * the result into the element's MappedState.
     * Replaces any existing inbound binding on this element.
     *
     * @param id     Element id.
     * @param source Callable returning current float value.
     */
    void bind(uint32_t id, std::function<float()> source);
 
    // =========================================================================
    // Inbound — MappedState overloads
    // =========================================================================
 
    template <typename T>
    void bind(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Nodes::Node> node,
        std::function<float(double)> project = {})
    {
        bind(state->id, std::move(node), std::move(project));
    }
 
    template <typename T>
    void bind(std::shared_ptr<MappedState<T>> state, std::function<float()> source)
    {
        bind(state->id, std::move(source));
    }
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::function<void(std::span<const float>)> sink)
    {
        write(state->id, std::move(sink));
    }
 
    // =========================================================================
    // Outbound — id overloads (primary implementation)
    // =========================================================================
 
    /**
     * @brief Route element value to a push constant slot on a ShaderProcessor.
     * @param id     Element id.
     * @param target VKBuffer whose push_constant staging receives the value.
     * @param offset Byte offset in the push constant struct.
     * @param size   Byte width. Defaults to sizeof(float).
     */
    void write(
        uint32_t id,
        const std::shared_ptr<Buffers::VKBuffer>& target_buffer,
        const std::string& shader_path,
        uint32_t offset,
        size_t size = sizeof(float));
 
    /**
     * @brief Route element value to a descriptor binding on @p target_buffer.
     *
     * Creates a FormaBindingsProcessor if one does not yet exist for this element
     * and attaches it to @p target_buffer. If a processor already exists from a
     * prior write() call, @p target_buffer must be the same buffer — a second
     * attachment is not made.
     *
     * @param id              Element id.
     * @param target_buffer   Buffer whose pipeline context receives the descriptor update.
     * @param shader_path     Shader path used to construct FormaBindingsProcessor if needed.
     * @param descriptor_name Descriptor name in the shader config.
     * @param binding_index   Vulkan binding index.
     * @param set             Descriptor set index.
     * @param role            UNIFORM or STORAGE.
     */
    void write(uint32_t id,
        const std::shared_ptr<Buffers::VKBuffer>& target_buffer,
        const std::string& shader_path,
        const std::string& descriptor_name,
        uint32_t binding_index,
        uint32_t set,
        Portal::Graphics::DescriptorRole role = Portal::Graphics::DescriptorRole::UNIFORM);
 
    /**
     * @brief Route element value to an AudioWriteProcessor each frame.
     * @param id     Element id.
     * @param target AudioWriteProcessor to call set_data() on.
     */
    void write(uint32_t id, std::shared_ptr<Buffers::AudioWriteProcessor> target);
 
    /**
     * @brief Route element value to a DataWriteProcessor each frame.
     * @param id     Element id.
     * @param target DataWriteProcessor to call set_data() on.
     */
    void write(uint32_t id, std::shared_ptr<Buffers::DataWriteProcessor> target);
 
    /**
     * @brief Route element value into a Constant node via set_constant().
     * @param id   Element id.
     * @param node Constant node updated each frame.
     */
    void write(uint32_t id, std::shared_ptr<Nodes::Constant> node);
 
    /**
     * @brief Route element bulk value to a caller-supplied sink each frame.
     *
     * When the element's MappedState<T> has a bulk_reader (T is vector<float>
     * or vector<double>), the full vector is forwarded as a span. For scalar
     * T the sink receives a single-element span of the scalar value.
     *
     * Intended for consumers that operate on coefficient arrays or other
     * N-element state: FIR/IIR coefficient vectors, Random node bounds,
     * any function accepting a contiguous float range.
     *
     * @param id   Element id.
     * @param sink Callable invoked each frame with the current value span.
     */
    void write(uint32_t id, std::function<void(std::span<const float>)> sink);
 
    // =========================================================================
    // Outbound — MappedState overloads
    // =========================================================================
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Buffers::VKBuffer> target_buffer,
        const std::string& shader_path,
        uint32_t offset,
        size_t size = sizeof(float))
    {
        write(state->id, std::move(target_buffer), shader_path, offset, size);
    }
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Buffers::VKBuffer> target_buffer,
        const std::string& shader_path,
        const std::string& descriptor_name,
        uint32_t binding_index,
        uint32_t set,
        Portal::Graphics::DescriptorRole role = Portal::Graphics::DescriptorRole::UNIFORM)
    {
        write(state->id, std::move(target_buffer), shader_path,
            descriptor_name, binding_index, set, role);
    }
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Buffers::AudioWriteProcessor> target)
    {
        write(state->id, std::move(target));
    }
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Buffers::DataWriteProcessor> target)
    {
        write(state->id, std::move(target));
    }
 
    template <typename T>
    void write(std::shared_ptr<MappedState<T>> state,
        std::shared_ptr<Nodes::Constant> node)
    {
        write(state->id, std::move(node));
    }
 
    // =========================================================================
    // Registration — called by Forma::create_element to make state findable
    // =========================================================================
 
    /**
     * @brief Register a MappedState<T> so that MappedState overloads and
     *        outbound bindings can resolve to the correct element id and reader.
     *
     * Called by Forma::create_element. The reader closes over the MappedState
     * and is stored type-erased as std::function<float()>.
     *
     * @tparam T        MappedState value type.
     * @param state     MappedState to register.
     * @param id        Element id from Layer::add.
     * @param buffer    FormaBuffer the element renders into.
     * @param project   Optional T -> float projection. Identity cast if empty.
     */
    template <typename T>
    void register_element(
        std::shared_ptr<MappedState<T>> state,
        uint32_t id,
        std::shared_ptr<Buffers::FormaBuffer> buffer,
        std::function<float(T)> project = {})
    {
        std::function<float()> reader;
        if (project) {
            reader = [s = state, p = std::move(project)] {
                return p(s->value);
            };
        } else if constexpr (std::is_convertible_v<T, float>) {
            reader = [s = state] {
                return static_cast<float>(s->value);
            };
        } else {
            reader = [] { return 0.F; };
        }
 
        std::function<std::vector<float>()> bulk_reader;
        if constexpr (std::is_same_v<T, std::vector<float>>) {
            bulk_reader = [s = state] { return s->value; };
        } else if constexpr (std::is_same_v<T, std::vector<double>>) {
            bulk_reader = [s = state] {
                std::vector<float> out;
                out.reserve(s->value.size());
                for (double v : s->value)
                    out.push_back(static_cast<float>(v));
                return out;
            };
        }
 
        std::function<void(float)> writer;
        if constexpr (std::is_convertible_v<float, T>) {
            writer = [s = state](float v) {
                s->write(static_cast<T>(v));
            };
        } else {
            writer = [](float) { };
        }
 
        state->id = id;
        m_records[id] = ElementRecord {
            .buffer = std::move(buffer),
            .bindings = nullptr,
            .reader = std::move(reader),
            .bulk_reader = std::move(bulk_reader),
            .writer = std::move(writer),
            .inbound_task = {},
            .outbound_tasks = {},
        };
    }
 
    /**
     * @brief Register a fully constructed Mapped<T> and own its sync loop.
     *
     * Delegates record and reader/writer setup to the existing
     * register_element overload, then spawns a per-frame GraphicsRoutine
     * that calls mapped.sync(). The routine is stored in outbound_tasks
     * and cancelled by unbind().
     *
     * @p mapped must outlive the Bridge registration.
     *
     * @tparam T      MappedState value type.
     * @param mapped  Fully constructed Mapped<T>, typically from create_element.
     * @param project Optional T -> float projection for outbound readers.
     *                Identity cast used if empty.
     */
    template <typename T>
    void register_element(Mapped<T> mapped, std::function<float(T)> project = {})
    {
        register_element(mapped.state, mapped.element.id, mapped.element.buffer, std::move(project));
        spawn_sync(mapped.element.id, [m = std::move(mapped)]() mutable { m.sync(); });
    }
 
    // =========================================================================
    // Binding lifecycle
    // =========================================================================
 
    /**
     * @brief Cancel all inbound and outbound bindings for an element.
     *        The element remains in its layer.
     */
    void unbind(uint32_t id);
 
    template <typename T>
    void unbind(std::shared_ptr<MappedState<T>> state)
    {
        unbind(state->id);
    }
 
    // =========================================================================
    // Binding handle
    // =========================================================================
 
    /**
     * @class Binding
     * @brief Non-owning handle for all bind/write/unbind operations on one element.
     *
     * Obtained via Bridge::at(id) or Bridge::at(state). Closes over the
     * Bridge reference and the element id so the caller never repeats either.
     * Every method forwards directly to the corresponding Bridge overload:
     * there is no deferred execution, no new mechanism.
     *
     * Binding holds a reference to its Bridge and must not outlive it.
     *
     * @code
     * bridge.at(el.element.id)
     *     .bind(envelope_node)
     *     .write(compute_buf, shader_path, offsetof(PC, cutoff))
     *     .write(audio_proc);
     * @endcode
     */
    class Binding {
    public:
        Binding(Bridge& bridge, uint32_t id) noexcept
            : m_bridge(bridge)
            , m_id(id)
        {
        }
 
        [[nodiscard]] uint32_t id() const noexcept { return m_id; }
 
        Binding& bind(std::shared_ptr<Nodes::Node> node,
            std::function<float(double)> project = {})
        {
            m_bridge.bind(m_id, std::move(node), std::move(project));
            return *this;
        }
 
        Binding& bind(std::function<float()> source)
        {
            m_bridge.bind(m_id, std::move(source));
            return *this;
        }
 
        Binding& write(
            const std::shared_ptr<Buffers::VKBuffer>& target,
            const std::string& shader_path,
            uint32_t offset,
            size_t size = sizeof(float))
        {
            m_bridge.write(m_id, target, shader_path, offset, size);
            return *this;
        }
 
        Binding& write(
            const std::shared_ptr<Buffers::VKBuffer>& target,
            const std::string& shader_path,
            const std::string& descriptor_name,
            uint32_t binding_index,
            uint32_t set,
            Portal::Graphics::DescriptorRole role = Portal::Graphics::DescriptorRole::UNIFORM)
        {
            m_bridge.write(m_id, target, shader_path,
                descriptor_name, binding_index, set, role);
            return *this;
        }
 
        Binding& write(std::shared_ptr<Buffers::AudioWriteProcessor> target)
        {
            m_bridge.write(m_id, std::move(target));
            return *this;
        }
 
        Binding& write(std::shared_ptr<Buffers::DataWriteProcessor> target)
        {
            m_bridge.write(m_id, std::move(target));
            return *this;
        }
 
        Binding& write(std::shared_ptr<Nodes::Constant> node)
        {
            m_bridge.write(m_id, std::move(node));
            return *this;
        }
 
        Binding& write(std::function<void(std::span<const float>)> sink)
        {
            m_bridge.write(m_id, std::move(sink));
            return *this;
        }
 
        void unbind()
        {
            m_bridge.unbind(m_id);
        }
 
    private:
        Bridge& m_bridge;
        uint32_t m_id;
    };
 
    // =========================================================================
    // at() — entry point for the Binding handle
    // =========================================================================
 
    /**
     * @brief Return a Binding handle for the element registered under @p id.
     *
     * The handle is lightweight and non-owning. Prefer this over repeated
     * bind(id, ...) / write(id, ...) calls when wiring one element to
     * multiple sources or destinations.
     */
    [[nodiscard]] Binding at(uint32_t id)
    {
        return Binding { *this, id };
    }
 
    /**
     * @brief Return a Binding handle resolved from a MappedState.
     */
    template <typename T>
    [[nodiscard]] Binding at(const std::shared_ptr<MappedState<T>>& state)
    {
        return Binding(*this, state->id);
    }
 
    /**
     * @brief Spawn a per-frame GraphicsRoutine that calls @p sync_fn each tick.
     *
     * Stores the task name in the outbound_tasks of the record for @p id so
     * that unbind() cancels it correctly. The coroutine body is type-free --
     * all type-specific work is captured inside @p sync_fn by the caller.
     *
     * @param id       Element id whose outbound_tasks receives the task name.
     * @param sync_fn  Callable invoked once per frame. Typically a lambda
     *                 capturing Mapped<T> by reference and calling sync().
     */
    void spawn_sync(uint32_t id, std::function<void()> sync_fn);
 
private:
    struct ElementRecord {
        std::shared_ptr<Buffers::FormaBuffer> buffer;
        std::shared_ptr<Buffers::FormaBindingsProcessor> bindings;
        std::function<float()> reader; ///< reads current value from MappedState (outbound)
        std::function<std::vector<float>()> bulk_reader; ///< populated for vector<float>/vector<double> T
        std::function<void(float)> writer; ///< writes new value into MappedState (inbound)
        std::string inbound_task;
        std::vector<std::string> outbound_tasks;
    };
 
    Vruta::TaskScheduler& m_scheduler;
    Buffers::BufferManager& m_buffer_manager;
 
    mutable uint32_t m_next_id { 0 };
 
    std::unordered_map<uint32_t, ElementRecord> m_records;
 
    std::string make_task_name(uint32_t id, const char* suffix) const;
    void cancel_inbound(ElementRecord& rec);
    void cancel_outbound(ElementRecord& rec);
    void spawn_inbound(uint32_t id, std::function<float()> source);
};
 
} // namespace MayaFlux::Portal::Forma