Re: [PATCH v2 2/3] docs: media: Document CLL and Mastering display
From: Hans Verkuil
Date: Wed Dec 02 2020 - 06:02:08 EST
On 24/11/2020 00:02, Stanimir Varbanov wrote:
> Document Content light level and Mastering display colour volume.
>
> Signed-off-by: Stanimir Varbanov <stanimir.varbanov@xxxxxxxxxx>
> ---
> .../media/v4l/ext-ctrls-codec.rst | 71 +++++++++++++++++++
> 1 file changed, 71 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> index ce728c757eaf..1d26a5db07ef 100644
> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> @@ -4382,3 +4382,74 @@ enum v4l2_mpeg_video_hevc_size_of_length_field -
> - Selecting this value specifies that HEVC slices are expected
> to be prefixed by Annex B start codes. According to :ref:`hevc`
> valid start codes can be 3-bytes 0x000001 or 4-bytes 0x00000001.
> +
> +``V4L2_CID_MPEG_VIDEO_HDR10_CLL_INFO (struct)``
> + The Content Light Level defines upper bounds for the nominal target
> + brightness light level of the pictures.
> +
> +.. c:type:: v4l2_ctrl_hdr10_cll_info
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: struct v4l2_ctrl_hdr10_cll_info
> + :header-rows: 0
> + :stub-columns: 0
> + :widths: 1 1 2
> +
> + * - __u16
> + - ``max_content_light_level``
> + - An upper bound on the maximum light level among all individual
> + samples for the pictures of coded video sequence, cd/m2. When
> + equal to 0 no such uppper bound is present.
> + * - __u16
> + - ``max_pic_average_light_level``
> + - An upper bound on the maximum average light level among the
> + samples for any individual picture of coded video sequence, cd/m2.
> + When equal to 0 no such uppper bound is present.
> +
> +``V4L2_CID_MPEG_VIDEO_HDR10_MASTERING_DISPLAY (struct)``
> + The mastering display defines the colour volume (the colour primaries,
> + white point and luminance range) of a display considered to be the
> + mastering display for current video content.
> +
> +.. c:type:: v4l2_ctrl_hdr10_mastering_display
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: struct v4l2_ctrl_hdr10_mastering_display
> + :header-rows: 0
> + :stub-columns: 0
> + :widths: 1 1 2
> +
> + * - __u16
> + - ``display_primaries_x[3]``
> + - Specifies the normalized x chromaticity coordinate of the colour
> + primary component c of the mastering display in increments of 0.00002.
> + For describing mastering display that use Red, Green and Blue colour
> + primaries, index value c equal to 0 correspond to Green primary, c
> + equal to 1 correspond to Blue primary and c equal to 2 correspond to
correspond -> corresponds (3 times)
> + Red colour primary.
> + * - __u16
> + - ``display_primaries_y[3]``
> + - Specifies the normalized y chromaticity coordinate of the colour
> + primary component c of the mastering display in increments of 0.00002.
> + For describing mastering display that use Red, Green and Blue colour
> + primaries, index value c equal to 0 correspond to Green primary, c
> + equal to 1 correspond to Blue primary and c equal to 2 correspond to
Ditto.
> + Red colour primary.
> + * - __u16
> + - ``white_point_x``
> + - Specifies the normalized x chromaticity coordinate of the white
> + point of the mastering display in increments of 0.00002.
> + * - __u16
> + - ``white_point_y``
> + - Specifies the normalized y chromaticity coordinate of the white
> + point of the mastering display in increments of 0.00002.
> + * - __u32
> + - ``max_luminance``
> + - Specifies the nominal maximum display luminance of the mastering
> + display in units of 0.0001 cd/m2.
> + * - __u32
> + - ``min_luminance``
> + - specifies the nominal minimum display luminance of the mastering
> + display in units of 0.0001 cd/m2.
>
I'd rename these last two fields to max/min_display_mastering_luminance to stay
in sync with the H.265 spec.
Regards,
Hans