SDOM.hpp

Go to the documentation of this file.

/*** SDOM.hpp **************************************
 *    ___ ___   ___  __  __   _              
 *   / __|   \ / _ \|  \/  | | |_  _ __ _ __ 
 *   \__ \ |) | (_) | |\/| |_| ' \| '_ \ '_ \
 *   |___/___/ \___/|_|  |_(_)_||_| .__/ .__/
 *                                |_|  |_|   
 *
 * The SDOM.hpp header file serves as a centralized location for 
 * defining commonly used types, global macros, and debugging 
 * utilities within the SDOM namespace. It includes type aliases, 
 * such as ID, and provides macros for error handling (ERROR), 
 * warnings (WARNING), and debugging (DEBUG) with formatted output. 
 * This file helps standardize and simplify code across the project. 
 * 
 * Note:
 *   SDOM.hpp includes both the umbrella header (SDOM_Front.hpp) for 
 *   implementation and an interface-safe header (SDOM_Interface.hpp) 
 *   for type definitions, macros, and utilities. This ensures you 
 *   have access to all SDOM features with a single include.  For 
 *   advanced usage, you may include individual SDOM headers as needed.
 *
 * This software is provided 'as-is', without any express or implied
 * warranty.  In no event will the authors be held liable for any damages
 * arising from the use of this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 * 1. The origin of this software must not be misrepresented; you must not
 *    claim that you wrote the original software. If you use this software
 *    in a product, an acknowledgment in the product documentation would be
 *    appreciated but is not required.
 * 2. Altered source versions must be plainly marked as such, and must not be
 *    misrepresented as being the original software.
 * 3. This notice may not be removed or altered from any source distribution.
 *
 * Released under the ZLIB License.
 * Original Author: Jay Faries (warte67)
 * 
 **********************/
 
#pragma once
 
#include <SDL3/SDL.h>
#include <SDL3_image/SDL_image.h>
#include <SDL3_mixer/SDL_mixer.h>
#include <SDL3_ttf/SDL_ttf.h>
 
#include <any>
#include <algorithm>
#include <chrono>
#include <functional>
#include <fstream>
#include <iomanip>
#include <iostream>
#include <map>
#include <memory>
#include <mutex>
#include <queue>
#include <sstream>
#include <string>
#include <unordered_map>
#include <unordered_set>
#include <vector>
 
// #define SOL_ALL_AUTOMAGIC 0
#include <sol/sol.hpp>
 
constexpr bool DEBUG_REGISTER_LUA = false;
 
// Enable verbose Lua-related test/info logs when set to 1. Default is off.
#ifndef DEBUG_LUA_TESTS
#define DEBUG_LUA_TESTS 0
#endif
 
// Garbage Collection / Orphan Retention
constexpr int ORPHAN_GRACE_PERIOD = 5000; // default grace period for orphaned objects (in milliseconds)
 
namespace SDOM 
{
    // Exception class definition
    class Exception : public std::exception 
    {
        public:
            Exception(const std::string& message, const std::string& file, int line)
                : message_(message), file_(file), line_(line) {}
            const char* what() const noexcept override { return message_.c_str(); }
            std::string getFile() const { return file_; }
            int getLine() const { return line_; }
        private:
            std::string message_;
            std::string file_;
            int line_;
    };    
 
    // // stand alone SDOM functions
    // static const char* version();
    // static const char* compilationDate();
 
    // class Core;
    // class Factory;
    // class Stage;
 
    // void quit();
    // void shutdown();
    // Core& getCore();
    // Factory& getFactory();
    // Stage* getStage();
    // DomHandle getStageHandle();
    // SDL_Renderer* getRenderer();
    // SDL_Window* getWindow();
    // SDL_Texture* getTexture();
 
 
    enum class AnchorPoint : uint8_t
    {
        // Main anchor points
        DEFAULT         = 0,    
        TOP_LEFT        = 0,    
        TOP_CENTER      = 1,    
        TOP_RIGHT       = 2,    
        MIDDLE_LEFT     = 3,    
        MIDDLE_CENTER   = 4,    
        MIDDLE_RIGHT    = 5,    
        BOTTOM_LEFT     = 6,    
        BOTTOM_CENTER   = 7,    
        BOTTOM_RIGHT    = 8,    
 
