Add texture loading callback for custom texture sources

Mischa · claude · revmischa · commit 85b8c08a02aa · 2026-02-01T17:13:33.000-08:00
Adds a callback that allows applications to provide textures from non-filesystem sources like archives, network, or procedurally generated content. The callback receives the texture name and can return either raw pixel data or an existing OpenGL texture ID. Changes: - Add SetTextureLoadCallback API for custom texture loading - Add texture ownership tracking to prevent deletion of app-provided textures - Update texture creation to use stb_image instead of SOIL - Add validation and error logging for callback-provided textures Fixes #870 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/src/api/include/projectM-4/callbacks.h b/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
diff --git a/src/libprojectM/CMakeLists.txt b/src/libprojectM/CMakeLists.txt
@@ -205,6 +205,7 @@ if(ENABLE_INSTALL)
 
         install(FILES
                 Renderer/RenderContext.hpp
+                Renderer/TextureTypes.hpp
                 DESTINATION "${PROJECTM_INCLUDE_DIR}/projectM-4/Renderer"
                 COMPONENT Devel
                 )
diff --git a/src/libprojectM/ProjectM.cpp b/src/libprojectM/ProjectM.cpp
@@ -89,11 +89,28 @@ void ProjectM::SetTexturePaths(std::vector<std::string> texturePaths)
 {
     m_textureSearchPaths = std::move(texturePaths);
     m_textureManager = std::make_unique<Renderer::TextureManager>(m_textureSearchPaths);
+    if (m_textureLoadCallback)
+    {
+        m_textureManager->SetTextureLoadCallback(m_textureLoadCallback);
+    }
 }
 
 void ProjectM::ResetTextures()
 {
     m_textureManager = std::make_unique<Renderer::TextureManager>(m_textureSearchPaths);
+    if (m_textureLoadCallback)
+    {
+        m_textureManager->SetTextureLoadCallback(m_textureLoadCallback);
+    }
+}
+
+void ProjectM::SetTextureLoadCallback(Renderer::TextureLoadCallback callback)
+{
+    m_textureLoadCallback = std::move(callback);
+    if (m_textureManager)
+    {
+        m_textureManager->SetTextureLoadCallback(m_textureLoadCallback);
+    }
 }
 
 void ProjectM::RenderFrame(uint32_t targetFramebufferObject /*= 0*/)
diff --git a/src/libprojectM/ProjectM.hpp b/src/libprojectM/ProjectM.hpp
@@ -23,6 +23,7 @@
 #include <projectM-4/projectM_cxx_export.h>
 
 #include <Renderer/RenderContext.hpp>
+#include <Renderer/TextureTypes.hpp>
 
 #include <Audio/PCM.hpp>
 
@@ -113,6 +114,12 @@ class PROJECTM_CXX_EXPORT ProjectM
 
     void ResetTextures();
 
+    /**
+     * @brief Sets a callback function for loading textures from non-filesystem sources.
+     * @param callback The callback function, or nullptr to disable.
+     */
+    void SetTextureLoadCallback(Renderer::TextureLoadCallback callback);
+
     void RenderFrame(uint32_t targetFramebufferObject = 0);
 
     /**
@@ -290,7 +297,8 @@ class PROJECTM_CXX_EXPORT ProjectM
     float m_texelOffsetX{0.0};       //!< Horizontal warp shader texel offset
     float m_texelOffsetY{0.0};       //!< Vertical warp shader texel offset
 
-    std::vector<std::string> m_textureSearchPaths; ///!< List of paths to search for texture files
+    std::vector<std::string> m_textureSearchPaths;     ///!< List of paths to search for texture files
+    Renderer::TextureLoadCallback m_textureLoadCallback; //!< Optional callback for loading textures from non-filesystem sources.
 
     /** Timing information */
     int m_frameCount{0}; //!< Rendered frame count since start
diff --git a/src/libprojectM/ProjectMCWrapper.cpp b/src/libprojectM/ProjectMCWrapper.cpp
@@ -116,6 +116,39 @@ void projectm_set_preset_switch_failed_event_callback(projectm_handle instance,
     projectMInstance->m_presetSwitchFailedEventUserData = user_data;
 }
 
