Re: [PATCH v3 2/3] docs: media: Document CLL and Mastering display

[Hans Verkuil]

On 08/12/2020 15:59, Stanimir Varbanov wrote:
> Document Content light level and Mastering display colour volume.
> 
> Signed-off-by: Stanimir Varbanov <stanimir.varbanov@xxxxxxxxxx>
> ---
>  .../userspace-api/media/v4l/common.rst        |  1 +
>  .../media/v4l/ext-ctrls-colorimetry.rst       | 88 +++++++++++++++++++
>  2 files changed, 89 insertions(+)
>  create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst
> 
> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst
> index 8c263c5a85d8..ea0435182e44 100644
> --- a/Documentation/userspace-api/media/v4l/common.rst
> +++ b/Documentation/userspace-api/media/v4l/common.rst
> @@ -51,6 +51,7 @@ applicable to all devices.
>      ext-ctrls-fm-tx
>      ext-ctrls-fm-rx
>      ext-ctrls-detect
> +    ext-ctrls-colorimetry
>      fourcc
>      format
>      planar-apis
> diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst
> new file mode 100644
> index 000000000000..16d9ddadbab6
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst
> @@ -0,0 +1,88 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _colorimetry-controls:
> +
> +*****************************
> +Colorimetry Control Reference
> +*****************************
> +
> +Below are controls within the Colorimetry control class.
> +
> +Colorimetry Control IDs
> +-----------------------
> +
> +.. _colorimetry-control-id:
> +
> +``V4L2_CID_COLORIMETRY_CLASS (class)``
> +    The Colorimetry class descriptor.
> +
> +``V4L2_CID_COLORIMETRY_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

An -> The
on -> for

> +        samples for the pictures of coded video sequence, cd/m2. When

of -> of a

> +        equal to 0 no such uppper bound is present.

uppper -> upper

> +    * - __u16
> +      - ``max_pic_average_light_level``
> +      - An upper bound on the maximum average light level among the

An -> The
on -> for

> +        samples for any individual picture of coded video sequence, cd/m2.

of -> of a

> +        When equal to 0 no such uppper bound is present.

uppper -> upper

> +
> +``V4L2_CID_COLORIMETRY_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.

for -> for the

> +
> +.. 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

describing -> describing the
use -> uses

> +        primaries, index value c equal to 0 correspond to Green primary, c

to Green -> to the Green
correspond -> corresponds

> +        equal to 1 correspond to Blue primary and c equal to 2 correspond to

ditto

> +        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
> +        Red colour primary.

ditto

> +    * - __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.
> 

Regards,

	Hans