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/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _hist-v4l2: 11 12*********************** 13Changes of the V4L2 API 14*********************** 15 16Soon after the V4L API was added to the kernel it was criticised as too 17inflexible. In August 1998 Bill Dirks proposed a number of improvements 18and began to work on documentation, example drivers and applications. 19With the help of other volunteers this eventually became the V4L2 API, 20not just an extension but a replacement for the V4L API. However it took 21another four years and two stable kernel releases until the new API was 22finally accepted for inclusion into the kernel in its present form. 23 24 25Early Versions 26============== 27 281998-08-20: First version. 29 301998-08-27: The :ref:`select() <func-select>` function was introduced. 31 321998-09-10: New video standard interface. 33 341998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise 35meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the 36aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set 37this flag if they intend to access controls only, as opposed to capture 38applications which need exclusive access. The ``VIDEO_STD_XXX`` 39identifiers are now ordinals instead of flags, and the 40``video_std_construct()`` helper function takes id and 41transmission arguments. 42 431998-09-28: Revamped video standard. Made video controls individually 44enumerable. 45 461998-10-02: The ``id`` field was removed from 47struct ``video_standard`` and the color subcarrier fields were 48renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was 49renamed to :ref:`VIDIOC_ENUMSTD`, 50:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to 51:ref:`VIDIOC_ENUMINPUT`. A first draft of the 52Codec API was released. 53 541998-11-08: Many minor changes. Most symbols have been renamed. Some 55material changes to struct :c:type:`v4l2_capability`. 56 571998-11-12: The read/write directon of some ioctls was misdefined. 58 591998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, 60and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio 61controls 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 64with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from 65``videodev.h`` since it was only used once in the ``videodev`` kernel 66module. The ``YUV422`` and ``YUV411`` planar image formats were added. 67 681998-11-28: A few ioctl symbols changed. Interfaces for codecs and video 69output devices were added. 70 711999-01-14: A raw VBI capture interface was added. 72 731999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. 74 75 76V4L2 Version 0.16 1999-01-31 77============================ 78 791999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF 80are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added 81digital zoom (cropping) controls. 82 83 84V4L2 Version 0.18 1999-03-16 85============================ 86 87Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver 88writers, this changes how you implement your ioctl handler. See the 89Driver Writer's Guide. Added some more control id codes. 90 91 92V4L2 Version 0.19 1999-06-05 93============================ 94 951999-03-18: Fill in the category and catname fields of v4l2_queryctrl 96objects before passing them to the driver. Required a minor change to 97the VIDIOC_QUERYCTRL handlers in the sample drivers. 98 991999-03-31: Better compatibility for v4l memory capture ioctls. Requires 100changes to drivers to fully support new compatibility features, see 101Driver Writer's Guide and v4l2cap.c. Added new control IDs: 102V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, 103and _YUV411P to _YUV411P. 104 1051999-04-04: Added a few more control IDs. 106 1071999-04-07: Added the button control type. 108 1091999-05-02: Fixed a typo in videodev.h, and added the 110V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag. 111 1121999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a 113malfunction of this ioctl. 114 1151999-06-05: Changed the value of V4L2_CID_WHITENESS. 116 117 118V4L2 Version 0.20 (1999-09-10) 119============================== 120 121Version 0.20 introduced a number of changes which were *not backward 122compatible* with 0.19 and earlier versions. Purpose of these changes was 123to simplify the API, while making it more extensible and following 124common Linux driver API conventions. 125 1261. 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 1302. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) 131 1323. 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 1514. 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 1665. 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 1756. 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 1887. 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 2118. 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 217V4L2 Version 0.20 incremental changes 218===================================== 219 2201999-12-23: In struct :c:type:`v4l2_vbi_format` the 221``reserved1`` field became ``offset``. Previously drivers were required 222to clear the ``reserved1`` field. 223 2242000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added. 225 2262000-07-31: The ``linux/poll.h`` header is now included by 227``videodev.h`` for compatibility with the original ``videodev.h`` file. 228 2292000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were 230added. 231 2322000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added. 233 2342000-12-04: A couple typos in symbol names were fixed. 235 2362001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in 237the ``videodev.h`` header file was renamed to ``v4l2_fourcc``. 238 2392001-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 241in the ``videodevX`` patch was fixed. Users of an earlier version of 242``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2 243drivers. 244 2452001-01-26: A possible kernel-level incompatibility between the 246``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h`` 247file in Linux 2.2.x with devfs patches applied was fixed. 248 2492001-03-02: Certain V4L ioctls which pass data in both direction 250although they are defined with read-only parameter, did not work 251correctly through the backward compatibility layer. [Solution?] 252 2532001-04-13: Big endian 16-bit RGB formats were added. 254 2552001-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 259multiple tuners into account.) 260 2612000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break 262compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and 263:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the 264struct ``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 267ambiguous phrase "rising edge" was changed to "leading edge". 268 269 270V4L2 Version 0.20 2000-11-23 271============================ 272 273A number of changes were made to the raw VBI interface. 274 2751. 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 2842. 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 2923. 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 3014. 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 306V4L2 Version 0.20 2002-07-25 307============================ 308 309Added sliced VBI interface proposal. 310 311 312V4L2 in Linux 2.5.46, 2002-10 313============================= 314 315Around October-November 2002, prior to an announced feature freeze of 316Linux 2.5, the API was revised, drawing from experience with V4L2 0.20. 317This unnamed version was finally merged into Linux 2.5.46. 318 3191. As specified in :ref:`related`, drivers must make related device 320 functions available under all minor device numbers. 321 3222. 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 3313. 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 3644. 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 3775. 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 3896. 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 4057. 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 4338. 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 4379. 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 48710. 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 49511. 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 54212. 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 55013. 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 57014. 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 58115. 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 58716. 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 59217. 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 60018. 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 60619. 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 61620. 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 62121. 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 626V4L2 2003-06-19 627=============== 628 6291. 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 6332. An optional driver access priority mechanism was added, see 634 :ref:`app-pri` for details. 635 6363. 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 6564. 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 6635. :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 6686. 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 677V4L2 2003-11-05 678=============== 679 6801. 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 7132. 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 718V4L2 in Linux 2.6.6, 2004-05-09 719=============================== 720 7211. 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 727V4L2 in Linux 2.6.8 728=================== 729 7301. 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 738V4L2 spec erratum 2004-08-01 739============================ 740 7411. The return value of the :ref:`func-open` function was incorrectly 742 documented. 743 7442. Audio output ioctls end in -AUDOUT, not -AUDIOOUT. 745 7463. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took 747 the wrong argument. 748 7494. 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 756V4L2 in Linux 2.6.14 757==================== 758 7591. 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 764V4L2 in Linux 2.6.15 765==================== 766 7671. The :ref:`VIDIOC_LOG_STATUS` ioctl was added. 768 7692. 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 7763. 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 784V4L2 spec erratum 2005-11-27 785============================ 786 787The capture example in :ref:`capture-example` called the 788:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if 789cropping is supported. In the video standard selection example in 790:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used 791the wrong argument type. 792 793 794V4L2 spec erratum 2006-01-10 795============================ 796 7971. 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 8032. :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 808V4L2 spec erratum 2006-02-03 809============================ 810 8111. 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 816V4L2 spec erratum 2006-02-04 817============================ 818 8191. 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 825V4L2 in Linux 2.6.17 826==================== 827 8281. 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 8342. 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 840V4L2 spec erratum 2006-09-23 (Draft 0.15) 841========================================= 842 8431. 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 8472. 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 8503. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio 851 capability flags. 852 8534. 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 8585. The ``reserved`` array in struct 859 :c:type:`v4l2_requestbuffers` has 2 elements, 860 not 32. 861 8626. In :ref:`output` and :ref:`raw-vbi` the device file names 863 ``/dev/vout`` which never caught on were replaced by ``/dev/video``. 864 8657. 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 870V4L2 in Linux 2.6.18 871==================== 872 8731. 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 885V4L2 in Linux 2.6.19 886==================== 887 8881. 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 8982. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES` 899 and 900 :ref:`VIDIOC_ENUM_FRAMEINTERVALS` 901 were added. 902 9033. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was 904 added. 905 906 907V4L2 spec erratum 2006-10-12 (Draft 0.17) 908========================================= 909 9101. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not 911 4:2:2 format. 912 913 914V4L2 in Linux 2.6.21 915==================== 916 9171. 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 922V4L2 in Linux 2.6.22 923==================== 924 9251. 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 9292. 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 9423. 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 949V4L2 in Linux 2.6.24 950==================== 951 9521. 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 957V4L2 in Linux 2.6.25 958==================== 959 9601. 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 9632. 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 9693. 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 9784. 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 984V4L2 in Linux 2.6.26 985==================== 986 9871. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16`` 988 were added. 989 9902. Added user controls ``V4L2_CID_CHROMA_AGC`` and 991 ``V4L2_CID_COLOR_KILLER``. 992 993 994V4L2 in Linux 2.6.27 995==================== 996 9971. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl 998 and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added. 999 10002. 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 1006V4L2 in Linux 2.6.28 1007==================== 1008 10091. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and 1010 ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings. 1011 10122. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding. 1013 10143. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and 1015 ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. 1016 1017 1018V4L2 in Linux 2.6.29 1019==================== 1020 10211. 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 10272. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and 1028 ``V4L2_PIX_FMT_NV61`` were added. 1029 10303. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``, 1031 ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and 1032 ``V4L2_CID_PRIVACY``. 1033 1034 1035V4L2 in Linux 2.6.30 1036==================== 1037 10381. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added. 1039 10402. New control ``V4L2_CID_COLORFX`` was added. 1041 1042 1043V4L2 in Linux 2.6.32 1044==================== 1045 10461. 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 10492. Finalized the RDS capture API. See :ref:`rds` for more information. 1050 10513. Added new capabilities for modulators and RDS encoders. 1052 10534. Add description for libv4l API. 1054 10555. Added support for string controls via new type 1056 ``V4L2_CTRL_TYPE_STRING``. 1057 10586. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation. 1059 10607. Added FM Modulator (FM TX) Extended Control Class: 1061 ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs. 1062 10638. Added FM Receiver (FM RX) Extended Control Class: 1064 ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs. 1065 10669. Added Remote Controller chapter, describing the default Remote 1067 Controller mapping for media devices. 1068 1069 1070V4L2 in Linux 2.6.33 1071==================== 1072 10731. Added support for Digital Video timings in order to support HDTV 1074 receivers and transmitters. 1075 1076 1077V4L2 in Linux 2.6.34 1078==================== 1079 10801. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` 1081 controls to the :ref:`Camera controls class <camera-controls>`. 1082 1083 1084V4L2 in Linux 2.6.37 1085==================== 1086 10871. 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 1093V4L2 in Linux 2.6.39 1094==================== 1095 10961. The old VIDIOC_*_OLD symbols and V4L1 support were removed. 1097 10982. 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 1103V4L2 in Linux 3.1 1104================= 1105 11061. 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 1114V4L2 in Linux 3.2 1115================= 1116 11171. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to 1118 userspace. 1119 11202. 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 1125V4L2 in Linux 3.3 1126================= 1127 11281. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the 1129 :ref:`User controls class <control>`. 1130 11312. Added the device_caps field to struct v4l2_capabilities and added 1132 the new V4L2_CAP_DEVICE_CAPS capability. 1133 1134 1135V4L2 in Linux 3.4 1136================= 1137 11381. Added :ref:`JPEG compression control class <jpeg-controls>`. 1139 11402. 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 1146V4L2 in Linux 3.5 1147================= 1148 11491. Added integer menus, the new type will be 1150 V4L2_CTRL_TYPE_INTEGER_MENU. 1151 11522. 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 11563. 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 11624. Added ``V4L2_CID_COLORFX_CBCR`` control. 1163 11645. 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 1173V4L2 in Linux 3.6 1174================= 1175 11761. Replaced ``input`` in struct :c:type:`v4l2_buffer` by 1177 ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. 1178 11792. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE 1180 capabilities. 1181 11823. Added support for frequency band enumerations: 1183 :ref:`VIDIOC_ENUM_FREQ_BANDS`. 1184 1185 1186V4L2 in Linux 3.9 1187================= 1188 11891. Added timestamp types to ``flags`` field in 1190 struct :c:type:`v4l2_buffer`. See :ref:`buffer-flags`. 1191 11922. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See 1193 :ref:`ctrl-changes-flags`. 1194 1195 1196V4L2 in Linux 3.10 1197================== 1198 11991. 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 12042. Added new debugging ioctl 1205 :ref:`VIDIOC_DBG_G_CHIP_INFO`. 1206 1207 1208V4L2 in Linux 3.11 1209================== 1210 12111. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. 1212 1213 1214V4L2 in Linux 3.14 1215================== 1216 12171. In struct :c:type:`v4l2_rect`, the type of ``width`` and 1218 ``height`` fields changed from _s32 to _u32. 1219 1220 1221V4L2 in Linux 3.15 1222================== 1223 12241. Added Software Defined Radio (SDR) Interface. 1225 1226 1227V4L2 in Linux 3.16 1228================== 1229 12301. Added event V4L2_EVENT_SOURCE_CHANGE. 1231 1232 1233V4L2 in Linux 3.17 1234================== 1235 12361. Extended struct :c:type:`v4l2_pix_format`. Added 1237 format flags. 1238 12392. Added compound control types and 1240 :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. 1241 1242 1243V4L2 in Linux 3.18 1244================== 1245 12461. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera 1247 controls. 1248 1249 1250V4L2 in Linux 3.19 1251================== 1252 12531. 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 1261V4L2 in Linux 4.4 1262================= 1263 12641. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of 1265 ``V4L2_TUNER_ADC`` is deprecated now. 1266 12672. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control. 1268 12693. Added transmitter support for Software Defined Radio (SDR) Interface. 1270 1271 1272.. _other: 1273 1274Relation of V4L2 to other Linux multimedia APIs 1275=============================================== 1276 1277 1278.. _xvideo: 1279 1280X Video Extension 1281----------------- 1282 1283The X Video Extension (abbreviated XVideo or just Xv) is an extension of 1284the X Window system, implemented for example by the XFree86 project. Its 1285scope is similar to V4L2, an API to video capture and output devices for 1286X clients. Xv allows applications to display live video in a window, 1287send window contents to a TV output, and capture or output still images 1288in XPixmaps [#f1]_. With their implementation XFree86 makes the extension 1289available across many operating systems and architectures. 1290 1291Because the driver is embedded into the X server Xv has a number of 1292advantages over the V4L2 :ref:`video overlay interface <overlay>`. The 1293driver can easily determine the overlay target, i. e. visible graphics 1294memory or off-screen buffers for a destructive overlay. It can program 1295the RAMDAC for a non-destructive overlay, scaling or color-keying, or 1296the clipping functions of the video capture hardware, always in sync 1297with drawing operations or windows moving or changing their stacking 1298order. 1299 1300To combine the advantages of Xv and V4L a special Xv driver exists in 1301XFree86 and XOrg, just programming any overlay capable Video4Linux 1302device it finds. To enable it ``/etc/X11/XF86Config`` must contain these 1303lines: 1304 1305:: 1306 1307 Section "Module" 1308 Load "v4l" 1309 EndSection 1310 1311As of XFree86 4.2 this driver still supports only V4L ioctls, however it 1312should work just fine with all V4L2 devices through the V4L2 1313backward-compatibility layer. Since V4L2 permits multiple opens it is 1314possible (if supported by the V4L2 driver) to capture video while an X 1315client requested video overlay. Restrictions of simultaneous capturing 1316and overlay are discussed in :ref:`overlay` apply. 1317 1318Only marginally related to V4L2, XFree86 extended Xv to support hardware 1319YUV to RGB conversion and scaling for faster video playback, and added 1320an interface to MPEG-2 decoding hardware. This API is useful to display 1321images captured with V4L2 devices. 1322 1323 1324Digital Video 1325------------- 1326 1327V4L2 does not support digital terrestrial, cable or satellite broadcast. 1328A separate project aiming at digital receivers exists. You can find its 1329homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux 1330DVB API has no connection to the V4L2 API except that drivers for hybrid 1331hardware may support both. 1332 1333 1334Audio Interfaces 1335---------------- 1336 1337[to do - OSS/ALSA] 1338 1339 1340.. _experimental: 1341 1342Experimental API Elements 1343========================= 1344 1345The following V4L2 API elements are currently experimental and may 1346change 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 1356Obsolete API Elements 1357===================== 1358 1359The following V4L2 API elements were superseded by new interfaces and 1360should 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. 1375