There are simply too many information at the same paragraph
when explaining the differences between MC and non-MC
centred devices.
Also, while using the V4L2_CAP_IO_MC flag to distinguish
it more formal, media developers understand the differences
as "MC-centric" and "video-node centric". So, add an alias
to make the text clearer for the targeted audience.
Fixes: e5b6b07a1b45 ("media: v4l2: Extend VIDIOC_ENUM_FMT to support MC-centric devices")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
.../media/v4l/vidioc-enum-fmt.rst | 41 ++++++++++++-------
1 file changed, 26 insertions(+), 15 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..aef6a69625b9 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
@@ -48,21 +48,32 @@ 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.
-
-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) If the driver doesn't advertise the ``V4L2_CAP_IO_MC`` :ref:`capability
+ <device-capabilities>` (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 input or output the list of enumerated image
+ formats may be different.
+
+2) If the driver advertises the ``V4L2_CAP_IO_MC`` :ref:`capability
+ <device-capabilities>` (also known as a 'MC-centric' driver)
+
+ 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.
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
--
2.25.4
