Merge branch 'master' into feature/playlist-preset-callback-946

Author: revmischa

.github/workflows/build_linux.yml

@@ -64,6 +64,7 @@ jobs:
             -DCMAKE_VERBOSE_MAKEFILE=YES \
             -DBUILD_SHARED_LIBS="${shared_libs}" \
             -DENABLE_BOOST_FILESYSTEM="${use_boost}" \
+            -DENABLE_CXX_INTERFACE=YES \
             -DBUILD_TESTING=YES
 
       - name: Build Debug
@@ -80,6 +81,16 @@ jobs:
           cmake --build "${{ github.workspace }}/cmake-build" --config "Debug" --target install
           cmake --build "${{ github.workspace }}/cmake-build" --config "Release" --target install
 
+      - name: Test C++ Interface
+        run: |
+          cmake -G "Ninja Multi-Config" \
+            -S "${{ github.workspace }}/tests/cxx-interface" \
+            -B "${{ github.workspace }}/cmake-build-cxx-api" \
+            -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install"
+          
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Debug"
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Release"
+
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/build_osx.yml

@@ -65,6 +65,7 @@ jobs:
             -DBUILD_SHARED_LIBS="${shared_libs}" \
             -DENABLE_BOOST_FILESYSTEM="${use_boost}" \
             -DCMAKE_OSX_ARCHITECTURES="${{ matrix.arch }}" \
+            -DENABLE_CXX_INTERFACE=YES \
             -DBUILD_TESTING=YES
 
       - name: Build Debug
@@ -81,6 +82,17 @@ jobs:
           cmake --build "${{ github.workspace }}/cmake-build" --config "Debug" --target install
           cmake --build "${{ github.workspace }}/cmake-build" --config "Release" --target install
 
+      - name: Test C++ Interface
+        run: |
+          cmake -G "Ninja Multi-Config" \
+            -S "${{ github.workspace }}/tests/cxx-interface" \
+            -B "${{ github.workspace }}/cmake-build-cxx-api" \
+            -DCMAKE_OSX_ARCHITECTURES="${{ matrix.arch }}" \
+            -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install"
+          
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Debug"
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Release"
+
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/build_windows.yml

