[FFmpeg-devel] [PATCH v2 01/18] avutil/frame: add AVFrame.alpha_mode
Kacper Michajlow
kasper93 at gmail.com
Wed Jul 23 19:00:02 EEST 2025
On Wed, 23 Jul 2025 at 15:56, Niklas Haas <ffmpeg at haasn.xyz> wrote:
>
> From: Niklas Haas <git at 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;
nitpick, but I think we no longer require variable declarations at the
beginning. Can just inline it.
> +
> + 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 at ffmpeg.org
> https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
>
> To unsubscribe, visit link above, or email
> ffmpeg-devel-request at ffmpeg.org with subject "unsubscribe".
More information about the ffmpeg-devel
mailing list