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