Core.hpp

Go to the documentation of this file.

#pragma once
 
/**
 * @file API/Core.hpp
 * @brief Core engine lifecycle and configuration API
 *
 * This header provides the fundamental engine control and configuration
 * functions that form the foundation of the MayaFlux framework. All other
 * subsystems depend on the engine being properly initialized and configured.
 *
 * The Core API handles:
 * - Engine initialization with various stream configurations
 * - Engine lifecycle management (Start, Pause, Resume, End)
 * - Access to core engine context and configuration
 * - Global stream information queries
 *
 * This is typically the first API users interact with when setting up
 * a MayaFlux application, and other API modules depend on these functions
 * for accessing engine subsystems.
 */
namespace MayaFlux {
 
namespace Core {
    struct GlobalStreamInfo;
    struct GlobalGraphicsConfig;
    struct GlobalInputConfig;
    struct GlobalNetworkConfig;
    class Engine;
}
 
//-------------------------------------------------------------------------
// Engine Management
//-------------------------------------------------------------------------
 
/**
 * @brief Checks if the default engine has been initialized
 * @return true if the engine is initialized, false otherwise
 */
MAYAFLUX_API bool is_initialized();
 
/**
 * @brief Checks if the default engine has currently accepted all configurations and initialized all managers
 * @return true if the engine is fully configured and ready for processing, false otherwise
 */
MAYAFLUX_API bool is_configured();
 
/**
 * @brief Gets the default engine instance
 * @return Reference to the default Engine
 *
 * Creates the engine if it doesn't exist yet. This is the centrally managed
 * engine instance that all convenience functions in this namespace operate on.
 */
MAYAFLUX_API Core::Engine& get_context();
 
/**
 * @brief Initializes the default engine with specified parameters
 * @param sample_rate Audio sample rate in Hz
 * @param buffer_size Size of audio processing buffer in frames
 * @param num_out_channels Number of output channels
 * @param num_in_channels Number of input channels
 *
 * Convenience wrapper for Engine::Init() on the default engine.
 */
MAYAFLUX_API void Init(uint32_t sample_rate, uint32_t buffer_size = 512, uint32_t num_out_channels = 2, uint32_t num_in_channels = 0);
 
/**
 * @brief Initializes the default engine with default settings
 *
 * Convenience wrapper for Engine::Init() on the default engine.
 */
MAYAFLUX_API void Init();
 
/**
 * @brief Initializes the default engine with specified stream and graphics info
 * @param stream_info Configuration for sample rate, buffer size, and channels
 * @param graphics_info Configuration for graphics/windowing backend
 * @param input_config Configuration for input handling
 * @param network_config Configuration for network subsystem
 *
 * Convenience wrapper for Engine::Init() on the default engine.
 */
MAYAFLUX_API void Init(Core::GlobalStreamInfo stream_info, Core::GlobalGraphicsConfig graphics_config, Core::GlobalInputConfig input_config, Core::GlobalNetworkConfig network_config);
 
/**
 * @brief Starts audio processing on the default engine
 *
 * Convenience wrapper for Engine::Start() on the default engine.
 */
MAYAFLUX_API void Start();
 
/**
 * @brief Pauses audio processing on the default engine
 *
 * Convenience wrapper for Engine::Pause() on the default engine.
 */
MAYAFLUX_API void Pause();
 
/**
 * @brief Resumes audio processing on the default engine
 *
 * Convenience wrapper for Engine::Resume() on the default engine.
 */
MAYAFLUX_API void Resume();
 
/**
 * @brief Blocks launcher until Ctrl-C is pressed (optional convenience function)
 *
 * Use this only in launcher applications that need to block the main
 * thread until shutdown is requested.
 *
 * Gates on SIGINT (Ctrl-C) alone, on every platform. Never reads or
 * consumes stdin, so stdin-driven backends (unix pipe, fileio) remain free
 * to use it while this call blocks.
 *
 * Usage (optional):
 * ```cpp
 * engine->start_graphics();
 * std::cout << "Press Ctrl-C to stop...\n";
 * MayaFlux::Await();  // Blocks here (optional)
 * engine->stop_graphics();
 * ```
 */
MAYAFLUX_API void Await();
 
/**
 * @brief Stops and cleans up the default engine
 *
 * Convenience wrapper for Engine::End() on the default engine.
 */
MAYAFLUX_API void End();
 
}