diff mbox series

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

Message ID 20201109173153.23720-3-stanimir.varbanov@linaro.org (mailing list archive)
State Superseded
Headers show
Series HDR10 static metadata | expand

Commit Message

Stanimir Varbanov Nov. 9, 2020, 5:31 p.m. UTC
Document Content light level and Mastering display colour volume.

Signed-off-by: Stanimir Varbanov <stanimir.varbanov@linaro.org>
---
 .../media/v4l/ext-ctrls-codec.rst             | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)

Comments

Hans Verkuil Nov. 10, 2020, 9:50 a.m. UTC | #1
On 09/11/2020 18:31, Stanimir Varbanov wrote:
> Document Content light level and Mastering display colour volume.
> 
> Signed-off-by: Stanimir Varbanov <stanimir.varbanov@linaro.org>
> ---
>  .../media/v4l/ext-ctrls-codec.rst             | 61 +++++++++++++++++++
>  1 file changed, 61 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..39d0aab5ca3d 100644
> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
> @@ -4382,3 +4382,64 @@ 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_HEVC_CLL_INFO (struct)``
> +    The Content Light Level defines upper bounds for the nominal target
> +    brightness light level of the pictures.
> +
> +.. c:type:: v4l2_ctrl_hevc_cll_info
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: struct v4l2_ctrl_hevc_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.
> +    * - __u16
> +      - ``max_pic_average_light_level``
> +      - An upper bound on the maximum average light level among the
> +        samples for any idividual picture of coded video sequence, cd/m2.

idividual -> individual

In the CTA-861-G spec value 0 is used to indicate that this information is
not present. How is that handled here? Can it be 0 as well in an HEVC stream?

Same for the next control.

> +
> +``V4L2_CID_MPEG_VIDEO_HEVC_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_hevc_mastering_display
> +
> +.. cssclass:: longtable
> +
> +.. flat-table:: struct v4l2_ctrl_hevc_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 of the mastering display.

CTA-861-G defines this as: "coded as unsigned 16-bit values in units
of 0.00002, where 0x0000 represents zero and 0xC350 represents 1.0000."

Is that true here as well? If so, then this should be documented because
"normalized x chromaticity coordinate" doesn't say anything meaningful.

> +    * - __u16
> +      - ``display_primaries_y[3]``
> +      - Specifies the normalized y chromaticity coordinate of the colour
> +        primary component of the mastering display.
> +    * - __u16
> +      - ``white_point_x``
> +      - Specifies the normalized x chromaticity coordinate of the white
> +        point of the mastering display.
> +    * - __u16
> +      - ``white_point_y``
> +      - Specifies the normalized y chromaticity coordinate of the white
> +        point of the mastering display.
> +    * - __u32
> +      - ``max_luminance``
> +      - Specifies the nominal maximum display luminance of the mastering
> +        display.

In CTA-861-G this is in 1 cd/m^2 units.

> +    * - __u32
> +      - ``min_luminance``
> +      - specifies the nominal minimum display luminance of the mastering
> +        display.

And this in units of 0.0001 cd/m^2.

Regards,

	Hans
Stanimir Varbanov Nov. 10, 2020, 10:28 a.m. UTC | #2
On 11/10/20 11:50 AM, Hans Verkuil wrote:
> On 09/11/2020 18:31, Stanimir Varbanov wrote:
>> Document Content light level and Mastering display colour volume.
>>
>> Signed-off-by: Stanimir Varbanov <stanimir.varbanov@linaro.org>
>> ---
>>  .../media/v4l/ext-ctrls-codec.rst             | 61 +++++++++++++++++++
>>  1 file changed, 61 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..39d0aab5ca3d 100644
>> --- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
>> +++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
>> @@ -4382,3 +4382,64 @@ 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_HEVC_CLL_INFO (struct)``
>> +    The Content Light Level defines upper bounds for the nominal target
>> +    brightness light level of the pictures.
>> +
>> +.. c:type:: v4l2_ctrl_hevc_cll_info
>> +
>> +.. cssclass:: longtable
>> +
>> +.. flat-table:: struct v4l2_ctrl_hevc_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.
>> +    * - __u16
>> +      - ``max_pic_average_light_level``
>> +      - An upper bound on the maximum average light level among the
>> +        samples for any idividual picture of coded video sequence, cd/m2.
> 
> idividual -> individual
> 
> In the CTA-861-G spec value 0 is used to indicate that this information is
> not present. How is that handled here? Can it be 0 as well in an HEVC stream?

