[FFmpeg-devel,v2] avutil/pixfmt: improve definition of AVColorRange

As it was brought up that the current documentation leaves things
as specific to YCbCr only, ICtCp and RGB are now mentioned.
Additionally, the specifications on which these definitions of
narrow and full range are defined are mentioned.

This way, the documentation of AVColorRange should now match how
most people seem to read interpret it at this point, and thus
flagging RGB AVFrames as full range is valid not only according to
common sense, but also the enum definition.
---
 libavutil/pixfmt.h | 54 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 3 deletions(-)

On Sat, Sep 19, 2020 at 02:42:01PM +0300, Jan Ekström wrote:
> As it was brought up that the current documentation leaves things
> as specific to YCbCr only, ICtCp and RGB are now mentioned.
> Additionally, the specifications on which these definitions of
> narrow and full range are defined are mentioned.
> 
> This way, the documentation of AVColorRange should now match how
> most people seem to read interpret it at this point, and thus
> flagging RGB AVFrames as full range is valid not only according to
> common sense, but also the enum definition.
> ---
>  libavutil/pixfmt.h | 54 +++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 51 insertions(+), 3 deletions(-)
> 
> diff --git a/libavutil/pixfmt.h b/libavutil/pixfmt.h
> index a46acf3c5e..480ac9bb42 100644
> --- a/libavutil/pixfmt.h
> +++ b/libavutil/pixfmt.h
> @@ -530,12 +530,60 @@ enum AVColorSpace {
>  };
>  
>  /**
> - * MPEG vs JPEG YUV range.
> + * Visual content value range.
> + *
> + * These values are based on definitions that can be found in multiple
> + * specifications, such as ITU-T BT.709 (3.4 - Quantization of RGB, luminance
> + * and colour-difference signals), ITU-T BT.2020 (Table 5 - Digital
> + * Representation) as well as ITU-T BT.2100 (Table 9 - Digital 10- and 12-bit
> + * integer representation). At the time of writing, the BT.2100 one is
> + * recommended, as it also defines the full range representation.
> + *
> + * Common definitions:
> + *   - For luminance planes such as Y in YCbCr and I in ICtCp, 'E' is the
> + *     original value in range of 0.0 to 1.0.
> + *   - For chrominance planes such as Cb,Cr and Ct,Cp, 'E' is the original
> + *     value in range of -0.5 to 0.5.
> + *   - 'n' is the output bit depth.
> + *   - For additional definitions such as rounding and clipping to valid n
> + *     bit unsigned integer range, please refer to BT.2100 (Table 9).
>   */
>  enum AVColorRange {
>      AVCOL_RANGE_UNSPECIFIED = 0,
> -    AVCOL_RANGE_MPEG        = 1, ///< the normal 219*2^(n-8) "MPEG" YUV ranges
> -    AVCOL_RANGE_JPEG        = 2, ///< the normal     2^n-1   "JPEG" YUV ranges
> +
> +    /**
> +     * Narrow or limited range content.
> +     *
> +     * - For RGB and luminance planes:

I suggest to only mention RGB in relation to narrow once this is also
supported by the implementation



> +     *
> +     *       (219 * E + 16) * 2^(n-8)
> +     *
> +     *   F.ex. the range of 16-235 for 8 bits
> +     *
> +     * - For chrominance planes:
> +     *
> +     *       (224 * E + 128) * 2^(n-8)
> +     *
> +     *   F.ex. the range of 16-240 for 8 bits
> +     */
> +    AVCOL_RANGE_MPEG        = 1,
> +
> +    /**
> +     * Full range content.
> +     *
> +     * - For RGB and luminance planes:
> +     *
> +     *       (2^n - 1) * E
> +     *
> +     *   F.ex. the range of 0-255 for 8 bits
> +     *
> +     * - For chrominance planes:
> +     *
> +     *       (2^n - 1) * E + 2^(n - 1)
> +     *
> +     *   F.ex. the range of 1-255 for 8 bits
> +     */
> +    AVCOL_RANGE_JPEG        = 2,
>      AVCOL_RANGE_NB               ///< Not part of ABI
>  };

ok

thanks

[...]

