1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _format: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************ 754f38fcaSMauro Carvalho ChehabData Formats 854f38fcaSMauro Carvalho Chehab************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabData Format Negotiation 1154f38fcaSMauro Carvalho Chehab======================= 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabDifferent devices exchange different kinds of data with applications, 1454f38fcaSMauro Carvalho Chehabfor example video images, raw or sliced VBI data, RDS datagrams. Even 1554f38fcaSMauro Carvalho Chehabwithin one kind many different formats are possible, in particular there is an 1654f38fcaSMauro Carvalho Chehababundance of image formats. Although drivers must provide a default and 1754f38fcaSMauro Carvalho Chehabthe selection persists across closing and reopening a device, 1854f38fcaSMauro Carvalho Chehabapplications should always negotiate a data format before engaging in 1954f38fcaSMauro Carvalho Chehabdata exchange. Negotiation means the application asks for a particular 2054f38fcaSMauro Carvalho Chehabformat and the driver selects and reports the best the hardware can do 2154f38fcaSMauro Carvalho Chehabto satisfy the request. Of course applications can also just query the 2254f38fcaSMauro Carvalho Chehabcurrent selection. 2354f38fcaSMauro Carvalho Chehab 2454f38fcaSMauro Carvalho ChehabA single mechanism exists to negotiate all data formats using the 2554f38fcaSMauro Carvalho Chehabaggregate struct :c:type:`v4l2_format` and the 2654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 2754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the 2854f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine 2954f38fcaSMauro Carvalho Chehabwhat the hardware *could* do, without actually selecting a new data 3054f38fcaSMauro Carvalho Chehabformat. The data formats supported by the V4L2 API are covered in the 3154f38fcaSMauro Carvalho Chehabrespective device section in :ref:`devices`. For a closer look at 3254f38fcaSMauro Carvalho Chehabimage formats see :ref:`pixfmt`. 3354f38fcaSMauro Carvalho Chehab 3454f38fcaSMauro Carvalho ChehabThe :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the 3554f38fcaSMauro Carvalho Chehabinitialization sequence. Prior to this point multiple panel applications 3654f38fcaSMauro Carvalho Chehabcan access the same device concurrently to select the current input, 3754f38fcaSMauro Carvalho Chehabchange controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 3854f38fcaSMauro Carvalho Chehabassigns a logical stream (video data, VBI data etc.) exclusively to one 3954f38fcaSMauro Carvalho Chehabfile descriptor. 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabExclusive means no other application, more precisely no other file 4254f38fcaSMauro Carvalho Chehabdescriptor, can grab this stream or change device properties 4354f38fcaSMauro Carvalho Chehabinconsistent with the negotiated parameters. A video standard change for 4454f38fcaSMauro Carvalho Chehabexample, when the new standard uses a different number of scan lines, 4554f38fcaSMauro Carvalho Chehabcan invalidate the selected image format. Therefore only the file 4654f38fcaSMauro Carvalho Chehabdescriptor owning the stream can make invalidating changes. Accordingly 4754f38fcaSMauro Carvalho Chehabmultiple file descriptors which grabbed different logical streams 4854f38fcaSMauro Carvalho Chehabprevent each other from interfering with their settings. When for 4954f38fcaSMauro Carvalho Chehabexample video overlay is about to start or already in progress, 5054f38fcaSMauro Carvalho Chehabsimultaneous video capturing may be restricted to the same cropping and 5154f38fcaSMauro Carvalho Chehabimage size. 5254f38fcaSMauro Carvalho Chehab 5354f38fcaSMauro Carvalho ChehabWhen applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side 5454f38fcaSMauro Carvalho Chehabeffects are implied by the next step, the selection of an I/O method 5554f38fcaSMauro Carvalho Chehabwith the :ref:`VIDIOC_REQBUFS` ioctl or implicit 56407e84cdSMauro Carvalho Chehabwith the first :c:func:`read()` or 57407e84cdSMauro Carvalho Chehab:c:func:`write()` call. 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho ChehabGenerally only one logical stream can be assigned to a file descriptor, 6054f38fcaSMauro Carvalho Chehabthe exception being drivers permitting simultaneous video capturing and 6154f38fcaSMauro Carvalho Chehaboverlay using the same file descriptor for compatibility with V4L and 6254f38fcaSMauro Carvalho Chehabearlier versions of V4L2. Switching the logical stream or returning into 6354f38fcaSMauro Carvalho Chehab"panel mode" is possible by closing and reopening the device. Drivers 6454f38fcaSMauro Carvalho Chehab*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. 6554f38fcaSMauro Carvalho Chehab 6654f38fcaSMauro Carvalho ChehabAll drivers exchanging data with applications must support the 6754f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the 6854f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. 6954f38fcaSMauro Carvalho Chehab 7054f38fcaSMauro Carvalho ChehabImage Format Enumeration 7154f38fcaSMauro Carvalho Chehab======================== 7254f38fcaSMauro Carvalho Chehab 7354f38fcaSMauro Carvalho ChehabApart of the generic format negotiation functions a special ioctl to 7454f38fcaSMauro Carvalho Chehabenumerate all image formats supported by video capture, overlay or 7554f38fcaSMauro Carvalho Chehaboutput devices is available. [#f1]_ 7654f38fcaSMauro Carvalho Chehab 7754f38fcaSMauro Carvalho ChehabThe :ref:`VIDIOC_ENUM_FMT` ioctl must be supported 7854f38fcaSMauro Carvalho Chehabby all drivers exchanging image data with applications. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho Chehab.. important:: 8154f38fcaSMauro Carvalho Chehab 8254f38fcaSMauro Carvalho Chehab Drivers are not supposed to convert image formats in kernel space. 8354f38fcaSMauro Carvalho Chehab They must enumerate only formats directly supported by the hardware. 8454f38fcaSMauro Carvalho Chehab If necessary driver writers should publish an example conversion 8554f38fcaSMauro Carvalho Chehab routine or library for integration into applications. 8654f38fcaSMauro Carvalho Chehab 8754f38fcaSMauro Carvalho Chehab.. [#f1] 8854f38fcaSMauro Carvalho Chehab Enumerating formats an application has no a-priori knowledge of 8954f38fcaSMauro Carvalho Chehab (otherwise it could explicitly ask for them and need not enumerate) 9054f38fcaSMauro Carvalho Chehab seems useless, but there are applications serving as proxy between 9154f38fcaSMauro Carvalho Chehab drivers and the actual video applications for which this is useful. 92