avcodec/avcodec: add AVCodecContext.alpha_mode

Following in the footsteps of the previous commit, this commit adds the
new fields to AVCodecContext so we can start properly setting it on codecs,
as well as limiting the list of supported options to detect a format mismatch
during encode.

This commit also sets up the necessary infrastructure to start using the
newly added field in all codecs.

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 - lavc 62.15.100 - avcodec.h codec_par.h
+  Add AVCodecContext.alpha_mode, AVCodecParameters.alpha_mode, and
+  AV_CODEC_CONFIG_ALPHA_MODE.
+
 2025-09-xx - xxxxxxxxxx - lavfi 11.6.100 - avfilter.h
   Add AVFilterLink.alpha_mode.
 

doc/codecs.texi

@@ -913,6 +913,14 @@ Possible values:
 
 @end table
 
+@item alpha_mode @var{integer} (@emph{decoding/encoding,video})
+Possible values:
+@table @samp
+@item premultiplied
+@item straight
+@end table
+
+
 @item log_level_offset @var{integer}
 Set the log level offset.
 

libavcodec/avcodec.c

@@ -759,6 +759,8 @@ int ff_default_get_supported_config(const AVCodecContext *avctx,
                                     const void **out_configs,
                                     int *out_num_configs)
 {
+    const FFCodec *codec2 = ffcodec(codec);
+
     switch (config) {
 FF_DISABLE_DEPRECATION_WARNINGS
     case AV_CODEC_CONFIG_PIX_FORMAT:
@@ -786,6 +788,10 @@ FF_ENABLE_DEPRECATION_WARNINGS
         if (out_num_configs)
             *out_num_configs = 0;
         return 0;
+
+    case AV_CODEC_CONFIG_ALPHA_MODE:
+        WRAP_CONFIG(AVMEDIA_TYPE_VIDEO, codec2->alpha_modes, enum AVAlphaMode, AVALPHA_MODE_UNSPECIFIED);
+
     default:
         return AVERROR(EINVAL);
     }

libavcodec/avcodec.h

@@ -1923,6 +1923,13 @@ typedef struct AVCodecContext {
      */
     AVFrameSideData  **decoded_side_data;
     int             nb_decoded_side_data;
+
+    /**
+     * Indicates how the alpha channel of the video is represented.
+     * - encoding: Set by user
+     * - decoding: Set by libavcodec
+     */
+    enum AVAlphaMode alpha_mode;
 } AVCodecContext;
 
 /**
@@ -2528,6 +2535,7 @@ enum AVCodecConfig {
     AV_CODEC_CONFIG_CHANNEL_LAYOUT, ///< AVChannelLayout, terminated by {0}
     AV_CODEC_CONFIG_COLOR_RANGE,    ///< AVColorRange, terminated by AVCOL_RANGE_UNSPECIFIED
     AV_CODEC_CONFIG_COLOR_SPACE,    ///< AVColorSpace, terminated by AVCOL_SPC_UNSPECIFIED
+    AV_CODEC_CONFIG_ALPHA_MODE,     ///< AVAlphaMode, terminated by AVALPHA_MODE_UNSPECIFIED
 };
 
 /**

libavcodec/codec_internal.h

@@ -153,6 +153,11 @@ typedef struct FFCodec {
      */
     unsigned cb_type:3;
 
+    /**
+     * This field determines the alpha modes supported by an encoder.
+     */
+    const enum AVAlphaMode *alpha_modes;
+
     int priv_data_size;
     /**
      * @name Frame-level threading support functions

libavcodec/codec_par.c

@@ -51,6 +51,7 @@ static void codec_parameters_reset(AVCodecParameters *par)
     par->framerate           = (AVRational){ 0, 1 };
     par->profile             = AV_PROFILE_UNKNOWN;
     par->level               = AV_LEVEL_UNKNOWN;
+    par->alpha_mode          = AVALPHA_MODE_UNSPECIFIED;
 }
 
 AVCodecParameters *avcodec_parameters_alloc(void)
@@ -165,6 +166,7 @@ int avcodec_parameters_from_context(AVCodecParameters *par,
         par->sample_aspect_ratio = codec->sample_aspect_ratio;
         par->video_delay         = codec->has_b_frames;
         par->framerate           = codec->framerate;
+        par->alpha_mode          = codec->alpha_mode;
         break;
     case AVMEDIA_TYPE_AUDIO:
         par->format           = codec->sample_fmt;
@@ -229,6 +231,7 @@ int avcodec_parameters_to_context(AVCodecContext *codec,
         codec->sample_aspect_ratio    = par->sample_aspect_ratio;
         codec->has_b_frames           = par->video_delay;
         codec->framerate              = par->framerate;
+        codec->alpha_mode             = par->alpha_mode;
         break;
     case AVMEDIA_TYPE_AUDIO:
         codec->sample_fmt       = par->format;

libavcodec/codec_par.h

@@ -212,6 +212,11 @@ typedef struct AVCodecParameters {
      * Audio only. Number of samples to skip after a discontinuity.
      */
     int seek_preroll;
+
+    /**
+     * Video with alpha channel only. Alpha channel handling
+     */
+    enum AVAlphaMode alpha_mode;
 } AVCodecParameters;
 
 /**

libavcodec/decode.c

@@ -568,6 +568,8 @@ static int fill_frame_props(const AVCodecContext *avctx, AVFrame *frame)
         frame->color_range = avctx->color_range;
     if (frame->chroma_location == AVCHROMA_LOC_UNSPECIFIED)
         frame->chroma_location = avctx->chroma_sample_location;
+    if (frame->alpha_mode == AVALPHA_MODE_UNSPECIFIED)
+        frame->alpha_mode = avctx->alpha_mode;
 
     if (avctx->codec_type == AVMEDIA_TYPE_VIDEO) {
             if (!frame->sample_aspect_ratio.num)  frame->sample_aspect_ratio = avctx->sample_aspect_ratio;

libavcodec/options_table.h

@@ -352,6 +352,11 @@ static const AVOption avcodec_options[] = {
 {"bottomleft",  "Bottom-left", 0, AV_OPT_TYPE_CONST, {.i64 = AVCHROMA_LOC_BOTTOMLEFT },  INT_MIN, INT_MAX, V|E|D, .unit = "chroma_sample_location_type"},
 {"bottom",      "Bottom",      0, AV_OPT_TYPE_CONST, {.i64 = AVCHROMA_LOC_BOTTOM },      INT_MIN, INT_MAX, V|E|D, .unit = "chroma_sample_location_type"},
 {"unspecified", "Unspecified", 0, AV_OPT_TYPE_CONST, {.i64 = AVCHROMA_LOC_UNSPECIFIED }, INT_MIN, INT_MAX, V|E|D, .unit = "chroma_sample_location_type"},
+{"alpha_mode", "alpha mode", OFFSET(alpha_mode), AV_OPT_TYPE_INT, {.i64 = AVALPHA_MODE_UNSPECIFIED }, 0, INT_MAX, V|E|D, .unit = "alpha_mode_type"},
+{"unknown",       "Unspecified",   0, AV_OPT_TYPE_CONST, {.i64 = AVALPHA_MODE_UNSPECIFIED   }, 0, 0, V|E|D, .unit = "alpha_mode_type"},
+{"unspecified",   "Unspecified",   0, AV_OPT_TYPE_CONST, {.i64 = AVALPHA_MODE_UNSPECIFIED   }, 0, 0, V|E|D, .unit = "alpha_mode_type"},
+{"premultiplied", "Premultiplied", 0, AV_OPT_TYPE_CONST, {.i64 = AVALPHA_MODE_PREMULTIPLIED }, 0, 0, V|E|D, .unit = "alpha_mode_type"},
+{"straight",      "Straight",      0, AV_OPT_TYPE_CONST, {.i64 = AVALPHA_MODE_STRAIGHT      }, 0, 0, V|E|D, .unit = "alpha_mode_type"},
 {"log_level_offset", "set the log level offset", OFFSET(log_level_offset), AV_OPT_TYPE_INT, {.i64 = 0 }, INT_MIN, INT_MAX },
 {"slices", "set the number of slices, used in parallelized encoding", OFFSET(slices), AV_OPT_TYPE_INT, {.i64 = 0 }, 0, INT_MAX, V|E},
 {"thread_type", "select multithreading type", OFFSET(thread_type), AV_OPT_TYPE_FLAGS, {.i64 = FF_THREAD_SLICE|FF_THREAD_FRAME }, 0, INT_MAX, V|A|E|D, .unit = "thread_type"},

libavcodec/version.h

@@ -29,8 +29,8 @@
 
 #include "version_major.h"
 
-#define LIBAVCODEC_VERSION_MINOR  14
-#define LIBAVCODEC_VERSION_MICRO 101
+#define LIBAVCODEC_VERSION_MINOR  15
+#define LIBAVCODEC_VERSION_MICRO 100
 
 #define LIBAVCODEC_VERSION_INT  AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \
                                                LIBAVCODEC_VERSION_MINOR, \