[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>
diff --git a/Documentation/media/uapi/v4l/pixfmt-002.rst b/Documentation/media/uapi/v4l/pixfmt-002.rst
index 0d9e697..2ee164c 100644
--- a/Documentation/media/uapi/v4l/pixfmt-002.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-002.rst
@@ -121,6 +121,11 @@
- 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 ae9ea7a..337e818 100644
--- a/Documentation/media/uapi/v4l/pixfmt-003.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-003.rst
@@ -78,6 +78,11 @@
- 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 a9890ff..7ae7dcf 100644
--- a/Documentation/media/uapi/v4l/pixfmt-006.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-006.rst
@@ -19,9 +19,16 @@
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 @@
+.. 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 @@
* - ``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 4a57972..3fdb34c 100644
--- a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst
@@ -9,7 +9,8 @@
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 1d3f27d..12622b2 100644
--- a/Documentation/media/videodev2.h.rst.exceptions
+++ b/Documentation/media/videodev2.h.rst.exceptions
@@ -87,6 +87,10 @@
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`