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