[FFmpeg-devel] [PATCH v2 01/18] avutil/frame: add AVFrame.alpha_mode

[Niklas Haas <ffmpeg@haasn.xyz>]

From: Niklas Haas <git@haasn.dev>

FFmpeg currently handles alpha in a quasi-arbitrary way. Some filters/codecs
assume alpha is premultiplied, others assume it is independent. If there is
to be any hope for order in this chaos, we need to start by defining an enum
for the possible range of values.
---
 doc/APIchanges      |  4 ++++
 libavutil/frame.c   |  2 ++
 libavutil/frame.h   |  7 +++++++
 libavutil/pixdesc.c | 27 +++++++++++++++++++++++++++
 libavutil/pixdesc.h | 10 ++++++++++
 libavutil/pixfmt.h  | 10 ++++++++++
 libavutil/version.h |  2 +-
 7 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/doc/APIchanges b/doc/APIchanges
index 5c40b7c13d..708325c0bf 100644
--- a/doc/APIchanges
+++ b/doc/APIchanges
@@ -2,6 +2,10 @@ The last version increases of all libraries were on 2025-03-28
 
 API changes, most recent first:
 
+2025-07-xx - xxxxxxxxxx - lavu 60.7.100 - frame.h pixfmt.h
+  Add AVAlphaMode, AVFrame.alpha_mode, av_alpha_mode_name() and
+  av_alpha_mode_from_name().
+
 2025-07-20 - xxxxxxxxxx - lavu 60.6.100 - attributes.h, avstring.h
   Add av_scanf_format() and use it on av_sscanf().
 
diff --git a/libavutil/frame.c b/libavutil/frame.c
index 8f3fda2371..be30eb09d2 100644
--- a/libavutil/frame.c
+++ b/libavutil/frame.c
@@ -45,6 +45,7 @@ static void get_frame_defaults(AVFrame *frame)
     frame->colorspace          = AVCOL_SPC_UNSPECIFIED;
     frame->color_range         = AVCOL_RANGE_UNSPECIFIED;
     frame->chroma_location     = AVCHROMA_LOC_UNSPECIFIED;
+    frame->alpha_mode          = AVALPHA_MODE_UNSPECIFIED;
     frame->flags               = 0;
 }
 
@@ -240,6 +241,7 @@ static int frame_copy_props(AVFrame *dst, const AVFrame *src, int force_copy)
     dst->colorspace             = src->colorspace;
     dst->color_range            = src->color_range;
     dst->chroma_location        = src->chroma_location;
+    dst->alpha_mode             = src->alpha_mode;
 
     av_dict_copy(&dst->metadata, src->metadata, 0);
 
diff --git a/libavutil/frame.h b/libavutil/frame.h
index c50cd263d9..357626be9d 100644
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -767,6 +767,13 @@ typedef struct AVFrame {
      * Duration of the frame, in the same units as pts. 0 if unknown.
      */
     int64_t duration;
+
+    /**
+     * Indicates how the alpha channel of the video is to be handled.
+     * - encoding: Set by user
+     * - decoding: Set by libavcodec
+     */
+    enum AVAlphaMode alpha_mode;
 } AVFrame;
 
 
diff --git a/libavutil/pixdesc.c b/libavutil/pixdesc.c
index f0be20d749..a74cde3de9 100644
--- a/libavutil/pixdesc.c
+++ b/libavutil/pixdesc.c
@@ -3345,6 +3345,12 @@ static const char * const chroma_location_names[] = {
     [AVCHROMA_LOC_BOTTOM] = "bottom",
 };
 
+static const char * const alpha_mode_names[] = {
+    [AVALPHA_MODE_UNSPECIFIED] = "unspecified",
+    [AVALPHA_MODE_PREMULTIPLIED] = "premultiplied",
+    [AVALPHA_MODE_STRAIGHT] = "straight",
+};
+
 static enum AVPixelFormat get_pix_fmt_internal(const char *name)
 {
     enum AVPixelFormat pix_fmt;
@@ -3878,3 +3884,24 @@ enum AVChromaLocation av_chroma_location_pos_to_enum(int xpos, int ypos)
     }
     return AVCHROMA_LOC_UNSPECIFIED;
 }
+
+const char *av_alpha_mode_name(enum AVAlphaMode mode)
+{
+    return (unsigned) mode < AVALPHA_MODE_NB ?
+        alpha_mode_names[mode] : NULL;
+}
+
+enum AVAlphaMode av_alpha_mode_from_name(const char *name)
+{
+    int i;
+
+    for (i = 0; i < FF_ARRAY_ELEMS(alpha_mode_names); i++) {
+        if (!alpha_mode_names[i])
+            continue;
+
+        if (av_strstart(name, alpha_mode_names[i], NULL))
+            return i;
+    }
+
+    return AVERROR(EINVAL);
+}
diff --git a/libavutil/pixdesc.h b/libavutil/pixdesc.h
index ba2f632814..0cc70eb64c 100644
--- a/libavutil/pixdesc.h
+++ b/libavutil/pixdesc.h
@@ -291,6 +291,16 @@ int av_chroma_location_enum_to_pos(int *xpos, int *ypos, enum AVChromaLocation p
  */
 enum AVChromaLocation av_chroma_location_pos_to_enum(int xpos, int ypos);
 
+/**
+ * @return the name for provided alpha mode or NULL if unknown.
+ */
+const char *av_alpha_mode_name(enum AVAlphaMode mode);
+
+/**
+ * @return the AVAlphaMode value for name or an AVError if not found.
+ */
+enum AVAlphaMode av_alpha_mode_from_name(const char *name);
+
 /**
  * Return the pixel format corresponding to name.
  *
diff --git a/libavutil/pixfmt.h b/libavutil/pixfmt.h
index 823ea8edab..6aa1c94cec 100644
--- a/libavutil/pixfmt.h
+++ b/libavutil/pixfmt.h
@@ -794,4 +794,14 @@ enum AVChromaLocation {
     AVCHROMA_LOC_NB               ///< Not part of ABI
 };
 
+/**
+ * Correlation between the alpha channel and color values.
+ */
+enum AVAlphaMode {
+    AVALPHA_MODE_UNSPECIFIED   = 0, ///< Unknown alpha handling, or no alpha channel
+    AVALPHA_MODE_PREMULTIPLIED = 1, ///< Alpha channel is multiplied into color values
+    AVALPHA_MODE_STRAIGHT      = 2, ///< Alpha channel is independent of color values
+    AVALPHA_MODE_NB                 ///< Not part of ABI
+};
+
 #endif /* AVUTIL_PIXFMT_H */
diff --git a/libavutil/version.h b/libavutil/version.h
index 946429b8fc..b454106960 100644
--- a/libavutil/version.h
+++ b/libavutil/version.h
@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  60
-#define LIBAVUTIL_VERSION_MINOR   6
+#define LIBAVUTIL_VERSION_MINOR   7
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \
-- 
2.50.1

_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".