diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l')
3 files changed, 98 insertions, 17 deletions
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst b/Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst index ac82882135ae..977facc3a1f4 100644 --- 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 8424d6f53b0c..71e828093310 100644 --- 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 296b7d437431..b8347a96a554 100644 --- 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 |