0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _format:
0005
0006 ************
0007 Data Formats
0008 ************
0009
0010 Data Format Negotiation
0011 =======================
0012
0013 Different devices exchange different kinds of data with applications,
0014 for example video images, raw or sliced VBI data, RDS datagrams. Even
0015 within one kind many different formats are possible, in particular there is an
0016 abundance of image formats. Although drivers must provide a default and
0017 the selection persists across closing and reopening a device,
0018 applications should always negotiate a data format before engaging in
0019 data exchange. Negotiation means the application asks for a particular
0020 format and the driver selects and reports the best the hardware can do
0021 to satisfy the request. Of course applications can also just query the
0022 current selection.
0023
0024 A single mechanism exists to negotiate all data formats using the
0025 aggregate struct :c:type:`v4l2_format` and the
0026 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
0027 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
0028 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
0029 what the hardware *could* do, without actually selecting a new data
0030 format. The data formats supported by the V4L2 API are covered in the
0031 respective device section in :ref:`devices`. For a closer look at
0032 image formats see :ref:`pixfmt`.
0033
0034 The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
0035 initialization sequence. Prior to this point multiple panel applications
0036 can access the same device concurrently to select the current input,
0037 change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
0038 assigns a logical stream (video data, VBI data etc.) exclusively to one
0039 file descriptor.
0040
0041 Exclusive means no other application, more precisely no other file
0042 descriptor, can grab this stream or change device properties
0043 inconsistent with the negotiated parameters. A video standard change for
0044 example, when the new standard uses a different number of scan lines,
0045 can invalidate the selected image format. Therefore only the file
0046 descriptor owning the stream can make invalidating changes. Accordingly
0047 multiple file descriptors which grabbed different logical streams
0048 prevent each other from interfering with their settings. When for
0049 example video overlay is about to start or already in progress,
0050 simultaneous video capturing may be restricted to the same cropping and
0051 image size.
0052
0053 When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
0054 effects are implied by the next step, the selection of an I/O method
0055 with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
0056 with the first :c:func:`read()` or
0057 :c:func:`write()` call.
0058
0059 Generally only one logical stream can be assigned to a file descriptor,
0060 the exception being drivers permitting simultaneous video capturing and
0061 overlay using the same file descriptor for compatibility with V4L and
0062 earlier versions of V4L2. Switching the logical stream or returning into
0063 "panel mode" is possible by closing and reopening the device. Drivers
0064 *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
0065
0066 All drivers exchanging data with applications must support the
0067 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
0068 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
0069
0070 Image Format Enumeration
0071 ========================
0072
0073 Apart of the generic format negotiation functions a special ioctl to
0074 enumerate all image formats supported by video capture, overlay or
0075 output devices is available. [#f1]_
0076
0077 The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
0078 by all drivers exchanging image data with applications.
0079
0080 .. important::
0081
0082 Drivers are not supposed to convert image formats in kernel space.
0083 They must enumerate only formats directly supported by the hardware.
0084 If necessary driver writers should publish an example conversion
0085 routine or library for integration into applications.
0086
0087 .. [#f1]
0088 Enumerating formats an application has no a-priori knowledge of
0089 (otherwise it could explicitly ask for them and need not enumerate)
0090 seems useless, but there are applications serving as proxy between
0091 drivers and the actual video applications for which this is useful.