        LEFT            = MIDDLE_LEFT,   
        CENTER          = MIDDLE_CENTER, 
        RIGHT           = MIDDLE_RIGHT,  
        TOP             = TOP_CENTER,    
        MIDDLE          = MIDDLE_CENTER, 
        BOTTOM          = BOTTOM_CENTER, 
        LEFT_TOP        = TOP_LEFT,      
        CENTER_TOP      = TOP_CENTER,    
        RIGHT_TOP       = TOP_RIGHT,     
        LEFT_MIDDLE     = MIDDLE_LEFT,   
        CENTER_MIDDLE   = MIDDLE_CENTER, 
        RIGHT_MIDDLE    = MIDDLE_RIGHT,  
        LEFT_BOTTOM     = BOTTOM_LEFT,   
        CENTER_BOTTOM   = BOTTOM_CENTER, 
        RIGHT_BOTTOM    = BOTTOM_RIGHT,  
    };
 
    /*
     * Note: Anchor name normalization
     * --------------------------------
     * Canonicalization of user-provided anchor strings is performed by
     * the helper function SDOM::normalizeAnchorString(const std::string&),
     * implemented in `src/SDOM_Utils.cpp`.
     *
     * Behavior summary:
     *  - Strips whitespace and lower-cases the input.
     *  - Recognizes a single operator character joining two keywords
     *    (one of: '-', '|', '&', '+', ',') and returns the joined form
     *    using '_' as the separator (e.g. "top+left" -> "top_left").
     *  - Validates keyword pairs (e.g. disallows "top_bottom" or
     *    "left_right") and returns an empty string while emitting a
     *    WARNING on invalid inputs.
     *
     * The Factory and other parsers call this function before looking up
     * entries in `stringToAnchorPoint_` so consumers can pass flexible
     * anchor names (spaces, different joiners, mixed case) and still
     * resolve to the canonical enum value.
     */
 
    inline static const std::unordered_map<AnchorPoint, std::string> anchorPointToString_ = {
        { AnchorPoint::TOP_LEFT,     "top_left" },
        { AnchorPoint::TOP_CENTER,   "top_center" },
        { AnchorPoint::TOP_RIGHT,    "top_right" },
        { AnchorPoint::MIDDLE_LEFT,  "middle_left" },
        { AnchorPoint::MIDDLE_CENTER,"middle_center" },
        { AnchorPoint::MIDDLE_RIGHT, "middle_right" },
        { AnchorPoint::BOTTOM_LEFT,  "bottom_left" },
        { AnchorPoint::BOTTOM_CENTER,"bottom_center" },
        { AnchorPoint::BOTTOM_RIGHT, "bottom_right" }
    };
 
    inline static const std::unordered_map<std::string, AnchorPoint> stringToAnchorPoint_ = {
        { "default",        AnchorPoint::DEFAULT },
        { "left",           AnchorPoint::LEFT },
        { "center",         AnchorPoint::CENTER },
        { "right",          AnchorPoint::RIGHT },
        { "top",            AnchorPoint::TOP },
        { "top_left",       AnchorPoint::TOP_LEFT },
        { "top_center",     AnchorPoint::TOP_CENTER },
        { "top_right",      AnchorPoint::TOP_RIGHT },
        { "middle",         AnchorPoint::MIDDLE },
        { "middle_left",    AnchorPoint::MIDDLE_LEFT },
        { "middle_center",  AnchorPoint::MIDDLE_CENTER },
        { "middle_right",   AnchorPoint::MIDDLE_RIGHT },
        { "bottom",         AnchorPoint::BOTTOM },
        { "bottom_left",    AnchorPoint::BOTTOM_LEFT },
        { "bottom_center",  AnchorPoint::BOTTOM_CENTER },
        { "bottom_right",   AnchorPoint::BOTTOM_RIGHT },
 
        { "center_middle",  AnchorPoint::MIDDLE_CENTER },
        { "right_middle",   AnchorPoint::MIDDLE_RIGHT },
        { "left_middle",    AnchorPoint::MIDDLE_LEFT },
        { "center_top",     AnchorPoint::TOP_CENTER },
        { "right_top",      AnchorPoint::TOP_RIGHT },
        { "left_top",       AnchorPoint::TOP_LEFT },
        { "center_bottom",  AnchorPoint::BOTTOM_CENTER },
        { "right_bottom",   AnchorPoint::BOTTOM_RIGHT },
        { "left_bottom",    AnchorPoint::BOTTOM_LEFT },
    }; // unordered_map stringToAnchorPoint_
 
