Forma.hpp

Go to the documentation of this file.

#pragma once
 
#include "Primitives/Picker.hpp"
#include "Tend.hpp"
 
namespace MayaFlux::Vruta {
class Event;
}
 
namespace MayaFlux::Portal::Forma {
 
/**
 * @file Forma.hpp
 * @brief Factory free functions for the Forma surface system.
 *
 * Call initialize() once after engine startup to store BufferManager,
 * TaskScheduler, and EventManager references. Subsequent factory calls
 * require only the arguments that legitimately vary per call (Window,
 * geometry function, initial value). This matches the Portal::Text and
 * Portal::Graphics initialization contracts.
 *
 * Typical sequence:
 * @code
 * Portal::Forma::initialize(buffer_manager, scheduler, event_manager);
 *
 * auto surface = Forma::create_surface(SurfaceConfig { .window = window, .name = "hud" });
 *
 * auto el = Forma::create_element<float>(surface, geom_fn, 0.5f);
 *
 * auto bridge = Forma::create_bridge();
 * 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
 */
 
// =============================================================================
// Lifecycle
// =============================================================================
 
/**
 * @brief Store engine-level references for use by all subsequent Forma calls.
 *
 * Must be called before any create_* call. Safe to call multiple times;
 * subsequent calls are no-ops and log a warning.
 *
 * @param node_graph_manager Engine NodeGraphManager. Must outlive all Forma objects.
 * @param buffer_manager  Engine BufferManager. Must outlive all Forma objects.
 * @param scheduler       Engine TaskScheduler. Must outlive all Bridge instances.
 * @param event_manager   Engine EventManager. Must outlive all Context instances.
 * @param window_manager  Engine WindowManager. Must outlive all Surface instances.
 * @return True on success, false if any argument is null.
 */
MAYAFLUX_API bool initialize(
    std::shared_ptr<Nodes::NodeGraphManager> node_graph_manager,
    std::shared_ptr<Buffers::BufferManager> buffer_manager,
    std::shared_ptr<Vruta::TaskScheduler> scheduler,
    std::shared_ptr<Vruta::EventManager> event_manager,
    std::shared_ptr<Core::WindowManager> window_manager);
 
/**
 * @brief Release stored references. Does not destroy any Forma objects.
 *
 * Call after all Forma objects have been destroyed, before engine shutdown.
 */
MAYAFLUX_API void shutdown();
 
/** @brief Whether initialize() has been called successfully. */
MAYAFLUX_API bool is_initialized();
 
/**
 * @brief Return the application-level Bridge instance.
 *
 * Valid only after initialize(). Lifetime is tied to the Forma module.
 */
[[nodiscard]] MAYAFLUX_API Bridge& bridge();
 
/**
 * @brief Access the Forma introspection subsystem.
 *
 * Returns the Inspector instance initialized alongside Bridge during
 * Portal::Forma::initialize(). The Inspector holds no state beyond
 * references to BufferManager and NodeGraphManager; it is a stable
 * entry point into the Inspect:: query functions.
 *
 * @pre Portal::Forma::initialize() must have been called.
 * @return Reference to the singleton Inspector. Lifetime is the Forma module lifetime.
 * @throws std::runtime_error if called before initialize().
 */
[[nodiscard]] MAYAFLUX_API Inspector& inspector();
 
// =============================================================================
// Layer
// =============================================================================
 
/**
 * @brief Construct a Layer and a Context wired to @p window.
 *
 * EventManager is taken from the stored initialize() state.
 * The caller owns both returned objects. The Context cancels its event
 * coroutines on destruction.
 *
 * @param window  Target window surface.
 * @param name    Unique name scoping the Context's event coroutines.
 * @return Pair of { shared_ptr<Layer>, shared_ptr<Context> }.
 */
[[nodiscard]] MAYAFLUX_API
    std::pair<std::shared_ptr<Layer>, std::shared_ptr<Context>>
    create_layer(
        const std::shared_ptr<Core::Window>& window,
        std::string name);
 
// =============================================================================
// Standalone buffer
// =============================================================================
 
/**
 * @brief Construct and register a FormaBuffer without creating a Mapped<T>.
 *
 * The buffer triangulates, so slices of any topology draw together as one
 * batch. Elements draw into slices of it, made with FormaTarget::slice_of,
 * each carrying its own topology. BufferManager is taken from the stored
 * initialize() state.
 *
 * With the default multi-texture shader, positive vertex weights select an
 * image and negative weights select glyph coverage. A custom fragment shader
 * can use different semantics, as the plot shader does for line and point
 * geometry mixed with glyphs.
 *
 * @param render Render settings; build it with Surface::render_config, which
 *               sets the window. Textures, shaders and the rest are the
 *               caller's.
 * @return Registered, render-ready FormaBuffer.
 */
[[nodiscard]] MAYAFLUX_API
    std::shared_ptr<Buffers::FormaBuffer>
    create_buffer(Graphics::RenderConfig render);
 
// =============================================================================
// Element
// =============================================================================
 
/**
 * @brief Construct a Surface from a SurfaceConfig.
 *
 * When @p config.layer/@p config.ctx are unset, builds a fresh Layer and a
 * Context wired to @p config.window using the EventManager stored by
 * Portal::Forma::initialize, from @p config.name. Set @p config.layer/
 * @p config.ctx yourself for the power-tinkerer case (custom Context
 * subclass, shared Layer across multiple Contexts, etc.) - @p config.name is
 * ignored when both are already set.
 *
 * @param config Window, name, optional pre-built Layer/Context, and
 *               close-handling behavior.
 * @pre Portal::Forma::initialize() must have been called.
 * @return A new Surface owning the window pointer plus the Layer and
 *         Context, built fresh or supplied.
 */
[[nodiscard]] MAYAFLUX_API Surface create_surface(SurfaceConfig config);
 
/**
 * @brief Tear down an element and everything related to it.
 *
 * The symmetric counterpart to create_element/create<T>/create_text_field:
 * walks surface.layer().closure(id) (id plus every id transitively
 * related via Layer::relate, e.g. a Collapsible's attached body, a
 * Scrollable's tracked rows, or a TextField's Scrollable viewport), calls
 * Context::unbind and Bridge::unbind on each id in that closure, then
 * Layer::remove(id) - which itself cascades the Layer-side removal
 * (buffer mark_for_removal, m_elements erase, m_relations cleanup) across
 * the same closure.
 *
 * This is the one call callers should use to tear down a composed Forma
 * element. Layer::remove(id) alone is still available for callers that
 * only need the Layer-side cascade with no Context/Bridge involvement.
 *
 * @param surface Surface owning the Layer, Context, and (via the module
 *                Bridge) the bindings @p id may participate in.
 * @param id      Element id to remove, as returned by layer().add()/Slot::id().
 */
MAYAFLUX_API void destroy(Surface& surface, uint32_t id);
 
/**
 * @brief Create a live plot in a new window.
 *
 * Creates the window, shows it, constructs the Surface, and places the plot
 * in a slice of one batch. Background, legend swatches and labels use slices
 * of that batch; a plot with labels selects the glyph-capable plot shader.
 * Returns the Mapped<shared_ptr<PlotContainer>> from Plot::place, plus the
 * Surface owning the window and layer.
 *
 * @param title      Window title.
 * @param width      Window width in pixels.
 * @param height     Window height in pixels.
 * @param container  Ready PlotContainer from Plot::source().build().
 * @param spec       SeriesSpec from Plot::series()...done().
 * @return Pair of { Mapped<shared_ptr<PlotContainer>>, Surface } for the created plot.
 */
[[nodiscard]] MAYAFLUX_API
    std::pair<Mapped<std::shared_ptr<Kakshya::PlotContainer>>, Surface>
    plot(
        std::string title,
        uint32_t width,
        uint32_t height,
        std::shared_ptr<Kakshya::PlotContainer> container,
        Plot::SeriesSpec spec);
 
// =============================================================================
// Introspection
// =============================================================================
 
/**
 * @brief Open or show the NodeGraphManager inspection window.
 *
 * First call creates a dedicated window, builds the InspectResult, and
 * schedules tap_all() via Bridge. Subsequent calls show() the existing window.
 */
MAYAFLUX_API void inspect_node_graph();
 
/**
 * @brief Open or show the BufferManager inspection window.
 *
 * First call creates a dedicated window, builds the InspectResult, and
 * schedules tap_all() via Bridge. Subsequent calls show() the existing window.
 */
MAYAFLUX_API void inspect_buffers();
 
/**
 * @brief Open or show the TaskScheduler inspection window.
 *
 * First call creates a dedicated window, builds the InspectResult, and
 * schedules tap_all() via Bridge. Subsequent calls show() the existing window.
 */
MAYAFLUX_API void inspect_scheduler();
 
/**
 * @brief Open or show the EventManager inspection window.
 *
 * First call creates a dedicated window, builds the InspectResult, and
 * schedules tap_all() via Bridge. Subsequent calls show() the existing window.
 */
MAYAFLUX_API void inspect_events();
 
/**
 * @brief Open a dedicated window inspecting a single Node and its modulator tree.
 */
MAYAFLUX_API void inspect(const std::shared_ptr<Nodes::Node>& node);
 
/**
 * @brief Open a dedicated window inspecting a single Buffer and its processing chain.
 */
MAYAFLUX_API void inspect(const std::shared_ptr<Buffers::Buffer>& buf);
 
/**
 * @brief Open a dedicated window inspecting a NodeNetwork.
 */
MAYAFLUX_API void inspect(const std::shared_ptr<Nodes::Network::NodeNetwork>& net);
 
/**
 * @brief Open a dedicated window inspecting a single Event.
 */
MAYAFLUX_API void inspect(const std::shared_ptr<Vruta::Event>& ev, std::string_view name = {});
 
} // namespace MayaFlux::Portal::Forma