Chronie.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/IO/Keys.hpp"
#include "MayaFlux/Kriya/Pattern.hpp"
 
namespace MayaFlux {
 
namespace Core {
    class Window;
    struct NetworkMessage;
    struct EndpointInfo;
}
 
namespace Nodes {
    class Node;
}
 
namespace Vruta {
    class TaskScheduler;
    class EventManager;
    class SoundRoutine;
    class GraphicsRoutine;
    class FreeRoutine;
    class NetworkSource;
}
 
namespace IO {
    class IOManager;
}
 
namespace Kriya {
    class BufferPipeline;
}
 
/**
 * @brief Gets the task scheduler from the default engine
 * @return Shared pointer to the centrally managed TaskScheduler
 *
 * Returns the scheduler that's managed by the default engine instance.
 * All scheduled tasks using the convenience functions will use this scheduler.
 */
MAYAFLUX_API std::shared_ptr<Vruta::TaskScheduler> get_scheduler();
 
/**
 * @brief Gets the event manager from the default engine
 * @return Shared pointer to the centrally managed EventManager
 *
 * Returns the event manager that's managed by the default engine instance.
 * Used for handling windowing and input events.
 */
MAYAFLUX_API std::shared_ptr<Vruta::EventManager> get_event_manager();
 
/**
 * @brief Creates a metronome task and addes it to the default scheduler list for evaluation
 * @param interval_seconds Time between calls in seconds
 * @param callback Function to call on each tick
 * @param name Name of the metronome task (optional but recommended).
     If not provided, a default name will be generated.
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 *
 * Uses the task scheduler from the default engine.
 */
MAYAFLUX_API void schedule_metro(double interval_seconds, std::function<void()> callback, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE);
 
/**
 * @brief Creates a sequence task that calls functions at specified times
 * and addes it to the default scheduler list for evaluation
 * @param sequence Vector of (time, function) pairs
 * @param name Name of the metronome task (optional but recommended).
     If not provided, a default name will be generated.
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 *
 * Uses the task scheduler from the default engine.
 */
MAYAFLUX_API void schedule_sequence(std::vector<std::pair<double, std::function<void()>>> sequence, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE);
 
/**
 * @brief Creates a line generator that interpolates between values over time and schedules it for evaluation
 * @param start_value Starting value
 * @param end_value Ending value
 * @param duration_seconds Total duration in seconds
 * @param step_duration Time between steps in seconds
 * @param retain Whether the coroutine should stay alive for potential restarts (default: true)
 * @param name Name of the line task (optional but recommended).
     If not provided, a default name will be generated.
 * @return shared_ptr to SoundRoutine object representing the line generator
 *
 * Uses the task scheduler from the default engine.
 */
MAYAFLUX_API std::shared_ptr<Vruta::SoundRoutine> schedule_line(float start_value, float end_value, float duration_seconds, uint32_t step_duration = 5, bool retain = true, std::string name = "");
 
/**
 * @brief Schedules a pattern generator whose steps are spaced by a list of durations
 * @param pattern_func Function that generates pattern values based on step index
 * @param callback Function to call with each pattern value
 * @param durations Seconds to wait after each step, stepped through in order and repeated
 * @param name Name of the pattern task (optional but recommended).
     If not provided, a default name will be generated.
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 *
 * A single interval is a list of one. Uses the task scheduler from the default engine.
 */
MAYAFLUX_API void schedule_pattern(std::function<std::any(uint64_t)> pattern_func, std::function<void(std::any)> callback, std::vector<double> durations, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE);
 
/**
 * @brief Schedules a pattern generator with one interval between steps
 * @param pattern_func Function that generates pattern values based on step index
 * @param callback Function to call with each pattern value
 * @param interval_seconds Time between pattern steps
 * @param name Name of the pattern task (optional but recommended).
     If not provided, a default name will be generated.
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 * @deprecated Pass a list of durations instead, with the interval as a list of one.
 *
 * Forwards to the durations overload. Uses the task scheduler from the default engine.
 */
[[deprecated("Pass a std::vector<double> of durations; a single interval is a list of one")]]
MAYAFLUX_API void schedule_pattern(std::function<std::any(uint64_t)> pattern_func, std::function<void(std::any)> callback, double interval_seconds, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE);
 
/**
 * @brief Gets a pointer to a task's current value
 * @param name Name of the task
 * @return Pointer to the float value, or nullptr if not found
 */
MAYAFLUX_API float* get_line_value(const std::string& name);
 
/**
 * @brief Schedules a new sound routine task
 * @param name Unique name for the task
 * @param task The sound routine to schedule
 * @param initialize Whether to initialize the task immediately
 */
MAYAFLUX_API void schedule_task(const std::string& name, Vruta::SoundRoutine&& task, bool initialize = false);
 
/**
 * @brief Schedules a new sound routine task
 * @param name Unique name for the task
 * @param task The sound routine to schedule
 * @param initialize Whether to initialize the task immediately
 */
MAYAFLUX_API void schedule_task(const std::string& name, Vruta::GraphicsRoutine&& task, bool initialize = false);
 
/**
 * @brief Schedules a new free routine conditional task
 * @param name Unique name for the task
 * @param task The sound routine to schedule
 * @param initialize Whether to initialize the task immediately
 */
MAYAFLUX_API void schedule_task(const std::string& name, Vruta::FreeRoutine&& task, bool initialize = false);
 
/**
 * @brief Schedules a routine of any type that is already held by a shared_ptr
 * @param name Unique name for the task. If empty, the scheduler generates one.
 * @param task The routine to schedule, for example the result of Kriya::pattern; a null routine is reported and ignored
 * @param initialize Whether to initialize the task immediately
 *
 * Covers every routine type, including cross routines, which have no rvalue overload.
 */
MAYAFLUX_API void schedule_task(const std::string& name, const std::shared_ptr<Vruta::Routine>& task, bool initialize = false);
 
/**
 * @brief Schedules a typed pattern whose steps are spaced by a list of durations
 * @tparam Index Step index type, default uint64_t
 * @param generator Callable from the step index to any value
 * @param callback Callable that takes the generated value
 * @param durations Seconds to wait after each step, stepped through in order and repeated
 * @param name Name of the pattern task (optional but recommended)
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 *
 * The value type is whatever the generator returns, so no std::any is involved.
 * `schedule_pattern(gen, cb, { 0.25, 0.5 })` selects this overload.
 */
template <std::incrementable Index = uint64_t, typename Generator, typename Callback>
    requires Kriya::PatternGenerator<Generator, Index>
    && Kriya::PatternCallback<Callback, typename Kriya::PatternTraits<Generator, Index>::value_type>
void schedule_pattern(Generator generator, Callback callback, std::vector<double> durations, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE)
{
    schedule_task(name, Kriya::pattern<Index>(std::move(generator), std::move(callback), std::move(durations), token));
}
 
/**
 * @brief Schedules a typed pattern driven by a condition or by a durations function
 * @tparam Index Step index type, default uint64_t
 * @param generator Callable from the step index to any value
 * @param callback Callable that takes the generated value
 * @param third A condition returning bool for the step index, or a function from a pass number to a range of seconds
 * @param name Name of the pattern task (optional but recommended)
 * @param token Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)
 *
 * Forwards to Kriya::pattern, which describes both forms. A condition runs a step each time it holds;
 * a durations function is asked once per pass and ends the pattern on an empty array.
 */
template <std::incrementable Index = uint64_t, typename Generator, typename Callback, typename Third>
    requires Kriya::PatternGenerator<Generator, Index>
    && Kriya::PatternCallback<Callback, typename Kriya::PatternTraits<Generator, Index>::value_type>
    && (Kriya::PatternCondition<Third, Index> || Kriya::PatternDurationSource<Third>)
void schedule_pattern(Generator generator, Callback callback, Third third, std::string name = "", Vruta::ProcessingToken token = Vruta::ProcessingToken::SAMPLE_ACCURATE)
{
    schedule_task(name, Kriya::pattern<Index>(std::move(generator), std::move(callback), std::move(third), token));
}
 
/**
 * @brief Cancels a scheduled task
 * @param name Name of the task to cancel
 * @return true if task was found and canceled, false otherwise
 */
MAYAFLUX_API bool cancel_task(const std::string& name);
 
/**
 * @brief Restarts a scheduled task
 * @param name Name of the task to restart
 * @return true if task was found and restarted, false otherwise
 */
MAYAFLUX_API bool restart_task(const std::string& name);
 
/**
 * @brief Updates parameters of a scheduled task
 * @tparam Args Parameter types
 * @param name Name of the task to update
 * @param args New parameter values
 * @return true if task was found and updated, false otherwise
 */
template <typename... Args>
MAYAFLUX_API bool update_task_params(const std::string& name, Args... args);
 
/**
 * @brief Creates a new buffer pipeline instance
 * @return Shared pointer to the created BufferPipeline
 *
 * Uses the task scheduler from the default engine.
 */
MAYAFLUX_API std::shared_ptr<Kriya::BufferPipeline> create_buffer_pipeline();
 
/**
 * @brief Creates a buffer pipeline that can reach an IOManager
 * @param io_manager IOManager the pipeline uses to display stream routes
 * @return Shared pointer to the created BufferPipeline
 *
 * Needed only for operations that open a display on a video stream, such as
 * route_to_container with a render config. Pipelines made without it, audio
 * ones included, carry no IOManager.
 */
MAYAFLUX_API std::shared_ptr<Kriya::BufferPipeline> create_buffer_pipeline(std::shared_ptr<IO::IOManager> io_manager);
 
/**
 * @brief Schedule a key press handler
 * @param window Window to listen to
 * @param key Key to wait for
 * @param callback Function to call on key press
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_key_pressed(window, MayaFlux::IO::Keys::Escape, []() {
 *     // Handle Escape key press
 * }, "escape_handler");
 * @endcode
 */
MAYAFLUX_API void on_key_pressed(
    const std::shared_ptr<Core::Window>& window,
    IO::Keys key,
    std::function<void()> callback,
    std::string name = "");
 
/**
 * @brief Schedule a key release handler
 * @param window Window to listen to
 * @param key Key to wait for
 * @param callback Function to call on key release
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_key_released(window, MayaFlux::IO::Keys::Enter, []() {
 *     // Handle Enter key release
 * }, "enter_release_handler");
 * @endcode
 */
MAYAFLUX_API void on_key_released(
    const std::shared_ptr<Core::Window>& window,
    IO::Keys key,
    std::function<void()> callback,
    std::string name = "");
 
/**
 * @brief Schedule a handler for any key press
 * @param window Window to listen to
 * @param callback Function to call with key code when any key is pressed
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_any_key(window, [](MayaFlux::IO::Keys key) {
 *     // Handle any key press, key code in 'key'
 * }, "any_key_handler");
 * @endcode
 */
MAYAFLUX_API void on_any_key(
    const std::shared_ptr<Core::Window>& window,
    std::function<void(IO::Keys)> callback,
    std::string name = "");
 
/**
 * @brief Schedule a mouse button press handler
 * @param window Window to listen to
 * @param button Mouse button to wait for
 * @param callback Function to call on button press (x, y)
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_mouse_pressed(window, MayaFlux::IO::MouseButtons::Left, [](double x, double y) {
 *     // Handle left mouse button press at (x, y)
 * }, "mouse_left_press_handler");
 * @endcode
 */
MAYAFLUX_API void on_mouse_pressed(
    const std::shared_ptr<Core::Window>& window,
    IO::MouseButtons button,
    std::function<void(double, double)> callback,
    std::string name = "");
 
/**
 * @brief Schedule a mouse button release handler
 * @param window Window to listen to
 * @param button Mouse button to wait for
 * @param callback Function to call on button release (x, y)
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_mouse_released(window, MayaFlux::IO::MouseButtons::Right, [](double x, double y) {
 *     // Handle right mouse button release at (x, y)
 * }, "mouse_right_release_handler");
 * @endcode
 */
MAYAFLUX_API void on_mouse_released(
    const std::shared_ptr<Core::Window>& window,
    IO::MouseButtons button,
    std::function<void(double, double)> callback,
    std::string name = "");
 
/**
 * @brief Schedule a mouse movement handler
 * @param window Window to listen to
 * @param callback Function to call on mouse move (x, y)
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_mouse_move(window, [](double x, double y) {
 *     // Handle mouse move at (x, y)
 * }, "mouse_move_handler");
 * @endcode
 */
MAYAFLUX_API void on_mouse_move(
    const std::shared_ptr<Core::Window>& window,
    std::function<void(double, double)> callback,
    std::string name = "");
 
/**
 * @brief Schedule a mouse drag handler
 * @param window Window to listen to
 * @param button Mouse button that must be held for dragging
 * @param callback Function to call on mouse drag (x, y)
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_mouse_drag(window, MayaFlux::IO::MouseButtons::Left, [](double x, double y) {
 *     // Handle mouse drag with left button at (x, y)
 * }, "mouse_left_drag_handler");
 * @endcode
 */
MAYAFLUX_API void on_mouse_drag(
    const std::shared_ptr<Core::Window>& window,
    IO::MouseButtons button,
    std::function<void(double, double)> callback,
    std::string name = "");
 
/**
 * @brief Schedule a mouse scroll handler
 * @param window Window to listen to
 * @param callback Function to call on scroll (xoffset, yoffset)
 * @param name Optional name for the event handler
 *
 * Example:
 * @code
 * MayaFlux::on_scroll(window, [](double xoffset, double yoffset) {
 *     // Handle mouse scroll with offsets
 * }, "mouse_scroll_handler");
 * @endcode
 */
MAYAFLUX_API void on_scroll(
    const std::shared_ptr<Core::Window>& window,
    std::function<void(double, double)> callback,
    std::string name = "");
 
/**
 * @brief Cancel an event handler by name
 * @param name Event handler name
 * @return True if cancelled successfully
 */
MAYAFLUX_API bool cancel_event_handler(const std::string& name);
 
/**
 * @brief Converts a time duration in seconds to the equivalent number of audio samples
 * @param seconds Time duration in seconds
 * @return Equivalent number of audio samples based on the current sample rate
 *
 * This function uses the sample rate from the default engine to calculate how many
 * audio samples correspond to the given time duration in seconds. It's useful for
 * scheduling tasks or processing buffers based on time intervals.
 */
MAYAFLUX_API uint64_t seconds_to_samples(double seconds);
 
/**
 * @brief Converts a time duration in seconds to the equivalent number of processing blocks
 * @param seconds Time duration in seconds
 * @return Equivalent number of blocks based on current sample rate and block size
 *
 * Uses the sample rate and block size from the default engine. Falls back to
 * 48kHz/512 samples if engine is not running.
 */
MAYAFLUX_API uint64_t seconds_to_blocks(double seconds);
 
/**
 * @brief Converts samples to blocks based on current block size
 * @param samples Number of samples
 * @return Number of blocks
 */
MAYAFLUX_API uint64_t samples_to_blocks(uint64_t samples);
 
/**
 * @brief Converts a number of audio samples to the equivalent time duration in seconds
 * @param samples Number of audio samples
 * @return Time duration in seconds based on the current sample rate
 */
MAYAFLUX_API double samples_to_seconds(uint64_t samples);
 
/**
 * @brief Schedule an on_message handler with an existing NetworkSource
 * @param source   Shared NetworkSource; coroutine frame takes co-ownership
 * @param callback Invoked with each received message
 * @param name     Optional name for the event handler
 *
 * @code
 * auto src = std::make_shared<Vruta::NetworkSource>(
 *     Core::EndpointInfo{ .transport = Core::NetworkTransport::UDP, .local_port = 8000 });
 * MayaFlux::on_network_message(src, [](const Core::NetworkMessage& msg) { });
 * @endcode
 */
MAYAFLUX_API void on_network_message(
    std::shared_ptr<Vruta::NetworkSource> source,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
/**
 * @brief Schedule an on_message handler, constructing the NetworkSource from config
 * @param info     Endpoint configuration used to open the source
 * @param callback Invoked with each received message
 * @param name     Optional name for the event handler
 * @return Shared pointer to the opened NetworkSource (caller owns lifetime anchor)
 *
 * @code
 * auto src = MayaFlux::on_network_message(
 *     Core::EndpointInfo{ .transport = Core::NetworkTransport::UDP, .local_port = 8000 },
 *     [](const Core::NetworkMessage& msg) { });
 * @endcode
 */
MAYAFLUX_API std::shared_ptr<Vruta::NetworkSource> on_network_message(
    const Core::EndpointInfo& info,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
/**
 * @brief Schedule an on_message_from handler with an existing NetworkSource
 * @param source         Shared NetworkSource
 * @param sender_address Sender IP address to filter on
 * @param callback       Invoked with each matching message
 * @param name           Optional name for the event handler
 */
MAYAFLUX_API void on_network_message_from(
    std::shared_ptr<Vruta::NetworkSource> source,
    std::string sender_address,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
/**
 * @brief Schedule an on_message_from handler, constructing the NetworkSource from config
 * @param info           Endpoint configuration used to open the source
 * @param sender_address Sender IP address to filter on
 * @param callback       Invoked with each matching message
 * @param name           Optional name for the event handler
 * @return Shared pointer to the opened NetworkSource
 */
MAYAFLUX_API std::shared_ptr<Vruta::NetworkSource> on_network_message_from(
    const Core::EndpointInfo& info,
    std::string sender_address,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
/**
 * @brief Schedule an on_message_matching handler with an existing NetworkSource
 * @param source    Shared NetworkSource
 * @param predicate Filter; only matching messages invoke callback
 * @param callback  Invoked with each matching message
 * @param name      Optional name for the event handler
 */
MAYAFLUX_API void on_network_message_matching(
    std::shared_ptr<Vruta::NetworkSource> source,
    std::function<bool(const Core::NetworkMessage&)> predicate,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
/**
 * @brief Schedule an on_message_matching handler, constructing the NetworkSource from config
 * @param info      Endpoint configuration used to open the source
 * @param predicate Filter; only matching messages invoke callback
 * @param callback  Invoked with each matching message
 * @param name      Optional name for the event handler
 * @return Shared pointer to the opened NetworkSource
 */
MAYAFLUX_API std::shared_ptr<Vruta::NetworkSource> on_network_message_matching(
    const Core::EndpointInfo& info,
    std::function<bool(const Core::NetworkMessage&)> predicate,
    std::function<void(const Core::NetworkMessage&)> callback,
    std::string name = "");
 
}