+void projectm_set_texture_load_event_callback(projectm_handle instance,
+                                              projectm_texture_load_event callback, void* user_data)
+{
+    auto projectMInstance = handle_to_instance(instance);
+    projectMInstance->m_textureLoadEventCallback = callback;
+    projectMInstance->m_textureLoadEventUserData = user_data;
+
+    if (callback != nullptr)
+    {
+        // Create a wrapper lambda that bridges C callback to C++ callback
+        projectMInstance->SetTextureLoadCallback(
+            [projectMInstance](const std::string& textureName, libprojectM::Renderer::TextureLoadData& data) {
+                if (projectMInstance->m_textureLoadEventCallback)
+                {
+                    projectm_texture_load_data cData{};
+                    projectMInstance->m_textureLoadEventCallback(
+                        textureName.c_str(), &cData, projectMInstance->m_textureLoadEventUserData);
+
+                    // Copy data from C structure to C++ structure
+                    data.data = cData.data;
+                    data.width = cData.width;
+                    data.height = cData.height;
+                    data.channels = cData.channels;
+                    data.textureId = cData.texture_id;
+                }
+            });
+    }
+    else
+    {
+        projectMInstance->SetTextureLoadCallback(nullptr);
+    }
+}
+
 void projectm_set_texture_search_paths(projectm_handle instance,
                                        const char** texture_search_paths,
                                        size_t count)
diff --git a/src/libprojectM/ProjectMCWrapper.hpp b/src/libprojectM/ProjectMCWrapper.hpp
@@ -39,6 +39,9 @@ class projectMWrapper : public ProjectM
 
     projectm_preset_switch_requested_event m_presetSwitchRequestedEventCallback{nullptr};
     void* m_presetSwitchRequestedEventUserData{nullptr};
+
+    projectm_texture_load_event m_textureLoadEventCallback{nullptr};
+    void* m_textureLoadEventUserData{nullptr};
 };
 
 } // namespace libprojectM
diff --git a/src/libprojectM/Renderer/Texture.cpp b/src/libprojectM/Renderer/Texture.cpp
@@ -34,13 +34,14 @@ Texture::Texture(std::string name, GLenum target, int width, int height, int dep
 }
 
 Texture::Texture(std::string name, const GLuint texID, const GLenum target,
-                 const int width, const int height, const bool isUserTexture)
+                 const int width, const int height, const bool isUserTexture, const bool owned)
     : m_textureId(texID)
     , m_target(target)
     , m_name(std::move(name))
     , m_width(width)
     , m_height(height)
     , m_isUserTexture(isUserTexture)
+    , m_owned(owned)
 {
 }
 
