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