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

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