0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _hist-v4l2:
0005
0006 ***********************
0007 Changes of the V4L2 API
0008 ***********************
0009
0010 Soon after the V4L API was added to the kernel it was criticised as too
0011 inflexible. In August 1998 Bill Dirks proposed a number of improvements
0012 and began to work on documentation, example drivers and applications.
0013 With the help of other volunteers this eventually became the V4L2 API,
0014 not just an extension but a replacement for the V4L API. However it took
0015 another four years and two stable kernel releases until the new API was
0016 finally accepted for inclusion into the kernel in its present form.
0017
0018 Early Versions
0019 ==============
0020
0021 1998-08-20: First version.
0022
0023 1998-08-27: The :c:func:`select()` function was introduced.
0024
0025 1998-09-10: New video standard interface.
0026
0027 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
0028 meaningless ``O_TRUNC`` :c:func:`open()` flag, and the
0029 aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set
0030 this flag if they intend to access controls only, as opposed to capture
0031 applications which need exclusive access. The ``VIDEO_STD_XXX``
0032 identifiers are now ordinals instead of flags, and the
0033 ``video_std_construct()`` helper function takes id and
0034 transmission arguments.
0035
0036 1998-09-28: Revamped video standard. Made video controls individually
0037 enumerable.
0038
0039 1998-10-02: The ``id`` field was removed from
0040 struct ``video_standard`` and the color subcarrier fields were
0041 renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
0042 renamed to :ref:`VIDIOC_ENUMSTD`,
0043 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to
0044 :ref:`VIDIOC_ENUMINPUT`. A first draft of the
0045 Codec API was released.
0046
0047 1998-11-08: Many minor changes. Most symbols have been renamed. Some
0048 material changes to struct v4l2_capability.
0049
0050 1998-11-12: The read/write directon of some ioctls was misdefined.
0051
0052 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``,
0053 and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio
0054 controls are now accessible with the
0055 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
0056 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting
0057 with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
0058 ``videodev.h`` since it was only used once in the ``videodev`` kernel
0059 module. The ``YUV422`` and ``YUV411`` planar image formats were added.
0060
0061 1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video
0062 output devices were added.
0063
0064 1999-01-14: A raw VBI capture interface was added.
0065
0066 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
0067
0068 V4L2 Version 0.16 1999-01-31
0069 ============================
0070
0071 1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
0072 are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
0073 digital zoom (cropping) controls.
0074
0075 V4L2 Version 0.18 1999-03-16
0076 ============================
0077
0078 Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver
0079 writers, this changes how you implement your ioctl handler. See the
0080 Driver Writer's Guide. Added some more control id codes.
0081
0082 V4L2 Version 0.19 1999-06-05
0083 ============================
0084
0085 1999-03-18: Fill in the category and catname fields of v4l2_queryctrl
0086 objects before passing them to the driver. Required a minor change to
0087 the VIDIOC_QUERYCTRL handlers in the sample drivers.
0088
0089 1999-03-31: Better compatibility for v4l memory capture ioctls. Requires
0090 changes to drivers to fully support new compatibility features, see
0091 Driver Writer's Guide and v4l2cap.c. Added new control IDs:
0092 V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
0093 and _YUV411P to _YUV411P.
0094
0095 1999-04-04: Added a few more control IDs.
0096
0097 1999-04-07: Added the button control type.
0098
0099 1999-05-02: Fixed a typo in videodev.h, and added the
0100 V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
0101
0102 1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a
0103 malfunction of this ioctl.
0104
0105 1999-06-05: Changed the value of V4L2_CID_WHITENESS.
0106
0107 V4L2 Version 0.20 (1999-09-10)
0108 ==============================
0109
0110 Version 0.20 introduced a number of changes which were *not backward
0111 compatible* with 0.19 and earlier versions. Purpose of these changes was
0112 to simplify the API, while making it more extensible and following
0113 common Linux driver API conventions.
0114
0115 1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct v4l2_clip
0116 was changed for compatibility with v4l. (1999-08-30)
0117
0118 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
0119
0120 3. All ioctl() commands that used an integer argument now take a pointer
0121 to an integer. Where it makes sense, ioctls will return the actual
0122 new value in the integer pointed to by the argument, a common
0123 convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW,
0124 VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
0125 VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
0126
0127 .. code-block:: c
0128
0129 err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
0130
0131 becomes
0132
0133 .. code-block:: c
0134
0135 int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
0136
0137 4. All the different get- and set-format commands were swept into one
0138 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
0139 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a
0140 type field selecting the union member as parameter. Purpose is to
0141 simplify the API by eliminating several ioctls and to allow new and
0142 driver private data streams without adding new ioctls.
0143
0144 This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``,
0145 ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``,
0146 ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format
0147 struct v4l2_format was renamed to struct v4l2_pix_format, while
0148 struct v4l2_format is now the envelopping structure
0149 for all format negotiations.
0150
0151 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and
0152 ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and
0153 ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct v4l2_streamparm
0154 selects the respective union member.
0155
0156 This change obsoletes the ``VIDIOC_G_OUTPARM`` and
0157 ``VIDIOC_S_OUTPARM`` ioctls.
0158
0159 6. Control enumeration was simplified, and two new control flags were
0160 introduced and one dropped. The ``catname`` field was replaced by a
0161 ``group`` field.
0162
0163 Drivers can now flag unsupported and temporarily unavailable controls
0164 with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED``
0165 respectively. The ``group`` name indicates a possibly narrower
0166 classification than the ``category``. In other words, there may be
0167 multiple groups within a category. Controls within a group would
0168 typically be drawn within a group box. Controls in different
0169 categories might have a greater separation, or may even appear in
0170 separate windows.
0171
0172 7. The struct v4l2_buffer ``timestamp`` was
0173 changed to a 64 bit integer, containing the sampling or output time
0174 of the frame in nanoseconds. Additionally timestamps will be in
0175 absolute system time, not starting from zero at the beginning of a
0176 stream. The data type name for timestamps is stamp_t, defined as a
0177 signed 64-bit integer. Output devices should not send a buffer out
0178 until the time in the timestamp field has arrived. I would like to
0179 follow SGI's lead, and adopt a multimedia timestamping system like
0180 their UST (Unadjusted System Time). See
0181 http://web.archive.org/web/\*/http://reality.sgi.com
0182 /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are
0183 64-bit signed integers (not struct timeval's) and given in nanosecond
0184 units. The UST clock starts at zero when the system is booted and
0185 runs continuously and uniformly. It takes a little over 292 years for
0186 UST to overflow. There is no way to set the UST clock. The regular
0187 Linux time-of-day clock can be changed periodically, which would
0188 cause errors if it were being used for timestamping a multimedia
0189 stream. A real UST style clock will require some support in the
0190 kernel that is not there yet. But in anticipation, I will change the
0191 timestamp field to a 64-bit integer, and I will change the
0192 v4l2_masterclock_gettime() function (used only by drivers) to
0193 return a 64-bit integer.
0194
0195 8. A ``sequence`` field was added to struct v4l2_buffer. The ``sequence``
0196 field counts captured frames, it is ignored by output devices. When a
0197 capture driver drops a frame, the sequence number of that frame is skipped.
0198
0199 V4L2 Version 0.20 incremental changes
0200 =====================================
0201
0202 1999-12-23: In struct v4l2_vbi_format the
0203 ``reserved1`` field became ``offset``. Previously drivers were required
0204 to clear the ``reserved1`` field.
0205
0206 2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added.
0207
0208 2000-07-31: The ``linux/poll.h`` header is now included by
0209 ``videodev.h`` for compatibility with the original ``videodev.h`` file.
0210
0211 2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
0212 added.
0213
0214 2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added.
0215
0216 2000-12-04: A couple typos in symbol names were fixed.
0217
0218 2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in
0219 the ``videodev.h`` header file was renamed to ``v4l2_fourcc``.
0220
0221 2001-01-25: A possible driver-level compatibility problem between the
0222 ``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included
0223 in the ``videodevX`` patch was fixed. Users of an earlier version of
0224 ``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2
0225 drivers.
0226
0227 2001-01-26: A possible kernel-level incompatibility between the
0228 ``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h``
0229 file in Linux 2.2.x with devfs patches applied was fixed.
0230
0231 2001-03-02: Certain V4L ioctls which pass data in both direction
0232 although they are defined with read-only parameter, did not work
0233 correctly through the backward compatibility layer. [Solution?]
0234
0235 2001-04-13: Big endian 16-bit RGB formats were added.
0236
0237 2001-09-17: New YUV formats and the
0238 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
0239 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added.
0240 (The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
0241 multiple tuners into account.)
0242
0243 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
0244 compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
0245 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the
0246 struct ``v4l2_fmt`` ``type`` field does not contain
0247 ``V4L2_BUF_TYPE_VBI``. In the documentation of the struct v4l2_vbi_format`,
0248 the ``offset`` field the ambiguous phrase "rising edge" was changed to
0249 "leading edge".
0250
0251 V4L2 Version 0.20 2000-11-23
0252 ============================
0253
0254 A number of changes were made to the raw VBI interface.
0255
0256 1. Figures clarifying the line numbering scheme were added to the V4L2
0257 API specification. The ``start``\ [0] and ``start``\ [1] fields no
0258 longer count line numbers beginning at zero. Rationale: a) The
0259 previous definition was unclear. b) The ``start``\ [] values are
0260 ordinal numbers. c) There is no point in inventing a new line
0261 numbering scheme. We now use line number as defined by ITU-R, period.
0262 Compatibility: Add one to the start values. Applications depending on
0263 the previous semantics may not function correctly.
0264
0265 2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
0266 "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
0267 resources at scan line granularity and some data services are
0268 transmitted only on the first field. The comment that both ``count``
0269 values will usually be equal is misleading and pointless and has been
0270 removed. This change *breaks compatibility* with earlier versions:
0271 Drivers may return ``EINVAL``, applications may not function correctly.
0272
0273 3. Drivers are again permitted to return negative (unknown) start values
0274 as proposed earlier. Why this feature was dropped is unclear. This
0275 change may *break compatibility* with applications depending on the
0276 start values being positive. The use of ``EBUSY`` and ``EINVAL``
0277 error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was
0278 clarified. The ``EBUSY`` error code was finally documented, and the
0279 ``reserved2`` field which was previously mentioned only in the
0280 ``videodev.h`` header file.
0281
0282 4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT``
0283 were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the
0284 latter was missing in the ``videodev.h`` file.
0285
0286 V4L2 Version 0.20 2002-07-25
0287 ============================
0288
0289 Added sliced VBI interface proposal.
0290
0291 V4L2 in Linux 2.5.46, 2002-10
0292 =============================
0293
0294 Around October-November 2002, prior to an announced feature freeze of
0295 Linux 2.5, the API was revised, drawing from experience with V4L2 0.20.
0296 This unnamed version was finally merged into Linux 2.5.46.
0297
0298 1. As specified in :ref:`related`, drivers must make related device
0299 functions available under all minor device numbers.
0300
0301 2. The :c:func:`open()` function requires access mode
0302 ``O_RDWR`` regardless of the device type. All V4L2 drivers
0303 exchanging data with applications must support the ``O_NONBLOCK``
0304 flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the
0305 meaningless ``O_TRUNC`` to indicate accesses without data exchange
0306 (panel applications) was dropped. Drivers must stay in "panel mode"
0307 until the application attempts to initiate a data exchange, see
0308 :ref:`open`.
0309
0310 3. The struct v4l2_capability changed
0311 dramatically. Note that also the size of the structure changed,
0312 which is encoded in the ioctl request code, thus older V4L2 devices
0313 will respond with an ``EINVAL`` error code to the new
0314 :ref:`VIDIOC_QUERYCAP` ioctl.
0315
0316 There are new fields to identify the driver, a new RDS device
0317 function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag
0318 indicates if the device has any audio connectors, another I/O
0319 capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these
0320 changes the ``type`` field became a bit set and was merged into the
0321 ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to
0322 ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced
0323 ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
0324 ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
0325 ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
0326 ``V4L2_CAP_READWRITE``.
0327
0328 The redundant fields ``inputs``, ``outputs`` and ``audios`` were
0329 removed. These properties can be determined as described in
0330 :ref:`video` and :ref:`audio`.
0331
0332 The somewhat volatile and therefore barely useful fields
0333 ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
0334 ``maxframerate`` were removed. This information is available as
0335 described in :ref:`format` and :ref:`standard`.
0336
0337 ``V4L2_FLAG_SELECT`` was removed. We believe the select() function
0338 is important enough to require support of it in all V4L2 drivers
0339 exchanging data with applications. The redundant
0340 ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
0341 available as described in :ref:`format`.
0342
0343 4. In struct v4l2_input the ``assoc_audio``
0344 field and the ``capability`` field and its only flag
0345 ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field.
0346 Instead of linking one video input to one audio input this field
0347 reports all audio inputs this video input combines with.
0348
0349 New fields are ``tuner`` (reversing the former link from tuners to
0350 video inputs), ``std`` and ``status``.
0351
0352 Accordingly struct v4l2_output lost its
0353 ``capability`` and ``assoc_audio`` fields. ``audioset``,
0354 ``modulator`` and ``std`` where added instead.
0355
0356 5. The struct v4l2_audio field ``audio`` was
0357 renamed to ``index``, for consistency with other structures. A new
0358 capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the
0359 audio input in question supports stereo sound.
0360 ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags
0361 where removed. This can be easily implemented using controls.
0362 (However the same applies to AVL which is still there.)
0363
0364 Again for consistency the struct v4l2_audioout field ``audio`` was renamed
0365 to ``index``.
0366
0367 6. The struct v4l2_tuner ``input`` field was
0368 replaced by an ``index`` field, permitting devices with multiple
0369 tuners. The link between video inputs and tuners is now reversed,
0370 inputs point to their tuner. The ``std`` substructure became a
0371 simple set (more about this below) and moved into struct v4l2_input.
0372 A ``type`` field was added.
0373
0374 Accordingly in struct v4l2_modulator the
0375 ``output`` was replaced by an ``index`` field.
0376
0377 In struct v4l2_frequency the ``port``
0378 field was replaced by a ``tuner`` field containing the respective
0379 tuner or modulator index number. A tuner ``type`` field was added
0380 and the ``reserved`` field became larger for future extensions
0381 (satellite tuners in particular).
0382
0383 7. The idea of completely transparent video standards was dropped.
0384 Experience showed that applications must be able to work with video
0385 standards beyond presenting the user a menu. Instead of enumerating
0386 supported standards with an ioctl applications can now refer to
0387 standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols
0388 defined in the ``videodev2.h`` header file. For details see
0389 :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
0390 :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this
0391 type as argument. :ref:`VIDIOC_QUERYSTD` was
0392 added to autodetect the received standard, if the hardware has this
0393 capability. In struct v4l2_standard an
0394 ``index`` field was added for
0395 :ref:`VIDIOC_ENUMSTD`. A
0396 :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
0397 machine readable identifier, also replacing the ``transmission``
0398 field. The misleading ``framerate`` field was renamed to
0399 ``frameperiod``. The now obsolete ``colorstandard`` information,
0400 originally needed to distguish between variations of standards, were
0401 removed.
0402
0403 Struct ``v4l2_enumstd`` ceased to be.
0404 :ref:`VIDIOC_ENUMSTD` now takes a pointer to a
0405 struct v4l2_standard directly. The
0406 information which standards are supported by a particular video
0407 input or output moved into struct v4l2_input
0408 and struct v4l2_output fields named ``std``,
0409 respectively.
0410
0411 8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
0412 ``category`` and ``group`` did not catch on and/or were not
0413 implemented as expected and therefore removed.
0414
0415 9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to
0416 negotiate data formats as with
0417 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of
0418 programming the hardware and regardless of I/O in progress.
0419
0420 In struct v4l2_format the ``fmt`` union was
0421 extended to contain struct v4l2_window. All
0422 image format negotiations are now possible with ``VIDIOC_G_FMT``,
0423 ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN``
0424 and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were
0425 removed. The ``type`` field changed to type enum v4l2_buf_type and
0426 the buffer type names changed as follows.
0427
0428
0429 .. flat-table::
0430 :header-rows: 1
0431 :stub-columns: 0
0432
0433 * - Old defines
0434 - enum v4l2_buf_type
0435 * - ``V4L2_BUF_TYPE_CAPTURE``
0436 - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
0437 * - ``V4L2_BUF_TYPE_CODECIN``
0438 - Omitted for now
0439 * - ``V4L2_BUF_TYPE_CODECOUT``
0440 - Omitted for now
0441 * - ``V4L2_BUF_TYPE_EFFECTSIN``
0442 - Omitted for now
0443 * - ``V4L2_BUF_TYPE_EFFECTSIN2``
0444 - Omitted for now
0445 * - ``V4L2_BUF_TYPE_EFFECTSOUT``
0446 - Omitted for now
0447 * - ``V4L2_BUF_TYPE_VIDEOOUT``
0448 - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
0449 * - ``-``
0450 - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
0451 * - ``-``
0452 - ``V4L2_BUF_TYPE_VBI_CAPTURE``
0453 * - ``-``
0454 - ``V4L2_BUF_TYPE_VBI_OUTPUT``
0455 * - ``-``
0456 - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
0457 * - ``-``
0458 - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
0459 * - ``V4L2_BUF_TYPE_PRIVATE_BASE``
0460 - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
0461
0462 10. In struct v4l2_fmtdesc a enum v4l2_buf_type field named ``type`` was
0463 added as in struct v4l2_format. The ``VIDIOC_ENUM_FBUFFMT`` ioctl is no
0464 longer needed and was removed. These calls can be replaced by
0465 :ref:`VIDIOC_ENUM_FMT` with type ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
0466
0467 11. In struct v4l2_pix_format the ``depth``
0468 field was removed, assuming applications which recognize the format
0469 by its four-character-code already know the color depth, and others
0470 do not care about it. The same rationale lead to the removal of the
0471 ``V4L2_FMT_FLAG_COMPRESSED`` flag. The
0472 ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers
0473 are not supposed to convert images in kernel space. A user library
0474 of conversion functions should be provided instead. The
0475 ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can
0476 set the ``bytesperline`` field to zero to get a reasonable default.
0477 Since the remaining flags were replaced as well, the ``flags`` field
0478 itself was removed.
0479
0480 The interlace flags were replaced by a enum v4l2_field value in a
0481 newly added ``field`` field.
0482
0483 .. flat-table::
0484 :header-rows: 1
0485 :stub-columns: 0
0486
0487 * - Old flag
0488 - enum v4l2_field
0489 * - ``V4L2_FMT_FLAG_NOT_INTERLACED``
0490 - ?
0491 * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
0492 - ``V4L2_FIELD_INTERLACED``
0493 * - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
0494 - ``V4L2_FIELD_TOP``
0495 * - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
0496 - ``V4L2_FIELD_BOTTOM``
0497 * - ``-``
0498 - ``V4L2_FIELD_SEQ_TB``
0499 * - ``-``
0500 - ``V4L2_FIELD_SEQ_BT``
0501 * - ``-``
0502 - ``V4L2_FIELD_ALTERNATE``
0503
0504 The color space flags were replaced by a enum v4l2_colorspace value in
0505 a newly added ``colorspace`` field, where one of
0506 ``V4L2_COLORSPACE_SMPTE170M``, ``V4L2_COLORSPACE_BT878``,
0507 ``V4L2_COLORSPACE_470_SYSTEM_M`` or
0508 ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``.
0509
0510 12. In struct v4l2_requestbuffers the
0511 ``type`` field was properly defined as enum v4l2_buf_type. Buffer types
0512 changed as mentioned above. A new ``memory`` field of type
0513 enum v4l2_memory was added to distinguish between
0514 I/O methods using buffers allocated by the driver or the
0515 application. See :ref:`io` for details.
0516
0517 13. In struct v4l2_buffer the ``type`` field was
0518 properly defined as enum v4l2_buf_type.
0519 Buffer types changed as mentioned above. A ``field`` field of type
0520 enum v4l2_field was added to indicate if a
0521 buffer contains a top or bottom field. The old field flags were
0522 removed. Since no unadjusted system time clock was added to the
0523 kernel as planned, the ``timestamp`` field changed back from type
0524 stamp_t, an unsigned 64 bit integer expressing the sample time in
0525 nanoseconds, to struct timeval. With the addition
0526 of a second memory mapping method the ``offset`` field moved into
0527 union ``m``, and a new ``memory`` field of type enum v4l2_memory
0528 was added to distinguish between
0529 I/O methods. See :ref:`io` for details.
0530
0531 The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility
0532 layer, after changes to this code it was no longer needed. The
0533 ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was
0534 indeed allocated in device memory rather than DMA-able system
0535 memory. It was barely useful and so was removed.
0536
0537 14. In struct v4l2_framebuffer the
0538 ``base[3]`` array anticipating double- and triple-buffering in
0539 off-screen video memory, however without defining a synchronization
0540 mechanism, was replaced by a single pointer. The
0541 ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were
0542 removed. Applications can determine this capability more accurately
0543 using the new cropping and scaling interface. The
0544 ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by
0545 ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
0546 ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
0547
0548 15. In struct v4l2_clip the ``x``, ``y``,
0549 ``width`` and ``height`` field moved into a ``c`` substructure of
0550 type struct v4l2_rect. The ``x`` and ``y``
0551 fields were renamed to ``left`` and ``top``, i. e. offsets to a
0552 context dependent origin.
0553
0554 16. In struct v4l2_window the ``x``, ``y``,
0555 ``width`` and ``height`` field moved into a ``w`` substructure as
0556 above. A ``field`` field of type enum v4l2_field was added to
0557 distinguish between field and frame (interlaced) overlay.
0558
0559 17. The digital zoom interface, including struct ``v4l2_zoomcap``,
0560 struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` and
0561 ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
0562 scaling interface. The previously unused
0563 struct v4l2_cropcap and struct v4l2_crop
0564 where redefined for this purpose. See :ref:`crop` for details.
0565
0566 18. In struct v4l2_vbi_format the
0567 ``SAMPLE_FORMAT`` field now contains a four-character-code as used
0568 to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces
0569 the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was
0570 extended.
0571
0572 19. In struct v4l2_captureparm the type of
0573 the ``timeperframe`` field changed from unsigned long to
0574 struct v4l2_fract. This allows the accurate
0575 expression of multiples of the NTSC-M frame rate 30000 / 1001. A new
0576 field ``readbuffers`` was added to control the driver behaviour in
0577 read I/O mode.
0578
0579 Similar changes were made to struct v4l2_outputparm.
0580
0581 20. The struct ``v4l2_performance`` and
0582 ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
0583 :ref:`read/write I/O method <rw>`, which is limited anyway, this
0584 information is already available to applications.
0585
0586 21. The example transformation from RGB to YCbCr color space in the old
0587 V4L2 documentation was inaccurate, this has been corrected in
0588 :ref:`pixfmt`.
0589
0590 V4L2 2003-06-19
0591 ===============
0592
0593 1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices.
0594 Prior to this change radio devices would identify solely by having
0595 exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``.
0596
0597 2. An optional driver access priority mechanism was added, see
0598 :ref:`app-pri` for details.
0599
0600 3. The audio input and output interface was found to be incomplete.
0601
0602 Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would
0603 enumerate the available audio inputs. An ioctl to determine the
0604 current audio input, if more than one combines with the current video
0605 input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to
0606 ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The
0607 :ref:`VIDIOC_ENUMAUDIO` ioctl was added to
0608 enumerate audio inputs, while
0609 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current
0610 audio input.
0611
0612 The same changes were made to
0613 :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and
0614 :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`.
0615
0616 Until further the "videodev" module will automatically translate
0617 between the old and new ioctls, but drivers and applications must be
0618 updated to successfully compile again.
0619
0620 4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly
0621 defined with write-read parameter. It was changed to write-only,
0622 while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``.
0623 The old ioctl was removed on Kernel 2.6.39. Until further the
0624 "videodev" kernel module will automatically translate to the new
0625 version, so drivers must be recompiled, but not applications.
0626
0627 5. :ref:`overlay` incorrectly stated that clipping rectangles define
0628 regions where the video can be seen. Correct is that clipping
0629 rectangles define regions where *no* video shall be displayed and so
0630 the graphics surface can be seen.
0631
0632 6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and
0633 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with
0634 write-only parameter, inconsistent with other ioctls modifying their
0635 argument. They were changed to write-read, while a ``_OLD`` suffix
0636 was added to the write-only versions. The old ioctls were removed on
0637 Kernel 2.6.39. Drivers and applications assuming a constant parameter
0638 need an update.
0639
0640 V4L2 2003-11-05
0641 ===============
0642
0643 1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
0644 transferred from Bill Dirks' V4L2 specification. Descriptions below
0645 refer to bytes in memory, in ascending address order.
0646
0647
0648 .. flat-table::
0649 :header-rows: 1
0650 :stub-columns: 0
0651
0652 * - Symbol
0653 - In this document prior to revision 0.5
0654 - Corrected
0655 * - ``V4L2_PIX_FMT_RGB24``
0656 - B, G, R
0657 - R, G, B
0658 * - ``V4L2_PIX_FMT_BGR24``
0659 - R, G, B
0660 - B, G, R
0661 * - ``V4L2_PIX_FMT_RGB32``
0662 - B, G, R, X
0663 - R, G, B, X
0664 * - ``V4L2_PIX_FMT_BGR32``
0665 - R, G, B, X
0666 - B, G, R, X
0667
0668 The ``V4L2_PIX_FMT_BGR24`` example was always correct.
0669
0670 In :ref:`v4l-image-properties` the mapping of the V4L
0671 ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
0672 pixel formats was accordingly corrected.
0673
0674 2. Unrelated to the fixes above, drivers may still interpret some V4L2
0675 RGB pixel formats differently. These issues have yet to be addressed,
0676 for details see :ref:`pixfmt-rgb`.
0677
0678 V4L2 in Linux 2.6.6, 2004-05-09
0679 ===============================
0680
0681 1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly
0682 defined with read-only parameter. It is now defined as write-read
0683 ioctl, while the read-only version was renamed to
0684 ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39.
0685
0686 V4L2 in Linux 2.6.8
0687 ===================
0688
0689 1. A new field ``input`` (former ``reserved[0]``) was added to the
0690 struct v4l2_buffer. Purpose of this
0691 field is to alternate between video inputs (e. g. cameras) in step
0692 with the video capturing process. This function must be enabled with
0693 the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
0694 longer read-only.
0695
0696 V4L2 spec erratum 2004-08-01
0697 ============================
0698
0699 1. The return value of the :ref:`func-open` function was incorrectly
0700 documented.
0701
0702 2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
0703
0704 3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
0705 the wrong argument.
0706
0707 4. The documentation of the :ref:`VIDIOC_QBUF` and
0708 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the
0709 struct v4l2_buffer ``memory`` field. It was
0710 also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
0711 error code was not documented.
0712
0713 V4L2 in Linux 2.6.14
0714 ====================
0715
0716 1. A new sliced VBI interface was added. It is documented in
0717 :ref:`sliced` and replaces the interface first proposed in V4L2
0718 specification 0.8.
0719
0720 V4L2 in Linux 2.6.15
0721 ====================
0722
0723 1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added.
0724
0725 2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
0726 ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
0727 ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
0728 ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
0729 set now includes ``V4L2_STD_NTSC_443``. See also
0730 :ref:`v4l2-std-id`.
0731
0732 3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
0733 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
0734 argument was replaced by a struct
0735 ``v4l2_mpeg_compression`` pointer. (The
0736 ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
0737 in Linux 2.6.25.)
0738
0739 V4L2 spec erratum 2005-11-27
0740 ============================
0741
0742 The capture example in :ref:`capture-example` called the
0743 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if
0744 cropping is supported. In the video standard selection example in
0745 :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
0746 the wrong argument type.
0747
0748 V4L2 spec erratum 2006-01-10
0749 ============================
0750
0751 1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct v4l2_input not only
0752 indicates if the color killer is enabled, but also if it is active.
0753 (The color killer disables color decoding when it detects no color
0754 in the video signal to improve the image quality.)
0755
0756 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not
0757 write-only as stated on its reference page. The ioctl changed in 2003
0758 as noted above.
0759
0760 V4L2 spec erratum 2006-02-03
0761 ============================
0762
0763 1. In struct v4l2_captureparm and struct v4l2_outputparm the ``timeperframe``
0764 field gives the time in seconds, not microseconds.
0765
0766 V4L2 spec erratum 2006-02-04
0767 ============================
0768
0769 1. The ``clips`` field in struct v4l2_window
0770 must point to an array of struct v4l2_clip, not
0771 a linked list, because drivers ignore the
0772 struct v4l2_clip. ``next`` pointer.
0773
0774 V4L2 in Linux 2.6.17
0775 ====================
0776
0777 1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
0778 South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
0779 ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
0780 ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
0781 ``V4L2_STD_SECAM_LC`` respectively.
0782
0783 2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
0784 languages of a bilingual program. The use of
0785 ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
0786 the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
0787
0788 V4L2 spec erratum 2006-09-23 (Draft 0.15)
0789 =========================================
0790
0791 1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
0792 ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were
0793 not mentioned along with other buffer types.
0794
0795 2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the
0796 struct v4l2_audio ``mode`` field is a flags field.
0797
0798 3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio
0799 capability flags.
0800
0801 4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that
0802 applications must initialize the tuner ``type`` field of
0803 struct v4l2_frequency before calling
0804 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`.
0805
0806 5. The ``reserved`` array in struct v4l2_requestbuffers has 2 elements,
0807 not 32.
0808
0809 6. In :ref:`output` and :ref:`raw-vbi` the device file names
0810 ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
0811
0812 7. With Linux 2.6.15 the possible range for VBI device minor numbers was
0813 extended from 224-239 to 224-255. Accordingly device file names
0814 ``/dev/vbi0`` to ``/dev/vbi31`` are possible now.
0815
0816 V4L2 in Linux 2.6.18
0817 ====================
0818
0819 1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
0820 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
0821 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a
0822 flag to skip unsupported controls with
0823 :ref:`VIDIOC_QUERYCTRL`, new control types
0824 ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
0825 (enum v4l2_ctrl_type), and new control flags
0826 ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``,
0827 ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
0828 (:ref:`control-flags`). See :ref:`extended-controls` for details.
0829
0830 V4L2 in Linux 2.6.19
0831 ====================
0832
0833 1. In struct v4l2_sliced_vbi_cap a
0834 buffer type field was added replacing a reserved field. Note on
0835 architectures where the size of enum types differs from int types the
0836 size of the structure changed. The
0837 :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl
0838 was redefined from being read-only to write-read. Applications must
0839 initialize the type field and clear the reserved fields now. These
0840 changes may *break the compatibility* with older drivers and
0841 applications.
0842
0843 2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES`
0844 and
0845 :ref:`VIDIOC_ENUM_FRAMEINTERVALS`
0846 were added.
0847
0848 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was
0849 added.
0850
0851 V4L2 spec erratum 2006-10-12 (Draft 0.17)
0852 =========================================
0853
0854 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
0855 4:2:2 format.
0856
0857 V4L2 in Linux 2.6.21
0858 ====================
0859
0860 1. The ``videodev2.h`` header file is now dual licensed under GNU
0861 General Public License version two or later, and under a 3-clause
0862 BSD-style license.
0863
0864 V4L2 in Linux 2.6.22
0865 ====================
0866
0867 1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and
0868 ``V4L2_FIELD_INTERLACED_BT`` were added. See enum v4l2_field for
0869 details.
0870
0871 2. Three new clipping/blending methods with a global or straight or
0872 inverted local alpha value were added to the video overlay interface.
0873 See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
0874 and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details.
0875
0876 A new ``global_alpha`` field was added to struct v4l2_window,
0877 extending the structure. This may **break compatibility** with
0878 applications using a struct v4l2_window directly. However the
0879 :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a
0880 pointer to a struct v4l2_format parent structure
0881 with padding bytes at the end, are not affected.
0882
0883 3. The format of the ``chromakey`` field in struct v4l2_window changed from
0884 "host order RGB32" to a pixel value in the same format as the framebuffer.
0885 This may **break compatibility** with existing applications. Drivers
0886 supporting the "host order RGB32" format are not known.
0887
0888 V4L2 in Linux 2.6.24
0889 ====================
0890
0891 1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
0892 ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
0893 ``V4L2_PIX_FMT_YUV32`` were added.
0894
0895 V4L2 in Linux 2.6.25
0896 ====================
0897
0898 1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
0899 :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
0900
0901 2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
0902 ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
0903 ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
0904 added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
0905 ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
0906
0907 3. A :ref:`Camera controls class <camera-controls>` was added, with
0908 the new controls ``V4L2_CID_EXPOSURE_AUTO``,
0909 ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
0910 ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
0911 ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
0912 ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
0913 ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
0914 ``V4L2_CID_FOCUS_AUTO``.
0915
0916 4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
0917 were superseded by the :ref:`extended controls <extended-controls>`
0918 interface in Linux 2.6.18, where finally removed from the
0919 ``videodev2.h`` header file.
0920
0921 V4L2 in Linux 2.6.26
0922 ====================
0923
0924 1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
0925 were added.
0926
0927 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
0928 ``V4L2_CID_COLOR_KILLER``.
0929
0930 V4L2 in Linux 2.6.27
0931 ====================
0932
0933 1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
0934 and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
0935
0936 2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
0937 ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
0938 ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
0939 ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
0940
0941 V4L2 in Linux 2.6.28
0942 ====================
0943
0944 1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
0945 ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
0946
0947 2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
0948
0949 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
0950 ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
0951
0952 V4L2 in Linux 2.6.29
0953 ====================
0954
0955 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to
0956 ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was
0957 introduced in its place. The old struct ``v4l2_chip_ident`` was renamed to
0958 struct ``v4l2_chip_ident_old``.
0959
0960 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
0961 ``V4L2_PIX_FMT_NV61`` were added.
0962
0963 3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
0964 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
0965 ``V4L2_CID_PRIVACY``.
0966
0967 V4L2 in Linux 2.6.30
0968 ====================
0969
0970 1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
0971
0972 2. New control ``V4L2_CID_COLORFX`` was added.
0973
0974 V4L2 in Linux 2.6.32
0975 ====================
0976
0977 1. In order to be easier to compare a V4L2 API and a kernel version, now
0978 V4L2 API is numbered using the Linux Kernel version numeration.
0979
0980 2. Finalized the RDS capture API. See :ref:`rds` for more information.
0981
0982 3. Added new capabilities for modulators and RDS encoders.
0983
0984 4. Add description for libv4l API.
0985
0986 5. Added support for string controls via new type
0987 ``V4L2_CTRL_TYPE_STRING``.
0988
0989 6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
0990
0991 7. Added FM Modulator (FM TX) Extended Control Class:
0992 ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
0993
0994 8. Added FM Receiver (FM RX) Extended Control Class:
0995 ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
0996
0997 9. Added Remote Controller chapter, describing the default Remote
0998 Controller mapping for media devices.
0999
1000 V4L2 in Linux 2.6.33
1001 ====================
1002
1003 1. Added support for Digital Video timings in order to support HDTV
1004 receivers and transmitters.
1005
1006 V4L2 in Linux 2.6.34
1007 ====================
1008
1009 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
1010 controls to the :ref:`Camera controls class <camera-controls>`.
1011
1012 V4L2 in Linux 2.6.37
1013 ====================
1014
1015 1. Remove the vtx (videotext/teletext) API. This API was no longer used
1016 and no hardware exists to verify the API. Nor were any userspace
1017 applications found that used it. It was originally scheduled for
1018 removal in 2.6.35.
1019
1020 V4L2 in Linux 2.6.39
1021 ====================
1022
1023 1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
1024
1025 2. Multi-planar API added. Does not affect the compatibility of current
1026 drivers and applications. See :ref:`multi-planar API <planar-apis>`
1027 for details.
1028
1029 V4L2 in Linux 3.1
1030 =================
1031
1032 1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
1033 per-driver one.
1034
1035 Standardize an error code for invalid ioctl.
1036
1037 Added V4L2_CTRL_TYPE_BITMASK.
1038
1039 V4L2 in Linux 3.2
1040 =================
1041
1042 1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
1043 userspace.
1044
1045 2. Add selection API for extended control over cropping and composing.
1046 Does not affect the compatibility of current drivers and
1047 applications. See :ref:`selection API <selection-api>` for details.
1048
1049 V4L2 in Linux 3.3
1050 =================
1051
1052 1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
1053 :ref:`User controls class <control>`.
1054
1055 2. Added the device_caps field to struct v4l2_capabilities and added
1056 the new V4L2_CAP_DEVICE_CAPS capability.
1057
1058 V4L2 in Linux 3.4
1059 =================
1060
1061 1. Added :ref:`JPEG compression control class <jpeg-controls>`.
1062
1063 2. Extended the DV Timings API:
1064 :ref:`VIDIOC_ENUM_DV_TIMINGS`,
1065 :ref:`VIDIOC_QUERY_DV_TIMINGS` and
1066 :ref:`VIDIOC_DV_TIMINGS_CAP`.
1067
1068 V4L2 in Linux 3.5
1069 =================
1070
1071 1. Added integer menus, the new type will be
1072 V4L2_CTRL_TYPE_INTEGER_MENU.
1073
1074 2. Added selection API for V4L2 subdev interface:
1075 :ref:`VIDIOC_SUBDEV_G_SELECTION` and
1076 :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
1077
1078 3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
1079 ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
1080 ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
1081 ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
1082 ``V4L2_CID_COLORFX`` control.
1083
1084 4. Added ``V4L2_CID_COLORFX_CBCR`` control.
1085
1086 5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
1087 ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
1088 ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
1089 ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
1090 ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
1091 ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
1092 ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
1093
1094 V4L2 in Linux 3.6
1095 =================
1096
1097 1. Replaced ``input`` in struct v4l2_buffer by
1098 ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
1099
1100 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
1101 capabilities.
1102
1103 3. Added support for frequency band enumerations:
1104 :ref:`VIDIOC_ENUM_FREQ_BANDS`.
1105
1106 V4L2 in Linux 3.9
1107 =================
1108
1109 1. Added timestamp types to ``flags`` field in
1110 struct v4l2_buffer. See :ref:`buffer-flags`.
1111
1112 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
1113 :ref:`ctrl-changes-flags`.
1114
1115 V4L2 in Linux 3.10
1116 ==================
1117
1118 1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
1119 VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
1120 VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
1121 capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
1122
1123 2. Added new debugging ioctl
1124 :ref:`VIDIOC_DBG_G_CHIP_INFO`.
1125
1126 V4L2 in Linux 3.11
1127 ==================
1128
1129 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
1130
1131 V4L2 in Linux 3.14
1132 ==================
1133
1134 1. In struct v4l2_rect, the type of ``width`` and
1135 ``height`` fields changed from _s32 to _u32.
1136
1137 V4L2 in Linux 3.15
1138 ==================
1139
1140 1. Added Software Defined Radio (SDR) Interface.
1141
1142 V4L2 in Linux 3.16
1143 ==================
1144
1145 1. Added event V4L2_EVENT_SOURCE_CHANGE.
1146
1147 V4L2 in Linux 3.17
1148 ==================
1149
1150 1. Extended struct v4l2_pix_format. Added
1151 format flags.
1152
1153 2. Added compound control types and
1154 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
1155
1156 V4L2 in Linux 3.18
1157 ==================
1158
1159 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
1160 controls.
1161
1162 V4L2 in Linux 3.19
1163 ==================
1164
1165 1. Rewrote Colorspace chapter, added new enum v4l2_ycbcr_encoding
1166 and enum v4l2_quantization fields to struct v4l2_pix_format,
1167 struct v4l2_pix_format_mplane and struct v4l2_mbus_framefmt.
1168
1169 V4L2 in Linux 4.4
1170 =================
1171
1172 1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
1173 ``V4L2_TUNER_ADC`` is deprecated now.
1174
1175 2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
1176
1177 3. Added transmitter support for Software Defined Radio (SDR) Interface.
1178
1179 .. _other:
1180
1181 Relation of V4L2 to other Linux multimedia APIs
1182 ===============================================
1183
1184 .. _xvideo:
1185
1186 X Video Extension
1187 -----------------
1188
1189 The X Video Extension (abbreviated XVideo or just Xv) is an extension of
1190 the X Window system, implemented for example by the XFree86 project. Its
1191 scope is similar to V4L2, an API to video capture and output devices for
1192 X clients. Xv allows applications to display live video in a window,
1193 send window contents to a TV output, and capture or output still images
1194 in XPixmaps [#f1]_. With their implementation XFree86 makes the extension
1195 available across many operating systems and architectures.
1196
1197 Because the driver is embedded into the X server Xv has a number of
1198 advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
1199 driver can easily determine the overlay target, i. e. visible graphics
1200 memory or off-screen buffers for a destructive overlay. It can program
1201 the RAMDAC for a non-destructive overlay, scaling or color-keying, or
1202 the clipping functions of the video capture hardware, always in sync
1203 with drawing operations or windows moving or changing their stacking
1204 order.
1205
1206 To combine the advantages of Xv and V4L a special Xv driver exists in
1207 XFree86 and XOrg, just programming any overlay capable Video4Linux
1208 device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
1209 lines:
1210
1211 ::
1212
1213 Section "Module"
1214 Load "v4l"
1215 EndSection
1216
1217 As of XFree86 4.2 this driver still supports only V4L ioctls, however it
1218 should work just fine with all V4L2 devices through the V4L2
1219 backward-compatibility layer. Since V4L2 permits multiple opens it is
1220 possible (if supported by the V4L2 driver) to capture video while an X
1221 client requested video overlay. Restrictions of simultaneous capturing
1222 and overlay are discussed in :ref:`overlay` apply.
1223
1224 Only marginally related to V4L2, XFree86 extended Xv to support hardware
1225 YUV to RGB conversion and scaling for faster video playback, and added
1226 an interface to MPEG-2 decoding hardware. This API is useful to display
1227 images captured with V4L2 devices.
1228
1229 Digital Video
1230 -------------
1231
1232 V4L2 does not support digital terrestrial, cable or satellite broadcast.
1233 A separate project aiming at digital receivers exists. You can find its
1234 homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
1235 DVB API has no connection to the V4L2 API except that drivers for hybrid
1236 hardware may support both.
1237
1238 Audio Interfaces
1239 ----------------
1240
1241 [to do - OSS/ALSA]
1242
1243 .. _experimental:
1244
1245 Experimental API Elements
1246 =========================
1247
1248 The following V4L2 API elements are currently experimental and may
1249 change in the future.
1250
1251 - :ref:`VIDIOC_DBG_G_REGISTER` and
1252 :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls.
1253
1254 - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
1255
1256 .. _obsolete:
1257
1258 Obsolete API Elements
1259 =====================
1260
1261 The following V4L2 API elements were superseded by new interfaces and
1262 should not be implemented in new drivers.
1263
1264 - ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
1265 Controls, :ref:`extended-controls`.
1266
1267 - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
1268 VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
1269 the DV Timings API (:ref:`dv-timings`).
1270
1271 - ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
1272 ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
1273 :ref:`VIDIOC_SUBDEV_G_SELECTION`.
1274
1275 .. [#f1]
1276 This is not implemented in XFree86.
