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