Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst
Extension
.rst
Size
10485 bytes
Lines
267
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_ENUM_FMT:

*********************
ioctl VIDIOC_ENUM_FMT
*********************

Name
====

VIDIOC_ENUM_FMT - Enumerate image formats

Synopsis
========

.. c:macro:: VIDIOC_ENUM_FMT

``int ioctl(int fd, VIDIOC_ENUM_FMT, struct v4l2_fmtdesc *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_fmtdesc`.

Description
===========

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
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.

Depending on the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`,
the ``mbus_code`` field is handled differently:

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

Annotation

Implementation Notes