1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 1 .. Permission is granted to copy, distribute and/or modify this
2 .. c:namespace:: V4L !! 2 .. document under the terms of the GNU Free Documentation License,
>> 3 .. Version 1.1 or any later version published by the Free Software
>> 4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
>> 5 .. and no Back-Cover Texts. A copy of the license is included at
>> 6 .. Documentation/userspace-api/media/fdl-appendix.rst.
>> 7 ..
>> 8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
3 9
4 .. _format: 10 .. _format:
5 11
6 ************ 12 ************
7 Data Formats 13 Data Formats
8 ************ 14 ************
9 15
>> 16
10 Data Format Negotiation 17 Data Format Negotiation
11 ======================= 18 =======================
12 19
13 Different devices exchange different kinds of 20 Different devices exchange different kinds of data with applications,
14 for example video images, raw or sliced VBI da 21 for example video images, raw or sliced VBI data, RDS datagrams. Even
15 within one kind many different formats are pos 22 within one kind many different formats are possible, in particular there is an
16 abundance of image formats. Although drivers m 23 abundance of image formats. Although drivers must provide a default and
17 the selection persists across closing and reop 24 the selection persists across closing and reopening a device,
18 applications should always negotiate a data fo 25 applications should always negotiate a data format before engaging in
19 data exchange. Negotiation means the applicati 26 data exchange. Negotiation means the application asks for a particular
20 format and the driver selects and reports the 27 format and the driver selects and reports the best the hardware can do
21 to satisfy the request. Of course applications 28 to satisfy the request. Of course applications can also just query the
22 current selection. 29 current selection.
23 30
24 A single mechanism exists to negotiate all dat 31 A single mechanism exists to negotiate all data formats using the
25 aggregate struct :c:type:`v4l2_format` and the 32 aggregate struct :c:type:`v4l2_format` and the
26 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 33 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
27 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Add 34 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
28 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can 35 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
29 what the hardware *could* do, without actually 36 what the hardware *could* do, without actually selecting a new data
30 format. The data formats supported by the V4L2 37 format. The data formats supported by the V4L2 API are covered in the
31 respective device section in :ref:`devices`. F 38 respective device section in :ref:`devices`. For a closer look at
32 image formats see :ref:`pixfmt`. 39 image formats see :ref:`pixfmt`.
33 40
34 The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl i 41 The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
35 initialization sequence. Prior to this point m 42 initialization sequence. Prior to this point multiple panel applications
36 can access the same device concurrently to sel 43 can access the same device concurrently to select the current input,
37 change controls or modify other properties. Th 44 change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
38 assigns a logical stream (video data, VBI data 45 assigns a logical stream (video data, VBI data etc.) exclusively to one
39 file descriptor. 46 file descriptor.
40 47
41 Exclusive means no other application, more pre 48 Exclusive means no other application, more precisely no other file
42 descriptor, can grab this stream or change dev 49 descriptor, can grab this stream or change device properties
43 inconsistent with the negotiated parameters. A 50 inconsistent with the negotiated parameters. A video standard change for
44 example, when the new standard uses a differen 51 example, when the new standard uses a different number of scan lines,
45 can invalidate the selected image format. Ther 52 can invalidate the selected image format. Therefore only the file
46 descriptor owning the stream can make invalida 53 descriptor owning the stream can make invalidating changes. Accordingly
47 multiple file descriptors which grabbed differ 54 multiple file descriptors which grabbed different logical streams
48 prevent each other from interfering with their 55 prevent each other from interfering with their settings. When for
49 example video overlay is about to start or alr 56 example video overlay is about to start or already in progress,
50 simultaneous video capturing may be restricted 57 simultaneous video capturing may be restricted to the same cropping and
51 image size. 58 image size.
52 59
53 When applications omit the :ref:`VIDIOC_S_FMT 60 When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
54 effects are implied by the next step, the sele 61 effects are implied by the next step, the selection of an I/O method
55 with the :ref:`VIDIOC_REQBUFS` ioctl or implic 62 with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
56 with the first :c:func:`read()` or !! 63 with the first :ref:`read() <func-read>` or
57 :c:func:`write()` call. !! 64 :ref:`write() <func-write>` call.
58 65
59 Generally only one logical stream can be assig 66 Generally only one logical stream can be assigned to a file descriptor,
60 the exception being drivers permitting simulta 67 the exception being drivers permitting simultaneous video capturing and
61 overlay using the same file descriptor for com 68 overlay using the same file descriptor for compatibility with V4L and
62 earlier versions of V4L2. Switching the logica 69 earlier versions of V4L2. Switching the logical stream or returning into
63 "panel mode" is possible by closing and reopen 70 "panel mode" is possible by closing and reopening the device. Drivers
64 *may* support a switch using :ref:`VIDIOC_S_FM 71 *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
65 72
66 All drivers exchanging data with applications 73 All drivers exchanging data with applications must support the
67 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`V 74 :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 75 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
>> 76
69 77
70 Image Format Enumeration 78 Image Format Enumeration
71 ======================== 79 ========================
72 80
73 Apart of the generic format negotiation functi 81 Apart of the generic format negotiation functions a special ioctl to
74 enumerate all image formats supported by video 82 enumerate all image formats supported by video capture, overlay or
75 output devices is available. [#f1]_ 83 output devices is available. [#f1]_
76 84
77 The :ref:`VIDIOC_ENUM_FMT` ioctl must be suppo 85 The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
78 by all drivers exchanging image data with appl 86 by all drivers exchanging image data with applications.
79 87
80 .. important:: 88 .. important::
81 89
82 Drivers are not supposed to convert image 90 Drivers are not supposed to convert image formats in kernel space.
83 They must enumerate only formats directly 91 They must enumerate only formats directly supported by the hardware.
84 If necessary driver writers should publish 92 If necessary driver writers should publish an example conversion
85 routine or library for integration into ap 93 routine or library for integration into applications.
86 94
87 .. [#f1] 95 .. [#f1]
88 Enumerating formats an application has no a 96 Enumerating formats an application has no a-priori knowledge of
89 (otherwise it could explicitly ask for them 97 (otherwise it could explicitly ask for them and need not enumerate)
90 seems useless, but there are applications s 98 seems useless, but there are applications serving as proxy between
91 drivers and the actual video applications f 99 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.