nv-sgl 0.6.0__cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

sgl/include/sgl/core/platform.h

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "sgl/core/macros.h"
+
+#include <filesystem>
+#include <functional>
+#include <optional>
+#include <span>
+#include <string_view>
+#include <string>
+#include <vector>
+
+#if SGL_WINDOWS
+#define DECLARE_HANDLE(name)                                                                                           \
+    struct name##__;                                                                                                   \
+    typedef struct name##__* name
+DECLARE_HANDLE(HWND);
+#undef DECLARE_HANDLE
+#endif
+
+namespace sgl {
+/// Native window handle.
+struct WindowHandle {
+#if SGL_WINDOWS
+    HWND hwnd;
+#elif SGL_LINUX
+    void* xdisplay;
+    uint32_t xwindow;
+#elif SGL_MACOS
+    void* nswindow;
+#endif
+};
+
+/// Shared library handle.
+using SharedLibraryHandle = void*;
+} // namespace sgl
+
+namespace sgl::platform {
+
+
+/// Initialize the platform layer.
+SGL_API void static_init();
+
+/// Shutdown the platform layer.
+SGL_API void static_shutdown();
+
+/// Inform the platform that the library is loaded from python.
+SGL_API void set_python_active(bool active);
+
+/// Check if the library is loaded from python.
+[[nodiscard]] SGL_API bool is_python_active();
+
+
+/// Set the window icon.
+SGL_API void set_window_icon(WindowHandle handle, const std::filesystem::path& path);
+
+/// The pixel scale factor of the primary display.
+[[nodiscard]] SGL_API float display_scale_factor();
+
+/// Setup a callback function to be called when Ctrl-C is detected.
+/// Use nullptr to remove handler.
+SGL_API void set_keyboard_interrupt_handler(std::function<void()> handler);
+
+// -------------------------------------------------------------------------------------------------
+// File dialogs
+// -------------------------------------------------------------------------------------------------
+
+struct FileDialogFilter {
+    /// Readable name (e.g. "JPEG").
+    std::string name;
+    /// File extension pattern (e.g. "*.jpg" or "*.jpg,*.jpeg").
+    std::string pattern;
+
+    FileDialogFilter() = default;
+    FileDialogFilter(std::string_view name, std::string_view pattern)
+        : name(name)
+        , pattern(pattern)
+    {
+    }
+    FileDialogFilter(std::pair<std::string_view, std::string_view> pair)
+        : name(pair.first)
+        , pattern(pair.second)
+    {
+    }
+};
+using FileDialogFilterList = std::vector<FileDialogFilter>;
+
+/// Show a file open dialog.
+/// \param filters List of file filters.
+/// \return The selected file path or nothing if the dialog was cancelled.
+[[nodiscard]] SGL_API std::optional<std::filesystem::path>
+open_file_dialog(std::span<const FileDialogFilter> filters = {});
+
+/// Show a file save dialog.
+/// \param filters List of file filters.
+/// \return The selected file path or nothing if the dialog was cancelled.
+[[nodiscard]] SGL_API std::optional<std::filesystem::path>
+save_file_dialog(std::span<const FileDialogFilter> filters = {});
+
+/// Show a folder selection dialog.
+/// \return The selected folder path or nothing if the dialog was cancelled.
+[[nodiscard]] SGL_API std::optional<std::filesystem::path> choose_folder_dialog();
+
+// -------------------------------------------------------------------------------------------------
+// Filesystem
+// -------------------------------------------------------------------------------------------------
+
+/// Compares two paths in their weakly canonical form, returning true if they match.
+/// Operator == on path does a string comparison, ignoring the fact that windows paths are case insensitive.
+/// STL's equivalent comparator throws when either of the paths does not exist.
+/// This complements the two by allowing comparing non-existent paths, but at the same time ignoring case on windows.
+[[nodiscard]] SGL_API bool is_same_path(const std::filesystem::path& lhs, const std::filesystem::path& rhs);
+
+/// Check if a file path has a given file extension. Does a case-insensitive comparison.
+[[nodiscard]] SGL_API bool has_extension(const std::filesystem::path& path, const std::string_view ext);
+
+/// Get the file extension from a path in lower-case and without the leading '.' character.
+[[nodiscard]] SGL_API std::string get_extension_from_path(const std::filesystem::path& path);
+
+/// Create a unique path to a temporary file.
+/// Note: A file with the same name could still be created by another process.
+[[nodiscard]] SGL_API std::filesystem::path get_temp_file_path();
+
+/// Create a junction (soft link).
+[[nodiscard]] SGL_API bool create_junction(const std::filesystem::path& link, const std::filesystem::path& target);
+
+/// Delete a junction (sof link).
+[[nodiscard]] SGL_API bool delete_junction(const std::filesystem::path& link);
+
+// -------------------------------------------------------------------------------------------------
+// System paths
+// -------------------------------------------------------------------------------------------------
+
+/// The full path to the current executable.
+[[nodiscard]] SGL_API const std::filesystem::path& executable_path();
+
+/// The current executable directory.
+[[nodiscard]] SGL_API const std::filesystem::path& executable_directory();
+
+/// The current executable name.
+[[nodiscard]] SGL_API const std::string& executable_name();
+
+/// The application data directory.
+[[nodiscard]] SGL_API const std::filesystem::path& app_data_directory();
+
+/// The home directory.
+[[nodiscard]] SGL_API const std::filesystem::path& home_directory();
+
+/// The project source directory. Note that this is only valid during development.
+[[nodiscard]] SGL_API const std::filesystem::path& project_directory();
+
+/// The runtime directory. This is the path where the sgl runtime library
+/// (sgl.dll, libsgl.so or libsgl.dynlib) resides.
+[[nodiscard]] SGL_API const std::filesystem::path& runtime_directory();
+
+// -------------------------------------------------------------------------------------------------
+// Environment
+// -------------------------------------------------------------------------------------------------
+
+/// Get the content of a system environment variable.
+[[nodiscard]] SGL_API std::optional<std::string> get_environment_variable(const char* name);
+
+// -------------------------------------------------------------------------------------------------
+// Memory
+// -------------------------------------------------------------------------------------------------
+
+/// The page size of the system.
+[[nodiscard]] SGL_API size_t page_size();
+
+struct MemoryStats {
+    /// Current resident/working set size in bytes.
+    uint64_t rss;
+    /// Peak resident/working set size in bytes.
+    uint64_t peak_rss;
+};
+
+/// Get the current memory stats.
+[[nodiscard]] SGL_API MemoryStats memory_stats();
+
+// -------------------------------------------------------------------------------------------------
+// Shared libraries
+// -------------------------------------------------------------------------------------------------
+
+/// Load a shared library.
+[[nodiscard]] SGL_API SharedLibraryHandle load_shared_library(const std::filesystem::path& path);
+
+/// Release a shared library.
+SGL_API void release_shared_library(SharedLibraryHandle library);
+
+/// Get a function pointer from a library.
+SGL_API void* get_proc_address(SharedLibraryHandle library, const char* proc_name);
+
+// -------------------------------------------------------------------------------------------------
+// Debugger
+// -------------------------------------------------------------------------------------------------
+
+/// Check if a debugger session is attached.
+[[nodiscard]] SGL_API bool is_debugger_present();
+
+/// Breaks in debugger (int 3 functionality).
+SGL_API void debug_break();
+
+/// Print a message into the debug window.
+SGL_API void print_to_debug_window(const char* str);
+
+// -------------------------------------------------------------------------------------------------
+// Stacktrace
+// -------------------------------------------------------------------------------------------------
+
+using StackFrame = uintptr_t;
+using StackTrace = std::vector<StackFrame>;
+
+struct ResolvedStackFrame {
+    uintptr_t address;
+    std::string module;
+    std::string symbol;
+    size_t offset;
+    std::string source;
+    uint32_t line;
+};
+
+using ResolvedStackTrace = std::vector<ResolvedStackFrame>;
+
+/// Generate a backtrace.
+[[nodiscard]] SGL_API StackTrace backtrace(size_t skip_frames = 1);
+
+/// Resolve a stack trace with symbol information.
+[[nodiscard]] SGL_API ResolvedStackTrace resolve_stacktrace(std::span<const StackFrame> trace);
+
+/// Convert resolved stack trace to a human readable string.
+[[nodiscard]] SGL_API std::string format_stacktrace(std::span<const ResolvedStackFrame> trace, size_t max_frames = 0);
+
+/// Convert resolved stack trace to a human readable string.
+[[nodiscard]] SGL_API std::string format_stacktrace(std::span<const StackFrame> trace, size_t max_frames = 0);
+
+
+} // namespace sgl::platform

