Add new logging API

BUILDING-cmake.md

@@ -115,13 +115,14 @@ Note that `ENABLE_GLES` will be forcibly set to `ON` for Emscripten and Android
 The following table contains a list of build options which are only useful in special circumstances, e.g. when
 developing libprojectM, trying experimental features or building the library for a special use-case/environment.
 
-| CMake option           | Default | Required dependencies          | Description                                                                                                                                                   |
-|------------------------|---------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `ENABLE_SDL_UI`        | `ON`    | `SDL2`                         | Builds the SDL-based test application. Only used for development testing, will not be installed.                                                              |
-| `ENABLE_INSTALL`       | `OFF`   | Building as a CMake subproject | Enable projectM install targets when built as a subproject via `add_subdirectory()`.                                                                          |
-| `ENABLE_DEBUG_POSTFIX` | `ON`    |                                | Adds `d` (by default) to the name of any binary file in debug builds.                                                                                         |
-| `ENABLE_SYSTEM_GLM`    | `OFF`   |                                | Builds against a system-installed GLM library.                                                                                                                |
-| `ENABLE_CXX_INTERFACE` | `OFF`   |                                | Exports symbols for the `ProjectM` and `PCM` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported. |
+| CMake option             | Default | Required dependencies          | Description                                                                                                                                                                                                                                      |
+|--------------------------|---------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ENABLE_SDL_UI`          | `ON`    | `SDL2`                         | Builds the SDL-based test application. Only used for development testing, will not be installed.                                                                                                                                                 |
+| `ENABLE_INSTALL`         | `OFF`   | Building as a CMake subproject | Enable projectM install targets when built as a subproject via `add_subdirectory()`.                                                                                                                                                             |
+| `ENABLE_DEBUG_POSTFIX`   | `ON`    |                                | Adds `d` (by default) to the name of any binary file in debug builds.                                                                                                                                                                            |
+| `ENABLE_SYSTEM_GLM`      | `OFF`   |                                | Builds against a system-installed GLM library.                                                                                                                                                                                                   |
+| `ENABLE_CXX_INTERFACE`   | `OFF`   |                                | Exports symbols for the `ProjectM` and `PCM` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported.                                                                                    |
+| `ENABLE_VERBOSE_LOGGING` | `OFF`   |                                | Enables code for `TRACE` and `DEBUG` log levels in release builds. By default, these will only be compiled for `Debug` builds. Enabling this will negatively affect performance, even if the actual log level is set to `INFORMATION` or higher. |
 
 ### Path options
 

CMakeLists.txt

@@ -25,6 +25,7 @@ option(ENABLE_DEBUG_POSTFIX "Add \"d\" (by default) after library names for debu
 option(ENABLE_PLAYLIST "Enable building the playlist management library" ON)
 option(ENABLE_BOOST_FILESYSTEM "Force the use of boost::filesystem, even if the compiler supports C++17." OFF)
 option(ENABLE_SDL_UI "Build the SDL2-based developer test UI. Ignored when building with Emscripten or for Android." OFF)
+option(ENABLE_VERBOSE_LOGGING "Enables TRACE and DEBUG logging even in release builds, negatively affecting the performance." OFF)
 
 option(BUILD_TESTING "Build the libprojectM test suite" OFF)
 option(BUILD_DOCS "Build documentation" OFF)
@@ -208,6 +209,11 @@ else()
     set(CMAKE_VISIBILITY_INLINES_HIDDEN ON)
 endif()
 
+# Disable trace/debug logging in release builds unless explicitly requested
+add_compile_definitions(
+        $<$<OR:$<CONFIG:Debug>,$<BOOL:${ENABLE_VERBOSE_LOGGING}>>:ENABLE_DEBUG_LOGGING>
+        )
+
 if(BUILD_DOCS)
     find_package(Doxygen REQUIRED)
     find_package(Sphinx REQUIRED breathe exhale)
@@ -220,15 +226,15 @@ if(BUILD_DOCS)
     set(DOXYGEN_EXCLUDE_PATTERNS "*.cpp")
 
     doxygen_add_docs(
-        projectm_doxygen
-        src
-        COMMENT "Generate HTML documentation")
+            projectm_doxygen
+            src
+            COMMENT "Generate HTML documentation")
 
     sphinx_add_docs(
-        projectm_sphinx
-        BREATHE_PROJECTS projectm_doxygen
-        BUILDER html
-        SOURCE_DIRECTORY docs)
+            projectm_sphinx
+            BREATHE_PROJECTS projectm_doxygen
+            BUILDER html
+            SOURCE_DIRECTORY docs)
 endif()
 
 add_subdirectory(vendor)

src/api/CMakeLists.txt

@@ -1,12 +1,24 @@
 add_library(projectM_api INTERFACE)
 
-target_sources(projectM_api
-        PRIVATE
+configure_file(version.h.in "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/version.h" @ONLY)
+
+include(GenerateExportHeader)
+
+set(PROJECTM_EXPORT_HEADER "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/projectM_export.h")
+
+generate_export_header(projectM_api
+        BASE_NAME projectM
+        EXPORT_FILE_NAME "${PROJECTM_EXPORT_HEADER}"
+        )
+
+set(PROJECTM_PUBLIC_HEADERS
         "${PROJECTM_EXPORT_HEADER}"
+        "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/version.h"
         include/projectM-4/audio.h
         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
@@ -15,9 +27,15 @@ target_sources(projectM_api
         include/projectM-4/user_sprites.h
         )
 
+target_sources(projectM_api
+        PRIVATE
+        ${PROJECTM_PUBLIC_HEADERS}
+        )
+
 set_target_properties(projectM_api PROPERTIES
         EXPORT_NAME API
         FOLDER libprojectM
+        PUBLIC_HEADER "${PROJECTM_PUBLIC_HEADERS}"
         )
 
 target_include_directories(projectM_api
@@ -27,17 +45,6 @@ target_include_directories(projectM_api
         "$<INSTALL_INTERFACE:${PROJECTM_INCLUDE_DIR}>"
         )
 
-configure_file(version.h.in "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/version.h" @ONLY)
-
-include(GenerateExportHeader)
-
-set(PROJECTM_EXPORT_HEADER "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/projectM_export.h")
-
-generate_export_header(projectM_api
-        BASE_NAME projectM
-        EXPORT_FILE_NAME "${PROJECTM_EXPORT_HEADER}"
-        )
-
 add_library(libprojectM::API ALIAS projectM_api)
 
 
@@ -51,16 +58,4 @@ if(ENABLE_INSTALL)
             PUBLIC_HEADER DESTINATION "${PROJECTM_INCLUDE_DIR}/projectM-4" COMPONENT Devel
             )
 
-    install(FILES
-            "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/projectM_export.h"
-            "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/version.h"
-            DESTINATION "${PROJECTM_INCLUDE_DIR}/projectM-4"
-            COMPONENT Devel
-            )
-
-    install(DIRECTORY include/projectM-4
-            DESTINATION "${PROJECTM_INCLUDE_DIR}"
-            COMPONENT Devel
-            )
-
 endif()

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

@@ -1,6 +1,6 @@
 /**
  * @file audio.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Functions to pass in audio data to libprojectM.
  * @since 4.0.0
  *

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

@@ -1,6 +1,6 @@
 /**
  * @file callbacks.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Functions and prototypes for projectM callbacks.
  * @since 4.0.0
  *
@@ -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/core.h

@@ -1,6 +1,6 @@
 /**
  * @file core.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Core functions to instantiate, destroy and control projectM.
  * @since 4.0.0
  *

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

@@ -1,6 +1,6 @@
 /**
  * @file debug.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Debug functions for both libprojectM and preset developers.
  * @since 4.0.0
  *

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/memory.h

@@ -1,6 +1,6 @@
 /**
  * @file memory.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Memory allocation/deallocation helpers.
  * @since 4.0.0
  *

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

@@ -1,6 +1,6 @@
 /**
  * @file parameters.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Functions to set and retrieve all sorts of projectM parameters and setting.
  * @since 4.0.0
  *

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

@@ -1,6 +1,6 @@
 /**
  * @file projectM.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Convenience include file that includes all other API headers.
  * @since 4.0.0
  *
@@ -29,6 +29,7 @@
 #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/parameters.h"
 #include "projectM-4/render_opengl.h"

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

@@ -1,6 +1,6 @@
 /**
  * @file render_opengl.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Functions to configure and render projectM visuals using OpenGL.
  *
  * projectM -- Milkdrop-esque visualisation SDK

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

@@ -1,6 +1,6 @@
 /**
  * @file touch.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Touch-related functions to add random waveforms.
  * @since 4.0.0
  *

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

@@ -1,6 +1,6 @@
 /**
  * @file types.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Types and enumerations used in the other API headers.
  * @since 4.0.0
  *
@@ -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/api/include/projectM-4/user_sprites.h

@@ -1,6 +1,6 @@
 /**
  * @file user_sprites.h
- * @copyright 2003-2024 projectM Team
+ * @copyright 2003-2025 projectM Team
  * @brief Types and enumerations used in the other API headers.
  * @since 4.2.0
  *

src/libprojectM/CMakeLists.txt

@@ -13,6 +13,8 @@ add_subdirectory(UserSprites)
 
 add_library(projectM_main OBJECT
         "${PROJECTM_EXPORT_HEADER}"
+        Logging.cpp
+        Logging.hpp
         Preset.hpp
         PresetFactory.cpp
         PresetFactory.hpp