]>
Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _format: | |
4 | ||
5 | ************ | |
6 | Data Formats | |
7 | ************ | |
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 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 :ref:`v4l2_format <v4l2-format>` and the | |
4e03cb76 | 26 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
af4a4d0d MCC |
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 | |
5377d91f MH |
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 | ||
2212ff25 | 34 | The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the |
5377d91f MH |
35 | initialization sequence. Prior to this point multiple panel applications |
36 | can access the same device concurrently to select the current input, | |
2212ff25 | 37 | change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
5377d91f MH |
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 | ||
2212ff25 | 53 | When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side |
5377d91f | 54 | effects are implied by the next step, the selection of an I/O method |
7347081e | 55 | with the :ref:`VIDIOC_REQBUFS` ioctl or implicit |
5377d91f MH |
56 | with the first :ref:`read() <func-read>` or |
57 | :ref:`write() <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 | |
2212ff25 | 64 | *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. |
5377d91f MH |
65 | |
66 | All drivers exchanging data with applications must support the | |
4e03cb76 | 67 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the |
2212ff25 | 68 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. |
5377d91f MH |
69 | |
70 | ||
71 | Image Format Enumeration | |
72 | ======================== | |
73 | ||
74 | Apart of the generic format negotiation functions a special ioctl to | |
75 | enumerate all image formats supported by video capture, overlay or | |
4855307b | 76 | output devices is available. [#f1]_ |
5377d91f | 77 | |
7347081e | 78 | The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported |
5377d91f MH |
79 | by all drivers exchanging image data with applications. |
80 | ||
81 | **Important** | |
82 | ||
83 | Drivers are not supposed to convert image formats in kernel space. | |
84 | They must enumerate only formats directly supported by the hardware. | |
85 | If necessary driver writers should publish an example conversion | |
86 | routine or library for integration into applications. | |
87 | ||
4855307b | 88 | .. [#f1] |
5377d91f MH |
89 | Enumerating formats an application has no a-priori knowledge of |
90 | (otherwise it could explicitly ask for them and need not enumerate) | |
91 | seems useless, but there are applications serving as proxy between | |
92 | drivers and the actual video applications for which this is useful. |