media: v4l2: add support for colorspace conversion API (CSC) for video capture

For video capture it is the driver that reports the colorspace,
transfer function, Y'CbCr/HSV encoding and quantization range
used by the video, and there is no way to request something
different, even though many HDTV receivers have some sort of
colorspace conversion capabilities.

For output video this feature already exists since the application
specifies this information for the video format it will send out, and
the transmitter will enable any available CSC if a format conversion has
to be performed in order to match the capabilities of the sink.

For video capture we propose adding new v4l2_pix_format flag:
V4L2_PIX_FMT_FLAG_SET_CSC. The flag is set by the application,
the driver will interpret the colorspace, xfer_func, ycbcr_enc/hsv_enc
and quantization fields as the requested colorspace information and will
attempt to do the conversion it supports.

Drivers set the flags
V4L2_FMT_FLAG_CSC_COLORSPACE,
V4L2_FMT_FLAG_CSC_XFER_FUNC,
V4L2_FMT_FLAG_CSC_YCBCR_ENC/V4L2_FMT_FLAG_CSC_HSV_ENC,
V4L2_FMT_FLAG_CSC_QUANTIZATION,
in the flags field of the struct v4l2_fmtdesc during enumeration to
indicate that they support colorspace conversion for the respective field.

Drivers do not have to actually look at the flags. If the flags are not
set, then the fields 'colorspace', 'xfer_func', 'ycbcr_enc/hsv_enc',
and 'quantization' are set to the default values by the core, i.e. just
pass on the received format without conversion.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Philipp Zabel <p.zabel@pengutronix.de>
Signed-off-by: Dafna Hirschfeld <dafna.hirschfeld@collabora.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst
index ac82882135ae70a0c054b21ed0e6e43dae5c7a1a..977facc3a1f41d6b072ac8e3107a282d48334640 100644 (file)
--- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst
@@ -98,29 +98,21 @@ describing all planes of that format.
     * - __u8
       - ``ycbcr_enc``
       - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
-        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`.
+       See struct :c:type:`v4l2_pix_format`.
     * - __u8
       - ``hsv_enc``
       - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
-        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`.
+       See struct :c:type:`v4l2_pix_format`.
     * - }
       -
     * - __u8
       - ``quantization``
       - Quantization range, from enum :c:type:`v4l2_quantization`.
-        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`.
+       See struct :c:type:`v4l2_pix_format`.
     * - __u8
       - ``xfer_func``
       - Transfer function, from enum :c:type:`v4l2_xfer_func`.
-        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`.
+       See struct :c:type:`v4l2_pix_format`.
     * - __u8
       - ``reserved[7]``
       - Reserved for future extensions. Should be zeroed by drivers and

diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
index 8424d6f53b0c6920f1253fa252db26c35d59a38a..71e828093310a8199ce978e8695242e9272aa9d9 100644 (file)
--- a/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst
@@ -109,7 +109,14 @@ Single-planar format structure
       - Image colorspace, from enum :c:type:`v4l2_colorspace`.
         This information supplements the ``pixelformat`` and must be set
        by the driver for capture streams and by the application for
-       output streams, see :ref:`colorspaces`.
+       output streams, see :ref:`colorspaces`. If the application sets the
+       flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
+       this field for a capture stream to request a specific colorspace
+       for the captured image data. If the driver cannot handle requested
+       conversion, it will return another supported colorspace.
+       The driver indicates that colorspace conversion is supported by setting
+       the flag V4L2_FMT_FLAG_CSC_COLORSPACE in the corresponding struct
+       :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
     * - __u32
       - ``priv``
       - This field indicates whether the remaining fields of the
@@ -146,13 +153,29 @@ Single-planar format structure
       - Y'CbCr encoding, from enum :c:type:`v4l2_ycbcr_encoding`.
         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`.
+       streams, see :ref:`colorspaces`. If the application sets the
+       flag ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
+       this field for a capture stream to request a specific Y'CbCr encoding
+       for the captured image data. If the driver cannot handle requested
+       conversion, it will return another supported encoding.
+       This field is ignored for HSV pixelformats. The driver indicates that
+       ycbcr_enc conversion is supported by setting the flag
+       V4L2_FMT_FLAG_CSC_YCBCR_ENC in the corresponding struct
+       :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
     * - __u32
       - ``hsv_enc``
       - HSV encoding, from enum :c:type:`v4l2_hsv_encoding`.
         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`.