sgl/include/sgl/core/plugin.h

@@ -0,0 +1,331 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "sgl/core/macros.h"
+#include "sgl/core/error.h"
+#include "sgl/core/platform.h"
+
+#include <filesystem>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <span>
+#include <string>
+#include <type_traits>
+#include <vector>
+
+namespace sgl {
+
+/**
+ * \brief Plugin manager for loading plugin libraries and creating plugin instances.
+ *
+ * The plugin system is based around the following principles:
+ * - Plugins are compiled into shared libraries known as _plugin libraries_.
+ * - A _plugin library_ registers one or more _plugin classes_ when being loaded.
+ * - A _plugin class_ needs to inherit from a known _plugin base class_, implementing it's interface.
+ * - A _plugin base class_ defines a `PluginInfo` struct, describing meta information about each
+ *   _plugin class_ as well as a `PluginCreate` typedef used for instantiating plugin classes.
+ *
+ * A _plugin base class_ can be any class that is exported from the main sgl library.
+ * It needs to define a `PluginInfo` struct as well as a `PluginCreate` typedef.
+ * The SGL_PLUGIN_BASE_CLASS macro extends the class with the required members for the plugin system.
+ * For example:
+ *
+ * \code
+ * class SGL_API PluginBase
+ * {
+ * public:
+ *     struct PluginInfo { const char* desc };
+ *     using PluginCreate = (PluginBase *)(*)();
+ *     SGL_PLUGIN_BASE_CLASS(PluginBase);
+ *
+ *     virtual void do_struff() = 0;
+ * };
+ * \endcode
+ *
+ * To implement a _plugin class_ type, we simply inherit from the base class.
+ * The SGL_PLUGIN_CLASS macro extends the class with the required members for the plugin system.
+ * The class also needs to implement a static create function, matching the `PluginCreate` type of the base class.
+ * For example:
+ *
+ * \code
+ * class PluginA : public PluginBase
+ * {
+ * public:
+ *     SGL_PLUGIN_CLASS(PluginA, "PluginA", PluginInfo({"plugin description string"}));
+ *
+ *     static PluginBase* create() { return new PluginA(); }
+ *
+ *     void do_struff() override { ... }
+ * };
+ * \endcode
+ *
+ * The _plugin library_ must export a `register_plugin` function for registering all the plugin class types when called.
+ *
+ * \code
+ * extern "C" SGL_API_EXPORT void register_plugin(sgl::PluginRegistry& registry)
+ * {
+ *     registry.register_class<PluginBase, PluginA>();
+ * }
+ * \endcode
+ *
+ * At runtime, the plugin manager can load plugin libraries using `load_plugin_by_name` and `load_plugin`.
+ * New plugin instances can be created using `create_class`, for example:
+ *
+ * \code
+ * PluginBase* p = PluginManager::instance().create_class<PluginBase>("PluginA");
+ * \endcode
+ *
+ * The `get_infos` function returns a list of plugin infos for all loaded plugin types of a given plugin base class.
+ */
+class SGL_API PluginManager {
+public:
+    /// Singleton accessor.
+    static PluginManager& instance();
+
+    /**
+     * \brief Create an instance of a plugin class.
+     *
+     * \tparam BaseT The plugin base class.
+     * \tparam Args The argument type pack used for construction.
+     * \param type The plugin type name.
+     * \param args Additional arguments passed on construction.
+     * \return Returns a new instance of the requested plugin type or nullptr if not registered.
+     */
+    template<typename BaseT, typename... Args>
+    std::invoke_result_t<typename BaseT::PluginCreate, Args...> create_class(std::string_view type, Args... args) const
+    {
+        std::lock_guard<std::mutex> lock(m_class_descs_mutex);
+        const ClassDesc<BaseT>* class_desc = find_class_desc<BaseT>(type);
+        return class_desc ? class_desc->create(args...)
+                          : std::invoke_result_t<typename BaseT::PluginCreate, Args...>{nullptr};
+    }
+
+    /**
+     * \brief Check if a given type of a plugin is available.
+     *
+     * \tparam BaseT The plugin base class.
+     * \param type The plugin type name.
+     * \return True if plugin type is available.
+     */
+    template<typename BaseT>
+    bool has_class(std::string_view type) const
+    {
+        std::lock_guard<std::mutex> lock(m_class_descs_mutex);
+        const ClassDesc<BaseT>* class_desc = find_class_desc<BaseT>(type);
+        return class_desc != nullptr;
+    }
+
+    /**
+     * \brief Get infos for all registered plugin types for a given plugin base class.
+     *
+     * \tparam BaseT The plugin base class.
+     * \return A list of infos.
+     */
+    template<typename BaseT>
+    std::vector<std::pair<std::string, typename BaseT::PluginInfo>> get_infos() const
+    {
+        std::lock_guard<std::mutex> lock(m_class_descs_mutex);
+        std::vector<std::pair<std::string, typename BaseT::PluginInfo>> result;
+
+        for (const auto& [name, desc] : m_class_descs)
+            if (auto match_desc = dynamic_cast<const ClassDesc<BaseT>*>(desc.get()))
+                result.push_back(std::make_pair(match_desc->type, match_desc->info));
+
+        return result;
+    }
+
+    /**
+     * \brief Load a plugin library by name.
+     * This will automatically determine the plugin path and file extension.
+     * \param plugin_dir Path to plugin directory.
+     * \param name Name of the plugin library.
+     * \return True if successful.
+     */
+    bool load_plugin_by_name(const std::filesystem::path& plugin_dir, std::string_view name);
+
+    /**
+     * Load a list of plugin libraries.
+     * \param plugin_dir Path to plugin directory.
+     * \param names Names of the plugin libraries.
+     */
+    void load_plugins_by_name(const std::filesystem::path& plugin_dir, std::span<const std::string> names);
+
+    /**
+     * Load a plugin library.
+     * \param path File path of the plugin library.
+     * \return True if successful.
+     */
+    bool load_plugin(const std::filesystem::path& path);
+
+    /**
+     * Release a previously loaded plugin library.
+     * \param path File path of the plugin library.
+     * \return True if successful.
+     */
+    bool release_plugin(const std::filesystem::path& path);
+
+    /**
+     * Release all loaded plugin libraries.
+     */
+    void release_all_plugins();
+
+private:
+    struct ClassDescBase {
+        ClassDescBase(SharedLibraryHandle library, std::string_view type)
+            : library(library)
+            , type(type)
+        {
+        }
+        virtual ~ClassDescBase() { }
+
+        SharedLibraryHandle library;
+        std::string type;
+    };
+
+    template<typename BaseT>
+    struct ClassDesc : public ClassDescBase {
+        typename BaseT::PluginInfo info;
+        typename BaseT::PluginCreate create;
+
+        ClassDesc(
+            SharedLibraryHandle library,
+            std::string_view type,
+            typename BaseT::PluginInfo info,
+            typename BaseT::PluginCreate create
+        )
+            : ClassDescBase(library, type)
+            , info(info)
+            , create(create)
+        {
+        }
+    };
+
+    template<typename BaseT>
+    void register_class(
+        SharedLibraryHandle library,
+        std::string_view type,
+        typename BaseT::PluginInfo info,
+        typename BaseT::PluginCreate create
+    )
+    {
+        std::lock_guard<std::mutex> lock(m_class_descs_mutex);
+
+        if (find_class_desc<BaseT>(type) != nullptr)
+            SGL_THROW(
+                "A plugin class with type name \"{}\" (base class type \"{}\") has already been registered.",
+                type,
+                BaseT::get_plugin_base_type()
+            );
+
+        auto desc = std::make_shared<ClassDesc<BaseT>>(library, type, info, create);
+        m_class_descs.emplace(type, std::move(desc));
+    }
+
+    template<typename BaseT>
+    const ClassDesc<BaseT>* find_class_desc(std::string_view type) const
+    {
+        if (auto it = m_class_descs.find(std::string(type)); it != m_class_descs.end())
+            if (auto desc = dynamic_cast<const ClassDesc<BaseT>*>(it->second.get()); desc && desc->type == type)
+                return desc;
+
+        return nullptr;
+    }
+
+    std::map<std::filesystem::path, SharedLibraryHandle> m_libraries;
+    std::map<std::string, std::shared_ptr<ClassDescBase>> m_class_descs;
+
+    mutable std::mutex m_libraries_mutex;
+    mutable std::mutex m_class_descs_mutex;
+
+    friend class PluginRegistry;
+};
+
+/**
+ * \brief Helper class passed to plugin libraries to register plugin classes.
+ */
+class PluginRegistry {
+public:
+    PluginRegistry(PluginManager& plugin_manager, SharedLibraryHandle library)
+        : m_plugin_manager(plugin_manager)
+        , m_library(library)
+    {
+    }
+    PluginRegistry(const PluginRegistry&) = delete;
+    PluginRegistry& operator=(const PluginRegistry&) = delete;
+
+    /**
+     * \brief Register a plugin class.
+     * Throws if a class with the same type name (and same base class) has already been registered.
+     *
+     * \tparam BaseT The plugin base class.
+     * \param type The plugin type name.
+     * \param info The plugin info (type of BaseT::PluginInfo).
+     * \param create The plugin create function (type of BaseT::PluginCreate).
+     */
+    template<typename BaseT>
+    void register_class(std::string_view type, typename BaseT::PluginInfo info, typename BaseT::PluginCreate create)
+    {
+        m_plugin_manager.register_class<BaseT>(m_library, type, info, create);
+    }
+
+    /**
+     * \brief Register a plugin class.
+     * This helper assumes that the plugin class has a `create` function matching the BaseT::PluginCreate type.
+     *
+     * \tparam BaseT The plugin base class.
+     * \tparam T The plugin class.
+     */
+    template<typename BaseT, typename T>
+    void register_class()
+    {
+        register_class<BaseT>(T::k_plugin_type, T::k_plugin_info, T::create);
+    }
+
+private:
+    PluginManager& m_plugin_manager;
+    SharedLibraryHandle m_library;
+};
+
+/**
+ * \brief Macro for extending a class to be used as a plugin base class.
+ *
+ * This macro must be applied in the class declaration of the plugin base class.
+ * It assumes that both a public PluginInfo struct type and a PluginCreate typedef
+ * are defined when invoked.
+ */
+#define SGL_PLUGIN_BASE_CLASS(cls)                                                                                     \
+public:                                                                                                                \
+    static_assert(std::is_class_v<cls> == true);                                                                       \
+    /* TODO: check for existance of cls::PluginCreate */                                                               \
+    static_assert(std::is_class_v<cls::PluginInfo> == true);                                                           \
+    static const std::string& get_plugin_base_type()                                                                   \
+    {                                                                                                                  \
+        static std::string type{#cls};                                                                                 \
+        return type;                                                                                                   \
+    }                                                                                                                  \
+    virtual const std::string& get_plugin_type() const = 0;                                                            \
+    virtual const PluginInfo& get_plugin_info() const = 0;
+
+/**
+ * \brief Macro for extending a class to be used as a plugin class.
+ *
+ * This macro must be applied in the class declaration of the plugin class.
+ */
+#define SGL_PLUGIN_CLASS(cls, type, info)                                                                              \
+public:                                                                                                                \
+    static_assert(std::is_class_v<cls> == true);                                                                       \
+    /* TODO: check inheritance of base plugin class */                                                                 \
+    static inline const std::string k_plugin_type{type};                                                               \
+    static inline const PluginInfo k_plugin_info{info};                                                                \
+    virtual const std::string& get_plugin_type() const final                                                           \
+    {                                                                                                                  \
+        return k_plugin_type;                                                                                          \
+    }                                                                                                                  \
+    virtual const PluginInfo& get_plugin_info() const final                                                            \
+    {                                                                                                                  \
+        return k_plugin_info;                                                                                          \
+    }
+
+} // namespace sgl

sgl/include/sgl/core/resolver.h

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <vector>
+#include <filesystem>
+
+namespace sgl {
+
+class Resolver {
+public:
+    virtual ~Resolver() = default;
+    virtual std::filesystem::path resolve(const std::filesystem::path& path) = 0;
+};
+
+class SearchPathsResolver : public Resolver {
+public:
+    SearchPathsResolver(std::vector<std::filesystem::path> search_paths)
+        : m_search_paths(std::move(search_paths))
+    {
+    }
+
+    std::filesystem::path resolve(const std::filesystem::path& path) override
+    {
+        if (!path.is_absolute()) {
+            for (const std::filesystem::path& search_path : m_search_paths) {
+                auto full_path = search_path / path;
+                if (std::filesystem::exists(full_path))
+                    return full_path;
+            }
+        }
+        return path;
+    }
+
+private:
+    std::vector<std::filesystem::path> m_search_paths;
+};
+
+} // namespace sgl