Add logging API functions and callbacks

Author: kblaschke

src/api/CMakeLists.txt

@@ -18,6 +18,7 @@ set(PROJECTM_PUBLIC_HEADERS
         include/projectM-4/callbacks.h
         include/projectM-4/core.h
         include/projectM-4/debug.h
+        include/projectM-4/logging.h
         include/projectM-4/memory.h
         include/projectM-4/projectM.h
         include/projectM-4/render_opengl.h

src/api/include/projectM-4/callbacks.h

@@ -91,4 +91,3 @@ PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_h
 #ifdef __cplusplus
 } // extern "C"
 #endif
-

src/api/include/projectM-4/logging.h

@@ -0,0 +1,94 @@
+/**
+ * @file logging.h
+ * @copyright 2003-2025 projectM Team
+ * @brief Functions for registering log callbacks and setting log levels.
+ * @since 4.2.0
+ *
+ * projectM -- Milkdrop-esque visualisation SDK
+ * Copyright (C)2003-2024 projectM Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ * See 'LICENSE.txt' included within this release
+ *
+ */
+
+#pragma once
+
+#include "projectM-4/types.h"
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+   * @brief Callback function that is executed if projectM wants to log a message.
+   *
+   * The message pointer is only valid inside the callback. Make a copy of the string inside the
+   * function to use it after the callback returns. Applications must not free the message pointer.
+   *
+   * @param message The message to be logged.
+   * @param log_level The log level this message was created for.
+   * @param user_data A user-defined data pointer that was provided when registering the callback,
+   *                  e.g. context information.
+   * @since 4.2.0
+   */
+typedef void (*projectm_log_callback)(const char* message, projectm_log_level log_level, void* user_data);
+
+
+/**
+ * @brief Sets a callback function that will be called for each message to be logged by projectM.
+ *
+ * The logging callback is independent of any projectM instance. Applications can set the callback
+ * globally, or only for a single thread, or both. If both a global and a thread-specific callback
+ * are set, the thread-specific callback takes precedence and the global callback will not be called.
+ *
+ * Since log messages will only be emitted by projectM when within an API call and the callback runs
+ * in the same thread as the projectM instance, applications can keep track of the instance making
+ * the call.
+ *
+ * If the application runs multiple projectM instances in separate threads, a global log callback
+ * (or the same thread callback registered in multiple threads) may be called in parallel from each
+ * thread, so the application has to take care about any possible race conditions in its own
+ * logging code and make sure it's thread-safe.
+ *
+ * To remove a callback, pass NULL as the callback argument. Thread-specific callbacks are removed
+ * automatically when the thread is terminated, though it is good practice to reset the callback at
+ * the end of a thread.
+ *
+ * @param callback A pointer to the callback function.
+ * @param current_thread_only If true, the callback is only set for the thread calling the function.
+ * @param user_data A pointer to any data that will be sent back in the callback, e.g. context
+ *                  information.
+ * @since 4.2.0
+ * @note Log messages can contain line breaks.
+ */
+PROJECTM_EXPORT void projectm_set_log_callback(projectm_log_callback callback,
+                                               bool current_thread_only,
+                                               void* user_data);
+
+/**
+ * Sets the minimum log level for which the callback should be called.
+ * @param instance The projectM instance handle.
+ * @param log_level The new log level to set. If set to PROJECTM_LOG_LEVEL_NOTSET, the global or default setting will be used.
+ * @param current_thread_only If true, the log level is only set for the thread calling the function.
+ * @since 4.2.0
+ */
+PROJECTM_EXPORT void projectm_set_log_level(projectm_log_level log_level,
+                                            bool current_thread_only);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif

src/api/include/projectM-4/types.h

@@ -78,7 +78,21 @@ typedef enum
     PROJECTM_TOUCH_TYPE_DOUBLE_LINE      //!< Draws a double-line waveform.
 } projectm_touch_type;
 
+/**
+ * Log level constants for use with the logging API functions.
+ * @since 4.2.0
+ */
+typedef enum
+{
+    PROJECTM_LOG_LEVEL_NOTSET = 0, //!< No specific log level, use default (INFO).
+    PROJECTM_LOG_LEVEL_TRACE = 1,  //!< Verbose trace logging. Only enabled in debug builds by default.
+    PROJECTM_LOG_LEVEL_DEBUG = 2,  //!< Development-related debug logging. Only enabled in debug builds by default.
+    PROJECTM_LOG_LEVEL_INFO = 3,   //!< Informational messages.
+    PROJECTM_LOG_LEVEL_WARN = 4,   //!< Warnings about non-critical issues.
+    PROJECTM_LOG_LEVEL_ERROR = 5,  //!< Recoverable errors, e.g. shader compilation or I/O errors.
+    PROJECTM_LOG_LEVEL_FATAL = 6   //!< Irrecoverable errors preventing projectM from working.
+} projectm_log_level;
+
 #ifdef __cplusplus
 } // extern "C"
 #endif
-

src/libprojectM/ProjectMCWrapper.cpp

@@ -2,6 +2,8 @@
 
 #include <projectM-4/projectM.h>
 
+#include <Logging.hpp>
+
 #include <Audio/AudioConstants.hpp>
 
 #include <cstring>
@@ -461,4 +463,28 @@ uint32_t projectm_sprite_get_max_sprites(projectm_handle instance)
     auto* projectMInstance = handle_to_instance(instance);
 
     return projectMInstance->UserSpriteLimit();
+}
+
+void projectm_set_log_callback(projectm_log_callback callback, bool current_thread_only, void* user_data)
+{
+    if (current_thread_only)
+    {
+        libprojectM::Logging::SetThreadCallback({reinterpret_cast<libprojectM::Logging::CallbackFunction>(callback), user_data});
+    }
+    else
+    {
+        libprojectM::Logging::SetGlobalCallback({reinterpret_cast<libprojectM::Logging::CallbackFunction>(callback), user_data});
+    }
+}
+
+void projectm_set_log_level(projectm_log_level log_level, bool current_thread_only)
+{
+    if (current_thread_only)
+    {
+        libprojectM::Logging::SetThreadLogLevel(static_cast<libprojectM::Logging::LogLevel>(log_level));
+    }
+    else
+    {
+        libprojectM::Logging::SetGlobalLogLevel(static_cast<libprojectM::Logging::LogLevel>(log_level));
+    }
 }