Add libplacebo GPU module with render and shader filters (#1236)

* Add libplacebo GPU module with render and shader filters

New module 'placebo' providing GPU-accelerated video processing via
libplacebo. Includes two filters:

- placebo.render: GPU scaling, debanding, dithering, and tonemapping
  with quality presets (fast/default/high_quality)
- placebo.shader: Custom mpv-compatible .hook shader support

Backend priority: D3D11 (Windows) -> Vulkan -> OpenGL.
Vulkan loader is dynamically loaded on Windows when libplacebo is
built without vk-proc-addr support.

Features:
- Singleton GPU context with thread-safe access
- Shader cache persistence
- Multiple scaling algorithms (ewa_lanczos, lanczos, mitchell, etc.)
- Tone mapping (auto, clip, mobius, reinhard, hable, bt.2390, spline)
- Graceful fallback to passthrough when no GPU is available

The module is enabled by default but skipped automatically when
libplacebo is not installed.

* Fix MinGW build: portable format specifiers, add libplacebo to CI

Use PRIu64/PRId64 from <inttypes.h> instead of %zu/%ld for size
logging in the placebo module. Add libplacebo-dev packages to
Ubuntu, Debian, and Fedora 42 CI workflows, and
mingw-w64-x86_64-libplacebo to the MSYS2 MinGW64 workflow.

* Fix clang-format violation in save_cache log line

Break long mlt_log_info() call into multi-line format to match
the project's clang-format rules (same style as load_cache above).

* 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.

* Support DYNAMIC shader parameters and base64-encoded shader_text

Add apply_shader_params() to override pl_hook DYNAMIC parameters from
MLT animated properties (shader_param.* prefix) on every frame.  Uses
mlt_properties_anim_get_double/int to correctly resolve keyframe strings
("0=200;50=100") at the current frame position.

Add base64 decoding for shader_text values prefixed with "base64:" to
support inline shaders with characters that are problematic in MLT
property strings.

* Fix clang-format-14 violations in placebo module

Run clang-format-14 (matching CI) on filter_placebo_shader.c and
gpu_context.c to fix designated initializer spacing, ternary line
breaks, and long argument lists.

* Refactor image conversion

- Refactored image conversion handling across various modules to use new framework functions for better clarity and maintainability.
- Now, there can be multiple possible image converters per frame stopping after the first success. But also, one converter can part of the work (e.g. dowload from GPU) while a later one converts it to the actual requested format.
- Replaced direct calls to `convert_image` with `mlt_frame_convert_image` and added checks for the existence of conversion functions.
- Improved documentation in YAML files to clarify the purpose of image conversion callbacks.
- Added tests to verify the correct propagation of image conversion functions through frames and producers.

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix early returns not releasing lock

* change a log to debug level

* add MLT_PLACEBO_CACHE_PATH and replace atext()

* Add placebo.convert filter

- Introduced new `mlt_image_private` format for module internal use.
- Improved placebo texture reuse across filters.

* fix cppcheck and redundant workflow runs

* fix ctest on msvc

* docs for placebo private image handling

* Enhance image conversion logic to handle private format cases

* Fix double-free of src_tex and out-of-bounds in imageconvert

- Remove incorrect pl_tex_destroy(src_tex) in error paths of the render
  and shader filters: src_tex is owned by the frame and freed automatically
  when placebo_frame_set_tex() replaces the "image" property, so manual
  destruction caused a double-free on frame close.
- Add *image = NULL after failed placebo_frame_set_tex() in render and
  shader filters (consistent with filter_placebo_convert.c).
- Guard filter_imageconvert's conversion_matrix access: mlt_image_private
  (and mlt_image_invalid) are out of range for the matrix indexed by
  [format - 1]; early-return 1 for any format outside [mlt_image_rgb,
  mlt_image_rgba64] to avoid an out-of-bounds read.

Agent-Logs-Url: https://github.com/mltframework/mlt/sessions/f71fd929-5b62-4e71-864a-13291a3ec28e

Co-authored-by: ddennedy <1146683+ddennedy@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix lazy allocation not thread-safe

* fix races in placebo.shader

* Add permanent failure flag for GPU initialization and fix leak

* Add permanent failure and shutdown flags for GPU management

* use "mlt_image_private"

and mlt_properties_clear()

* add `mlt_frame_prepend_convert_image()`

* add `mlt_frame_prepend_convert_image()`

* fix cppcheck and redundant workflow runs

* fix ctest on msvc

* remove placebo.convert filter

prepend the callback on the frame as-needed

* fix cppcheck

* mlt_frame_append_convert_image()

* update CMakeLists.txt to require libplacebo version 5.229

and simplify cppcheck suppression for placebo module

* improve placebo.render meta & cleanup

* Change minimum Fedora build test version to 40

---------

Co-authored-by: D-Ogi <D-Ogi@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ddennedy <1146683+ddennedy@users.noreply.github.com>

Author: 4 people

.github/workflows/build-distros.yml

@@ -19,7 +19,7 @@ on:
           - debian-testing
           - debian-stable
           - fedora-44
-          - fedora-38
+          - fedora-40
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -37,7 +37,7 @@ jobs:
               sed -i 's/^Types: deb/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
               DEBIAN_FRONTEND=noninteractive apt-get -qq update
               DEBIAN_FRONTEND=noninteractive apt-get -yqq build-dep mlt
-              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libqt6svg6-dev
+              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake libplacebo-dev qt6-base-dev libqt6svg6-dev
               git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
               cd /tmp/rnnoise
               ./autogen.sh
@@ -50,7 +50,7 @@ jobs:
               sed -i 's/^Types: deb/Types: deb deb-src/' /etc/apt/sources.list.d/ubuntu.sources
               DEBIAN_FRONTEND=noninteractive apt-get -qq update
               DEBIAN_FRONTEND=noninteractive apt-get -yqq build-dep mlt
-              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libqt6svg6-dev
+              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libplacebo-dev libqt6svg6-dev
               git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
               cd /tmp/rnnoise
               ./autogen.sh
@@ -63,7 +63,7 @@ jobs:
               sed -i '/^#\sdeb-src /s/^#//' "/etc/apt/sources.list"
               DEBIAN_FRONTEND=noninteractive apt-get -qq update
               DEBIAN_FRONTEND=noninteractive apt-get -yqq build-dep mlt
-              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libqt6svg6-dev libqt6core5compat6-dev
+              DEBIAN_FRONTEND=noninteractive apt-get -yqq install autoconf automake git libtool pkg-config wget cmake libplacebo-dev qt6-base-dev libqt6svg6-dev libqt6core5compat6-dev
               git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
               cd /tmp/rnnoise
               ./autogen.sh
@@ -76,7 +76,7 @@ jobs:
               echo 'deb-src http://deb.debian.org/debian testing main' >> /etc/apt/sources.list
               apt-get -qq update
               apt-get -yqq build-dep mlt
-              apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libqt6svg6-dev
+              apt-get -yqq install autoconf automake git libtool pkg-config wget cmake libplacebo-dev qt6-base-dev libqt6svg6-dev
               git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
               cd /tmp/rnnoise
               ./autogen.sh
@@ -90,7 +90,7 @@ jobs:
               echo 'deb http://deb.debian.org/debian bookworm-backports main' >> /etc/apt/sources.list
               apt-get -qq update
               apt-get -yqq build-dep mlt
-              apt-get -yqq install autoconf automake git libtool pkg-config wget cmake qt6-base-dev libqt6svg6-dev
+              apt-get -yqq install autoconf automake git libtool pkg-config wget cmake libplacebo-dev qt6-base-dev libqt6svg6-dev
               git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
               cd /tmp/rnnoise
               ./autogen.sh
@@ -109,9 +109,9 @@ jobs:
                 libtheora-devel libvorbis-devel libvdpau-devel \
                 libsoup-devel liboil-devel python-devel alsa-lib \
                 pulseaudio-libs-devel gcc-c++ cmake ffmpeg-free-devel \
-                movit-devel rubberband-devel vid.stab-devel rnnoise-devel
-          - name: fedora-38
-            image: fedora:38
+                libplacebo-devel movit-devel rubberband-devel vid.stab-devel rnnoise-devel
+          - name: fedora-40
+            image: fedora:40
             setup_script: |
               yum --assumeyes groupinstall "Development Tools"
               yum --assumeyes install \
@@ -122,7 +122,7 @@ jobs:
                 libtheora-devel libvorbis-devel libvdpau-devel \
                 libsoup-devel liboil-devel python-devel alsa-lib \
                 pulseaudio-libs-devel gcc-c++ cmake ffmpeg-free-devel \
-                movit-devel rubberband-devel vid.stab-devel rnnoise-devel
+                libplacebo-devel movit-devel rubberband-devel vid.stab-devel rnnoise-devel
 
     container:
       image: ${{ matrix.image }}

.github/workflows/build-linux.yml

@@ -46,7 +46,7 @@ jobs:
           sudo sed -i '/^#\sdeb-src /s/^#//' "/etc/apt/sources.list"
           sudo apt-get -qq update
           sudo apt-get -yqq build-dep mlt
-          sudo apt-get -yqq install autoconf automake git libtool pkg-config wget qt6-base-dev libqt6svg6-dev libqt6core5compat6-dev
+          sudo apt-get -yqq install autoconf automake git libtool pkg-config wget libplacebo-dev qt6-base-dev libqt6svg6-dev libqt6core5compat6-dev
           git clone --depth 1 --branch v0.2 https://github.com/xiph/rnnoise.git /tmp/rnnoise
           pushd /tmp/rnnoise
           ./autogen.sh

.github/workflows/build-msys2-mingw64.yml

@@ -68,6 +68,7 @@ jobs:
             mingw-w64-x86_64-x264
             mingw-w64-x86_64-x265
             mingw-w64-x86_64-zimg
+            mingw-w64-x86_64-libplacebo
 
       - uses: actions/checkout@v4
 

.github/workflows/static-code-analysis.yml

@@ -27,6 +27,7 @@ jobs:
         --library=cppcheck.cfg
         --suppress=ctuOneDefinitionRuleViolation
         --suppress=syntaxError:src/modules/xml/common.c
+        --suppress=syntaxError:src/modules/placebo/*.c
     steps:
       - uses: actions/checkout@v4
       - name: Install Cppcheck

CMakeLists.txt

@@ -35,6 +35,7 @@ option(MOD_NORMALIZE "Enable Normalize module (GPL)" ON)
 option(MOD_OLDFILM "Enable Oldfilm module" ON)
 option(MOD_OPENCV "Enable OpenCV module" OFF)
 option(MOD_OPENFX "Enable OpenFX module (GPL)" ON)
+option(MOD_PLACEBO "Enable libplacebo GPU module" ON)
 option(MOD_PLUS "Enable Plus module" ON)
 option(MOD_PLUSGPL "Enable PlusGPL module (GPL)" ON)
 option(MOD_QT6 "Enable Qt6 module (GPL)" ON)
@@ -319,6 +320,15 @@ if(MOD_OPENFX)
   pkg_check_modules(glib IMPORTED_TARGET glib-2.0)
 endif()
 
+if(MOD_PLACEBO)
+  pkg_check_modules(libplacebo IMPORTED_TARGET libplacebo>=5.229)
+  if(libplacebo_FOUND)
+    list(APPEND MLT_SUPPORTED_COMPONENTS placebo)
+  else()
+    set(MOD_PLACEBO OFF)
+  endif()
+endif()
+
 if(MOD_PLUS)
   pkg_check_modules(libebur128 IMPORTED_TARGET libebur128)
   list(APPEND MLT_SUPPORTED_COMPONENTS plus)
@@ -598,6 +608,7 @@ add_feature_info("Module: Normalize" MOD_NORMALIZE "")
 add_feature_info("Module: Oldfilm" MOD_OLDFILM "")
 add_feature_info("Module: OpenCV" MOD_OPENCV "")
 add_feature_info("Module: OpenFX" MOD_OPENFX "")
+add_feature_info("Module: Placebo" MOD_PLACEBO "")
 add_feature_info("Module: Plus" MOD_PLUS "")
 add_feature_info("Module: PlusGPL" MOD_PLUSGPL "")
 add_feature_info("Module: Qt6" MOD_QT6 "")

makefile

@@ -30,7 +30,4 @@ cppcheck:
 		--library=cppcheck.cfg \
 		--suppress=ctuOneDefinitionRuleViolation \
 		--suppress=syntaxError:src/modules/xml/common.c \
-        --suppress=syntaxError:src/modules/placebo/filter_placebo_convert.c \
-        --suppress=syntaxError:src/modules/placebo/filter_placebo_render.c \
-        --suppress=syntaxError:src/modules/placebo/filter_placebo_shader.c \
-        --suppress=syntaxError:src/modules/placebo/gpu_context.c
+    --suppress=syntaxError:src/modules/placebo/*.c

src/framework/mlt_frame.c

@@ -448,6 +448,7 @@ static int generate_test_image(mlt_properties properties,
         case mlt_image_none:
         case mlt_image_movit:
         case mlt_image_opengl_texture:
+        case mlt_image_private:
             *format = mlt_image_yuv422;
             break;
         case mlt_image_invalid:
@@ -1157,15 +1158,13 @@ mlt_frame mlt_frame_clone(mlt_frame self, int is_deep)
         }
         size = 0;
         data = mlt_properties_get_data(properties, "image", &size);
-        if (data && mlt_image_movit != mlt_properties_get_int(properties, "format")) {
+        mlt_image_format format = mlt_properties_get_int(properties, "format");
+        if (data && format != mlt_image_movit && format != mlt_image_private) {
             int width = mlt_properties_get_int(properties, "width");
             int height = mlt_properties_get_int(properties, "height");
 
             if (!size)
-                size = mlt_image_format_size(mlt_properties_get_int(properties, "format"),
-                                             width,
-                                             height,
-                                             NULL);
+                size = mlt_image_format_size(format, width, height, NULL);
             copy = mlt_pool_alloc(size);
             memcpy(copy, data, size);
             mlt_properties_set_data(new_props, "image", copy, size, mlt_pool_release, NULL);
@@ -1299,15 +1298,13 @@ mlt_frame mlt_frame_clone_image(mlt_frame self, int is_deep)
 
     if (is_deep) {
         data = mlt_properties_get_data(properties, "image", &size);
-        if (data && mlt_image_movit != mlt_properties_get_int(properties, "format")) {
+        mlt_image_format format = mlt_properties_get_int(properties, "format");
+        if (data && format != mlt_image_movit && format != mlt_image_private) {
             int width = mlt_properties_get_int(properties, "width");
             int height = mlt_properties_get_int(properties, "height");
 
             if (!size)
-                size = mlt_image_format_size(mlt_properties_get_int(properties, "format"),
-                                             width,
-                                             height,
-                                             NULL);
+                size = mlt_image_format_size(format, width, height, NULL);
             copy = mlt_pool_alloc(size);
             memcpy(copy, data, size);
             mlt_properties_set_data(new_props, "image", copy, size, mlt_pool_release, NULL);

src/framework/mlt_image.c

@@ -188,7 +188,8 @@ int mlt_image_calculate_size(mlt_image self)
         return self->width * self->height * 3 / 2;
     case mlt_image_movit:
     case mlt_image_opengl_texture:
-        return 4;
+    case mlt_image_private:
+        return sizeof(void *);
     case mlt_image_yuv422p16:
         return self->width * self->height * 4;
     case mlt_image_yuv420p10:
@@ -228,6 +229,8 @@ const char *mlt_image_format_name(mlt_image_format format)
         return "glsl";
     case mlt_image_opengl_texture:
         return "opengl_texture";
+    case mlt_image_private:
+        return "private";
     case mlt_image_yuv422p16:
         return "yuv422p16";
     case mlt_image_yuv420p10:
@@ -489,6 +492,7 @@ mlt_colorspace mlt_image_default_colorspace(mlt_image_format format, int height)
     case mlt_image_rgba64:
     case mlt_image_movit:
     case mlt_image_opengl_texture:
+    case mlt_image_private:
         colorspace = mlt_colorspace_rgb;
         break;
     case mlt_image_yuv422:
@@ -605,6 +609,7 @@ void mlt_image_fill_black(mlt_image self)
     case mlt_image_none:
     case mlt_image_movit:
     case mlt_image_opengl_texture:
+    case mlt_image_private:
         return;
     case mlt_image_rgb:
     case mlt_image_rgba:
@@ -693,6 +698,7 @@ void mlt_image_fill_checkerboard(mlt_image self, double sample_aspect_ratio)
     case mlt_image_none:
     case mlt_image_movit:
     case mlt_image_opengl_texture:
+    case mlt_image_private:
         return;
     case mlt_image_rgb:
     case mlt_image_rgba: {
@@ -798,6 +804,7 @@ void mlt_image_fill_white(mlt_image self, int full_range)
     case mlt_image_none:
     case mlt_image_movit:
     case mlt_image_opengl_texture:
+    case mlt_image_private:
         return;
     case mlt_image_rgb:
     case mlt_image_rgba:
@@ -952,9 +959,10 @@ int mlt_image_format_size(mlt_image_format format, int width, int height, int *b
         return width * height * 3 / 2;
     case mlt_image_movit:
     case mlt_image_opengl_texture:
+    case mlt_image_private:
         if (bpp)
             *bpp = 0;
-        return 4;
+        return sizeof(void *);
     case mlt_image_yuv422p16:
         if (bpp)
             *bpp = 4;

src/framework/mlt_types.h

@@ -2,7 +2,7 @@
  * \file mlt_types.h
  * \brief Provides forward definitions of all public types
  *
- * Copyright (C) 2003-2025 Meltytech, LLC
+ * Copyright (C) 2003-2026 Meltytech, LLC
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -49,7 +49,8 @@ typedef enum {
     mlt_image_yuv420p10, /**< planar YUV 4:2:0, 15bpp, (1 Cr & Cb sample per 2x2 Y samples), little-endian */
     mlt_image_yuv444p10, /**< planar YUV 4:4:4, 30bpp, (1 Cr & Cb sample per 1x1 Y samples), little-endian */
     mlt_image_rgba64, /**< 16-bit RGB with alpha channel */
-    mlt_image_invalid
+    mlt_image_invalid,
+    mlt_image_private /**< for module internal use only */
 } mlt_image_format;
 
 /** The set of supported audio formats */

src/modules/CMakeLists.txt

@@ -48,6 +48,10 @@ if(MOD_MOVIT)
   add_subdirectory(movit)
 endif()
 
+if(MOD_PLACEBO)
+  add_subdirectory(placebo)
+endif()
+
 if(MOD_PLUS)
   add_subdirectory(plus)
 endif()