avutil/frame: add AVFrame.alpha_mode

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.

7 files changed, 59 insertions, 1 deletions

diff --git a/doc/APIchanges b/doc/APIchanges
index bd5a76cbe6..d49cdd8bdc 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-09-xx - xxxxxxxxxx - lavu 60.11.100 - frame.h pixfmt.h
+  Add AVAlphaMode, AVFrame.alpha_mode, av_alpha_mode_name() and
+  av_alpha_mode_from_name().
+
 2025-09-xx - xxxxxxxxxx - lsws 9.3.100 - swscale.h
   Add SWS_UNSTABLE flag.
 
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 d7d98e67e4..088b24b717 100644
--- a/libavutil/frame.h
+++ b/libavutil/frame.h
@@ -773,6 +773,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..3c31ee2132 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,22 @@ 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)
+{
+    for (int 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
@@ -292,6 +292,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.
  *
  * If there is no pixel format with name name, then looks for a
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 27b9fe73d8..a1707d3f4e 100644
--- a/libavutil/version.h
+++ b/libavutil/version.h
@@ -79,7 +79,7 @@
  */
 
 #define LIBAVUTIL_VERSION_MAJOR  60
-#define LIBAVUTIL_VERSION_MINOR  10
+#define LIBAVUTIL_VERSION_MINOR  11
 #define LIBAVUTIL_VERSION_MICRO 100
 
 #define LIBAVUTIL_VERSION_INT   AV_VERSION_INT(LIBAVUTIL_VERSION_MAJOR, \