    struct Bounds
    {
        float left = 0.0f;   
        float top = 0.0f;    
        float right = 0.0f;  
        float bottom = 0.0f; 
 
        float width() const { return abs(right - left); }
 
        float height() const { return abs(bottom - top); }
        
        // Equality operator with epsilon for floating-point comparison
        bool operator==(const Bounds& other) const {
            constexpr float epsilon = 0.0001f;
            return std::abs(left - other.left)   < epsilon &&
                std::abs(top - other.top)     < epsilon &&
                std::abs(right - other.right) < epsilon &&
                std::abs(bottom - other.bottom) < epsilon;
        }
 
        bool operator!=(const Bounds& other) const {
            return !(*this == other);
        }
    };
 
} // namespace SDOM
 
// Macro for throwing exceptions
#define ERROR(message) throw SDOM::Exception(message, __FILE__, __LINE__)
 
 
// Macro for showing warnings
#define WARNING(message) SDOM::showWarning(message, __FILE__, __LINE__)
 
// Macro for debug logging (statement-safe, parenthesized parameter)
#define DEBUG_LOG(...) do { \
    std::ostringstream _sdom_dbg_oss; \
    _sdom_dbg_oss << __VA_ARGS__; \
    std::cout << CLR::GREEN << "[DEBUG] " << _sdom_dbg_oss.str() << CLR::RESET << std::endl; \
} while(0)
 
// Macro for failure logging (statement-safe, parenthesized parameter)
#define FAIL(...) do { \
    std::ostringstream _sdom_dbg_oss; \
    _sdom_dbg_oss << __VA_ARGS__; \
    std::cout << CLR::RED << "[FAILED] " << _sdom_dbg_oss.str() << CLR::RESET << std::endl; \
} while(0)
 
// Macro for informational logging (statement-safe, parenthesized parameter)
#define INFO(...) do { \
    std::ostringstream _sdom_dbg_oss; \
    _sdom_dbg_oss << __VA_ARGS__; \
    std::cout << CLR::YELLOW << "[INFO] " << (_sdom_dbg_oss.str()) << CLR::RESET << std::endl; } while(0)
 
// Lua-specific informational logging (only active when DEBUG_LUA_TESTS == 1)
#define LUA_INFO(...) do { if (DEBUG_LUA_TESTS) { std::ostringstream _sdom_lua_dbg_oss; _sdom_lua_dbg_oss << __VA_ARGS__; std::cout << CLR::YELLOW << "[LUA-INFO] " << (_sdom_lua_dbg_oss.str()) << CLR::RESET << std::endl; } } while(0)
 
// Macro for debug errors (statement-safe)
#define DEBUG_ERR(message) do { std::cout << CLR::DARK << \
    "\n      Debug: " << \
    CLR::YELLOW << (message) << std::endl << CLR::DARK << \
    "      File:  " << CLR::ORANGE << __FILE__  << CLR::DARK << std::endl << \
    "      Line:  " << CLR::ORANGE  << __LINE__ << CLR::RESET << "\n" << std::endl; } while(0)
 
// Assertion macro for testing equality
#define ASSERT_EQ(val, expected) \
    if ((val) != (expected)) { \
        ERROR("Assertion failed: " + std::string(#val) + " == " + std::string(#expected) \
                  + ", actual: " + std::to_string((val)) + ", expected: " + std::to_string((expected))); \
    }
 
#include <SDOM/SDOM_SDL_Utils.hpp>
#include <SDOM/SDOM_CLR.hpp>
#include <SDOM/SDOM_DisplayHandle.hpp>
#include <SDOM/SDOM_AssetHandle.hpp>
#include <SDOM/SDOM_UnitTests.hpp>
#include <SDOM/SDOM_Utils.hpp>
 
#ifndef SDOM_USE_INDIVIDUAL_HEADERS
    // SDOM_Front.hpp is an umbrella header meant for implementation files only.
    // Including it from SDOM.hpp can create circular includes (SDOM.hpp -> SDOM_Front.hpp -> SDOM_Core.hpp -> SDOM.hpp)
    // which may leave class definitions incomplete during header processing. Consumers who want the full
    // API should include SDOM_Front.hpp directly in .cpp files. Keep this block intentionally empty here
    // to avoid accidental circular include dependencies.
#endif