Reuse GPU textures between chained placebo filters

When multiple placebo filters are stacked on one clip, each filter
previously did a full RAM→GPU upload and GPU→RAM download. The
intermediate uploads are redundant because the next placebo filter
would re-upload the same pixels immediately.

Each filter now attaches its output texture to the mlt_frame via
placebo_frame_put_tex(). The next placebo filter calls
placebo_frame_take_tex() to grab it directly as source, skipping
the upload. The download to RAM still happens every time (MLT
expects the image buffer to be current for non-GPU filters).

Staleness detection: put_tex records the RAM buffer pointer,
take_tex compares it against the current pointer. If a CPU filter
ran in between and requested a writable buffer (triggering a copy
and new allocation), the pointers differ and take_tex returns NULL,
falling back to a fresh upload.

Also cleans up internal ticket-style comments (C1/W2/etc.) with
descriptions of actual logic and pitfalls.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: D-Ogi

src/modules/placebo/filter_placebo_render.c

@@ -99,7 +99,7 @@ static int filter_get_image(mlt_frame frame,
         return mlt_frame_get_image(frame, image, format, width, height, writable);
     }
 
-    /* W2 fix: verify RGBA8 format is supported */
+    /* Not all GPU backends guarantee rgba8 support (e.g. some OpenGL ES) */
     pl_fmt rgba_fmt = pl_find_named_fmt(gpu, "rgba8");
     if (!rgba_fmt) {
         mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU does not support rgba8 format\n");
@@ -116,38 +116,48 @@ static int filter_get_image(mlt_frame frame,
     int h = *height;
     size_t stride = w * 4;
 
-    /* W4 fix: hold render lock for all GPU operations */
+    /* pl_renderer is not thread-safe; hold the lock for the entire
+     * upload → render → download sequence */
     placebo_render_lock();
 
-    /* Create source texture and upload */
-    pl_tex src_tex = pl_tex_create(gpu,
-                                   pl_tex_params(.w = w,
-                                                 .h = h,
-                                                 .format = rgba_fmt,
-                                                 .sampleable = true,
-                                                 .host_writable = true, ));
-    if (!src_tex) {
-        mlt_log_error(MLT_FILTER_SERVICE(filter), "Failed to create source texture\n");
-        placebo_render_unlock();
-        return 0; /* pass through original frame data */
-    }
+    /* Try to reuse a GPU texture left by a preceding placebo filter on
+     * this frame. Returns NULL if there is none, or if the RAM buffer was
+     * reallocated by an intervening CPU filter (stale texture). */
+    pl_tex reused_src = placebo_frame_take_tex(frame, *image);
+    pl_tex src_tex;
+    if (reused_src) {
+        src_tex = reused_src;
+    } else {
+        src_tex = pl_tex_create(gpu,
+                                pl_tex_params(.w = w,
+                                              .h = h,
+                                              .format = rgba_fmt,
+                                              .sampleable = true,
+                                              .host_writable = true, ));
+        if (!src_tex) {
+            mlt_log_error(MLT_FILTER_SERVICE(filter), "Failed to create source texture\n");
+            placebo_render_unlock();
+            return 0;
+        }
 
-    /* C4 fix: check upload return */
-    if (!pl_tex_upload(gpu,
-                       pl_tex_transfer_params(.tex = src_tex,
-                                              .row_pitch = stride,
-                                              .ptr = *image, ))) {
-        mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU texture upload failed\n");
-        pl_tex_destroy(gpu, &src_tex);
-        placebo_render_unlock();
-        return 0;
+        if (!pl_tex_upload(gpu,
+                           pl_tex_transfer_params(.tex = src_tex,
+                                                  .row_pitch = stride,
+                                                  .ptr = *image, ))) {
+            mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU texture upload failed\n");
+            pl_tex_destroy(gpu, &src_tex);
+            placebo_render_unlock();
+            return 0;
+        }
     }
 
-    /* Create destination texture */
+    /* sampleable is needed so a subsequent placebo filter can bind this
+     * texture as its source without re-uploading from RAM. */
     pl_tex dst_tex = pl_tex_create(gpu,
                                    pl_tex_params(.w = w,
                                                  .h = h,
                                                  .format = rgba_fmt,
+                                                 .sampleable = true,
                                                  .renderable = true,
                                                  .host_readable = true, ));
     if (!dst_tex) {
@@ -228,17 +238,20 @@ static int filter_get_image(mlt_frame frame,
         mlt_log_warning(MLT_FILTER_SERVICE(filter), "pl_render_image failed\n");
     }
 
-    /* C4 fix: check download return */
+    /* Always download to RAM — MLT expects *image to hold current pixels,
+     * even though the texture may be reused on the GPU side. */
     if (!pl_tex_download(gpu,
                          pl_tex_transfer_params(.tex = dst_tex,
                                                 .row_pitch = stride,
                                                 .ptr = *image, ))) {
         mlt_log_warning(MLT_FILTER_SERVICE(filter), "GPU texture download failed\n");
     }
 
-    /* Cleanup textures */
     pl_tex_destroy(gpu, &src_tex);
-    pl_tex_destroy(gpu, &dst_tex);
+    /* Keep dst_tex alive on the frame for the next placebo filter to
+     * pick up via take_tex(). Unclaimed textures are freed automatically
+     * by the frame destructor (frame_gpu_destroy). */
+    placebo_frame_put_tex(frame, dst_tex, *image);
 
     placebo_render_unlock();
 

src/modules/placebo/filter_placebo_shader.c

@@ -34,7 +34,7 @@
 
 #ifdef _WIN32
 #include <windows.h>
-/* Use _stat on Windows to avoid deprecation warnings (S5) */
+/* MSVC marks stat() as deprecated; _stat is the replacement */
 #include <sys/stat.h>
 #define stat_func _stat
 #define stat_struct _stat
@@ -54,7 +54,8 @@ typedef struct
     char *loaded_text;   /* inline text that was loaded */
 } shader_private;
 
-/* C3 fix: single cleanup function used both by filter_close and mlt_properties destructor */
+/* Destructor registered via mlt_properties_set_data; handles both normal
+ * filter teardown and early destruction if the filter is removed mid-session. */
 static void shader_private_destroy(void *ptr)
 {
     shader_private *priv = (shader_private *) ptr;
@@ -81,7 +82,7 @@ static char *read_file(const char *path, size_t *out_len)
     long len = ftell(f);
     fseek(f, 0, SEEK_SET);
 
-    if (len <= 0 || len > 10 * 1024 * 1024) { /* W7 fix: reject files > 10 MB */
+    if (len <= 0 || len > 10 * 1024 * 1024) { /* sanity limit for shader files */
         fclose(f);
         return NULL;
     }
@@ -210,14 +211,14 @@ static int filter_get_image(mlt_frame frame,
         return mlt_frame_get_image(frame, image, format, width, height, writable);
     }
 
-    /* W2 fix: verify RGBA8 format is supported */
+    /* Not all GPU backends guarantee rgba8 support (e.g. some OpenGL ES) */
     pl_fmt rgba_fmt = pl_find_named_fmt(gpu, "rgba8");
     if (!rgba_fmt) {
         mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU does not support rgba8 format\n");
         return mlt_frame_get_image(frame, image, format, width, height, writable);
     }
 
-    /* Get or create private data (C3 fix: single destructor path) */
+    /* Lazily allocate private data; destruction is handled by mlt_properties */
     shader_private *priv = mlt_properties_get_data(filter_props, "_shader_priv", NULL);
     if (!priv) {
         priv = calloc(1, sizeof(shader_private));
@@ -242,38 +243,48 @@ static int filter_get_image(mlt_frame frame,
     int h = *height;
     size_t stride = w * 4;
 
-    /* W4 fix: hold render lock for all GPU operations */
+    /* pl_renderer is not thread-safe; hold the lock for the entire
+     * upload → render → download sequence */
     placebo_render_lock();
 
-    /* Create source texture and upload */
-    pl_tex src_tex = pl_tex_create(gpu,
-                                   pl_tex_params(.w = w,
-                                                 .h = h,
-                                                 .format = rgba_fmt,
-                                                 .sampleable = true,
-                                                 .host_writable = true, ));
-    if (!src_tex) {
-        mlt_log_error(MLT_FILTER_SERVICE(filter), "Failed to create source texture\n");
-        placebo_render_unlock();
-        return 0;
-    }
+    /* Try to reuse a GPU texture left by a preceding placebo filter on
+     * this frame. Returns NULL if there is none, or if the RAM buffer was
+     * reallocated by an intervening CPU filter (stale texture). */
+    pl_tex reused_src = placebo_frame_take_tex(frame, *image);
+    pl_tex src_tex;
+    if (reused_src) {
+        src_tex = reused_src;
+    } else {
+        src_tex = pl_tex_create(gpu,
+                                pl_tex_params(.w = w,
+                                              .h = h,
+                                              .format = rgba_fmt,
+                                              .sampleable = true,
+                                              .host_writable = true, ));
+        if (!src_tex) {
+            mlt_log_error(MLT_FILTER_SERVICE(filter), "Failed to create source texture\n");
+            placebo_render_unlock();
+            return 0;
+        }
 
-    /* C4 fix: check upload return */
-    if (!pl_tex_upload(gpu,
-                       pl_tex_transfer_params(.tex = src_tex,
-                                              .row_pitch = stride,
-                                              .ptr = *image, ))) {
-        mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU texture upload failed\n");
-        pl_tex_destroy(gpu, &src_tex);
-        placebo_render_unlock();
-        return 0;
+        if (!pl_tex_upload(gpu,
+                           pl_tex_transfer_params(.tex = src_tex,
+                                                  .row_pitch = stride,
+                                                  .ptr = *image, ))) {
+            mlt_log_error(MLT_FILTER_SERVICE(filter), "GPU texture upload failed\n");
+            pl_tex_destroy(gpu, &src_tex);
+            placebo_render_unlock();
+            return 0;
+        }
     }
 
-    /* Create destination texture */
+    /* sampleable is needed so a subsequent placebo filter can bind this
+     * texture as its source without re-uploading from RAM. */
     pl_tex dst_tex = pl_tex_create(gpu,
                                    pl_tex_params(.w = w,
                                                  .h = h,
                                                  .format = rgba_fmt,
+                                                 .sampleable = true,
                                                  .renderable = true,
                                                  .host_readable = true, ));
     if (!dst_tex) {
@@ -315,17 +326,20 @@ static int filter_get_image(mlt_frame frame,
         mlt_log_warning(MLT_FILTER_SERVICE(filter), "pl_render_image with shader hook failed\n");
     }
 
-    /* C4 fix: check download return */
+    /* Always download to RAM — MLT expects *image to hold current pixels,
+     * even though the texture may be reused on the GPU side. */
     if (!pl_tex_download(gpu,
                          pl_tex_transfer_params(.tex = dst_tex,
                                                 .row_pitch = stride,
                                                 .ptr = *image, ))) {
         mlt_log_warning(MLT_FILTER_SERVICE(filter), "GPU texture download failed\n");
     }
 
-    /* Cleanup */
     pl_tex_destroy(gpu, &src_tex);
-    pl_tex_destroy(gpu, &dst_tex);
+    /* Keep dst_tex alive on the frame for the next placebo filter to
+     * pick up via take_tex(). Unclaimed textures are freed automatically
+     * by the frame destructor (frame_gpu_destroy). */
+    placebo_frame_put_tex(frame, dst_tex, *image);
 
     placebo_render_unlock();
 
@@ -347,7 +361,6 @@ mlt_filter filter_placebo_shader_init(mlt_profile profile,
     mlt_filter filter = mlt_filter_new();
     if (filter) {
         filter->process = filter_process;
-        /* C3 fix: no filter->close needed -- cleanup via mlt_properties destructor */
         mlt_properties props = MLT_FILTER_PROPERTIES(filter);
         mlt_properties_set(props, "shader_path", arg ? arg : "");
         mlt_properties_set(props, "shader_text", "");

src/modules/placebo/gpu_context.c

@@ -19,6 +19,7 @@
 
 #include "gpu_context.h"
 
+#include <framework/mlt_frame.h>
 #include <libplacebo/cache.h>
 #include <libplacebo/dispatch.h>
 #include <libplacebo/gpu.h>
@@ -63,7 +64,7 @@ static pl_d3d11 s_d3d11 = NULL;
 
 #ifdef PL_HAVE_VULKAN
 static pl_vulkan s_vulkan = NULL;
-static pl_vk_inst s_vk_inst = NULL; /* stored to avoid leak (W1) */
+static pl_vk_inst s_vk_inst = NULL; /* must outlive pl_vulkan; destroyed in gpu_release */
 #ifdef _WIN32
 static HMODULE s_vulkan_dll = NULL; /* dynamically loaded vulkan-1.dll */
 #endif
@@ -80,7 +81,7 @@ static pl_cache s_cache = NULL;
 
 static int s_initialized = 0;
 
-/* ---------- Mutex (C1 fix: use SRWLOCK on Windows -- statically initializable) ---------- */
+/* ---------- Mutex (SRWLOCK on Windows is statically initializable, unlike CRITICAL_SECTION) ---------- */
 
 #ifdef _WIN32
 static SRWLOCK s_mutex = SRWLOCK_INIT;
@@ -165,7 +166,7 @@ static void ensure_cache_dir(const char *path)
     char *last_sep = strrchr(dir, '/');
     if (last_sep) {
         *last_sep = '\0';
-        mkdir(dir, 0755); /* W5 fix: actually create the directory */
+        mkdir(dir, 0755);
     }
 #endif
 }
@@ -304,7 +305,6 @@ static int init_gpu(void)
 
     load_cache();
 
-    /* C2 fix: register cleanup at process exit */
     atexit(placebo_gpu_release);
 
     return 1;
@@ -358,7 +358,6 @@ pl_renderer placebo_renderer_get(void)
     return result;
 }
 
-/* W4 fix: render lock for thread safety around pl_renderer/pl_dispatch calls */
 void placebo_render_lock(void)
 {
     RENDER_LOCK();
@@ -369,6 +368,81 @@ void placebo_render_unlock(void)
     RENDER_UNLOCK();
 }
 
+/* ---------- Frame GPU texture reuse ----------
+ *
+ * When multiple placebo filters are chained on one producer, each filter
+ * would normally upload the frame to GPU, render, and download back to RAM.
+ * For N filters that means N uploads and N downloads — the intermediate
+ * RAM roundtrips are pure waste because the next placebo filter will
+ * re-upload the same data immediately.
+ *
+ * To avoid this, each placebo filter attaches its output texture to the
+ * mlt_frame via put_tex(). The next placebo filter in the chain calls
+ * take_tex() to grab it and use it directly as its source, skipping the
+ * upload. The download to RAM still happens every time (MLT expects the
+ * image buffer to be current), but the upload is eliminated for all
+ * filters after the first one.
+ *
+ * Staleness detection: if a non-placebo CPU filter runs between two
+ * placebo filters, it may reallocate the image buffer (e.g. via
+ * mlt_frame_get_image with writable=1, which triggers a copy).
+ * put_tex() records the buffer pointer, and take_tex() compares it
+ * against the current pointer. A mismatch means the texture content
+ * no longer matches RAM, so take_tex() returns NULL and the caller
+ * falls back to a fresh upload. This is safe because MLT's standard
+ * mechanism for a filter to modify frame data is to request a writable
+ * buffer, which always produces a new allocation.
+ */
+
+typedef struct
+{
+    pl_tex tex;
+    const uint8_t *image_ptr; /* RAM buffer address at time of put_tex */
+} placebo_frame_gpu;
+
+/* Called by mlt_properties when the frame is destroyed or the property
+ * is overwritten. Must acquire render_lock because pl_tex_destroy
+ * touches GPU state, and this destructor may fire from any thread. */
+static void frame_gpu_destroy(void *ptr)
+{
+    placebo_frame_gpu *d = ptr;
+    if (d && d->tex) {
+        pl_gpu gpu = placebo_gpu_get();
+        if (gpu) {
+            placebo_render_lock();
+            pl_tex_destroy(gpu, &d->tex);
+            placebo_render_unlock();
+        }
+    }
+    free(d);
+}
+
+pl_tex placebo_frame_take_tex(mlt_frame frame, const uint8_t *current_image)
+{
+    mlt_properties props = MLT_FRAME_PROPERTIES(frame);
+    placebo_frame_gpu *d = mlt_properties_get_data(props, "_placebo_gpu", NULL);
+    if (!d || !d->tex)
+        return NULL;
+    if (d->image_ptr != current_image)
+        return NULL; /* buffer was reallocated — texture is stale */
+    pl_tex tex = d->tex;
+    d->tex = NULL; /* transfer ownership to caller; disarm destructor */
+    return tex;
+}
+
+void placebo_frame_put_tex(mlt_frame frame, pl_tex tex, const uint8_t *image_ptr)
+{
+    placebo_frame_gpu *d = calloc(1, sizeof(placebo_frame_gpu));
+    d->tex = tex;
+    d->image_ptr = image_ptr;
+    /* If a previous texture was attached, set_data replaces it and
+     * frame_gpu_destroy fires for the old one. After take_tex() the
+     * old entry has tex=NULL so the destructor becomes a no-op. */
+    mlt_properties_set_data(MLT_FRAME_PROPERTIES(frame), "_placebo_gpu", d, 0, frame_gpu_destroy, NULL);
+}
+
+/* ---------- GPU teardown ---------- */
+
 void placebo_gpu_release(void)
 {
     LOCK();
@@ -405,7 +479,6 @@ void placebo_gpu_release(void)
         pl_vulkan_destroy(&s_vulkan);
         s_vulkan = NULL;
     }
-    /* W1 fix: destroy Vulkan instance */
     if (s_vk_inst) {
         pl_vk_inst_destroy(&s_vk_inst);
         s_vk_inst = NULL;