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.

Author: ddennedy

NEWS

@@ -1,6 +1,28 @@
 MLT Release Notes
 -----------------
 
+Version 7.40.0
+
+Framework
+  - Added list-based image-conversion callback dispatch on mlt_frame.
+    Use `mlt_frame_push_convert_image()` to register a converter instead of
+    setting `frame->convert_image` directly. Multiple converters are tried in
+    registration order; the first that succeeds wins. New public API:
+    - `mlt_frame_push_convert_image()`
+    - `mlt_frame_convert_image()`
+    - `mlt_frame_next_convert_image()`
+    - `mlt_frame_has_convert_image()`
+    - `mlt_frame_copy_convert_image()`
+  - API behavior change: `mlt_frame_s::convert_image` is now read-only after
+    init and is permanently set to the dispatcher `mlt_frame_convert_image()`.
+    External code that set this field directly to a custom function will no
+    longer have that function called. If you really need that (never heard of
+    someone who does), clear the frame's "_convert_image_callbacks" property
+    and use `mlt_frame_push_convert_image()` instead.
+  - Image converters (`movit.convert`, `avcolor_space`, `imageconvert`) are
+    now attached data-driven via `loader.ini` key `image_convert`.
+
+
 Version 7.38.0
 
 Framework

src/framework/mlt.vers

@@ -687,3 +687,12 @@ MLT_7.36.0 {
     mlt_color_convert_trc;
     mlt_profile_is_valid;
 } MLT_7.34.0;
+
+MLT_7.40.0 {
+  global:
+    mlt_frame_push_convert_image;
+    mlt_frame_has_convert_image;
+    mlt_frame_convert_image;
+    mlt_frame_next_convert_image;
+    mlt_frame_copy_convert_image;
+} MLT_7.34.0;

src/framework/mlt_frame.c

@@ -63,6 +63,7 @@ mlt_frame mlt_frame_init(mlt_service service)
         self->stack_image = mlt_deque_init();
         self->stack_audio = mlt_deque_init();
         self->stack_service = mlt_deque_init();
+        self->convert_image = mlt_frame_convert_image;
     }
 
     return self;
@@ -423,8 +424,8 @@ static int generate_test_image(mlt_properties properties,
                                           mlt_frame_get_aspect_ratio(test_frame));
                 mlt_properties_set_int(properties, "width", *width);
                 mlt_properties_set_int(properties, "height", *height);
