From 5f3d32ec739fcfe83bb3e39a0ca44f3b097e5a94 Mon Sep 17 00:00:00 2001
From: Ricardo Ribalda Delgado <ricardo.ribalda@gmail.com>
Date: Thu, 18 Aug 2016 11:33:37 -0300
Subject: [PATCH] [media] Documentation: Add HSV encodings
Describe the hsv_enc field and its use.
Signed-off-by: Ricardo Ribalda Delgado <ricardo.ribalda@gmail.com>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/media/uapi/v4l/pixfmt-002.rst | 5 +++
Documentation/media/uapi/v4l/pixfmt-003.rst | 5 +++
Documentation/media/uapi/v4l/pixfmt-006.rst | 31 +++++++++++++++++--
.../media/uapi/v4l/pixfmt-packed-hsv.rst | 3 +-
.../media/videodev2.h.rst.exceptions | 4 +++
5 files changed, 44 insertions(+), 4 deletions(-)
diff --git a/Documentation/media/uapi/v4l/pixfmt-002.rst b/Documentation/media/uapi/v4l/pixfmt-002.rst
index 0d9e697f5d4ea..2ee164c256377 100644
--- a/Documentation/media/uapi/v4l/pixfmt-002.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-002.rst
@@ -121,6 +121,11 @@ Single-planar format structure
- This information supplements the ``colorspace`` and must be set by
the driver for capture streams and by the application for output
streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_hsv_encoding`
+ - ``hsv_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
* - enum :c:type:`v4l2_quantization`
- ``quantization``
- This information supplements the ``colorspace`` and must be set by
diff --git a/Documentation/media/uapi/v4l/pixfmt-003.rst b/Documentation/media/uapi/v4l/pixfmt-003.rst
index ae9ea7a791de5..337e8188caf17 100644
--- a/Documentation/media/uapi/v4l/pixfmt-003.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-003.rst
@@ -78,6 +78,11 @@ describing all planes of that format.
- This information supplements the ``colorspace`` and must be set by
the driver for capture streams and by the application for output
streams, see :ref:`colorspaces`.
+ * - enum :c:type:`v4l2_hsv_encoding`
+ - ``hsv_enc``
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
* - enum :c:type:`v4l2_quantization`
- ``quantization``
- This information supplements the ``colorspace`` and must be set by
diff --git a/Documentation/media/uapi/v4l/pixfmt-006.rst b/Documentation/media/uapi/v4l/pixfmt-006.rst
index a9890ff6038be..7ae7dcf73f63c 100644
--- a/Documentation/media/uapi/v4l/pixfmt-006.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-006.rst
@@ -19,9 +19,16 @@ colorspace field of struct :c:type:`v4l2_pix_format`
or struct :c:type:`v4l2_pix_format_mplane`
needs to be filled in.
-.. note::
+.. _hsv-colorspace:
- The default R'G'B' quantization is full range for all
+On :ref:`HSV formats <hsv-formats>` the *Hue* is defined as the angle on
+the cylindrical color representation. Usually this angle is measured in
+degrees, i.e. 0-360. When we map this angle value into 8 bits, there are
+two basic ways to do it: Divide the angular value by 2 (0-179), or use the
+whole range, 0-255, dividing the angular value by 1.41. The enum
+:c:type:`v4l2_hsv_encoding` specifies which encoding is used.
+
+.. note:: The default R'G'B' quantization is full range for all
colorspaces except for BT.2020 which uses limited range R'G'B'
quantization.
@@ -123,6 +130,24 @@ needs to be filled in.
+.. c:type:: v4l2_hsv_encoding
+
+.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
+
+.. flat-table:: V4L2 HSV Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Details
+ * - ``V4L2_HSV_ENC_180``
+ - For the Hue, each LSB is two degrees.
+ * - ``V4L2_HSV_ENC_256``
+ - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each
+ LSB is roughly 1.41 degrees.
+
+
+
.. c:type:: v4l2_quantization
.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|
@@ -136,7 +161,7 @@ needs to be filled in.
* - ``V4L2_QUANTIZATION_DEFAULT``
- Use the default quantization encoding as defined by the
colorspace. This is always full range for R'G'B' (except for the
- BT.2020 colorspace) and usually limited range for Y'CbCr.
+ BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr.
* - ``V4L2_QUANTIZATION_FULL_RANGE``
- Use the full range quantization encoding. I.e. the range [0â¦1] is
mapped to [0â¦255] (with possible clipping to [1â¦254] to avoid the
diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst
index 4a579727f61c1..3fdb34ce2f095 100644
--- a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst
@@ -9,7 +9,8 @@ Packed HSV formats
Description
===========
-The *hue* (h) is measured in degrees, one LSB represents two degrees.
+The *hue* (h) is measured in degrees, the equivalence between degrees and LSBs
+depends on the hsv-encoding used, see :ref:`colorspaces`.
The *saturation* (s) and the *value* (v) are measured in percentage of the
cylinder: 0 being the smallest value and 255 the maximum.
diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions
index 1d3f27d922b21..12622b2593fa0 100644
--- a/Documentation/media/videodev2.h.rst.exceptions
+++ b/Documentation/media/videodev2.h.rst.exceptions
@@ -87,6 +87,10 @@ replace symbol V4L2_YCBCR_ENC_XV601 :c:type:`v4l2_ycbcr_encoding`
replace symbol V4L2_YCBCR_ENC_XV709 :c:type:`v4l2_ycbcr_encoding`
replace symbol V4L2_YCBCR_ENC_SMPTE240M :c:type:`v4l2_ycbcr_encoding`
+# Documented enum v4l2_hsv_encoding
+replace symbol V4L2_HSV_ENC_180 :c:type:`v4l2_hsv_encoding`
+replace symbol V4L2_HSV_ENC_256 :c:type:`v4l2_hsv_encoding`
+
# Documented enum v4l2_quantization
replace symbol V4L2_QUANTIZATION_DEFAULT :c:type:`v4l2_quantization`
replace symbol V4L2_QUANTIZATION_FULL_RANGE :c:type:`v4l2_quantization`
--
2.30.2