1.. Permission is granted to copy, distribute and/or modify this 2.. document under the terms of the GNU Free Documentation License, 3.. Version 1.1 or any later version published by the Free Software 4.. Foundation, with no Invariant Sections, no Front-Cover Texts 5.. and no Back-Cover Texts. A copy of the license is included at 6.. Documentation/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _format: 11 12************ 13Data Formats 14************ 15 16 17Data Format Negotiation 18======================= 19 20Different devices exchange different kinds of data with applications, 21for example video images, raw or sliced VBI data, RDS datagrams. Even 22within one kind many different formats are possible, in particular there is an 23abundance of image formats. Although drivers must provide a default and 24the selection persists across closing and reopening a device, 25applications should always negotiate a data format before engaging in 26data exchange. Negotiation means the application asks for a particular 27format and the driver selects and reports the best the hardware can do 28to satisfy the request. Of course applications can also just query the 29current selection. 30 31A single mechanism exists to negotiate all data formats using the 32aggregate struct :c:type:`v4l2_format` and the 33:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 34:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the 35:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine 36what the hardware *could* do, without actually selecting a new data 37format. The data formats supported by the V4L2 API are covered in the 38respective device section in :ref:`devices`. For a closer look at 39image formats see :ref:`pixfmt`. 40 41The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the 42initialization sequence. Prior to this point multiple panel applications 43can access the same device concurrently to select the current input, 44change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 45assigns a logical stream (video data, VBI data etc.) exclusively to one 46file descriptor. 47 48Exclusive means no other application, more precisely no other file 49descriptor, can grab this stream or change device properties 50inconsistent with the negotiated parameters. A video standard change for 51example, when the new standard uses a different number of scan lines, 52can invalidate the selected image format. Therefore only the file 53descriptor owning the stream can make invalidating changes. Accordingly 54multiple file descriptors which grabbed different logical streams 55prevent each other from interfering with their settings. When for 56example video overlay is about to start or already in progress, 57simultaneous video capturing may be restricted to the same cropping and 58image size. 59 60When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side 61effects are implied by the next step, the selection of an I/O method 62with the :ref:`VIDIOC_REQBUFS` ioctl or implicit 63with the first :ref:`read() <func-read>` or 64:ref:`write() <func-write>` call. 65 66Generally only one logical stream can be assigned to a file descriptor, 67the exception being drivers permitting simultaneous video capturing and 68overlay using the same file descriptor for compatibility with V4L and 69earlier versions of V4L2. Switching the logical stream or returning into 70"panel mode" is possible by closing and reopening the device. Drivers 71*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. 72 73All drivers exchanging data with applications must support the 74:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the 75:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. 76 77 78Image Format Enumeration 79======================== 80 81Apart of the generic format negotiation functions a special ioctl to 82enumerate all image formats supported by video capture, overlay or 83output devices is available. [#f1]_ 84 85The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported 86by all drivers exchanging image data with applications. 87 88.. important:: 89 90 Drivers are not supposed to convert image formats in kernel space. 91 They must enumerate only formats directly supported by the hardware. 92 If necessary driver writers should publish an example conversion 93 routine or library for integration into applications. 94 95.. [#f1] 96 Enumerating formats an application has no a-priori knowledge of 97 (otherwise it could explicitly ask for them and need not enumerate) 98 seems useless, but there are applications serving as proxy between 99 drivers and the actual video applications for which this is useful. 100