Documentation/media/uapi/v4l/hist-v4l2.rst

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