-                if (test_frame->convert_image && requested_format != mlt_image_none)
-                    test_frame->convert_image(test_frame, buffer, format, requested_format);
+                if (mlt_frame_has_convert_image(test_frame) && requested_format != mlt_image_none)
+                    mlt_frame_convert_image(test_frame, buffer, format, requested_format);
                 mlt_properties_set_int(properties, "format", *format);
             }
         } else {
@@ -516,8 +517,8 @@ int mlt_frame_get_image(mlt_frame self,
         if (!error && buffer && *buffer) {
             mlt_properties_set_int(properties, "width", *width);
             mlt_properties_set_int(properties, "height", *height);
-            if (self->convert_image && requested_format != mlt_image_none)
-                self->convert_image(self, buffer, format, requested_format);
+            if (mlt_frame_has_convert_image(self) && requested_format != mlt_image_none)
+                mlt_frame_convert_image(self, buffer, format, requested_format);
             mlt_properties_set_int(properties, "format", *format);
         } else {
             error = generate_test_image(properties, buffer, format, width, height, writable);
@@ -527,8 +528,8 @@ int mlt_frame_get_image(mlt_frame self,
         *buffer = mlt_properties_get_data(properties, "image", NULL);
         *width = mlt_properties_get_int(properties, "width");
         *height = mlt_properties_get_int(properties, "height");
-        if (self->convert_image && *buffer && requested_format != mlt_image_none) {
-            self->convert_image(self, buffer, format, requested_format);
+        if (mlt_frame_has_convert_image(self) && *buffer && requested_format != mlt_image_none) {
+            mlt_frame_convert_image(self, buffer, format, requested_format);
             mlt_properties_set_int(properties, "format", *format);
         }
     } else {
@@ -829,6 +830,161 @@ void mlt_frame_close(mlt_frame self)
     }
 }
 
+/* ---- Image conversion callback list ---- */
+
+#define CONVERT_IMAGE_CALLBACKS "_convert_image_callbacks"
+#define CONVERT_IMAGE_IDX "_convert_image_idx"
+
+static int do_convert_image(
+    mlt_frame self, uint8_t **image, mlt_image_format *format, mlt_image_format output, int idx)
+{
+    mlt_properties props = MLT_FRAME_PROPERTIES(self);
+    mlt_deque list = mlt_properties_get_data(props, CONVERT_IMAGE_CALLBACKS, NULL);
+    int count = list ? mlt_deque_count(list) : 0;
+
+    while (idx < count) {
+        mlt_properties_set_int(props, CONVERT_IMAGE_IDX, idx);
+        mlt_convert_image fn = (mlt_convert_image) mlt_deque_peek(list, idx);
+        int error = fn(self, image, format, output);
+        if (!error)
+            return 0;
+        // fn may have internally advanced _convert_image_idx via mlt_frame_next_convert_image;
+        // skip past any indices already tried to avoid double-calling.
+        int next = mlt_properties_get_int(props, CONVERT_IMAGE_IDX);
+        idx = (next > idx) ? next + 1 : idx + 1;
+    }
+    return 1;
+}
+
+/** Register an image-conversion callback on the frame.
+ *
+ * Callbacks are appended to a list and dispatched in order by
+ * \p mlt_frame_convert_image. If \p convert is already registered on this
+ * frame it is silently ignored (deduplication). Has no effect if either
+ * argument is NULL.
+ *
+ * \public \memberof mlt_frame_s
+ * \param self a frame
+ * \param convert the conversion callback to register
+ */
+void mlt_frame_push_convert_image(mlt_frame self, mlt_convert_image convert)
+{
+    if (!self || !convert)
+        return;
+    mlt_properties props = MLT_FRAME_PROPERTIES(self);
+    mlt_deque list = mlt_properties_get_data(props, CONVERT_IMAGE_CALLBACKS, NULL);
+    if (!list) {
+        list = mlt_deque_init();
+        mlt_properties_set_data(props,
+                                CONVERT_IMAGE_CALLBACKS,
+                                list,
+                                0,
+                                (mlt_destructor) mlt_deque_close,
+                                NULL);
+    }
+    // Deduplicate: don't register the same function pointer twice.
+    for (int i = 0; i < mlt_deque_count(list); i++)
+        if (mlt_deque_peek(list, i) == (void *) convert)
+            return;
+    mlt_deque_push_back(list, (void *) convert);
+}
+
+/** Determine whether any image-conversion callbacks are registered.
+ *
+ * \public \memberof mlt_frame_s
+ * \param self a frame
+ * \return non-zero if at least one callback has been pushed, zero otherwise
+ */
+int mlt_frame_has_convert_image(mlt_frame self)
+{
+    if (!self)
+        return 0;
+    mlt_deque list = mlt_properties_get_data(MLT_FRAME_PROPERTIES(self),
+                                             CONVERT_IMAGE_CALLBACKS,
+                                             NULL);
+    return list && mlt_deque_count(list) > 0;
+}
+
+/** Convert the frame image to the requested format.
+ *
+ * Dispatches the registered conversion callbacks in order, stopping at the
+ * first one that succeeds (returns 0). If no callback succeeds, returns 1.
+ * This is also the function stored in the \p convert_image field of every
+ * frame; external callers that hold a pointer to that field will therefore
+ * invoke this dispatcher transparently.
+ *
+ * \public \memberof mlt_frame_s
+ * \param self a frame
+ * \param[in,out] image the image buffer pointer
+ * \param[in,out] format the current image format; updated to \p output on success
+ * \param output the desired image format
+ * \return 0 on success, 1 if no callback could perform the conversion
+ */
+int mlt_frame_convert_image(mlt_frame self,
+                            uint8_t **image,
+                            mlt_image_format *format,
+                            mlt_image_format output)
+{
+    return do_convert_image(self, image, format, output, 0);
+}
+
+/** Advance to the next image-conversion callback and continue dispatching.
+ *
+ * Call this from inside a conversion callback to delegate to the next
+ * registered callback in the list (fallback chaining). The current
+ * callback's index is read from the frame's internal dispatch state, so
+ * this must only be called from within an active \p mlt_frame_convert_image
+ * dispatch.
+ *
+ * \public \memberof mlt_frame_s
+ * \param self a frame
+ * \param[in,out] image the image buffer pointer
+ * \param[in,out] format the current image format
+ * \param output the desired image format
+ * \return 0 if a subsequent callback succeeded, 1 if none did
+ */
+int mlt_frame_next_convert_image(mlt_frame self,
+                                 uint8_t **image,
+                                 mlt_image_format *format,
+                                 mlt_image_format output)
+{
+    int idx = mlt_properties_get_int(MLT_FRAME_PROPERTIES(self), CONVERT_IMAGE_IDX);
+    return do_convert_image(self, image, format, output, idx + 1);
+}
+
+/** Copy the image-conversion callback list from one frame to another.
+ *
+ * Used by the tractor and clone functions to propagate converters attached
+ * to track or source frames onto merged or cloned frames. If \p dst already
+ * has a callback list the copy is skipped (first-wins semantics).
+ *
+ * \public \memberof mlt_frame_s
+ * \param dst the frame to copy callbacks onto
+ * \param src the frame to copy callbacks from
+ */
+void mlt_frame_copy_convert_image(mlt_frame dst, mlt_frame src)
+{
+    mlt_deque src_list = mlt_properties_get_data(MLT_FRAME_PROPERTIES(src),
+                                                 CONVERT_IMAGE_CALLBACKS,
+                                                 NULL);
+    if (!src_list || !mlt_deque_count(src_list))
+        return;
+    mlt_deque dst_list = mlt_properties_get_data(MLT_FRAME_PROPERTIES(dst),
+                                                 CONVERT_IMAGE_CALLBACKS,
+                                                 NULL);
+    if (dst_list)
+        return;
+    dst_list = mlt_deque_init();
+    for (int i = 0; i < mlt_deque_count(src_list); i++)
+        mlt_deque_push_back(dst_list, mlt_deque_peek(src_list, i));
+    mlt_properties_set_data(MLT_FRAME_PROPERTIES(dst),
+                            CONVERT_IMAGE_CALLBACKS,
+                            dst_list,
+                            0,
+                            (mlt_destructor) mlt_deque_close,
+                            NULL);
+}
+
 /***** convenience functions *****/
 
 void mlt_frame_write_ppm(mlt_frame frame)
@@ -942,18 +1098,7 @@ mlt_frame mlt_frame_clone(mlt_frame self, int is_deep)
                             0,
                             NULL,
                             NULL);
-    mlt_properties_set_data(new_props,
-                            "movit.convert",
-                            mlt_properties_get_data(properties, "movit.convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
-    mlt_properties_set_data(new_props,
-                            "_movit cpu_convert",
-                            mlt_properties_get_data(properties, "_movit cpu_convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
+    mlt_frame_copy_convert_image(new_frame, self);
 
     if (is_deep) {
         data = mlt_properties_get_data(properties, "audio", &size);
@@ -1045,18 +1190,7 @@ mlt_frame mlt_frame_clone_audio(mlt_frame self, int is_deep)
                             0,
                             NULL,
                             NULL);
-    mlt_properties_set_data(new_props,
-                            "movit.convert",
-                            mlt_properties_get_data(properties, "movit.convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
-    mlt_properties_set_data(new_props,
-                            "_movit cpu_convert",
-                            mlt_properties_get_data(properties, "_movit cpu_convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
+    mlt_frame_copy_convert_image(new_frame, self);
 
     if (is_deep) {
         data = mlt_properties_get_data(properties, "audio", &size);
@@ -1117,18 +1251,7 @@ mlt_frame mlt_frame_clone_image(mlt_frame self, int is_deep)
                             0,
                             NULL,
                             NULL);
-    mlt_properties_set_data(new_props,
-                            "movit.convert",
-                            mlt_properties_get_data(properties, "movit.convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
-    mlt_properties_set_data(new_props,
-                            "_movit cpu_convert",
-                            mlt_properties_get_data(properties, "_movit cpu_convert", NULL),
-                            0,
-                            NULL,
-                            NULL);
+    mlt_frame_copy_convert_image(new_frame, self);
 
     if (is_deep) {
         data = mlt_properties_get_data(properties, "image", &size);

src/framework/mlt_frame.h

@@ -3,7 +3,7 @@
  * \brief interface for all frame classes
  * \see mlt_frame_s
  *
- * Copyright (C) 2003-2023 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
@@ -52,6 +52,16 @@ typedef int (*mlt_get_audio)(mlt_frame self,
                              int *channels,
                              int *samples);
 
+/** Callback function to convert image format.
+ *
+ * Registered converters are tried in order. Return non-zero to indicate the
+ * conversion was not handled so the next registered converter will be tried.
+ */
+typedef int (*mlt_convert_image)(mlt_frame self,
+                                 uint8_t **image,
+                                 mlt_image_format *input,
+                                 mlt_image_format output);
+
 /** \brief Frame class
  *
  * The frame is the primary data object that gets passed around to and through services.
@@ -91,7 +101,9 @@ struct mlt_frame_s
 {
     struct mlt_properties_s parent; /**< \private A frame extends properties. */
 
-    /** Convert the image format (callback function).
+    /** Image format conversion dispatcher (read-only after init).
+	 * Always set to mlt_frame_convert_image by mlt_frame_init().
+	 * Do not set this field directly; use mlt_frame_push_convert_image() instead.
 	 * \param self a frame
 	 * \param[in,out] image a buffer of image data
 	 * \param[in,out] input the image format of supplied image data
@@ -171,6 +183,17 @@ MLT_EXPORT mlt_producer mlt_frame_get_original_producer(mlt_frame self);
 MLT_EXPORT void mlt_frame_close(mlt_frame self);
 MLT_EXPORT mlt_properties mlt_frame_unique_properties(mlt_frame self, mlt_service service);
 MLT_EXPORT mlt_properties mlt_frame_get_unique_properties(mlt_frame self, mlt_service service);
+MLT_EXPORT void mlt_frame_push_convert_image(mlt_frame self, mlt_convert_image convert);
+MLT_EXPORT int mlt_frame_has_convert_image(mlt_frame self);
+MLT_EXPORT int mlt_frame_convert_image(mlt_frame self,
+                                       uint8_t **image,
+                                       mlt_image_format *format,
+                                       mlt_image_format output);
+MLT_EXPORT int mlt_frame_next_convert_image(mlt_frame self,
+                                            uint8_t **image,
+                                            mlt_image_format *format,
+                                            mlt_image_format output);
+MLT_EXPORT void mlt_frame_copy_convert_image(mlt_frame dst, mlt_frame src);
 MLT_EXPORT mlt_frame mlt_frame_clone(mlt_frame self, int is_deep);
 MLT_EXPORT mlt_frame mlt_frame_clone_audio(mlt_frame self, int is_deep);
 MLT_EXPORT mlt_frame mlt_frame_clone_image(mlt_frame self, int is_deep);

src/framework/mlt_tractor.c

@@ -3,7 +3,7 @@
  * \brief tractor service class
  * \see mlt_tractor_s
  *
- * Copyright (C) 2003-2022 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
@@ -418,8 +418,8 @@ static int producer_get_image(mlt_frame self,
     if (data) {
         mlt_frame_set_alpha(self, data, size, NULL);
     }
-    self->convert_image = frame->convert_image;
     self->convert_audio = frame->convert_audio;
+    mlt_frame_copy_convert_image(self, frame);
     return 0;
 }
 
@@ -537,11 +537,10 @@ static int producer_get_frame(mlt_producer parent, mlt_frame_ptr frame, int trac
                                                   subtitle_properties);
                 }
 
-                // Copy the format conversion virtual functions
-                if (!(*frame)->convert_image && temp->convert_image)
-                    (*frame)->convert_image = temp->convert_image;
+                // Copy the format conversion callbacks
                 if (!(*frame)->convert_audio && temp->convert_audio)
                     (*frame)->convert_audio = temp->convert_audio;
+                mlt_frame_copy_convert_image(*frame, temp);
 
                 // Check for last track
                 done = mlt_properties_get_int(temp_properties, "last_track");