ITU-T Rec. H265 says: When equal to 0, no such upper bound is indicated
by max_content_light_level.

So, the meaning is the same as in CTA-861-G.

> 
> Same for the next control.
> 
>> +
>> +``V4L2_CID_MPEG_VIDEO_HEVC_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_hevc_mastering_display
>> +
>> +.. cssclass:: longtable
>> +
>> +.. flat-table:: struct v4l2_ctrl_hevc_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 of the mastering display.
> 
> CTA-861-G defines this as: "coded as unsigned 16-bit values in units
> of 0.00002, where 0x0000 represents zero and 0xC350 represents 1.0000."
> 
> Is that true here as well? If so, then this should be documented because
> "normalized x chromaticity coordinate" doesn't say anything meaningful.

Yes, it is the same. Will document that in next version.

> 
>> +    * - __u16
>> +      - ``display_primaries_y[3]``
>> +      - Specifies the normalized y chromaticity coordinate of the colour
>> +        primary component of the mastering display.
>> +    * - __u16
>> +      - ``white_point_x``
>> +      - Specifies the normalized x chromaticity coordinate of the white
>> +        point of the mastering display.
>> +    * - __u16
>> +      - ``white_point_y``
>> +      - Specifies the normalized y chromaticity coordinate of the white
>> +        point of the mastering display.
>> +    * - __u32
>> +      - ``max_luminance``
>> +      - Specifies the nominal maximum display luminance of the mastering
>> +        display.
> 
> In CTA-861-G this is in 1 cd/m^2 units.

In Rec. H265 max_luminance is in the range of 50 000 to 100 000 000 and
units of 0.0001 cd/m2.

> 
>> +    * - __u32
>> +      - ``min_luminance``
>> +      - specifies the nominal minimum display luminance of the mastering
>> +        display.
> 
> And this in units of 0.0001 cd/m^2.

min_luminance - range of 1 to 50 000 and units of 0.0001 cd/m2.

I will update all these in next patchset version.

> 
> Regards,
> 
> 	Hans
>
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
index ce728c757eaf..39d0aab5ca3d 100644
--- a/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
+++ b/Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst
@@ -4382,3 +4382,64 @@  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_HEVC_CLL_INFO (struct)``
+    The Content Light Level defines upper bounds for the nominal target
+    brightness light level of the pictures.
+
+.. c:type:: v4l2_ctrl_hevc_cll_info
+
+.. cssclass:: longtable
+
+.. flat-table:: struct v4l2_ctrl_hevc_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.
+    * - __u16
+      - ``max_pic_average_light_level``
+      - An upper bound on the maximum average light level among the
+        samples for any idividual picture of coded video sequence, cd/m2.
+
+``V4L2_CID_MPEG_VIDEO_HEVC_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_hevc_mastering_display
+
+.. cssclass:: longtable
+
+.. flat-table:: struct v4l2_ctrl_hevc_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 of the mastering display.
+    * - __u16
+      - ``display_primaries_y[3]``
+      - Specifies the normalized y chromaticity coordinate of the colour
+        primary component of the mastering display.
+    * - __u16
+      - ``white_point_x``
+      - Specifies the normalized x chromaticity coordinate of the white
+        point of the mastering display.
+    * - __u16
+      - ``white_point_y``
+      - Specifies the normalized y chromaticity coordinate of the white
+        point of the mastering display.
+    * - __u32
+      - ``max_luminance``
+      - Specifies the nominal maximum display luminance of the mastering
+        display.
+    * - __u32
+      - ``min_luminance``
+      - specifies the nominal minimum display luminance of the mastering
+        display.