From 5f3d32ec739fcfe83bb3e39a0ca44f3b097e5a94 Mon Sep 17 00:00:00 2001 From: Ricardo Ribalda Delgado 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 Acked-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/pixfmt-002.rst | 5 ++++ Documentation/media/uapi/v4l/pixfmt-003.rst | 5 ++++ Documentation/media/uapi/v4l/pixfmt-006.rst | 31 +++++++++++++++++++--- Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst | 3 ++- Documentation/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 0d9e697..2ee164c 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 ae9ea7a..337e818 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 a9890ff..7ae7dcf 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 ` 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 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 @@ 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 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_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.7.4