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