[FFmpeg-devel] lavc: clarify color_range semantics

Mark this option as encode-only and extend description.

Address issue: http://trac.ffmpeg.org/ticket/443
---
 libavcodec/avcodec.h       |  6 +++++-
 libavcodec/options_table.h | 14 +++++++-------
 2 files changed, 12 insertions(+), 8 deletions(-)

On 2023-01-15 11:11 pm, Stefano Sabatini wrote:
> Mark this option as encode-only and extend description.

There are scripts which set this (and other color props) on the input, 
and then those streams can be sent to multiple filters with the props 
set, instead of having to use setparams in each chain.

Regards,
Gyan

>
> Address issue: http://trac.ffmpeg.org/ticket/443
> ---
>   libavcodec/avcodec.h       |  6 +++++-
>   libavcodec/options_table.h | 14 +++++++-------
>   2 files changed, 12 insertions(+), 8 deletions(-)
>
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index 0ac581d660..53ae40255f 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -976,7 +976,11 @@ typedef struct AVCodecContext {
>   
>       /**
>        * MPEG vs JPEG YUV range.
> -     * - encoding: Set by user
> +     *
> +     * - encoding: Set by user to override the default output color range value,
> +     *   it might cause a failure in case the specified value is not legal. If
> +     *   not specified, libavcodec sets the color range depending on the output
> +     *   format.
>        * - decoding: Set by libavcodec
>        */
>       enum AVColorRange color_range;
> diff --git a/libavcodec/options_table.h b/libavcodec/options_table.h
> index 7924ca6144..a668d39d79 100644
> --- a/libavcodec/options_table.h
> +++ b/libavcodec/options_table.h
> @@ -338,13 +338,13 @@ static const AVOption avcodec_options[] = {
>   {"ycocg",             "YCGCO",              0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_SPC_YCGCO },              INT_MIN, INT_MAX, V|E|D, "colorspace_type"},
>   {"bt2020_ncl",        "BT.2020 NCL",        0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_SPC_BT2020_NCL },         INT_MIN, INT_MAX, V|E|D, "colorspace_type"},
>   {"bt2020_cl",         "BT.2020 CL",         0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_SPC_BT2020_CL },          INT_MIN, INT_MAX, V|E|D, "colorspace_type"},
> -{"color_range", "color range", OFFSET(color_range), AV_OPT_TYPE_INT, {.i64 = AVCOL_RANGE_UNSPECIFIED }, 0, INT_MAX, V|E|D, "color_range_type"},
> -{"unknown", "Unspecified",     0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_UNSPECIFIED }, INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> -{"tv", "MPEG (219*2^(n-8))",   0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_MPEG },        INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> -{"pc", "JPEG (2^n-1)",         0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_JPEG },        INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> -{"unspecified", "Unspecified", 0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_UNSPECIFIED }, INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> -{"mpeg", "MPEG (219*2^(n-8))", 0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_MPEG },        INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> -{"jpeg", "JPEG (2^n-1)",       0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_JPEG },        INT_MIN, INT_MAX, V|E|D, "color_range_type"},
> +{"color_range", "color range", OFFSET(color_range), AV_OPT_TYPE_INT, {.i64 = AVCOL_RANGE_UNSPECIFIED }, 0, INT_MAX, V|E, "color_range_type"},
> +{"unknown", "Unspecified",     0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_UNSPECIFIED }, INT_MIN, INT_MAX, V|E, "color_range_type"},
> +{"tv", "MPEG (219*2^(n-8))",   0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_MPEG },        INT_MIN, INT_MAX, V|E, "color_range_type"},
> +{"pc", "JPEG (2^n-1)",         0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_JPEG },        INT_MIN, INT_MAX, V|E, "color_range_type"},
> +{"unspecified", "Unspecified", 0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_UNSPECIFIED }, INT_MIN, INT_MAX, V|E, "color_range_type"},
> +{"mpeg", "MPEG (219*2^(n-8))", 0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_MPEG },        INT_MIN, INT_MAX, V|E, "color_range_type"},
> +{"jpeg", "JPEG (2^n-1)",       0, AV_OPT_TYPE_CONST, {.i64 = AVCOL_RANGE_JPEG },        INT_MIN, INT_MAX, V|E, "color_range_type"},
>   {"chroma_sample_location", "chroma sample location", OFFSET(chroma_sample_location), AV_OPT_TYPE_INT, {.i64 = AVCHROMA_LOC_UNSPECIFIED }, 0, INT_MAX, V|E|D, "chroma_sample_location_type"},
>   {"unknown",     "Unspecified", 0, AV_OPT_TYPE_CONST, {.i64 = AVCHROMA_LOC_UNSPECIFIED }, INT_MIN, INT_MAX, V|E|D, "chroma_sample_location_type"},
>   {"left",        "Left",        0, AV_OPT_TYPE_CONST, {.i64 = AVCHROMA_LOC_LEFT },        INT_MIN, INT_MAX, V|E|D, "chroma_sample_location_type"},

On date Monday 2023-01-16 09:46:35 +0530, Gyan Doshi wrote:
> On 2023-01-15 11:11 pm, Stefano Sabatini wrote:
> > Mark this option as encode-only and extend description.
> 
> There are scripts which set this (and other color props) on the input, and
> then those streams can be sent to multiple filters with the props set,
> instead of having to use setparams in each chain.

Good point, amended with this considerations in mind.

On date Wednesday 2023-01-25 01:44:25 +0100, Stefano Sabatini wrote:
> On date Monday 2023-01-16 09:46:35 +0530, Gyan Doshi wrote:
> > On 2023-01-15 11:11 pm, Stefano Sabatini wrote:
> > > Mark this option as encode-only and extend description.
> > 
> > There are scripts which set this (and other color props) on the input, and
> > then those streams can be sent to multiple filters with the props set,
> > instead of having to use setparams in each chain.
> 
> Good point, amended with this considerations in mind.

> From bcddce6d1ea802638770dcfd8e7ecb6d798f63c6 Mon Sep 17 00:00:00 2001
> From: Stefano Sabatini <stefasab@gmail.com>
> Date: Sun, 15 Jan 2023 18:16:45 +0100
> Subject: [PATCH] lavc: clarify color_range semantics
> 
> Extend description for decoding and encoding use cases.
> 
> Address issue: http://trac.ffmpeg.org/ticket/443
> ---
>  libavcodec/avcodec.h | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/libavcodec/avcodec.h b/libavcodec/avcodec.h
> index 0ac581d660..85bb95144d 100644
> --- a/libavcodec/avcodec.h
> +++ b/libavcodec/avcodec.h
> @@ -976,8 +976,11 @@ typedef struct AVCodecContext {
>  
>      /**
>       * MPEG vs JPEG YUV range.
> -     * - encoding: Set by user
> -     * - decoding: Set by libavcodec
> +     * - encoding: Set by user to override the default output color range value,
> +     *   If not specified, libavcodec sets the color range depending on the
> +     *   output format.
> +     * - decoding: Set by libavcodec, can be set by the user to propagate the
> +     *   color range to components reading from the decoder context.
>       */
>      enum AVColorRange color_range;

Ping.

Will apply in a few days if I see no comments.

On date Sunday 2023-03-26 21:55:58 +0200, Stefano Sabatini wrote:
> On date Wednesday 2023-01-25 01:44:25 +0100, Stefano Sabatini wrote:
[...]
> Ping.
> 
> Will apply in a few days if I see no comments.

Applied.