@@ -61,7 +62,7 @@ Texture::Texture(std::string name, const void* data, GLenum target, int width, i
 
 Texture::~Texture()
 {
-    if (m_textureId > 0)
+    if (m_textureId > 0 && m_owned)
     {
         glDeleteTextures(1, &m_textureId);
         m_textureId = 0;
diff --git a/src/libprojectM/Renderer/Texture.hpp b/src/libprojectM/Renderer/Texture.hpp
@@ -53,17 +53,18 @@ class Texture
 
     /**
      * @brief Constructor. Creates a new texture instance from an existing OpenGL texture.
-     * The class will take ownership of the texture, e.g. freeing it when destroyed!
      * @param name Optional name of the texture for referencing in Milkdrop shaders.
      * @param texID The OpenGL texture name (ID).
      * @param target The texture target type, e.g. GL_TEXTURE_2D.
      * @param width Width in pixels.
      * @param height Height in pixels.
      * @param isUserTexture true if the texture is an externally-loaded image, false if it's an internal texture.
+     * @param owned If true (default), the class takes ownership and will delete the texture when destroyed.
+     *              If false, the texture is managed externally and won't be deleted.
      */
     explicit Texture(std::string name, GLuint texID, GLenum target,
                      int width, int height,
-                     bool isUserTexture);
+                     bool isUserTexture, bool owned = true);
 
     /**
      * @brief Constructor. Creates a new texture from image data with the given size and format.
@@ -169,6 +170,7 @@ class Texture
     int m_height{0};             //!< Texture height in pixels.
     int m_depth{0};              //!< Texture depth in pixels. Only used for 3D textures.
     bool m_isUserTexture{false}; //!< true if it's a user texture, false if an internal one.
+    bool m_owned{true};          //!< true if this class owns the texture and should delete it.
 
     GLint m_internalFormat{}; //!< OpenGL internal format, e.g. GL_RGBA8
     GLenum m_format{};        //!< OpenGL color format, e.g. GL_RGBA
diff --git a/src/libprojectM/Renderer/TextureManager.cpp b/src/libprojectM/Renderer/TextureManager.cpp
@@ -173,9 +173,61 @@ auto TextureManager::TryLoadingTexture(const std::string& name) -> TextureSample
 
     ExtractTextureSettings(name, wrapMode, filterMode, unqualifiedName);
 
+    std::string lowerCaseUnqualifiedName = Utils::ToLower(unqualifiedName);
+
+    // Try callback first if registered
+    if (m_textureLoadCallback)
+    {
+        TextureLoadData loadData;
+        m_textureLoadCallback(unqualifiedName, loadData);
+
+        // Check if callback provided an existing OpenGL texture ID
+        if (loadData.textureId != 0 && loadData.width > 0 && loadData.height > 0)
+        {
+            // App-provided textures are not owned by projectM - pass false for ownership
+            auto newTexture = std::make_shared<Texture>(unqualifiedName, loadData.textureId,
+                                                        GL_TEXTURE_2D, loadData.width, loadData.height, true, false);
+            m_textures[lowerCaseUnqualifiedName] = newTexture;
+            uint32_t memoryBytes = loadData.width * loadData.height * (loadData.channels > 0 ? loadData.channels : 4);
+            m_textureStats.insert({lowerCaseUnqualifiedName, {memoryBytes}});
+            LOG_DEBUG("[TextureManager] Loaded texture \"" + unqualifiedName + "\" from callback (texture ID)");
+            return {newTexture, m_samplers.at({wrapMode, filterMode}), name, unqualifiedName};
+        }
+        else if (loadData.textureId != 0)
+        {
+            LOG_WARN("[TextureManager] Callback provided texture ID for \"" + unqualifiedName + "\" but width/height are invalid; falling back to filesystem");
+        }
+
+        // Check if callback provided raw pixel data
+        if (loadData.data != nullptr && loadData.width > 0 && loadData.height > 0)
+        {
+            int width = static_cast<int>(loadData.width);
+            int height = static_cast<int>(loadData.height);
+            int channels = static_cast<int>(loadData.channels > 0 ? loadData.channels : 4);
+
+            auto format = TextureFormatFromChannels(channels);
+            auto newTexture = std::make_shared<Texture>(unqualifiedName,
+                                                        reinterpret_cast<const void*>(loadData.data),
+                                                        GL_TEXTURE_2D, width, height, 0,
+                                                        format, format, GL_UNSIGNED_BYTE, true);
+            if (!newTexture->Empty())
+            {
+                m_textures[lowerCaseUnqualifiedName] = newTexture;
+                uint32_t memoryBytes = width * height * channels;
+                m_textureStats.insert({lowerCaseUnqualifiedName, {memoryBytes}});
+                LOG_DEBUG("[TextureManager] Loaded texture \"" + unqualifiedName + "\" from callback (pixel data)");
+                return {newTexture, m_samplers.at({wrapMode, filterMode}), name, unqualifiedName};
+            }
+            else
+            {
+                LOG_WARN("[TextureManager] Failed to create OpenGL texture from callback pixel data for \"" + unqualifiedName + "\"; falling back to filesystem");
+            }
+        }
+    }
+
+    // Fall back to filesystem loading
     ScanTextures();
 
-    std::string lowerCaseUnqualifiedName = Utils::ToLower(unqualifiedName);
     for (const auto& file : m_scannedTextureFiles)
     {
         if (file.lowerCaseBaseName != lowerCaseUnqualifiedName)
@@ -377,5 +429,10 @@ uint32_t TextureManager::TextureFormatFromChannels(int channels)
     }
 }
 
+void TextureManager::SetTextureLoadCallback(TextureLoadCallback callback)
+{
+    m_textureLoadCallback = std::move(callback);
+}
+
 } // namespace Renderer
 } // namespace libprojectM
diff --git a/src/libprojectM/Renderer/TextureManager.hpp b/src/libprojectM/Renderer/TextureManager.hpp
@@ -1,6 +1,7 @@
 #pragma once
 
 #include "Renderer/TextureSamplerDescriptor.hpp"
+#include "Renderer/TextureTypes.hpp"
 
 #include <map>
 #include <string>
@@ -58,6 +59,12 @@ class TextureManager
      */
     void PurgeTextures();
 
+    /**
+     * @brief Sets a callback function for loading textures from non-filesystem sources.
+     * @param callback The callback function, or nullptr to disable.
+     */
+    void SetTextureLoadCallback(TextureLoadCallback callback);
+
 private:
     /**
      * Texture usage statistics. Used to determine when to purge a texture.
@@ -103,6 +110,8 @@ class TextureManager
     std::map<std::string, UsageStats> m_textureStats;                       //!< Map with texture stats for user-loaded files.
     std::vector<std::string> m_randomTextures;
     std::vector<std::string> m_extensions{".jpg", ".jpeg", ".dds", ".png", ".tga", ".bmp", ".dib"};
+
+    TextureLoadCallback m_textureLoadCallback; //!< Optional callback for loading textures from non-filesystem sources.
 };
 
 } // namespace Renderer
diff --git a/src/libprojectM/Renderer/TextureTypes.hpp b/src/libprojectM/Renderer/TextureTypes.hpp
@@ -0,0 +1,28 @@
+#pragma once
+
+#include <functional>
+#include <string>
+
+namespace libprojectM {
+namespace Renderer {
+
+/**
+ * @brief Structure containing texture data provided by a callback.
+ */
+struct TextureLoadData {
+    const unsigned char* data{nullptr}; //!< Pointer to raw pixel data (RGBA/RGB format).
+    unsigned int width{0};              //!< Width of the texture in pixels.
+    unsigned int height{0};             //!< Height of the texture in pixels.
+    unsigned int channels{0};           //!< Number of color channels (3 for RGB, 4 for RGBA).
+    unsigned int textureId{0};          //!< An existing OpenGL texture ID to use.
+};
+
+/**
+ * @brief Callback function type for loading textures.
+ * @param textureName The name of the texture being requested.
+ * @param[out] data Structure to fill with texture data.
+ */
+using TextureLoadCallback = std::function<void(const std::string& textureName, TextureLoadData& data)>;
+
+} // namespace Renderer
+} // namespace libprojectM