+       streams, see :ref:`colorspaces`. If the application sets the flag
+       ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set this
+       field for a capture stream to request a specific HSV encoding for the
+       captured image data. If the driver cannot handle requested
+       conversion, it will return another supported encoding.
+       This field is ignored for non-HSV pixelformats. The driver indicates
+       that hsv_enc conversion is supported by setting the flag
+       V4L2_FMT_FLAG_CSC_HSV_ENC in the corresponding struct
+       :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
     * - }
       -
     * - __u32
@@ -160,13 +183,27 @@ Single-planar format structure
       - Quantization range, from enum :c:type:`v4l2_quantization`.
         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`.
+       streams, see :ref:`colorspaces`. If the application sets the flag
+       ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
+       this field for a capture stream to request a specific quantization
+       range for the captured image data. If the driver cannot handle requested
+       conversion, it will return another supported quantization.
+       The driver indicates that quantization conversion is supported by setting
+       the flag V4L2_FMT_FLAG_CSC_QUANTIZATION in the corresponding struct
+       :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
     * - __u32
       - ``xfer_func``
       - Transfer function, from enum :c:type:`v4l2_xfer_func`.
         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`.
+       streams, see :ref:`colorspaces`. If the application sets the flag
+       ``V4L2_PIX_FMT_FLAG_SET_CSC`` then the application can set
+       this field for a capture stream to request a specific transfer function
+       for the captured image data. If the driver cannot handle requested
+       conversion, it will return another supported transfer function.
+       The driver indicates that xfer_func conversion is supported by setting
+       the flag V4L2_FMT_FLAG_CSC_XFER_FUNC in the corresponding struct
+       :c:type:`v4l2_fmtdesc` during enumeration. See :ref:`fmtdesc-flags`.
 
 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 
@@ -184,3 +221,20 @@ Single-planar format structure
        by RGBA values (128, 192, 255, 128), the same pixel described with
        premultiplied colors would be described by RGBA values (64, 96,
        128, 128)
+    * .. _`v4l2-pix-fmt-flag-set-csc`:
+
+      - ``V4L2_PIX_FMT_FLAG_SET_CSC``
+      - 0x00000002
+      - Set by the application. It is only used for capture and is
+        ignored for output streams. If set, then request the device to do
+       colorspace conversion from the received colorspace to the requested
+       colorspace values. If the colorimetry field (``colorspace``, ``xfer_func``,
+       ``ycbcr_enc``, ``hsv_enc`` or ``quantization``) is set to ``*_DEFAULT``,
+       then that colorimetry setting will remain unchanged from what was received.
+       So in order to change the quantization, only the ``quantization`` field shall
+       be set to non default value (``V4L2_QUANTIZATION_FULL_RANGE`` or
+       ``V4L2_QUANTIZATION_LIM_RANGE``) and all other colorimetry fields shall
+       be set to ``*_DEFAULT``.
+
+       To check which conversions are supported by the hardware for the current
+       pixel format, see :ref:`fmtdesc-flags`.

diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
index 296b7d437431c33ab63b09546afa4f68b8a9bf04..b8347a96a554c659ed7bcc9bc25f0f587dd8f2c9 100644 (file)
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
@@ -191,6 +191,41 @@ the ``mbus_code`` field is handled differently:
        This flag can only be used in combination with the
        ``V4L2_FMT_FLAG_COMPRESSED`` flag, since this applies to
         compressed formats only. This flag is valid for stateful encoders only.