On Sun, Sep 20, 2020 at 5:50 PM Michael Niedermayer
<michael@niedermayer.cc> wrote:
>
> On Sat, Sep 19, 2020 at 02:42:01PM +0300, Jan Ekström wrote:
> > As it was brought up that the current documentation leaves things
> > as specific to YCbCr only, ICtCp and RGB are now mentioned.
> > Additionally, the specifications on which these definitions of
> > narrow and full range are defined are mentioned.
> >
> > This way, the documentation of AVColorRange should now match how
> > most people seem to read interpret it at this point, and thus
> > flagging RGB AVFrames as full range is valid not only according to
> > common sense, but also the enum definition.
> > ---
> >  libavutil/pixfmt.h | 54 +++++++++++++++++++++++++++++++++++++++++++---
> >  1 file changed, 51 insertions(+), 3 deletions(-)
> >
> > diff --git a/libavutil/pixfmt.h b/libavutil/pixfmt.h
> > index a46acf3c5e..480ac9bb42 100644
> > --- a/libavutil/pixfmt.h
> > +++ b/libavutil/pixfmt.h
> > @@ -530,12 +530,60 @@ enum AVColorSpace {
> >  };
> >
> >  /**
> > - * MPEG vs JPEG YUV range.
> > + * Visual content value range.
> > + *
> > + * These values are based on definitions that can be found in multiple
> > + * specifications, such as ITU-T BT.709 (3.4 - Quantization of RGB, luminance
> > + * and colour-difference signals), ITU-T BT.2020 (Table 5 - Digital
> > + * Representation) as well as ITU-T BT.2100 (Table 9 - Digital 10- and 12-bit
> > + * integer representation). At the time of writing, the BT.2100 one is
> > + * recommended, as it also defines the full range representation.
> > + *
> > + * Common definitions:
> > + *   - For luminance planes such as Y in YCbCr and I in ICtCp, 'E' is the
> > + *     original value in range of 0.0 to 1.0.
> > + *   - For chrominance planes such as Cb,Cr and Ct,Cp, 'E' is the original
> > + *     value in range of -0.5 to 0.5.
> > + *   - 'n' is the output bit depth.
> > + *   - For additional definitions such as rounding and clipping to valid n
> > + *     bit unsigned integer range, please refer to BT.2100 (Table 9).
> >   */
> >  enum AVColorRange {
> >      AVCOL_RANGE_UNSPECIFIED = 0,
> > -    AVCOL_RANGE_MPEG        = 1, ///< the normal 219*2^(n-8) "MPEG" YUV ranges
> > -    AVCOL_RANGE_JPEG        = 2, ///< the normal     2^n-1   "JPEG" YUV ranges
> > +
> > +    /**
> > +     * Narrow or limited range content.
> > +     *
> > +     * - For RGB and luminance planes:
>
> I suggest to only mention RGB in relation to narrow once this is also
> supported by the implementation
>

I did wonder if I should leave this out, but I did end up just
following what the specification notes if we were going to be basing
on the specification.

In any case, it can easily be left out. Will do.

>
>
> > +     *
> > +     *       (219 * E + 16) * 2^(n-8)
> > +     *
> > +     *   F.ex. the range of 16-235 for 8 bits
> > +     *
> > +     * - For chrominance planes:
> > +     *
> > +     *       (224 * E + 128) * 2^(n-8)
> > +     *
> > +     *   F.ex. the range of 16-240 for 8 bits
> > +     */
> > +    AVCOL_RANGE_MPEG        = 1,
> > +
> > +    /**
> > +     * Full range content.
> > +     *
> > +     * - For RGB and luminance planes:
> > +     *
> > +     *       (2^n - 1) * E
> > +     *
> > +     *   F.ex. the range of 0-255 for 8 bits
> > +     *
> > +     * - For chrominance planes:
> > +     *
> > +     *       (2^n - 1) * E + 2^(n - 1)
> > +     *
> > +     *   F.ex. the range of 1-255 for 8 bits
> > +     */
> > +    AVCOL_RANGE_JPEG        = 2,
> >      AVCOL_RANGE_NB               ///< Not part of ABI
> >  };
>
> ok
>
> thanks
>
> [...]
> --
> Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB
>
> Those who would give up essential Liberty, to purchase a little
> temporary Safety, deserve neither Liberty nor Safety -- Benjamin Franklin
> _______________________________________________
> 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".