Original file line number	Diff line number	Diff line change
`@@ -205,6 +205,7 @@ if(ENABLE_INSTALL)`
`205`	`205`
`206`	`206`	`install(FILES`
`207`	`207`	`Renderer/RenderContext.hpp`
	`208`	`+ Renderer/TextureTypes.hpp`
`208`	`209`	`DESTINATION "${PROJECTM_INCLUDE_DIR}/projectM-4/Renderer"`
`209`	`210`	`COMPONENT Devel`
`210`	`211`	`)`
Original file line number	Diff line number	Diff line change
`@@ -34,13 +34,14 @@ Texture::Texture(std::string name, GLenum target, int width, int height, int dep`
`34`	`34`	`}`
`35`	`35`
`36`	`36`	`Texture::Texture(std::string name, const GLuint texID, const GLenum target,`
`37`		`- const int width, const int height, const bool isUserTexture)`
	`37`	`+ const int width, const int height, const bool isUserTexture, const bool owned)`
`38`	`38`	`: m_textureId(texID)`
`39`	`39`	`, m_target(target)`
`40`	`40`	`, m_name(std::move(name))`
`41`	`41`	`, m_width(width)`
`42`	`42`	`, m_height(height)`
`43`	`43`	`, m_isUserTexture(isUserTexture)`
	`44`	`+ , m_owned(owned)`
`44`	`45`	`{`
`45`	`46`	`}`
`46`	`47`
`@@ -61,7 +62,7 @@ Texture::Texture(std::string name, const void* data, GLenum target, int width, i`
`61`	`62`
`62`	`63`	`Texture::~Texture()`
`63`	`64`	`{`
`64`		`- if (m_textureId > 0)`
	`65`	`+ if (m_textureId > 0 && m_owned)`
`65`	`66`	`{`
`66`	`67`	`glDeleteTextures(1, &m_textureId);`
`67`	`68`	`m_textureId = 0;`