92 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _format:5 6************7Data Formats8************9 10Data Format Negotiation11=======================12 13Different devices exchange different kinds of data with applications,14for example video images, raw or sliced VBI data, RDS datagrams. Even15within one kind many different formats are possible, in particular there is an16abundance of image formats. Although drivers must provide a default and17the selection persists across closing and reopening a device,18applications should always negotiate a data format before engaging in19data exchange. Negotiation means the application asks for a particular20format and the driver selects and reports the best the hardware can do21to satisfy the request. Of course applications can also just query the22current selection.23 24A single mechanism exists to negotiate all data formats using the25aggregate struct :c:type:`v4l2_format` and the26:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and27:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the28:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine29what the hardware *could* do, without actually selecting a new data30format. The data formats supported by the V4L2 API are covered in the31respective device section in :ref:`devices`. For a closer look at32image formats see :ref:`pixfmt`.33 34The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the35initialization sequence. Prior to this point multiple panel applications36can access the same device concurrently to select the current input,37change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`38assigns a logical stream (video data, VBI data etc.) exclusively to one39file descriptor.40 41Exclusive means no other application, more precisely no other file42descriptor, can grab this stream or change device properties43inconsistent with the negotiated parameters. A video standard change for44example, when the new standard uses a different number of scan lines,45can invalidate the selected image format. Therefore only the file46descriptor owning the stream can make invalidating changes. Accordingly47multiple file descriptors which grabbed different logical streams48prevent each other from interfering with their settings. When for49example video overlay is about to start or already in progress,50simultaneous video capturing may be restricted to the same cropping and51image size.52 53When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side54effects are implied by the next step, the selection of an I/O method55with the :ref:`VIDIOC_REQBUFS` ioctl or implicit56with the first :c:func:`read()` or57:c:func:`write()` call.58 59Generally only one logical stream can be assigned to a file descriptor,60the exception being drivers permitting simultaneous video capturing and61overlay using the same file descriptor for compatibility with V4L and62earlier versions of V4L2. Switching the logical stream or returning into63"panel mode" is possible by closing and reopening the device. Drivers64*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.65 66All drivers exchanging data with applications must support the67:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the68:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.69 70Image Format Enumeration71========================72 73Apart of the generic format negotiation functions a special ioctl to74enumerate all image formats supported by video capture, overlay or75output devices is available. [#f1]_76 77The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported78by 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 conversion85 routine or library for integration into applications.86 87.. [#f1]88 Enumerating formats an application has no a-priori knowledge of89 (otherwise it could explicitly ask for them and need not enumerate)90 seems useless, but there are applications serving as proxy between91 drivers and the actual video applications for which this is useful.92