+    * - ``V4L2_FMT_FLAG_CSC_COLORSPACE``
+      - 0x0020
+      - The driver allows the application to try to change the default
+       colorspace. This flag is relevant only for capture devices.
+       The application can ask to configure the colorspace of the capture device
+       when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+       :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
+    * - ``V4L2_FMT_FLAG_CSC_XFER_FUNC``
+      - 0x0040
+      - The driver allows the application to try to change the default
+       transfer function. This flag is relevant only for capture devices.
+       The application can ask to configure the transfer function of the capture
+       device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+       :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
+    * - ``V4L2_FMT_FLAG_CSC_YCBCR_ENC``
+      - 0x0080
+      - The driver allows the application to try to change the default
+       Y'CbCr encoding. This flag is relevant only for capture devices.
+       The application can ask to configure the Y'CbCr encoding of the capture device
+       when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+       :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
+    * - ``V4L2_FMT_FLAG_CSC_HSV_ENC``
+      - 0x0080
+      - The driver allows the application to try to change the default
+       HSV encoding. This flag is relevant only for capture devices.
+       The application can ask to configure the HSV encoding of the capture device
+       when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+       :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
+    * - ``V4L2_FMT_FLAG_CSC_QUANTIZATION``
+      - 0x0100
+      - The driver allows the application to try to change the default
+       quantization. This flag is relevant only for capture devices.
+       The application can ask to configure the quantization of the capture
+       device when calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+       :ref:`V4L2_PIX_FMT_FLAG_SET_CSC <v4l2-pix-fmt-flag-set-csc>` set.
 
 
 Return Value

diff --git a/Documentation/userspace-api/media/videodev2.h.rst.exceptions b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
index 659799cc1ecabef44a19eefd2708066c2e25f8dd..121e396a2779626f7c8ff6dba51cdf81855f9fe3 100644 (file)
--- a/Documentation/userspace-api/media/videodev2.h.rst.exceptions
+++ b/Documentation/userspace-api/media/videodev2.h.rst.exceptions
@@ -188,6 +188,11 @@ replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags
 replace define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM fmtdesc-flags
 replace define V4L2_FMT_FLAG_DYN_RESOLUTION fmtdesc-flags
 replace define V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL fmtdesc-flags
+replace define V4L2_FMT_FLAG_CSC_COLORSPACE fmtdesc-flags
+replace define V4L2_FMT_FLAG_CSC_XFER_FUNC fmtdesc-flags
+replace define V4L2_FMT_FLAG_CSC_YCBCR_ENC fmtdesc-flags
+replace define V4L2_FMT_FLAG_CSC_HSV_ENC fmtdesc-flags
+replace define V4L2_FMT_FLAG_CSC_QUANTIZATION fmtdesc-flags
 
 # V4L2 timecode types
 replace define V4L2_TC_TYPE_24FPS timecode-type

diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 4769628790dae48b34c985747dcb3110c98cb412..b2bc83f3702450f83b4d11a57c710d9bce6afcae 100644 (file)
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -777,6 +777,7 @@ struct v4l2_pix_format {
 
 /* Flags */
 #define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA 0x00000001
+#define V4L2_PIX_FMT_FLAG_SET_CSC      0x00000002
 
 /*
  *     F O R M A T   E N U M E R A T I O N
@@ -796,6 +797,11 @@ struct v4l2_fmtdesc {
 #define V4L2_FMT_FLAG_CONTINUOUS_BYTESTREAM    0x0004
 #define V4L2_FMT_FLAG_DYN_RESOLUTION           0x0008
 #define V4L2_FMT_FLAG_ENC_CAP_FRAME_INTERVAL   0x0010
+#define V4L2_FMT_FLAG_CSC_COLORSPACE           0x0020
+#define V4L2_FMT_FLAG_CSC_XFER_FUNC            0x0040
+#define V4L2_FMT_FLAG_CSC_YCBCR_ENC            0x0080
+#define V4L2_FMT_FLAG_CSC_HSV_ENC              V4L2_FMT_FLAG_CSC_YCBCR_ENC
+#define V4L2_FMT_FLAG_CSC_QUANTIZATION         0x0100
 
        /* Frame Size and frame rate enumeration */
 /*