@@ -96,7 +96,9 @@ jobs:
             -DCMAKE_VERBOSE_MAKEFILE=YES `
             -DBUILD_SHARED_LIBS="$($shared_libs)" `
             -DENABLE_BOOST_FILESYSTEM="$($use_boost)" `
-            -DBUILD_TESTING=YES
+            -DENABLE_CXX_INTERFACE=YES `
+            -DBUILD_TESTING=YES `
+            -DCMAKE_VERBOSE_MAKEFILE=ON
 
       - name: Build Debug
         run: cmake --build "${{ github.workspace }}/cmake-build" --config "Debug" --parallel
@@ -112,6 +114,39 @@ jobs:
           cmake --build "${{ github.workspace }}/cmake-build" --config "Debug" --target INSTALL
           cmake --build "${{ github.workspace }}/cmake-build" --config "Release" --target INSTALL
 
+      - name: Test C++ Interface
+        run: |
+          if("${{ matrix.fslib }}" -eq "boost") {
+            $use_boost = "ON"
+          } else {
+            $use_boost = "OFF"
+          }
+          if("${{ matrix.arch }}" -eq "X64") {
+            $triplet = "x64-windows"
+          } else {
+            $triplet = "x86-windows"
+          }
+          if("${{ matrix.libs }}" -eq "shared") {
+            $runtime = "DLL"
+          } else {
+            $runtime = ""
+            $triplet = $triplet + "-static"
+          }
+          
+          cmake -G "Visual Studio 17 2022" `
+            -A "${{ matrix.arch }}" `
+            -S "${{ github.workspace }}/tests/cxx-interface" `
+            -B "${{ github.workspace }}/cmake-build-cxx-api" `
+            -DCMAKE_PREFIX_PATH="${{ github.workspace }}/install" `
+            -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>$($runtime)" `
+            -DCMAKE_TOOLCHAIN_FILE="${Env:VCPKG_INSTALLATION_ROOT}/scripts/buildsystems/vcpkg.cmake" `
+            -DVCPKG_TARGET_TRIPLET="$($triplet)" `
+            -DENABLE_BOOST_FILESYSTEM="$($use_boost)" `
+            -DCMAKE_VERBOSE_MAKEFILE=ON
+          
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Debug"
+          cmake --build "${{ github.workspace }}/cmake-build-cxx-api" --config "Release"
+
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:

CMakeLists.txt

@@ -97,6 +97,7 @@ endif()
 cmake_dependent_option(BUILD_SHARED_LIBS "Build and install libprojectM as a shared libraries. If OFF, builds as static libraries." ON "NOT ENABLE_EMSCRIPTEN" OFF)
 cmake_dependent_option(ENABLE_GLES "Enable OpenGL ES support" OFF "NOT ENABLE_EMSCRIPTEN AND NOT CMAKE_SYSTEM_NAME STREQUAL Android" ON)
 cmake_dependent_option(ENABLE_INSTALL "Enable installing projectM libraries and headers." OFF "NOT PROJECT_IS_TOP_LEVEL" ON)
+cmake_dependent_option(ENABLE_MACOS_FRAMEWORK "Build as macOS Framework bundles instead of plain shared libraries." OFF "CMAKE_SYSTEM_NAME STREQUAL Darwin AND BUILD_SHARED_LIBS" OFF)
 
 # Experimental/unsupported features
 option(ENABLE_CXX_INTERFACE "Enable exporting C++ symbols for ProjectM and PCM classes, not only the C API. Warning: This is not very portable." OFF)
@@ -199,16 +200,6 @@ else()
     endif()
 endif()
 
-if(ENABLE_CXX_INTERFACE)
-    set(CMAKE_C_VISIBILITY_PRESET default)
-    set(CMAKE_CXX_VISIBILITY_PRESET default)
-    set(CMAKE_VISIBILITY_INLINES_HIDDEN OFF)
-else()
-    set(CMAKE_C_VISIBILITY_PRESET hidden)
-    set(CMAKE_CXX_VISIBILITY_PRESET hidden)
-    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>
@@ -278,6 +269,7 @@ if(ENABLE_SDL_UI)
     message(STATUS "        SDL2 version:            ${SDL2_VERSION}")
 endif()
 message(STATUS "    OpenGL ES:                   ${ENABLE_GLES}")
+message(STATUS "    macOS Framework:             ${ENABLE_MACOS_FRAMEWORK}")
 message(STATUS "    Emscripten:                  ${ENABLE_EMSCRIPTEN}")
 if(CMAKE_SYSTEM_NAME STREQUAL Emscripten)
     message(STATUS "    - PThreads:              ${USE_PTHREADS}")

src/api/CMakeLists.txt

@@ -11,23 +11,35 @@ generate_export_header(projectM_api
         EXPORT_FILE_NAME "${PROJECTM_EXPORT_HEADER}"
         )
 
+# Always generate the header, but we only install it if the C++ interface is actually enabled.
+set(PROJECTM_CXX_EXPORT_HEADER "${CMAKE_CURRENT_BINARY_DIR}/include/projectM-4/projectM_cxx_export.h")
+
+generate_export_header(projectM_api
+        BASE_NAME projectM_CXX
+        EXPORT_FILE_NAME "${PROJECTM_CXX_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/parameters.h
-        include/projectM-4/projectM.h
-        include/projectM-4/render_opengl.h
-        include/projectM-4/touch.h
-        include/projectM-4/types.h
-        include/projectM-4/user_sprites.h
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/audio.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/callbacks.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/core.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/debug.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/logging.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/memory.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/parameters.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/projectM.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/render_opengl.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/touch.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/types.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/projectM-4/user_sprites.h"
         )
 
+if(ENABLE_CXX_INTERFACE)
+    list(APPEND PROJECTM_PUBLIC_HEADERS ${PROJECTM_CXX_EXPORT_HEADER})
+endif()
+
 target_sources(projectM_api
         PRIVATE
         ${PROJECTM_PUBLIC_HEADERS}
@@ -46,6 +58,14 @@ target_include_directories(projectM_api
         "$<INSTALL_INTERFACE:${PROJECTM_INCLUDE_DIR}>"
         )
 
+if(NOT BUILD_SHARED_LIBS)
+    target_compile_definitions(projectM_api
+            INTERFACE
+            PROJECTM_STATIC_DEFINE
+            PROJECTM_CXX_STATIC_DEFINE
+            )
+endif()
+
 add_library(libprojectM::API ALIAS projectM_api)
 
 

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

@@ -88,6 +88,79 @@ PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_h
                                                                       projectm_preset_switch_failed_event callback,
                                                                       void* user_data);
 
+/**
+ * @brief Structure containing texture data returned by the texture load callback.
+ *
+ * Applications can provide texture data in one of two ways:
+ * 1. Raw pixel data: Set data to a valid pointer, width/height to the dimensions,
+ *    and channels to the number of color channels (3 for RGB, 4 for RGBA).
+ * 2. Existing OpenGL texture: Set texture_id to a valid OpenGL texture ID.
+ *
+ * If both are provided, the texture_id takes precedence.
+ * If neither is provided (data is NULL and texture_id is 0), projectM will
+ * attempt to load the texture from the filesystem.
+ *
+ * @warning When providing a texture_id, projectM takes ownership of the OpenGL texture
+ *          and will delete it (via glDeleteTextures) when it is no longer needed. Do not
+ *          delete the texture yourself or reuse the texture ID after passing it here.
+ *
+ * @since 4.2.0
+ */
+typedef struct projectm_texture_load_data {
+    const unsigned char* data; /**< Pointer to raw pixel data in standard OpenGL format (first row is bottom of image). Can be NULL. */
+    unsigned int width;        /**< Width of the texture in pixels. Must be > 0 when providing data or texture_id. */
+    unsigned int height;       /**< Height of the texture in pixels. Must be > 0 when providing data or texture_id. */
+    unsigned int channels;     /**< Number of color channels (3 for RGB, 4 for RGBA). */
+    unsigned int texture_id;   /**< An existing OpenGL texture ID to use. Set to 0 if not used. */
+} projectm_texture_load_data;
+
+/**
+ * @brief Callback function that is executed when projectM needs to load a texture.
+ *
+ * This callback allows applications to provide textures from sources other than
+ * the filesystem, such as:
+ * - Loading textures from archives (e.g., ZIP files)
+ * - Loading textures over the network
+ * - Generating textures procedurally
+ * - Providing pre-loaded textures or video frames
+ *
+ * When called, the application should populate the provided data structure with
+ * either raw pixel data or an OpenGL texture ID. If the application cannot provide
+ * the requested texture, it should leave the structure unchanged (data = NULL,
+ * texture_id = 0) and projectM will fall back to loading from the filesystem.
+ *
+ * @note The texture_name pointer is only valid inside the callback. Make a copy if
+ *       it needs to be retained for later use.
+ * @note If providing raw pixel data, the data pointer must remain valid until
+ *       projectM has finished processing it (i.e., until the callback returns).
+ * @note This callback is always invoked from the same thread that calls projectM
+ *       rendering functions. No additional synchronization is required.
+ *
+ * @param texture_name The name of the texture being requested, as used in the preset.
+ * @param[out] data Pointer to a structure where the application should place texture data.
+ * @param user_data A user-defined data pointer that was provided when registering the callback.
+ * @since 4.2.0
+ */
+typedef void (*projectm_texture_load_event)(const char* texture_name,
+                                            projectm_texture_load_data* data,
+                                            void* user_data);
+
+/**
+ * @brief Sets a callback function that will be called when projectM needs to load a texture.
+ *
+ * This allows applications to provide textures from non-filesystem sources.
+ * Only one callback can be registered per projectM instance. To remove the callback, use NULL.
+ *
+ * @param instance The projectM instance handle.
+ * @param callback A pointer to the callback 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
+ */
+PROJECTM_EXPORT void projectm_set_texture_load_event_callback(projectm_handle instance,
+                                                              projectm_texture_load_event callback,
+                                                              void* user_data);
+
 #ifdef __cplusplus
 } // extern "C"
 #endif

src/libprojectM/Audio/CMakeLists.txt

@@ -20,4 +20,18 @@ target_include_directories(Audio
 target_link_libraries(Audio
         PUBLIC
         libprojectM::API
-        )
+        )
+
+if(BUILD_SHARED_LIBS)
+    if(ENABLE_CXX_INTERFACE)
+        target_compile_definitions(Audio
+                PRIVATE
+                projectM_api_EXPORTS
+                )
+    else()
+        target_compile_definitions(Audio
+                PRIVATE
+                PROJECTM_CXX_STATIC_DEFINE
+                )
+    endif()
+endif()

src/libprojectM/Audio/FrameAudioData.hpp

@@ -8,14 +8,14 @@
 
 #include "Audio/AudioConstants.hpp"
 
-#include <projectM-4/projectM_export.h>
+#include <projectM-4/projectM_cxx_export.h>
 
 #include <array>
 
 namespace libprojectM {
 namespace Audio {
 
-class PROJECTM_EXPORT FrameAudioData
+class PROJECTM_CXX_EXPORT FrameAudioData
 {
 public:
     float bass{0.f};

src/libprojectM/Audio/Loudness.hpp

@@ -7,6 +7,8 @@
 
 #include "Audio/AudioConstants.hpp"
 
+#include <projectM-4/projectM_cxx_export.h>
+
 #include <array>
 #include <cstdint>
 
@@ -16,14 +18,14 @@ namespace Audio {
 /**
  * @brief Calculates beat-detection loudness relative to the previous frame(s).
  */
-class Loudness
+class PROJECTM_CXX_EXPORT Loudness
 {
 public:
     /**
      * @brief Frequency bands.
      * Only the first half of the spectrum is used for these bands, each using one third of this half.
      */
-    enum class Band : int
+    enum class Band : std::uint8_t
     {
         Bass = 0,    //!< Bass band (first sixth of the spectrum)
         Middles = 1, //!< Middles band (second sixth of the spectrum)
@@ -76,7 +78,7 @@ class Loudness
     void UpdateBandAverage(double secondsSinceLastFrame, uint32_t frame);
 
     /**
-     * @brief Adjusts the dampening rate according the the current FPS.
+     * @brief Adjusts the dampening rate according to the current FPS.
      * @param rate The rate to be dampened.
      * @param secondsSinceLastFrame (Fractional) seconds passed since the last frame.
      * @return The dampened rate value.

src/libprojectM/Audio/MilkdropFFT.hpp

@@ -29,7 +29,10 @@ OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 #pragma once
 
+#include <projectM-4/projectM_cxx_export.h>
+
 #include <complex>
+#include <cstddef>
 #include <vector>
 
 namespace libprojectM {
@@ -40,7 +43,7 @@ namespace Audio {
  * Also applies an equalizer pattern with an envelope curve to the resulting data to smooth out
  * certain artifacts.
  */
-class MilkdropFFT
+class PROJECTM_CXX_EXPORT MilkdropFFT
 {
 public:
     /**