diff options
| -rw-r--r-- | Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst | 55 |
1 files changed, 37 insertions, 18 deletions
diff --git a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst index 9694111772a2..a53dd3d7f7e2 100644 --- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst +++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst @@ -39,8 +39,8 @@ Arguments Description =========== -To enumerate image formats applications initialize the ``type`` and -``index`` field of struct :c:type:`v4l2_fmtdesc` and call +To enumerate image formats applications initialize the ``type``, ``mbus_code`` +and ``index`` fields of struct :c:type:`v4l2_fmtdesc` and call the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers fill the rest of the structure or return an ``EINVAL`` error code. All formats are enumerable by beginning at index zero and incrementing by @@ -48,21 +48,36 @@ one until ``EINVAL`` is returned. If applicable, drivers shall return formats in preference order, where preferred formats are returned before (that is, with lower ``index`` value) less-preferred formats. -If the driver doesn't advertise the ``V4L2_CAP_IO_MC`` :ref:`capability -<device-capabilities>`, applications shall initialize the ``mbus_code`` field -to zero and drivers shall ignore the value of the field. Drivers shall -enumerate all image formats. The enumerated formats may depend on the active -input or output of the device. +Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`, +the ``mbus_code`` field is handled differently: -If the driver advertises the ``V4L2_CAP_IO_MC`` :ref:`capability -<device-capabilities>`, applications may initialize the ``mbus_code`` field to -a valid :ref:`media bus format code <v4l2-mbus-pixelcode>`. If the -``mbus_code`` field is not zero, drivers shall restrict enumeration to only the -image formats that can produce (for video output devices) or be produced from -(for video capture devices) that media bus code. Regardless of the value of -the ``mbus_code`` field, the enumerated image formats shall not depend on the -active configuration of the video device or device pipeline. Enumeration shall -otherwise operate as previously described. +1) ``V4L2_CAP_IO_MC`` is not set (also known as a 'video-node-centric' driver) + + Applications shall initialize the ``mbus_code`` field to zero and drivers + shall ignore the value of the field. + + Drivers shall enumerate all image formats. + + .. note:: + + After switching the input or output the list of enumerated image + formats may be different. + +2) ``V4L2_CAP_IO_MC`` is set (also known as an 'MC-centric' driver) + + If the ``mbus_code`` field is zero, then all image formats + shall be enumerated. + + If the ``mbus_code`` field is initialized to a valid (non-zero) + :ref:`media bus format code <v4l2-mbus-pixelcode>`, then drivers + shall restrict enumeration to only the image formats that can produce + (for video output devices) or be produced from (for video capture + devices) that media bus code. If the ``mbus_code`` is unsupported by + the driver, then ``EINVAL`` shall be returned. + + Regardless of the value of the ``mbus_code`` field, the enumerated image + formats shall not depend on the active configuration of the video device + or device pipeline. .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| @@ -87,8 +102,9 @@ otherwise operate as previously described. ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, ``V4L2_BUF_TYPE_SDR_CAPTURE``, - ``V4L2_BUF_TYPE_SDR_OUTPUT`` and - ``V4L2_BUF_TYPE_META_CAPTURE``. + ``V4L2_BUF_TYPE_SDR_OUTPUT``, + ``V4L2_BUF_TYPE_META_CAPTURE`` and + ``V4L2_BUF_TYPE_META_OUTPUT``. See :c:type:`v4l2_buf_type`. * - __u32 - ``flags`` @@ -174,3 +190,6 @@ appropriately. The generic error codes are described at the EINVAL The struct :c:type:`v4l2_fmtdesc` ``type`` is not supported or the ``index`` is out of bounds. + + If ``V4L2_CAP_IO_MC`` is set and the specified ``mbus_code`` + is unsupported, then also return this error code. |