hist-v4l2.rst

   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 direction 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 enveloping 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.