| 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. |