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