1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _hist-v4l2: 4 .. _hist-v4l2:
5 5
6 *********************** 6 ***********************
7 Changes of the V4L2 API 7 Changes of the V4L2 API
8 *********************** 8 ***********************
9 9
10 Soon after the V4L API was added to the kernel 10 Soon after the V4L API was added to the kernel it was criticised as too
11 inflexible. In August 1998 Bill Dirks proposed 11 inflexible. In August 1998 Bill Dirks proposed a number of improvements
12 and began to work on documentation, example dr 12 and began to work on documentation, example drivers and applications.
13 With the help of other volunteers this eventua 13 With the help of other volunteers this eventually became the V4L2 API,
14 not just an extension but a replacement for th 14 not just an extension but a replacement for the V4L API. However it took
15 another four years and two stable kernel relea 15 another four years and two stable kernel releases until the new API was
16 finally accepted for inclusion into the kernel 16 finally accepted for inclusion into the kernel in its present form.
17 17
18 Early Versions 18 Early Versions
19 ============== 19 ==============
20 20
21 1998-08-20: First version. 21 1998-08-20: First version.
22 22
23 1998-08-27: The :c:func:`select()` function wa 23 1998-08-27: The :c:func:`select()` function was introduced.
24 24
25 1998-09-10: New video standard interface. 25 1998-09-10: New video standard interface.
26 26
27 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was re 27 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
28 meaningless ``O_TRUNC`` :c:func:`open()` flag, 28 meaningless ``O_TRUNC`` :c:func:`open()` flag, and the
29 aliases ``O_NONCAP`` and ``O_NOIO`` were defin 29 aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set
30 this flag if they intend to access controls on 30 this flag if they intend to access controls only, as opposed to capture
31 applications which need exclusive access. The 31 applications which need exclusive access. The ``VIDEO_STD_XXX``
32 identifiers are now ordinals instead of flags, 32 identifiers are now ordinals instead of flags, and the
33 ``video_std_construct()`` helper function take 33 ``video_std_construct()`` helper function takes id and
34 transmission arguments. 34 transmission arguments.
35 35
36 1998-09-28: Revamped video standard. Made vide 36 1998-09-28: Revamped video standard. Made video controls individually
37 enumerable. 37 enumerable.
38 38
39 1998-10-02: The ``id`` field was removed from 39 1998-10-02: The ``id`` field was removed from
40 struct ``video_standard`` and the color subcar 40 struct ``video_standard`` and the color subcarrier fields were
41 renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was 41 renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
42 renamed to :ref:`VIDIOC_ENUMSTD`, 42 renamed to :ref:`VIDIOC_ENUMSTD`,
43 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to 43 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to
44 :ref:`VIDIOC_ENUMINPUT`. A first draft of the 44 :ref:`VIDIOC_ENUMINPUT`. A first draft of the
45 Codec API was released. 45 Codec API was released.
46 46
47 1998-11-08: Many minor changes. Most symbols h 47 1998-11-08: Many minor changes. Most symbols have been renamed. Some
48 material changes to struct v4l2_capability. 48 material changes to struct v4l2_capability.
49 49
50 1998-11-12: The read/write direction of some i !! 50 1998-11-12: The read/write directon of some ioctls was misdefined.
51 51
52 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to 52 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``,
53 and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_P 53 and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio
54 controls are now accessible with the 54 controls are now accessible with the
55 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and 55 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
56 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls un 56 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting
57 with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` de 57 with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
58 ``videodev.h`` since it was only used once in 58 ``videodev.h`` since it was only used once in the ``videodev`` kernel
59 module. The ``YUV422`` and ``YUV411`` planar i 59 module. The ``YUV422`` and ``YUV411`` planar image formats were added.
60 60
61 1998-11-28: A few ioctl symbols changed. Inter 61 1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video
62 output devices were added. 62 output devices were added.
63 63
64 1999-01-14: A raw VBI capture interface was ad 64 1999-01-14: A raw VBI capture interface was added.
65 65
66 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was r 66 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
67 67
68 V4L2 Version 0.16 1999-01-31 68 V4L2 Version 0.16 1999-01-31
69 ============================ 69 ============================
70 70
71 1999-01-27: There is now one QBUF ioctl, VIDIO 71 1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
72 are gone. VIDIOC_QBUF takes a v4l2_buffer as a 72 are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
73 digital zoom (cropping) controls. 73 digital zoom (cropping) controls.
74 74
75 V4L2 Version 0.18 1999-03-16 75 V4L2 Version 0.18 1999-03-16
76 ============================ 76 ============================
77 77
78 Added a v4l to V4L2 ioctl compatibility layer 78 Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver
79 writers, this changes how you implement your i 79 writers, this changes how you implement your ioctl handler. See the
80 Driver Writer's Guide. Added some more control 80 Driver Writer's Guide. Added some more control id codes.
81 81
82 V4L2 Version 0.19 1999-06-05 82 V4L2 Version 0.19 1999-06-05
83 ============================ 83 ============================
84 84
85 1999-03-18: Fill in the category and catname f 85 1999-03-18: Fill in the category and catname fields of v4l2_queryctrl
86 objects before passing them to the driver. Req 86 objects before passing them to the driver. Required a minor change to
87 the VIDIOC_QUERYCTRL handlers in the sample dr 87 the VIDIOC_QUERYCTRL handlers in the sample drivers.
88 88
89 1999-03-31: Better compatibility for v4l memor 89 1999-03-31: Better compatibility for v4l memory capture ioctls. Requires
90 changes to drivers to fully support new compat 90 changes to drivers to fully support new compatibility features, see
91 Driver Writer's Guide and v4l2cap.c. Added new 91 Driver Writer's Guide and v4l2cap.c. Added new control IDs:
92 V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_Y 92 V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
93 and _YUV411P to _YUV411P. 93 and _YUV411P to _YUV411P.
94 94
95 1999-04-04: Added a few more control IDs. 95 1999-04-04: Added a few more control IDs.
96 96
97 1999-04-07: Added the button control type. 97 1999-04-07: Added the button control type.
98 98
99 1999-05-02: Fixed a typo in videodev.h, and ad 99 1999-05-02: Fixed a typo in videodev.h, and added the
100 V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GR 100 V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
101 101
102 1999-05-20: Definition of VIDIOC_G_CTRL was wr 102 1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a
103 malfunction of this ioctl. 103 malfunction of this ioctl.
104 104
105 1999-06-05: Changed the value of V4L2_CID_WHIT 105 1999-06-05: Changed the value of V4L2_CID_WHITENESS.
106 106
107 V4L2 Version 0.20 (1999-09-10) 107 V4L2 Version 0.20 (1999-09-10)
108 ============================== 108 ==============================
109 109
110 Version 0.20 introduced a number of changes wh 110 Version 0.20 introduced a number of changes which were *not backward
111 compatible* with 0.19 and earlier versions. Pu 111 compatible* with 0.19 and earlier versions. Purpose of these changes was
112 to simplify the API, while making it more exte 112 to simplify the API, while making it more extensible and following
113 common Linux driver API conventions. 113 common Linux driver API conventions.
114 114
115 1. Some typos in ``V4L2_FMT_FLAG`` symbols wer 115 1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct v4l2_clip
116 was changed for compatibility with v4l. (19 116 was changed for compatibility with v4l. (1999-08-30)
117 117
118 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-0 118 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
119 119
120 3. All ioctl() commands that used an integer a 120 3. All ioctl() commands that used an integer argument now take a pointer
121 to an integer. Where it makes sense, ioctls 121 to an integer. Where it makes sense, ioctls will return the actual
122 new value in the integer pointed to by the 122 new value in the integer pointed to by the argument, a common
123 convention in the V4L2 API. The affected io 123 convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW,
124 VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S 124 VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
125 VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_E 125 VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
126 126
127 .. code-block:: c 127 .. code-block:: c
128 128
129 err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); 129 err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
130 130
131 becomes 131 becomes
132 132
133 .. code-block:: c 133 .. code-block:: c
134 134
135 int a = V4L2_XXX; err = ioctl(fd, VIDIO 135 int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
136 136
137 4. All the different get- and set-format comma 137 4. All the different get- and set-format commands were swept into one
138 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 138 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
139 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl ta 139 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a
140 type field selecting the union member as pa 140 type field selecting the union member as parameter. Purpose is to
141 simplify the API by eliminating several ioc 141 simplify the API by eliminating several ioctls and to allow new and
142 driver private data streams without adding 142 driver private data streams without adding new ioctls.
143 143
144 This change obsoletes the following ioctls: 144 This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``,
145 ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, `` 145 ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``,
146 ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT`` 146 ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format
147 struct v4l2_format was renamed to struct v4 147 struct v4l2_format was renamed to struct v4l2_pix_format, while
148 struct v4l2_format is now the enveloping st !! 148 struct v4l2_format is now the envelopping structure
149 for all format negotiations. 149 for all format negotiations.
150 150
151 5. Similar to the changes above, the ``VIDIOC_ 151 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and
152 ``VIDIOC_S_PARM`` ioctls were merged with ` 152 ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and
153 ``VIDIOC_S_OUTPARM``. A ``type`` field in t 153 ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct v4l2_streamparm
154 selects the respective union member. 154 selects the respective union member.
155 155
156 This change obsoletes the ``VIDIOC_G_OUTPAR 156 This change obsoletes the ``VIDIOC_G_OUTPARM`` and
157 ``VIDIOC_S_OUTPARM`` ioctls. 157 ``VIDIOC_S_OUTPARM`` ioctls.
158 158
159 6. Control enumeration was simplified, and two 159 6. Control enumeration was simplified, and two new control flags were
160 introduced and one dropped. The ``catname`` 160 introduced and one dropped. The ``catname`` field was replaced by a
161 ``group`` field. 161 ``group`` field.
162 162
163 Drivers can now flag unsupported and tempor 163 Drivers can now flag unsupported and temporarily unavailable controls
164 with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2 164 with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED``
165 respectively. The ``group`` name indicates 165 respectively. The ``group`` name indicates a possibly narrower
166 classification than the ``category``. In ot 166 classification than the ``category``. In other words, there may be
167 multiple groups within a category. Controls 167 multiple groups within a category. Controls within a group would
168 typically be drawn within a group box. Cont 168 typically be drawn within a group box. Controls in different
169 categories might have a greater separation, 169 categories might have a greater separation, or may even appear in
170 separate windows. 170 separate windows.
171 171
172 7. The struct v4l2_buffer ``timestamp`` was 172 7. The struct v4l2_buffer ``timestamp`` was
173 changed to a 64 bit integer, containing the 173 changed to a 64 bit integer, containing the sampling or output time
174 of the frame in nanoseconds. Additionally t 174 of the frame in nanoseconds. Additionally timestamps will be in
175 absolute system time, not starting from zer 175 absolute system time, not starting from zero at the beginning of a
176 stream. The data type name for timestamps i 176 stream. The data type name for timestamps is stamp_t, defined as a
177 signed 64-bit integer. Output devices shoul 177 signed 64-bit integer. Output devices should not send a buffer out
178 until the time in the timestamp field has a 178 until the time in the timestamp field has arrived. I would like to
179 follow SGI's lead, and adopt a multimedia t 179 follow SGI's lead, and adopt a multimedia timestamping system like
180 their UST (Unadjusted System Time). See 180 their UST (Unadjusted System Time). See
181 http://web.archive.org/web/\*/http://realit 181 http://web.archive.org/web/\*/http://reality.sgi.com
182 /cpirazzi_engr/lg/time/intro.html. UST uses 182 /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are
183 64-bit signed integers (not struct timeval' 183 64-bit signed integers (not struct timeval's) and given in nanosecond
184 units. The UST clock starts at zero when th 184 units. The UST clock starts at zero when the system is booted and
185 runs continuously and uniformly. It takes a 185 runs continuously and uniformly. It takes a little over 292 years for
186 UST to overflow. There is no way to set the 186 UST to overflow. There is no way to set the UST clock. The regular
187 Linux time-of-day clock can be changed peri 187 Linux time-of-day clock can be changed periodically, which would
188 cause errors if it were being used for time 188 cause errors if it were being used for timestamping a multimedia
189 stream. A real UST style clock will require 189 stream. A real UST style clock will require some support in the
190 kernel that is not there yet. But in antici 190 kernel that is not there yet. But in anticipation, I will change the
191 timestamp field to a 64-bit integer, and I 191 timestamp field to a 64-bit integer, and I will change the
192 v4l2_masterclock_gettime() function (used o 192 v4l2_masterclock_gettime() function (used only by drivers) to
193 return a 64-bit integer. 193 return a 64-bit integer.
194 194
195 8. A ``sequence`` field was added to struct v4 195 8. A ``sequence`` field was added to struct v4l2_buffer. The ``sequence``
196 field counts captured frames, it is ignored 196 field counts captured frames, it is ignored by output devices. When a
197 capture driver drops a frame, the sequence 197 capture driver drops a frame, the sequence number of that frame is skipped.
198 198
199 V4L2 Version 0.20 incremental changes 199 V4L2 Version 0.20 incremental changes
200 ===================================== 200 =====================================
201 201
202 1999-12-23: In struct v4l2_vbi_format the 202 1999-12-23: In struct v4l2_vbi_format the
203 ``reserved1`` field became ``offset``. Previou 203 ``reserved1`` field became ``offset``. Previously drivers were required
204 to clear the ``reserved1`` field. 204 to clear the ``reserved1`` field.
205 205
206 2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED 206 2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added.
207 207
208 2000-07-31: The ``linux/poll.h`` header is now 208 2000-07-31: The ``linux/poll.h`` header is now included by
209 ``videodev.h`` for compatibility with the orig 209 ``videodev.h`` for compatibility with the original ``videodev.h`` file.
210 210
211 2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L 211 2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
212 added. 212 added.
213 213
214 2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added. 214 2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added.
215 215
216 2000-12-04: A couple typos in symbol names wer 216 2000-12-04: A couple typos in symbol names were fixed.
217 217
218 2001-01-18: To avoid namespace conflicts the ` 218 2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in
219 the ``videodev.h`` header file was renamed to 219 the ``videodev.h`` header file was renamed to ``v4l2_fourcc``.
220 220
221 2001-01-25: A possible driver-level compatibil 221 2001-01-25: A possible driver-level compatibility problem between the
222 ``videodev.h`` file in Linux 2.4.0 and the ``v 222 ``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included
223 in the ``videodevX`` patch was fixed. Users of 223 in the ``videodevX`` patch was fixed. Users of an earlier version of
224 ``videodevX`` on Linux 2.4.0 should recompile 224 ``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2
225 drivers. 225 drivers.
226 226
227 2001-01-26: A possible kernel-level incompatib 227 2001-01-26: A possible kernel-level incompatibility between the
228 ``videodev.h`` file in the ``videodevX`` patch 228 ``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h``
229 file in Linux 2.2.x with devfs patches applied 229 file in Linux 2.2.x with devfs patches applied was fixed.
230 230
231 2001-03-02: Certain V4L ioctls which pass data 231 2001-03-02: Certain V4L ioctls which pass data in both direction
232 although they are defined with read-only param 232 although they are defined with read-only parameter, did not work
233 correctly through the backward compatibility l 233 correctly through the backward compatibility layer. [Solution?]
234 234
235 2001-04-13: Big endian 16-bit RGB formats were 235 2001-04-13: Big endian 16-bit RGB formats were added.
236 236
237 2001-09-17: New YUV formats and the 237 2001-09-17: New YUV formats and the
238 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` 238 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
239 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` 239 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added.
240 (The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ 240 (The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
241 multiple tuners into account.) 241 multiple tuners into account.)
242 242
243 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. T 243 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
244 compatibility* as the :ref:`VIDIOC_G_FMT <VIDI 244 compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
245 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may 245 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the
246 struct ``v4l2_fmt`` ``type`` field does not co 246 struct ``v4l2_fmt`` ``type`` field does not contain
247 ``V4L2_BUF_TYPE_VBI``. In the documentation of 247 ``V4L2_BUF_TYPE_VBI``. In the documentation of the struct v4l2_vbi_format`,
248 the ``offset`` field the ambiguous phrase "ris 248 the ``offset`` field the ambiguous phrase "rising edge" was changed to
249 "leading edge". 249 "leading edge".
250 250
251 V4L2 Version 0.20 2000-11-23 251 V4L2 Version 0.20 2000-11-23
252 ============================ 252 ============================
253 253
254 A number of changes were made to the raw VBI i 254 A number of changes were made to the raw VBI interface.
255 255
256 1. Figures clarifying the line numbering schem 256 1. Figures clarifying the line numbering scheme were added to the V4L2
257 API specification. The ``start``\ [0] and ` 257 API specification. The ``start``\ [0] and ``start``\ [1] fields no
258 longer count line numbers beginning at zero 258 longer count line numbers beginning at zero. Rationale: a) The
259 previous definition was unclear. b) The ``s 259 previous definition was unclear. b) The ``start``\ [] values are
260 ordinal numbers. c) There is no point in in 260 ordinal numbers. c) There is no point in inventing a new line
261 numbering scheme. We now use line number as 261 numbering scheme. We now use line number as defined by ITU-R, period.
262 Compatibility: Add one to the start values. 262 Compatibility: Add one to the start values. Applications depending on
263 the previous semantics may not function cor 263 the previous semantics may not function correctly.
264 264
265 2. The restriction "count[0] > 0 and count[1] 265 2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
266 "(count[0] + count[1]) > 0". Rationale: Dri 266 "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
267 resources at scan line granularity and some 267 resources at scan line granularity and some data services are
268 transmitted only on the first field. The co 268 transmitted only on the first field. The comment that both ``count``
269 values will usually be equal is misleading 269 values will usually be equal is misleading and pointless and has been
270 removed. This change *breaks compatibility* 270 removed. This change *breaks compatibility* with earlier versions:
271 Drivers may return ``EINVAL``, applications 271 Drivers may return ``EINVAL``, applications may not function correctly.
272 272
273 3. Drivers are again permitted to return negat 273 3. Drivers are again permitted to return negative (unknown) start values
274 as proposed earlier. Why this feature was d 274 as proposed earlier. Why this feature was dropped is unclear. This
275 change may *break compatibility* with appli 275 change may *break compatibility* with applications depending on the
276 start values being positive. The use of ``E 276 start values being positive. The use of ``EBUSY`` and ``EINVAL``
277 error codes with the :ref:`VIDIOC_S_FMT <VI 277 error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was
278 clarified. The ``EBUSY`` error code was fin 278 clarified. The ``EBUSY`` error code was finally documented, and the
279 ``reserved2`` field which was previously me 279 ``reserved2`` field which was previously mentioned only in the
280 ``videodev.h`` header file. 280 ``videodev.h`` header file.
281 281
282 4. New buffer types ``V4L2_TYPE_VBI_INPUT`` an 282 4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT``
283 were added. The former is an alias for the 283 were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the
284 latter was missing in the ``videodev.h`` fi 284 latter was missing in the ``videodev.h`` file.
285 285
286 V4L2 Version 0.20 2002-07-25 286 V4L2 Version 0.20 2002-07-25
287 ============================ 287 ============================
288 288
289 Added sliced VBI interface proposal. 289 Added sliced VBI interface proposal.
290 290
291 V4L2 in Linux 2.5.46, 2002-10 291 V4L2 in Linux 2.5.46, 2002-10
292 ============================= 292 =============================
293 293
294 Around October-November 2002, prior to an anno 294 Around October-November 2002, prior to an announced feature freeze of
295 Linux 2.5, the API was revised, drawing from e 295 Linux 2.5, the API was revised, drawing from experience with V4L2 0.20.
296 This unnamed version was finally merged into L 296 This unnamed version was finally merged into Linux 2.5.46.
297 297
298 1. As specified in :ref:`related`, drivers mu 298 1. As specified in :ref:`related`, drivers must make related device
299 functions available under all minor device 299 functions available under all minor device numbers.
300 300
301 2. The :c:func:`open()` function requires acc 301 2. The :c:func:`open()` function requires access mode
302 ``O_RDWR`` regardless of the device type. 302 ``O_RDWR`` regardless of the device type. All V4L2 drivers
303 exchanging data with applications must sup 303 exchanging data with applications must support the ``O_NONBLOCK``
304 flag. The ``O_NOIO`` flag, a V4L2 symbol w 304 flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the
305 meaningless ``O_TRUNC`` to indicate access 305 meaningless ``O_TRUNC`` to indicate accesses without data exchange
306 (panel applications) was dropped. Drivers 306 (panel applications) was dropped. Drivers must stay in "panel mode"
307 until the application attempts to initiate 307 until the application attempts to initiate a data exchange, see
308 :ref:`open`. 308 :ref:`open`.
309 309
310 3. The struct v4l2_capability changed 310 3. The struct v4l2_capability changed
311 dramatically. Note that also the size of t 311 dramatically. Note that also the size of the structure changed,
312 which is encoded in the ioctl request code 312 which is encoded in the ioctl request code, thus older V4L2 devices
313 will respond with an ``EINVAL`` error code 313 will respond with an ``EINVAL`` error code to the new
314 :ref:`VIDIOC_QUERYCAP` ioctl. 314 :ref:`VIDIOC_QUERYCAP` ioctl.
315 315
316 There are new fields to identify the drive 316 There are new fields to identify the driver, a new RDS device
317 function ``V4L2_CAP_RDS_CAPTURE``, the ``V 317 function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag
318 indicates if the device has any audio conn 318 indicates if the device has any audio connectors, another I/O
319 capability V4L2_CAP_ASYNCIO can be flagged 319 capability V4L2_CAP_ASYNCIO can be flagged. In response to these
320 changes the ``type`` field became a bit se 320 changes the ``type`` field became a bit set and was merged into the
321 ``flags`` field. ``V4L2_FLAG_TUNER`` was r 321 ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to
322 ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERL 322 ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced
323 ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_C 323 ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
324 ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FL 324 ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
325 ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` 325 ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
326 ``V4L2_CAP_READWRITE``. 326 ``V4L2_CAP_READWRITE``.
327 327
328 The redundant fields ``inputs``, ``outputs 328 The redundant fields ``inputs``, ``outputs`` and ``audios`` were
329 removed. These properties can be determine 329 removed. These properties can be determined as described in
330 :ref:`video` and :ref:`audio`. 330 :ref:`video` and :ref:`audio`.
331 331
332 The somewhat volatile and therefore barely 332 The somewhat volatile and therefore barely useful fields
333 ``maxwidth``, ``maxheight``, ``minwidth``, 333 ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
334 ``maxframerate`` were removed. This inform 334 ``maxframerate`` were removed. This information is available as
335 described in :ref:`format` and :ref:`stand 335 described in :ref:`format` and :ref:`standard`.
336 336
337 ``V4L2_FLAG_SELECT`` was removed. We belie 337 ``V4L2_FLAG_SELECT`` was removed. We believe the select() function
338 is important enough to require support of 338 is important enough to require support of it in all V4L2 drivers
339 exchanging data with applications. The red 339 exchanging data with applications. The redundant
340 ``V4L2_FLAG_MONOCHROME`` flag was removed, 340 ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
341 available as described in :ref:`format`. 341 available as described in :ref:`format`.
342 342
343 4. In struct v4l2_input the ``assoc_audio`` 343 4. In struct v4l2_input the ``assoc_audio``
344 field and the ``capability`` field and its 344 field and the ``capability`` field and its only flag
345 ``V4L2_INPUT_CAP_AUDIO`` was replaced by t 345 ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field.
346 Instead of linking one video input to one 346 Instead of linking one video input to one audio input this field
347 reports all audio inputs this video input 347 reports all audio inputs this video input combines with.
348 348
349 New fields are ``tuner`` (reversing the fo 349 New fields are ``tuner`` (reversing the former link from tuners to
350 video inputs), ``std`` and ``status``. 350 video inputs), ``std`` and ``status``.
351 351
352 Accordingly struct v4l2_output lost its 352 Accordingly struct v4l2_output lost its
353 ``capability`` and ``assoc_audio`` fields. 353 ``capability`` and ``assoc_audio`` fields. ``audioset``,
354 ``modulator`` and ``std`` where added inst 354 ``modulator`` and ``std`` where added instead.
355 355
356 5. The struct v4l2_audio field ``audio`` was 356 5. The struct v4l2_audio field ``audio`` was
357 renamed to ``index``, for consistency with 357 renamed to ``index``, for consistency with other structures. A new
358 capability flag ``V4L2_AUDCAP_STEREO`` was 358 capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the
359 audio input in question supports stereo so 359 audio input in question supports stereo sound.
360 ``V4L2_AUDCAP_EFFECTS`` and the correspond 360 ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags
361 where removed. This can be easily implemen 361 where removed. This can be easily implemented using controls.
362 (However the same applies to AVL which is 362 (However the same applies to AVL which is still there.)
363 363
364 Again for consistency the struct v4l2_audi 364 Again for consistency the struct v4l2_audioout field ``audio`` was renamed
365 to ``index``. 365 to ``index``.
366 366
367 6. The struct v4l2_tuner ``input`` field was 367 6. The struct v4l2_tuner ``input`` field was
368 replaced by an ``index`` field, permitting 368 replaced by an ``index`` field, permitting devices with multiple
369 tuners. The link between video inputs and 369 tuners. The link between video inputs and tuners is now reversed,
370 inputs point to their tuner. The ``std`` s 370 inputs point to their tuner. The ``std`` substructure became a
371 simple set (more about this below) and mov 371 simple set (more about this below) and moved into struct v4l2_input.
372 A ``type`` field was added. 372 A ``type`` field was added.
373 373
374 Accordingly in struct v4l2_modulator the 374 Accordingly in struct v4l2_modulator the
375 ``output`` was replaced by an ``index`` fi 375 ``output`` was replaced by an ``index`` field.
376 376
377 In struct v4l2_frequency the ``port`` 377 In struct v4l2_frequency the ``port``
378 field was replaced by a ``tuner`` field co 378 field was replaced by a ``tuner`` field containing the respective
379 tuner or modulator index number. A tuner ` 379 tuner or modulator index number. A tuner ``type`` field was added
380 and the ``reserved`` field became larger f 380 and the ``reserved`` field became larger for future extensions
381 (satellite tuners in particular). 381 (satellite tuners in particular).
382 382
383 7. The idea of completely transparent video s 383 7. The idea of completely transparent video standards was dropped.
384 Experience showed that applications must b 384 Experience showed that applications must be able to work with video
385 standards beyond presenting the user a men 385 standards beyond presenting the user a menu. Instead of enumerating
386 supported standards with an ioctl applicat 386 supported standards with an ioctl applications can now refer to
387 standards by :ref:`v4l2_std_id <v4l2-std-i 387 standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols
388 defined in the ``videodev2.h`` header file 388 defined in the ``videodev2.h`` header file. For details see
389 :ref:`standard`. The :ref:`VIDIOC_G_STD <V 389 :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
390 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now tak 390 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this
391 type as argument. :ref:`VIDIOC_QUERYSTD` w 391 type as argument. :ref:`VIDIOC_QUERYSTD` was
392 added to autodetect the received standard, 392 added to autodetect the received standard, if the hardware has this
393 capability. In struct v4l2_standard an 393 capability. In struct v4l2_standard an
394 ``index`` field was added for 394 ``index`` field was added for
395 :ref:`VIDIOC_ENUMSTD`. A 395 :ref:`VIDIOC_ENUMSTD`. A
396 :ref:`v4l2_std_id <v4l2-std-id>` field nam 396 :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
397 machine readable identifier, also replacin 397 machine readable identifier, also replacing the ``transmission``
398 field. The misleading ``framerate`` field 398 field. The misleading ``framerate`` field was renamed to
399 ``frameperiod``. The now obsolete ``colors 399 ``frameperiod``. The now obsolete ``colorstandard`` information,
400 originally needed to distguish between var 400 originally needed to distguish between variations of standards, were
401 removed. 401 removed.
402 402
403 Struct ``v4l2_enumstd`` ceased to be. 403 Struct ``v4l2_enumstd`` ceased to be.
404 :ref:`VIDIOC_ENUMSTD` now takes a pointer 404 :ref:`VIDIOC_ENUMSTD` now takes a pointer to a
405 struct v4l2_standard directly. The 405 struct v4l2_standard directly. The
406 information which standards are supported 406 information which standards are supported by a particular video
407 input or output moved into struct v4l2_inp 407 input or output moved into struct v4l2_input
408 and struct v4l2_output fields named ``std` 408 and struct v4l2_output fields named ``std``,
409 respectively. 409 respectively.
410 410
411 8. The struct :ref:`v4l2_queryctrl <v4l2-quer 411 8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
412 ``category`` and ``group`` did not catch o 412 ``category`` and ``group`` did not catch on and/or were not
413 implemented as expected and therefore remo 413 implemented as expected and therefore removed.
414 414
415 9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` i 415 9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to
416 negotiate data formats as with 416 negotiate data formats as with
417 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but wi 417 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of
418 programming the hardware and regardless of 418 programming the hardware and regardless of I/O in progress.
419 419
420 In struct v4l2_format the ``fmt`` union wa 420 In struct v4l2_format the ``fmt`` union was
421 extended to contain struct v4l2_window. Al 421 extended to contain struct v4l2_window. All
422 image format negotiations are now possible 422 image format negotiations are now possible with ``VIDIOC_G_FMT``,
423 ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; i 423 ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN``
424 and ``VIDIOC_S_WIN`` ioctls to prepare for 424 and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were
425 removed. The ``type`` field changed to typ 425 removed. The ``type`` field changed to type enum v4l2_buf_type and
426 the buffer type names changed as follows. 426 the buffer type names changed as follows.
427 427
428 428
429 .. flat-table:: 429 .. flat-table::
430 :header-rows: 1 430 :header-rows: 1
431 :stub-columns: 0 431 :stub-columns: 0
432 432
433 * - Old defines 433 * - Old defines
434 - enum v4l2_buf_type 434 - enum v4l2_buf_type
435 * - ``V4L2_BUF_TYPE_CAPTURE`` 435 * - ``V4L2_BUF_TYPE_CAPTURE``
436 - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` 436 - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
437 * - ``V4L2_BUF_TYPE_CODECIN`` 437 * - ``V4L2_BUF_TYPE_CODECIN``
438 - Omitted for now 438 - Omitted for now
439 * - ``V4L2_BUF_TYPE_CODECOUT`` 439 * - ``V4L2_BUF_TYPE_CODECOUT``
440 - Omitted for now 440 - Omitted for now
441 * - ``V4L2_BUF_TYPE_EFFECTSIN`` 441 * - ``V4L2_BUF_TYPE_EFFECTSIN``
442 - Omitted for now 442 - Omitted for now
443 * - ``V4L2_BUF_TYPE_EFFECTSIN2`` 443 * - ``V4L2_BUF_TYPE_EFFECTSIN2``
444 - Omitted for now 444 - Omitted for now
445 * - ``V4L2_BUF_TYPE_EFFECTSOUT`` 445 * - ``V4L2_BUF_TYPE_EFFECTSOUT``
446 - Omitted for now 446 - Omitted for now
447 * - ``V4L2_BUF_TYPE_VIDEOOUT`` 447 * - ``V4L2_BUF_TYPE_VIDEOOUT``
448 - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` 448 - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
449 * - ``-`` 449 * - ``-``
450 - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` 450 - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
451 * - ``-`` 451 * - ``-``
452 - ``V4L2_BUF_TYPE_VBI_CAPTURE`` 452 - ``V4L2_BUF_TYPE_VBI_CAPTURE``
453 * - ``-`` 453 * - ``-``
454 - ``V4L2_BUF_TYPE_VBI_OUTPUT`` 454 - ``V4L2_BUF_TYPE_VBI_OUTPUT``
455 * - ``-`` 455 * - ``-``
456 - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE 456 - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
457 * - ``-`` 457 * - ``-``
458 - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT` 458 - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
459 * - ``V4L2_BUF_TYPE_PRIVATE_BASE`` 459 * - ``V4L2_BUF_TYPE_PRIVATE_BASE``
460 - ``V4L2_BUF_TYPE_PRIVATE`` (but thi 460 - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
461 461
462 10. In struct v4l2_fmtdesc a enum v4l2_buf_typ 462 10. In struct v4l2_fmtdesc a enum v4l2_buf_type field named ``type`` was
463 added as in struct v4l2_format. The ``VIDI 463 added as in struct v4l2_format. The ``VIDIOC_ENUM_FBUFFMT`` ioctl is no
464 longer needed and was removed. These calls 464 longer needed and was removed. These calls can be replaced by
465 :ref:`VIDIOC_ENUM_FMT` with type ``V4L2_BU 465 :ref:`VIDIOC_ENUM_FMT` with type ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
466 466
467 11. In struct v4l2_pix_format the ``depth`` 467 11. In struct v4l2_pix_format the ``depth``
468 field was removed, assuming applications w 468 field was removed, assuming applications which recognize the format
469 by its four-character-code already know th 469 by its four-character-code already know the color depth, and others
470 do not care about it. The same rationale l 470 do not care about it. The same rationale lead to the removal of the
471 ``V4L2_FMT_FLAG_COMPRESSED`` flag. The 471 ``V4L2_FMT_FLAG_COMPRESSED`` flag. The
472 ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag w 472 ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers
473 are not supposed to convert images in kern 473 are not supposed to convert images in kernel space. A user library
474 of conversion functions should be provided 474 of conversion functions should be provided instead. The
475 ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was re 475 ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can
476 set the ``bytesperline`` field to zero to 476 set the ``bytesperline`` field to zero to get a reasonable default.
477 Since the remaining flags were replaced as 477 Since the remaining flags were replaced as well, the ``flags`` field
478 itself was removed. 478 itself was removed.
479 479
480 The interlace flags were replaced by a enu 480 The interlace flags were replaced by a enum v4l2_field value in a
481 newly added ``field`` field. 481 newly added ``field`` field.
482 482
483 .. flat-table:: 483 .. flat-table::
484 :header-rows: 1 484 :header-rows: 1
485 :stub-columns: 0 485 :stub-columns: 0
486 486
487 * - Old flag 487 * - Old flag
488 - enum v4l2_field 488 - enum v4l2_field
489 * - ``V4L2_FMT_FLAG_NOT_INTERLACED`` 489 * - ``V4L2_FMT_FLAG_NOT_INTERLACED``
490 - ? 490 - ?
491 * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V 491 * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
492 - ``V4L2_FIELD_INTERLACED`` 492 - ``V4L2_FIELD_INTERLACED``
493 * - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L 493 * - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
494 - ``V4L2_FIELD_TOP`` 494 - ``V4L2_FIELD_TOP``
495 * - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L 495 * - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
496 - ``V4L2_FIELD_BOTTOM`` 496 - ``V4L2_FIELD_BOTTOM``
497 * - ``-`` 497 * - ``-``
498 - ``V4L2_FIELD_SEQ_TB`` 498 - ``V4L2_FIELD_SEQ_TB``
499 * - ``-`` 499 * - ``-``
500 - ``V4L2_FIELD_SEQ_BT`` 500 - ``V4L2_FIELD_SEQ_BT``
501 * - ``-`` 501 * - ``-``
502 - ``V4L2_FIELD_ALTERNATE`` 502 - ``V4L2_FIELD_ALTERNATE``
503 503
504 The color space flags were replaced by a e 504 The color space flags were replaced by a enum v4l2_colorspace value in
505 a newly added ``colorspace`` field, where 505 a newly added ``colorspace`` field, where one of
506 ``V4L2_COLORSPACE_SMPTE170M``, ``V4L2_COLO 506 ``V4L2_COLORSPACE_SMPTE170M``, ``V4L2_COLORSPACE_BT878``,
507 ``V4L2_COLORSPACE_470_SYSTEM_M`` or 507 ``V4L2_COLORSPACE_470_SYSTEM_M`` or
508 ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces 508 ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``.
509 509
510 12. In struct v4l2_requestbuffers the 510 12. In struct v4l2_requestbuffers the
511 ``type`` field was properly defined as enu 511 ``type`` field was properly defined as enum v4l2_buf_type. Buffer types
512 changed as mentioned above. A new ``memory 512 changed as mentioned above. A new ``memory`` field of type
513 enum v4l2_memory was added to distinguish 513 enum v4l2_memory was added to distinguish between
514 I/O methods using buffers allocated by the 514 I/O methods using buffers allocated by the driver or the
515 application. See :ref:`io` for details. 515 application. See :ref:`io` for details.
516 516
517 13. In struct v4l2_buffer the ``type`` field w 517 13. In struct v4l2_buffer the ``type`` field was
518 properly defined as enum v4l2_buf_type. 518 properly defined as enum v4l2_buf_type.
519 Buffer types changed as mentioned above. A 519 Buffer types changed as mentioned above. A ``field`` field of type
520 enum v4l2_field was added to indicate if a 520 enum v4l2_field was added to indicate if a
521 buffer contains a top or bottom field. The 521 buffer contains a top or bottom field. The old field flags were
522 removed. Since no unadjusted system time c 522 removed. Since no unadjusted system time clock was added to the
523 kernel as planned, the ``timestamp`` field 523 kernel as planned, the ``timestamp`` field changed back from type
524 stamp_t, an unsigned 64 bit integer expres 524 stamp_t, an unsigned 64 bit integer expressing the sample time in
525 nanoseconds, to struct timeval. With the a 525 nanoseconds, to struct timeval. With the addition
526 of a second memory mapping method the ``of 526 of a second memory mapping method the ``offset`` field moved into
527 union ``m``, and a new ``memory`` field of 527 union ``m``, and a new ``memory`` field of type enum v4l2_memory
528 was added to distinguish between 528 was added to distinguish between
529 I/O methods. See :ref:`io` for details. 529 I/O methods. See :ref:`io` for details.
530 530
531 The ``V4L2_BUF_REQ_CONTIG`` flag was used 531 The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility
532 layer, after changes to this code it was n 532 layer, after changes to this code it was no longer needed. The
533 ``V4L2_BUF_ATTR_DEVICEMEM`` flag would ind 533 ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was
534 indeed allocated in device memory rather t 534 indeed allocated in device memory rather than DMA-able system
535 memory. It was barely useful and so was re 535 memory. It was barely useful and so was removed.
536 536
537 14. In struct v4l2_framebuffer the 537 14. In struct v4l2_framebuffer the
538 ``base[3]`` array anticipating double- and 538 ``base[3]`` array anticipating double- and triple-buffering in
539 off-screen video memory, however without d 539 off-screen video memory, however without defining a synchronization
540 mechanism, was replaced by a single pointe 540 mechanism, was replaced by a single pointer. The
541 ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_ 541 ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were
542 removed. Applications can determine this c 542 removed. Applications can determine this capability more accurately
543 using the new cropping and scaling interfa 543 using the new cropping and scaling interface. The
544 ``V4L2_FBUF_CAP_CLIPPING`` flag was replac 544 ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by
545 ``V4L2_FBUF_CAP_LIST_CLIPPING`` and 545 ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
546 ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. 546 ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
547 547
548 15. In struct v4l2_clip the ``x``, ``y``, 548 15. In struct v4l2_clip the ``x``, ``y``,
549 ``width`` and ``height`` field moved into 549 ``width`` and ``height`` field moved into a ``c`` substructure of
550 type struct v4l2_rect. The ``x`` and ``y`` 550 type struct v4l2_rect. The ``x`` and ``y``
551 fields were renamed to ``left`` and ``top` 551 fields were renamed to ``left`` and ``top``, i. e. offsets to a
552 context dependent origin. 552 context dependent origin.
553 553
554 16. In struct v4l2_window the ``x``, ``y``, 554 16. In struct v4l2_window the ``x``, ``y``,
555 ``width`` and ``height`` field moved into 555 ``width`` and ``height`` field moved into a ``w`` substructure as
556 above. A ``field`` field of type enum v4l2 556 above. A ``field`` field of type enum v4l2_field was added to
557 distinguish between field and frame (inter 557 distinguish between field and frame (interlaced) overlay.
558 558
559 17. The digital zoom interface, including stru 559 17. The digital zoom interface, including struct ``v4l2_zoomcap``,
560 struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` 560 struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` and
561 ``V4L2_ZOOM_WHILESTREAMING`` was replaced 561 ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
562 scaling interface. The previously unused 562 scaling interface. The previously unused
563 struct v4l2_cropcap and struct v4l2_crop 563 struct v4l2_cropcap and struct v4l2_crop
564 where redefined for this purpose. See :ref 564 where redefined for this purpose. See :ref:`crop` for details.
565 565
566 18. In struct v4l2_vbi_format the 566 18. In struct v4l2_vbi_format the
567 ``SAMPLE_FORMAT`` field now contains a fou 567 ``SAMPLE_FORMAT`` field now contains a four-character-code as used
568 to identify video image formats and ``V4L2 568 to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces
569 the ``V4L2_VBI_SF_UBYTE`` define. The ``re 569 the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was
570 extended. 570 extended.
571 571
572 19. In struct v4l2_captureparm the type of 572 19. In struct v4l2_captureparm the type of
573 the ``timeperframe`` field changed from un 573 the ``timeperframe`` field changed from unsigned long to
574 struct v4l2_fract. This allows the accurat 574 struct v4l2_fract. This allows the accurate
575 expression of multiples of the NTSC-M fram 575 expression of multiples of the NTSC-M frame rate 30000 / 1001. A new
576 field ``readbuffers`` was added to control 576 field ``readbuffers`` was added to control the driver behaviour in
577 read I/O mode. 577 read I/O mode.
578 578
579 Similar changes were made to struct v4l2_o 579 Similar changes were made to struct v4l2_outputparm.
580 580
581 20. The struct ``v4l2_performance`` and 581 20. The struct ``v4l2_performance`` and
582 ``VIDIOC_G_PERF`` ioctl were dropped. Exce 582 ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
583 :ref:`read/write I/O method <rw>`, which i 583 :ref:`read/write I/O method <rw>`, which is limited anyway, this
584 information is already available to applic 584 information is already available to applications.
585 585
586 21. The example transformation from RGB to YCb 586 21. The example transformation from RGB to YCbCr color space in the old
587 V4L2 documentation was inaccurate, this ha 587 V4L2 documentation was inaccurate, this has been corrected in
588 :ref:`pixfmt`. 588 :ref:`pixfmt`.
589 589
590 V4L2 2003-06-19 590 V4L2 2003-06-19
591 =============== 591 ===============
592 592
593 1. A new capability flag ``V4L2_CAP_RADIO`` wa 593 1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices.
594 Prior to this change radio devices would id 594 Prior to this change radio devices would identify solely by having
595 exactly one tuner whose type field reads `` 595 exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``.
596 596
597 2. An optional driver access priority mechanis 597 2. An optional driver access priority mechanism was added, see
598 :ref:`app-pri` for details. 598 :ref:`app-pri` for details.
599 599
600 3. The audio input and output interface was fo 600 3. The audio input and output interface was found to be incomplete.
601 601
602 Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC 602 Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would
603 enumerate the available audio inputs. An io 603 enumerate the available audio inputs. An ioctl to determine the
604 current audio input, if more than one combi 604 current audio input, if more than one combines with the current video
605 input, did not exist. So ``VIDIOC_G_AUDIO`` 605 input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to
606 ``VIDIOC_G_AUDIO_OLD``, this ioctl was remo 606 ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The
607 :ref:`VIDIOC_ENUMAUDIO` ioctl was added to 607 :ref:`VIDIOC_ENUMAUDIO` ioctl was added to
608 enumerate audio inputs, while 608 enumerate audio inputs, while
609 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now 609 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current
610 audio input. 610 audio input.
611 611
612 The same changes were made to 612 The same changes were made to
613 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` an 613 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and
614 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT> 614 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`.
615 615
616 Until further the "videodev" module will au 616 Until further the "videodev" module will automatically translate
617 between the old and new ioctls, but drivers 617 between the old and new ioctls, but drivers and applications must be
618 updated to successfully compile again. 618 updated to successfully compile again.
619 619
620 4. The :ref:`VIDIOC_OVERLAY` ioctl was incorre 620 4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly
621 defined with write-read parameter. It was c 621 defined with write-read parameter. It was changed to write-only,
622 while the write-read version was renamed to 622 while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``.
623 The old ioctl was removed on Kernel 2.6.39. 623 The old ioctl was removed on Kernel 2.6.39. Until further the
624 "videodev" kernel module will automatically 624 "videodev" kernel module will automatically translate to the new
625 version, so drivers must be recompiled, but 625 version, so drivers must be recompiled, but not applications.
626 626
627 5. :ref:`overlay` incorrectly stated that clip 627 5. :ref:`overlay` incorrectly stated that clipping rectangles define
628 regions where the video can be seen. Correc 628 regions where the video can be seen. Correct is that clipping
629 rectangles define regions where *no* video 629 rectangles define regions where *no* video shall be displayed and so
630 the graphics surface can be seen. 630 the graphics surface can be seen.
631 631
632 6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` an 632 6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and
633 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls 633 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with
634 write-only parameter, inconsistent with oth 634 write-only parameter, inconsistent with other ioctls modifying their
635 argument. They were changed to write-read, 635 argument. They were changed to write-read, while a ``_OLD`` suffix
636 was added to the write-only versions. The o 636 was added to the write-only versions. The old ioctls were removed on
637 Kernel 2.6.39. Drivers and applications ass 637 Kernel 2.6.39. Drivers and applications assuming a constant parameter
638 need an update. 638 need an update.
639 639
640 V4L2 2003-11-05 640 V4L2 2003-11-05
641 =============== 641 ===============
642 642
643 1. In :ref:`pixfmt-rgb` the following pixel fo 643 1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
644 transferred from Bill Dirks' V4L2 specifica 644 transferred from Bill Dirks' V4L2 specification. Descriptions below
645 refer to bytes in memory, in ascending addr 645 refer to bytes in memory, in ascending address order.
646 646
647 647
648 .. flat-table:: 648 .. flat-table::
649 :header-rows: 1 649 :header-rows: 1
650 :stub-columns: 0 650 :stub-columns: 0
651 651
652 * - Symbol 652 * - Symbol
653 - In this document prior to revision 653 - In this document prior to revision 0.5
654 - Corrected 654 - Corrected
655 * - ``V4L2_PIX_FMT_RGB24`` 655 * - ``V4L2_PIX_FMT_RGB24``
656 - B, G, R 656 - B, G, R
657 - R, G, B 657 - R, G, B
658 * - ``V4L2_PIX_FMT_BGR24`` 658 * - ``V4L2_PIX_FMT_BGR24``
659 - R, G, B 659 - R, G, B
660 - B, G, R 660 - B, G, R
661 * - ``V4L2_PIX_FMT_RGB32`` 661 * - ``V4L2_PIX_FMT_RGB32``
662 - B, G, R, X 662 - B, G, R, X
663 - R, G, B, X 663 - R, G, B, X
664 * - ``V4L2_PIX_FMT_BGR32`` 664 * - ``V4L2_PIX_FMT_BGR32``
665 - R, G, B, X 665 - R, G, B, X
666 - B, G, R, X 666 - B, G, R, X
667 667
668 The ``V4L2_PIX_FMT_BGR24`` example was alwa 668 The ``V4L2_PIX_FMT_BGR24`` example was always correct.
669 669
670 In :ref:`v4l-image-properties` the mapping 670 In :ref:`v4l-image-properties` the mapping of the V4L
671 ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE 671 ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
672 pixel formats was accordingly corrected. 672 pixel formats was accordingly corrected.
673 673
674 2. Unrelated to the fixes above, drivers may s 674 2. Unrelated to the fixes above, drivers may still interpret some V4L2
675 RGB pixel formats differently. These issues 675 RGB pixel formats differently. These issues have yet to be addressed,
676 for details see :ref:`pixfmt-rgb`. 676 for details see :ref:`pixfmt-rgb`.
677 677
678 V4L2 in Linux 2.6.6, 2004-05-09 678 V4L2 in Linux 2.6.6, 2004-05-09
679 =============================== 679 ===============================
680 680
681 1. The :ref:`VIDIOC_CROPCAP` ioctl was incorre 681 1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly
682 defined with read-only parameter. It is now 682 defined with read-only parameter. It is now defined as write-read
683 ioctl, while the read-only version was rena 683 ioctl, while the read-only version was renamed to
684 ``VIDIOC_CROPCAP_OLD``. The old ioctl was r 684 ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39.
685 685
686 V4L2 in Linux 2.6.8 686 V4L2 in Linux 2.6.8
687 =================== 687 ===================
688 688
689 1. A new field ``input`` (former ``reserved[0] 689 1. A new field ``input`` (former ``reserved[0]``) was added to the
690 struct v4l2_buffer. Purpose of this 690 struct v4l2_buffer. Purpose of this
691 field is to alternate between video inputs 691 field is to alternate between video inputs (e. g. cameras) in step
692 with the video capturing process. This func 692 with the video capturing process. This function must be enabled with
693 the new ``V4L2_BUF_FLAG_INPUT`` flag. The ` 693 the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
694 longer read-only. 694 longer read-only.
695 695
696 V4L2 spec erratum 2004-08-01 696 V4L2 spec erratum 2004-08-01
697 ============================ 697 ============================
698 698
699 1. The return value of the :ref:`func-open` fu 699 1. The return value of the :ref:`func-open` function was incorrectly
700 documented. 700 documented.
701 701
702 2. Audio output ioctls end in -AUDOUT, not -AU 702 2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
703 703
704 3. In the Current Audio Input example the ``VI 704 3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
705 the wrong argument. 705 the wrong argument.
706 706
707 4. The documentation of the :ref:`VIDIOC_QBUF` 707 4. The documentation of the :ref:`VIDIOC_QBUF` and
708 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls di 708 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the
709 struct v4l2_buffer ``memory`` field. It was 709 struct v4l2_buffer ``memory`` field. It was
710 also missing from examples. Also on the ``V 710 also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
711 error code was not documented. 711 error code was not documented.
712 712
713 V4L2 in Linux 2.6.14 713 V4L2 in Linux 2.6.14
714 ==================== 714 ====================
715 715
716 1. A new sliced VBI interface was added. It is 716 1. A new sliced VBI interface was added. It is documented in
717 :ref:`sliced` and replaces the interface fi 717 :ref:`sliced` and replaces the interface first proposed in V4L2
718 specification 0.8. 718 specification 0.8.
719 719
720 V4L2 in Linux 2.6.15 720 V4L2 in Linux 2.6.15
721 ==================== 721 ====================
722 722
723 1. The :ref:`VIDIOC_LOG_STATUS` ioctl was adde 723 1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added.
724 724
725 2. New video standards ``V4L2_STD_NTSC_443``, 725 2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
726 ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K 726 ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
727 ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC 727 ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
728 ``V4L2_STD_ATSC_16_VSB``) were defined. Not 728 ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
729 set now includes ``V4L2_STD_NTSC_443``. See 729 set now includes ``V4L2_STD_NTSC_443``. See also
730 :ref:`v4l2-std-id`. 730 :ref:`v4l2-std-id`.
731 731
732 3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` 732 3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
733 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCO 733 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
734 argument was replaced by a struct 734 argument was replaced by a struct
735 ``v4l2_mpeg_compression`` pointer. (The 735 ``v4l2_mpeg_compression`` pointer. (The
736 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCO 736 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
737 in Linux 2.6.25.) 737 in Linux 2.6.25.)
738 738
739 V4L2 spec erratum 2005-11-27 739 V4L2 spec erratum 2005-11-27
740 ============================ 740 ============================
741 741
742 The capture example in :ref:`capture-example` 742 The capture example in :ref:`capture-example` called the
743 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl wit 743 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if
744 cropping is supported. In the video standard s 744 cropping is supported. In the video standard selection example in
745 :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC 745 :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
746 the wrong argument type. 746 the wrong argument type.
747 747
748 V4L2 spec erratum 2006-01-10 748 V4L2 spec erratum 2006-01-10
749 ============================ 749 ============================
750 750
751 1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struc 751 1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct v4l2_input not only
752 indicates if the color killer is enabled, b 752 indicates if the color killer is enabled, but also if it is active.
753 (The color killer disables color decoding w 753 (The color killer disables color decoding when it detects no color
754 in the video signal to improve the image qu 754 in the video signal to improve the image quality.)
755 755
756 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a w 756 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not
757 write-only as stated on its reference page. 757 write-only as stated on its reference page. The ioctl changed in 2003
758 as noted above. 758 as noted above.
759 759
760 V4L2 spec erratum 2006-02-03 760 V4L2 spec erratum 2006-02-03
761 ============================ 761 ============================
762 762
763 1. In struct v4l2_captureparm and struct v4l2_ 763 1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe``
764 field gives the time in seconds, not micros 764 field gives the time in seconds, not microseconds.
765 765
766 V4L2 spec erratum 2006-02-04 766 V4L2 spec erratum 2006-02-04
767 ============================ 767 ============================
768 768
769 1. The ``clips`` field in struct v4l2_window 769 1. The ``clips`` field in struct v4l2_window
770 must point to an array of struct v4l2_clip, 770 must point to an array of struct v4l2_clip, not
771 a linked list, because drivers ignore the 771 a linked list, because drivers ignore the
772 struct v4l2_clip. ``next`` pointer. 772 struct v4l2_clip. ``next`` pointer.
773 773
774 V4L2 in Linux 2.6.17 774 V4L2 in Linux 2.6.17
775 ==================== 775 ====================
776 776
777 1. New video standard macros were added: ``V4L 777 1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
778 South Korea), and the sets ``V4L2_STD_MN``, 778 South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
779 ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The `` 779 ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
780 ``V4L2_STD_SECAM`` sets now include ``V4L2_ 780 ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
781 ``V4L2_STD_SECAM_LC`` respectively. 781 ``V4L2_STD_SECAM_LC`` respectively.
782 782
783 2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was d 783 2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
784 languages of a bilingual program. The use o 784 languages of a bilingual program. The use of
785 ``V4L2_TUNER_MODE_STEREO`` for this purpose 785 ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
786 the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` 786 the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
787 787
788 V4L2 spec erratum 2006-09-23 (Draft 0.15) 788 V4L2 spec erratum 2006-09-23 (Draft 0.15)
789 ========================================= 789 =========================================
790 790
791 1. In various places ``V4L2_BUF_TYPE_SLICED_VB 791 1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
792 ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the 792 ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were
793 not mentioned along with other buffer types 793 not mentioned along with other buffer types.
794 794
795 2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` i 795 2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the
796 struct v4l2_audio ``mode`` field is a flags 796 struct v4l2_audio ``mode`` field is a flags field.
797 797
798 3. :ref:`VIDIOC_QUERYCAP` did not mention the 798 3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio
799 capability flags. 799 capability flags.
800 800
801 4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQU 801 4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that
802 applications must initialize the tuner ``ty 802 applications must initialize the tuner ``type`` field of
803 struct v4l2_frequency before calling 803 struct v4l2_frequency before calling
804 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENC 804 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`.
805 805
806 5. The ``reserved`` array in struct v4l2_reque 806 5. The ``reserved`` array in struct v4l2_requestbuffers has 2 elements,
807 not 32. 807 not 32.
808 808
809 6. In :ref:`output` and :ref:`raw-vbi` the dev 809 6. In :ref:`output` and :ref:`raw-vbi` the device file names
810 ``/dev/vout`` which never caught on were re 810 ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
811 811
812 7. With Linux 2.6.15 the possible range for VB 812 7. With Linux 2.6.15 the possible range for VBI device minor numbers was
813 extended from 224-239 to 224-255. According 813 extended from 224-239 to 224-255. Accordingly device file names
814 ``/dev/vbi0`` to ``/dev/vbi31`` are possibl 814 ``/dev/vbi0`` to ``/dev/vbi31`` are possible now.
815 815
816 V4L2 in Linux 2.6.18 816 V4L2 in Linux 2.6.18
817 ==================== 817 ====================
818 818
819 1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC 819 1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
820 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRL 820 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
821 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CT 821 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a
822 flag to skip unsupported controls with 822 flag to skip unsupported controls with
823 :ref:`VIDIOC_QUERYCTRL`, new control types 823 :ref:`VIDIOC_QUERYCTRL`, new control types
824 ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTR 824 ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
825 (enum v4l2_ctrl_type), and new control flag 825 (enum v4l2_ctrl_type), and new control flags
826 ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_F 826 ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``,
827 ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL 827 ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
828 (:ref:`control-flags`). See :ref:`extended- 828 (:ref:`control-flags`). See :ref:`extended-controls` for details.
829 829
830 V4L2 in Linux 2.6.19 830 V4L2 in Linux 2.6.19
831 ==================== 831 ====================
832 832
833 1. In struct v4l2_sliced_vbi_cap a 833 1. In struct v4l2_sliced_vbi_cap a
834 buffer type field was added replacing a res 834 buffer type field was added replacing a reserved field. Note on
835 architectures where the size of enum types 835 architectures where the size of enum types differs from int types the
836 size of the structure changed. The 836 size of the structure changed. The
837 :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLI 837 :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl
838 was redefined from being read-only to write 838 was redefined from being read-only to write-read. Applications must
839 initialize the type field and clear the res 839 initialize the type field and clear the reserved fields now. These
840 changes may *break the compatibility* with 840 changes may *break the compatibility* with older drivers and
841 applications. 841 applications.
842 842
843 2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES` 843 2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES`
844 and 844 and
845 :ref:`VIDIOC_ENUM_FRAMEINTERVALS` 845 :ref:`VIDIOC_ENUM_FRAMEINTERVALS`
846 were added. 846 were added.
847 847
848 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` 848 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was
849 added. 849 added.
850 850
851 V4L2 spec erratum 2006-10-12 (Draft 0.17) 851 V4L2 spec erratum 2006-10-12 (Draft 0.17)
852 ========================================= 852 =========================================
853 853
854 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-forma 854 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
855 4:2:2 format. 855 4:2:2 format.
856 856
857 V4L2 in Linux 2.6.21 857 V4L2 in Linux 2.6.21
858 ==================== 858 ====================
859 859
860 1. The ``videodev2.h`` header file is now dual 860 1. The ``videodev2.h`` header file is now dual licensed under GNU
861 General Public License version two or later 861 General Public License version two or later, and under a 3-clause
862 BSD-style license. 862 BSD-style license.
863 863
864 V4L2 in Linux 2.6.22 864 V4L2 in Linux 2.6.22
865 ==================== 865 ====================
866 866
867 1. Two new field orders ``V4L2_FIELD_INTERLACE 867 1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and
868 ``V4L2_FIELD_INTERLACED_BT`` were added. Se 868 ``V4L2_FIELD_INTERLACED_BT`` were added. See enum v4l2_field for
869 details. 869 details.
870 870
871 2. Three new clipping/blending methods with a 871 2. Three new clipping/blending methods with a global or straight or
872 inverted local alpha value were added to th 872 inverted local alpha value were added to the video overlay interface.
873 See the description of the :ref:`VIDIOC_G_F 873 See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
874 and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` io 874 and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details.
875 875
876 A new ``global_alpha`` field was added to s 876 A new ``global_alpha`` field was added to struct v4l2_window,
877 extending the structure. This may **break c 877 extending the structure. This may **break compatibility** with
878 applications using a struct v4l2_window dir 878 applications using a struct v4l2_window directly. However the
879 :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` io 879 :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a
880 pointer to a struct v4l2_format parent stru 880 pointer to a struct v4l2_format parent structure
881 with padding bytes at the end, are not affe 881 with padding bytes at the end, are not affected.
882 882
883 3. The format of the ``chromakey`` field in st 883 3. The format of the ``chromakey`` field in struct v4l2_window changed from
884 "host order RGB32" to a pixel value in the 884 "host order RGB32" to a pixel value in the same format as the framebuffer.
885 This may **break compatibility** with exist 885 This may **break compatibility** with existing applications. Drivers
886 supporting the "host order RGB32" format ar 886 supporting the "host order RGB32" format are not known.
887 887
888 V4L2 in Linux 2.6.24 888 V4L2 in Linux 2.6.24
889 ==================== 889 ====================
890 890
891 1. The pixel formats ``V4L2_PIX_FMT_PAL8``, `` 891 1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
892 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV 892 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
893 ``V4L2_PIX_FMT_YUV32`` were added. 893 ``V4L2_PIX_FMT_YUV32`` were added.
894 894
895 V4L2 in Linux 2.6.25 895 V4L2 in Linux 2.6.25
896 ==================== 896 ====================
897 897
898 1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V 898 1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
899 :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SB 899 :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
900 900
901 2. New :ref:`controls <control>` ``V4L2_CID_PO 901 2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
902 ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BAL 902 ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
903 ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKL 903 ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
904 added. The controls ``V4L2_CID_BLACK_LEVEL` 904 added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
905 ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER 905 ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
906 906
907 3. A :ref:`Camera controls class <camera-contr 907 3. A :ref:`Camera controls class <camera-controls>` was added, with
908 the new controls ``V4L2_CID_EXPOSURE_AUTO`` 908 the new controls ``V4L2_CID_EXPOSURE_AUTO``,
909 ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_ 909 ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
910 ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_ 910 ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
911 ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RES 911 ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
912 ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ 912 ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
913 ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOC 913 ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
914 ``V4L2_CID_FOCUS_AUTO``. 914 ``V4L2_CID_FOCUS_AUTO``.
915 915
916 4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MP 916 4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
917 were superseded by the :ref:`extended contr 917 were superseded by the :ref:`extended controls <extended-controls>`
918 interface in Linux 2.6.18, where finally re 918 interface in Linux 2.6.18, where finally removed from the
919 ``videodev2.h`` header file. 919 ``videodev2.h`` header file.
920 920
921 V4L2 in Linux 2.6.26 921 V4L2 in Linux 2.6.26
922 ==================== 922 ====================
923 923
924 1. The pixel formats ``V4L2_PIX_FMT_Y16`` and 924 1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
925 were added. 925 were added.
926 926
927 2. Added user controls ``V4L2_CID_CHROMA_AGC`` 927 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
928 ``V4L2_CID_COLOR_KILLER``. 928 ``V4L2_CID_COLOR_KILLER``.
929 929
930 V4L2 in Linux 2.6.27 930 V4L2 in Linux 2.6.27
931 ==================== 931 ====================
932 932
933 1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl 933 1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
934 and the ``V4L2_CAP_HW_FREQ_SEEK`` capabilit 934 and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
935 935
936 2. The pixel formats ``V4L2_PIX_FMT_YVYU``, `` 936 2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
937 ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA 937 ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
938 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGB 938 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
939 ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_ 939 ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
940 940
941 V4L2 in Linux 2.6.28 941 V4L2 in Linux 2.6.28
942 ==================== 942 ====================
943 943
944 1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and 944 1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
945 ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio 945 ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
946 946
947 2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC 947 2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
948 948
949 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` 949 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
950 ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. 950 ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
951 951
952 V4L2 in Linux 2.6.29 952 V4L2 in Linux 2.6.29
953 ==================== 953 ====================
954 954
955 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renam 955 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to
956 ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DB 956 ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was
957 introduced in its place. The old struct ``v 957 introduced in its place. The old struct ``v4l2_chip_ident`` was renamed to
958 struct ``v4l2_chip_ident_old``. 958 struct ``v4l2_chip_ident_old``.
959 959
960 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, `` 960 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
961 ``V4L2_PIX_FMT_NV61`` were added. 961 ``V4L2_PIX_FMT_NV61`` were added.
962 962
963 3. Added camera controls ``V4L2_CID_ZOOM_ABSOL 963 3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
964 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM 964 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
965 ``V4L2_CID_PRIVACY``. 965 ``V4L2_CID_PRIVACY``.
966 966
967 V4L2 in Linux 2.6.30 967 V4L2 in Linux 2.6.30
968 ==================== 968 ====================
969 969
970 1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONL 970 1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
971 971
972 2. New control ``V4L2_CID_COLORFX`` was added. 972 2. New control ``V4L2_CID_COLORFX`` was added.
973 973
974 V4L2 in Linux 2.6.32 974 V4L2 in Linux 2.6.32
975 ==================== 975 ====================
976 976
977 1. In order to be easier to compare a V4L2 API 977 1. In order to be easier to compare a V4L2 API and a kernel version, now
978 V4L2 API is numbered using the Linux Kernel 978 V4L2 API is numbered using the Linux Kernel version numeration.
979 979
980 2. Finalized the RDS capture API. See :ref:`rd 980 2. Finalized the RDS capture API. See :ref:`rds` for more information.
981 981
982 3. Added new capabilities for modulators and R 982 3. Added new capabilities for modulators and RDS encoders.
983 983
984 4. Add description for libv4l API. 984 4. Add description for libv4l API.
985 985
986 5. Added support for string controls via new t 986 5. Added support for string controls via new type
987 ``V4L2_CTRL_TYPE_STRING``. 987 ``V4L2_CTRL_TYPE_STRING``.
988 988
989 6. Added ``V4L2_CID_BAND_STOP_FILTER`` documen 989 6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
990 990
991 7. Added FM Modulator (FM TX) Extended Control 991 7. Added FM Modulator (FM TX) Extended Control Class:
992 ``V4L2_CTRL_CLASS_FM_TX`` and their Control 992 ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
993 993
994 8. Added FM Receiver (FM RX) Extended Control 994 8. Added FM Receiver (FM RX) Extended Control Class:
995 ``V4L2_CTRL_CLASS_FM_RX`` and their Control 995 ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
996 996
997 9. Added Remote Controller chapter, describing 997 9. Added Remote Controller chapter, describing the default Remote
998 Controller mapping for media devices. 998 Controller mapping for media devices.
999 999
1000 V4L2 in Linux 2.6.33 1000 V4L2 in Linux 2.6.33
1001 ==================== 1001 ====================
1002 1002
1003 1. Added support for Digital Video timings in 1003 1. Added support for Digital Video timings in order to support HDTV
1004 receivers and transmitters. 1004 receivers and transmitters.
1005 1005
1006 V4L2 in Linux 2.6.34 1006 V4L2 in Linux 2.6.34
1007 ==================== 1007 ====================
1008 1008
1009 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L 1009 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
1010 controls to the :ref:`Camera controls clas 1010 controls to the :ref:`Camera controls class <camera-controls>`.
1011 1011
1012 V4L2 in Linux 2.6.37 1012 V4L2 in Linux 2.6.37
1013 ==================== 1013 ====================
1014 1014
1015 1. Remove the vtx (videotext/teletext) API. T 1015 1. Remove the vtx (videotext/teletext) API. This API was no longer used
1016 and no hardware exists to verify the API. 1016 and no hardware exists to verify the API. Nor were any userspace
1017 applications found that used it. It was or 1017 applications found that used it. It was originally scheduled for
1018 removal in 2.6.35. 1018 removal in 2.6.35.
1019 1019
1020 V4L2 in Linux 2.6.39 1020 V4L2 in Linux 2.6.39
1021 ==================== 1021 ====================
1022 1022
1023 1. The old VIDIOC_*_OLD symbols and V4L1 supp 1023 1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
1024 1024
1025 2. Multi-planar API added. Does not affect th 1025 2. Multi-planar API added. Does not affect the compatibility of current
1026 drivers and applications. See :ref:`multi- 1026 drivers and applications. See :ref:`multi-planar API <planar-apis>`
1027 for details. 1027 for details.
1028 1028
1029 V4L2 in Linux 3.1 1029 V4L2 in Linux 3.1
1030 ================= 1030 =================
1031 1031
1032 1. VIDIOC_QUERYCAP now returns a per-subsyste 1032 1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
1033 per-driver one. 1033 per-driver one.
1034 1034
1035 Standardize an error code for invalid ioct 1035 Standardize an error code for invalid ioctl.
1036 1036
1037 Added V4L2_CTRL_TYPE_BITMASK. 1037 Added V4L2_CTRL_TYPE_BITMASK.
1038 1038
1039 V4L2 in Linux 3.2 1039 V4L2 in Linux 3.2
1040 ================= 1040 =================
1041 1041
1042 1. V4L2_CTRL_FLAG_VOLATILE was added to signa 1042 1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
1043 userspace. 1043 userspace.
1044 1044
1045 2. Add selection API for extended control ove 1045 2. Add selection API for extended control over cropping and composing.
1046 Does not affect the compatibility of curre 1046 Does not affect the compatibility of current drivers and
1047 applications. See :ref:`selection API <sel 1047 applications. See :ref:`selection API <selection-api>` for details.
1048 1048
1049 V4L2 in Linux 3.3 1049 V4L2 in Linux 3.3
1050 ================= 1050 =================
1051 1051
1052 1. Added ``V4L2_CID_ALPHA_COMPONENT`` control 1052 1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
1053 :ref:`User controls class <control>`. 1053 :ref:`User controls class <control>`.
1054 1054
1055 2. Added the device_caps field to struct v4l2 1055 2. Added the device_caps field to struct v4l2_capabilities and added
1056 the new V4L2_CAP_DEVICE_CAPS capability. 1056 the new V4L2_CAP_DEVICE_CAPS capability.
1057 1057
1058 V4L2 in Linux 3.4 1058 V4L2 in Linux 3.4
1059 ================= 1059 =================
1060 1060
1061 1. Added :ref:`JPEG compression control class 1061 1. Added :ref:`JPEG compression control class <jpeg-controls>`.
1062 1062
1063 2. Extended the DV Timings API: 1063 2. Extended the DV Timings API:
1064 :ref:`VIDIOC_ENUM_DV_TIMINGS`, 1064 :ref:`VIDIOC_ENUM_DV_TIMINGS`,
1065 :ref:`VIDIOC_QUERY_DV_TIMINGS` and 1065 :ref:`VIDIOC_QUERY_DV_TIMINGS` and
1066 :ref:`VIDIOC_DV_TIMINGS_CAP`. 1066 :ref:`VIDIOC_DV_TIMINGS_CAP`.
1067 1067
1068 V4L2 in Linux 3.5 1068 V4L2 in Linux 3.5
1069 ================= 1069 =================
1070 1070
1071 1. Added integer menus, the new type will be 1071 1. Added integer menus, the new type will be
1072 V4L2_CTRL_TYPE_INTEGER_MENU. 1072 V4L2_CTRL_TYPE_INTEGER_MENU.
1073 1073
1074 2. Added selection API for V4L2 subdev interf 1074 2. Added selection API for V4L2 subdev interface:
1075 :ref:`VIDIOC_SUBDEV_G_SELECTION` and 1075 :ref:`VIDIOC_SUBDEV_G_SELECTION` and
1076 :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SU 1076 :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
1077 1077
1078 3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COL 1078 3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
1079 ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILH 1079 ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
1080 ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLO 1080 ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
1081 ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items 1081 ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
1082 ``V4L2_CID_COLORFX`` control. 1082 ``V4L2_CID_COLORFX`` control.
1083 1083
1084 4. Added ``V4L2_CID_COLORFX_CBCR`` control. 1084 4. Added ``V4L2_CID_COLORFX_CBCR`` control.
1085 1085
1086 5. Added camera controls ``V4L2_CID_AUTO_EXPO 1086 5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
1087 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``, 1087 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
1088 ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_C 1088 ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
1089 ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_ 1089 ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
1090 ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOC 1090 ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
1091 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_ 1091 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
1092 ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_ 1092 ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
1093 1093
1094 V4L2 in Linux 3.6 1094 V4L2 in Linux 3.6
1095 ================= 1095 =================
1096 1096
1097 1. Replaced ``input`` in struct v4l2_buffer b 1097 1. Replaced ``input`` in struct v4l2_buffer by
1098 ``reserved2`` and removed ``V4L2_BUF_FLAG_ 1098 ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
1099 1099
1100 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDE 1100 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
1101 capabilities. 1101 capabilities.
1102 1102
1103 3. Added support for frequency band enumerati 1103 3. Added support for frequency band enumerations:
1104 :ref:`VIDIOC_ENUM_FREQ_BANDS`. 1104 :ref:`VIDIOC_ENUM_FREQ_BANDS`.
1105 1105
1106 V4L2 in Linux 3.9 1106 V4L2 in Linux 3.9
1107 ================= 1107 =================
1108 1108
1109 1. Added timestamp types to ``flags`` field i 1109 1. Added timestamp types to ``flags`` field in
1110 struct v4l2_buffer. See :ref:`buffer-flags 1110 struct v4l2_buffer. See :ref:`buffer-flags`.
1111 1111
1112 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control 1112 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
1113 :ref:`ctrl-changes-flags`. 1113 :ref:`ctrl-changes-flags`.
1114 1114
1115 V4L2 in Linux 3.10 1115 V4L2 in Linux 3.10
1116 ================== 1116 ==================
1117 1117
1118 1. Removed obsolete and unused DV_PRESET ioct 1118 1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
1119 VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET 1119 VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
1120 VIDIOC_ENUM_DV_PRESET. Remove the related 1120 VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
1121 capability flags V4L2_IN_CAP_PRESETS and V 1121 capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
1122 1122
1123 2. Added new debugging ioctl 1123 2. Added new debugging ioctl
1124 :ref:`VIDIOC_DBG_G_CHIP_INFO`. 1124 :ref:`VIDIOC_DBG_G_CHIP_INFO`.
1125 1125
1126 V4L2 in Linux 3.11 1126 V4L2 in Linux 3.11
1127 ================== 1127 ==================
1128 1128
1129 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT` 1129 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
1130 1130
1131 V4L2 in Linux 3.14 1131 V4L2 in Linux 3.14
1132 ================== 1132 ==================
1133 1133
1134 1. In struct v4l2_rect, the type of ``width`` 1134 1. In struct v4l2_rect, the type of ``width`` and
1135 ``height`` fields changed from _s32 to _u3 1135 ``height`` fields changed from _s32 to _u32.
1136 1136
1137 V4L2 in Linux 3.15 1137 V4L2 in Linux 3.15
1138 ================== 1138 ==================
1139 1139
1140 1. Added Software Defined Radio (SDR) Interfa 1140 1. Added Software Defined Radio (SDR) Interface.
1141 1141
1142 V4L2 in Linux 3.16 1142 V4L2 in Linux 3.16
1143 ================== 1143 ==================
1144 1144
1145 1. Added event V4L2_EVENT_SOURCE_CHANGE. 1145 1. Added event V4L2_EVENT_SOURCE_CHANGE.
1146 1146
1147 V4L2 in Linux 3.17 1147 V4L2 in Linux 3.17
1148 ================== 1148 ==================
1149 1149
1150 1. Extended struct v4l2_pix_format. Added 1150 1. Extended struct v4l2_pix_format. Added
1151 format flags. 1151 format flags.
1152 1152
1153 2. Added compound control types and 1153 2. Added compound control types and
1154 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYC 1154 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
1155 1155
1156 V4L2 in Linux 3.18 1156 V4L2 in Linux 3.18
1157 ================== 1157 ==================
1158 1158
1159 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CI 1159 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
1160 controls. 1160 controls.
1161 1161
1162 V4L2 in Linux 3.19 1162 V4L2 in Linux 3.19
1163 ================== 1163 ==================
1164 1164
1165 1. Rewrote Colorspace chapter, added new enum 1165 1. Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding
1166 and enum v4l2_quantization fields to struc 1166 and enum v4l2_quantization fields to struct v4l2_pix_format,
1167 struct v4l2_pix_format_mplane and struct v 1167 struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt.
1168 1168
1169 V4L2 in Linux 4.4 1169 V4L2 in Linux 4.4
1170 ================= 1170 =================
1171 1171
1172 1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER 1172 1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
1173 ``V4L2_TUNER_ADC`` is deprecated now. 1173 ``V4L2_TUNER_ADC`` is deprecated now.
1174 1174
1175 2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tun 1175 2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
1176 1176
1177 3. Added transmitter support for Software Def 1177 3. Added transmitter support for Software Defined Radio (SDR) Interface.
1178 1178
1179 .. _other: 1179 .. _other:
1180 1180
1181 Relation of V4L2 to other Linux multimedia AP 1181 Relation of V4L2 to other Linux multimedia APIs
1182 ============================================= 1182 ===============================================
1183 1183
1184 .. _xvideo: 1184 .. _xvideo:
1185 1185
1186 X Video Extension 1186 X Video Extension
1187 ----------------- 1187 -----------------
1188 1188
1189 The X Video Extension (abbreviated XVideo or 1189 The X Video Extension (abbreviated XVideo or just Xv) is an extension of
1190 the X Window system, implemented for example 1190 the X Window system, implemented for example by the XFree86 project. Its
1191 scope is similar to V4L2, an API to video cap 1191 scope is similar to V4L2, an API to video capture and output devices for
1192 X clients. Xv allows applications to display 1192 X clients. Xv allows applications to display live video in a window,
1193 send window contents to a TV output, and capt 1193 send window contents to a TV output, and capture or output still images
1194 in XPixmaps [#f1]_. With their implementation 1194 in XPixmaps [#f1]_. With their implementation XFree86 makes the extension
1195 available across many operating systems and a 1195 available across many operating systems and architectures.
1196 1196
1197 Because the driver is embedded into the X ser 1197 Because the driver is embedded into the X server Xv has a number of
1198 advantages over the V4L2 :ref:`video overlay 1198 advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
1199 driver can easily determine the overlay targe 1199 driver can easily determine the overlay target, i. e. visible graphics
1200 memory or off-screen buffers for a destructiv 1200 memory or off-screen buffers for a destructive overlay. It can program
1201 the RAMDAC for a non-destructive overlay, sca 1201 the RAMDAC for a non-destructive overlay, scaling or color-keying, or
1202 the clipping functions of the video capture h 1202 the clipping functions of the video capture hardware, always in sync
1203 with drawing operations or windows moving or 1203 with drawing operations or windows moving or changing their stacking
1204 order. 1204 order.
1205 1205
1206 To combine the advantages of Xv and V4L a spe 1206 To combine the advantages of Xv and V4L a special Xv driver exists in
1207 XFree86 and XOrg, just programming any overla 1207 XFree86 and XOrg, just programming any overlay capable Video4Linux
1208 device it finds. To enable it ``/etc/X11/XF86 1208 device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
1209 lines: 1209 lines:
1210 1210
1211 :: 1211 ::
1212 1212
1213 Section "Module" 1213 Section "Module"
1214 Load "v4l" 1214 Load "v4l"
1215 EndSection 1215 EndSection
1216 1216
1217 As of XFree86 4.2 this driver still supports 1217 As of XFree86 4.2 this driver still supports only V4L ioctls, however it
1218 should work just fine with all V4L2 devices t 1218 should work just fine with all V4L2 devices through the V4L2
1219 backward-compatibility layer. Since V4L2 perm 1219 backward-compatibility layer. Since V4L2 permits multiple opens it is
1220 possible (if supported by the V4L2 driver) to 1220 possible (if supported by the V4L2 driver) to capture video while an X
1221 client requested video overlay. Restrictions 1221 client requested video overlay. Restrictions of simultaneous capturing
1222 and overlay are discussed in :ref:`overlay` a 1222 and overlay are discussed in :ref:`overlay` apply.
1223 1223
1224 Only marginally related to V4L2, XFree86 exte 1224 Only marginally related to V4L2, XFree86 extended Xv to support hardware
1225 YUV to RGB conversion and scaling for faster 1225 YUV to RGB conversion and scaling for faster video playback, and added
1226 an interface to MPEG-2 decoding hardware. Thi 1226 an interface to MPEG-2 decoding hardware. This API is useful to display
1227 images captured with V4L2 devices. 1227 images captured with V4L2 devices.
1228 1228
1229 Digital Video 1229 Digital Video
1230 ------------- 1230 -------------
1231 1231
1232 V4L2 does not support digital terrestrial, ca 1232 V4L2 does not support digital terrestrial, cable or satellite broadcast.
1233 A separate project aiming at digital receiver 1233 A separate project aiming at digital receivers exists. You can find its
1234 homepage at `https://linuxtv.org <https://lin 1234 homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
1235 DVB API has no connection to the V4L2 API exc 1235 DVB API has no connection to the V4L2 API except that drivers for hybrid
1236 hardware may support both. 1236 hardware may support both.
1237 1237
1238 Audio Interfaces 1238 Audio Interfaces
1239 ---------------- 1239 ----------------
1240 1240
1241 [to do - OSS/ALSA] 1241 [to do - OSS/ALSA]
1242 1242
1243 .. _experimental: 1243 .. _experimental:
1244 1244
1245 Experimental API Elements 1245 Experimental API Elements
1246 ========================= 1246 =========================
1247 1247
1248 The following V4L2 API elements are currently 1248 The following V4L2 API elements are currently experimental and may
1249 change in the future. 1249 change in the future.
1250 1250
1251 - :ref:`VIDIOC_DBG_G_REGISTER` and 1251 - :ref:`VIDIOC_DBG_G_REGISTER` and
1252 :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_ 1252 :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls.
1253 1253
1254 - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. 1254 - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
1255 1255
1256 .. _obsolete: 1256 .. _obsolete:
1257 1257
1258 Obsolete API Elements 1258 Obsolete API Elements
1259 ===================== 1259 =====================
1260 1260
1261 The following V4L2 API elements were supersed 1261 The following V4L2 API elements were superseded by new interfaces and
1262 should not be implemented in new drivers. 1262 should not be implemented in new drivers.
1263 1263
1264 - ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGC 1264 - ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
1265 Controls, :ref:`extended-controls`. 1265 Controls, :ref:`extended-controls`.
1266 1266
1267 - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, 1267 - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
1268 VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV 1268 VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
1269 the DV Timings API (:ref:`dv-timings`). 1269 the DV Timings API (:ref:`dv-timings`).
1270 1270
1271 - ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBD 1271 - ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
1272 ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC 1272 ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
1273 :ref:`VIDIOC_SUBDEV_G_SELECTION`. 1273 :ref:`VIDIOC_SUBDEV_G_SELECTION`.
1274 1274
1275 .. [#f1] 1275 .. [#f1]
1276 This is not implemented in XFree86. 1276 This is not implemented in XFree86.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.