diff options
Diffstat (limited to 'Documentation/userspace-api/media/v4l/hist-v4l2.rst')
| -rw-r--r-- | Documentation/userspace-api/media/v4l/hist-v4l2.rst | 1374 |
1 files changed, 1374 insertions, 0 deletions
diff --git a/Documentation/userspace-api/media/v4l/hist-v4l2.rst b/Documentation/userspace-api/media/v4l/hist-v4l2.rst new file mode 100644 index 000000000000..7913d017cd33 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/hist-v4l2.rst @@ -0,0 +1,1374 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/userspace-api/media/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _hist-v4l2: + +*********************** +Changes of the V4L2 API +*********************** + +Soon after the V4L API was added to the kernel it was criticised as too +inflexible. In August 1998 Bill Dirks proposed a number of improvements +and began to work on documentation, example drivers and applications. +With the help of other volunteers this eventually became the V4L2 API, +not just an extension but a replacement for the V4L API. However it took +another four years and two stable kernel releases until the new API was +finally accepted for inclusion into the kernel in its present form. + + +Early Versions +============== + +1998-08-20: First version. + +1998-08-27: The :ref:`select() <func-select>` function was introduced. + +1998-09-10: New video standard interface. + +1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise +meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the +aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set +this flag if they intend to access controls only, as opposed to capture +applications which need exclusive access. The ``VIDEO_STD_XXX`` +identifiers are now ordinals instead of flags, and the +``video_std_construct()`` helper function takes id and +transmission arguments. + +1998-09-28: Revamped video standard. Made video controls individually +enumerable. + +1998-10-02: The ``id`` field was removed from struct +struct ``video_standard`` and the color subcarrier fields were +renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was +renamed to :ref:`VIDIOC_ENUMSTD`, +:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to +:ref:`VIDIOC_ENUMINPUT`. A first draft of the +Codec API was released. + +1998-11-08: Many minor changes. Most symbols have been renamed. Some +material changes to struct :c:type:`v4l2_capability`. + +1998-11-12: The read/write directon of some ioctls was misdefined. + +1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, +and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio +controls are now accessible with the +:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and +:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting +with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from +``videodev.h`` since it was only used once in the ``videodev`` kernel +module. The ``YUV422`` and ``YUV411`` planar image formats were added. + +1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video +output devices were added. + +1999-01-14: A raw VBI capture interface was added. + +1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. + + +V4L2 Version 0.16 1999-01-31 +============================ + +1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF +are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added +digital zoom (cropping) controls. + + +V4L2 Version 0.18 1999-03-16 +============================ + +Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver +writers, this changes how you implement your ioctl handler. See the +Driver Writer's Guide. Added some more control id codes. + + +V4L2 Version 0.19 1999-06-05 +============================ + +1999-03-18: Fill in the category and catname fields of v4l2_queryctrl +objects before passing them to the driver. Required a minor change to +the VIDIOC_QUERYCTRL handlers in the sample drivers. + +1999-03-31: Better compatibility for v4l memory capture ioctls. Requires +changes to drivers to fully support new compatibility features, see +Driver Writer's Guide and v4l2cap.c. Added new control IDs: +V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, +and _YUV411P to _YUV411P. + +1999-04-04: Added a few more control IDs. + +1999-04-07: Added the button control type. + +1999-05-02: Fixed a typo in videodev.h, and added the +V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag. + +1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a +malfunction of this ioctl. + +1999-06-05: Changed the value of V4L2_CID_WHITENESS. + + +V4L2 Version 0.20 (1999-09-10) +============================== + +Version 0.20 introduced a number of changes which were *not backward +compatible* with 0.19 and earlier versions. Purpose of these changes was +to simplify the API, while making it more extensible and following +common Linux driver API conventions. + +1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct + :c:type:`v4l2_clip` was changed for compatibility with + v4l. (1999-08-30) + +2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) + +3. All ioctl() commands that used an integer argument now take a pointer + to an integer. Where it makes sense, ioctls will return the actual + new value in the integer pointed to by the argument, a common + convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW, + VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, + VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example + + + .. code-block:: c + + err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); + + becomes + + + .. code-block:: c + + int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); + +4. All the different get- and set-format commands were swept into one + :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a + type field selecting the union member as parameter. Purpose is to + simplify the API by eliminating several ioctls and to allow new and + driver private data streams without adding new ioctls. + + This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``, + ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, + ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format + structure struct :c:type:`v4l2_format` was renamed to struct + :c:type:`v4l2_pix_format`, while struct + :c:type:`v4l2_format` is now the envelopping structure + for all format negotiations. + +5. Similar to the changes above, the ``VIDIOC_G_PARM`` and + ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and + ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct + :c:type:`v4l2_streamparm` selects the respective + union member. + + This change obsoletes the ``VIDIOC_G_OUTPARM`` and + ``VIDIOC_S_OUTPARM`` ioctls. + +6. Control enumeration was simplified, and two new control flags were + introduced and one dropped. The ``catname`` field was replaced by a + ``group`` field. + + Drivers can now flag unsupported and temporarily unavailable controls + with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED`` + respectively. The ``group`` name indicates a possibly narrower + classification than the ``category``. In other words, there may be + multiple groups within a category. Controls within a group would + typically be drawn within a group box. Controls in different + categories might have a greater separation, or may even appear in + separate windows. + +7. The struct :c:type:`v4l2_buffer` ``timestamp`` was + changed to a 64 bit integer, containing the sampling or output time + of the frame in nanoseconds. Additionally timestamps will be in + absolute system time, not starting from zero at the beginning of a + stream. The data type name for timestamps is stamp_t, defined as a + signed 64-bit integer. Output devices should not send a buffer out + until the time in the timestamp field has arrived. I would like to + follow SGI's lead, and adopt a multimedia timestamping system like + their UST (Unadjusted System Time). See + http://web.archive.org/web/\*/http://reality.sgi.com + /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are + 64-bit signed integers (not struct timeval's) and given in nanosecond + units. The UST clock starts at zero when the system is booted and + runs continuously and uniformly. It takes a little over 292 years for + UST to overflow. There is no way to set the UST clock. The regular + Linux time-of-day clock can be changed periodically, which would + cause errors if it were being used for timestamping a multimedia + stream. A real UST style clock will require some support in the + kernel that is not there yet. But in anticipation, I will change the + timestamp field to a 64-bit integer, and I will change the + v4l2_masterclock_gettime() function (used only by drivers) to + return a 64-bit integer. + +8. A ``sequence`` field was added to struct + :c:type:`v4l2_buffer`. The ``sequence`` field counts + captured frames, it is ignored by output devices. When a capture + driver drops a frame, the sequence number of that frame is skipped. + + +V4L2 Version 0.20 incremental changes +===================================== + +1999-12-23: In struct :c:type:`v4l2_vbi_format` the +``reserved1`` field became ``offset``. Previously drivers were required +to clear the ``reserved1`` field. + +2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added. + +2000-07-31: The ``linux/poll.h`` header is now included by +``videodev.h`` for compatibility with the original ``videodev.h`` file. + +2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were +added. + +2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added. + +2000-12-04: A couple typos in symbol names were fixed. + +2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in +the ``videodev.h`` header file was renamed to ``v4l2_fourcc``. + +2001-01-25: A possible driver-level compatibility problem between the +``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included +in the ``videodevX`` patch was fixed. Users of an earlier version of +``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2 +drivers. + +2001-01-26: A possible kernel-level incompatibility between the +``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h`` +file in Linux 2.2.x with devfs patches applied was fixed. + +2001-03-02: Certain V4L ioctls which pass data in both direction +although they are defined with read-only parameter, did not work +correctly through the backward compatibility layer. [Solution?] + +2001-04-13: Big endian 16-bit RGB formats were added. + +2001-09-17: New YUV formats and the +:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and +:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added. +(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take +multiple tuners into account.) + +2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break +compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and +:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct +struct ``v4l2_fmt`` ``type`` field does not contain +``V4L2_BUF_TYPE_VBI``. In the documentation of the struct +:c:type:`v4l2_vbi_format` ``offset`` field the +ambiguous phrase "rising edge" was changed to "leading edge". + + +V4L2 Version 0.20 2000-11-23 +============================ + +A number of changes were made to the raw VBI interface. + +1. Figures clarifying the line numbering scheme were added to the V4L2 + API specification. The ``start``\ [0] and ``start``\ [1] fields no + longer count line numbers beginning at zero. Rationale: a) The + previous definition was unclear. b) The ``start``\ [] values are + ordinal numbers. c) There is no point in inventing a new line + numbering scheme. We now use line number as defined by ITU-R, period. + Compatibility: Add one to the start values. Applications depending on + the previous semantics may not function correctly. + +2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to + "(count[0] + count[1]) > 0". Rationale: Drivers may allocate + resources at scan line granularity and some data services are + transmitted only on the first field. The comment that both ``count`` + values will usually be equal is misleading and pointless and has been + removed. This change *breaks compatibility* with earlier versions: + Drivers may return ``EINVAL``, applications may not function correctly. + +3. Drivers are again permitted to return negative (unknown) start values + as proposed earlier. Why this feature was dropped is unclear. This + change may *break compatibility* with applications depending on the + start values being positive. The use of ``EBUSY`` and ``EINVAL`` + error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was + clarified. The ``EBUSY`` error code was finally documented, and the + ``reserved2`` field which was previously mentioned only in the + ``videodev.h`` header file. + +4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT`` + were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the + latter was missing in the ``videodev.h`` file. + + +V4L2 Version 0.20 2002-07-25 +============================ + +Added sliced VBI interface proposal. + + +V4L2 in Linux 2.5.46, 2002-10 +============================= + +Around October-November 2002, prior to an announced feature freeze of +Linux 2.5, the API was revised, drawing from experience with V4L2 0.20. +This unnamed version was finally merged into Linux 2.5.46. + +1. As specified in :ref:`related`, drivers must make related device + functions available under all minor device numbers. + +2. The :ref:`open() <func-open>` function requires access mode + ``O_RDWR`` regardless of the device type. All V4L2 drivers + exchanging data with applications must support the ``O_NONBLOCK`` + flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the + meaningless ``O_TRUNC`` to indicate accesses without data exchange + (panel applications) was dropped. Drivers must stay in "panel mode" + until the application attempts to initiate a data exchange, see + :ref:`open`. + +3. The struct :c:type:`v4l2_capability` changed + dramatically. Note that also the size of the structure changed, + which is encoded in the ioctl request code, thus older V4L2 devices + will respond with an ``EINVAL`` error code to the new + :ref:`VIDIOC_QUERYCAP` ioctl. + + There are new fields to identify the driver, a new RDS device + function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag + indicates if the device has any audio connectors, another I/O + capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these + changes the ``type`` field became a bit set and was merged into the + ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to + ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced + ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and + ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``. + ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into + ``V4L2_CAP_READWRITE``. + + The redundant fields ``inputs``, ``outputs`` and ``audios`` were + removed. These properties can be determined as described in + :ref:`video` and :ref:`audio`. + + The somewhat volatile and therefore barely useful fields + ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``, + ``maxframerate`` were removed. This information is available as + described in :ref:`format` and :ref:`standard`. + + ``V4L2_FLAG_SELECT`` was removed. We believe the select() function + is important enough to require support of it in all V4L2 drivers + exchanging data with applications. The redundant + ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is + available as described in :ref:`format`. + +4. In struct :c:type:`v4l2_input` the ``assoc_audio`` + field and the ``capability`` field and its only flag + ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field. + Instead of linking one video input to one audio input this field + reports all audio inputs this video input combines with. + + New fields are ``tuner`` (reversing the former link from tuners to + video inputs), ``std`` and ``status``. + + Accordingly struct :c:type:`v4l2_output` lost its + ``capability`` and ``assoc_audio`` fields. ``audioset``, + ``modulator`` and ``std`` where added instead. + +5. The struct :c:type:`v4l2_audio` field ``audio`` was + renamed to ``index``, for consistency with other structures. A new + capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the + audio input in question supports stereo sound. + ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags + where removed. This can be easily implemented using controls. + (However the same applies to AVL which is still there.) + + Again for consistency the struct + :c:type:`v4l2_audioout` field ``audio`` was renamed + to ``index``. + +6. The struct :c:type:`v4l2_tuner` ``input`` field was + replaced by an ``index`` field, permitting devices with multiple + tuners. The link between video inputs and tuners is now reversed, + inputs point to their tuner. The ``std`` substructure became a + simple set (more about this below) and moved into struct + :c:type:`v4l2_input`. A ``type`` field was added. + + Accordingly in struct :c:type:`v4l2_modulator` the + ``output`` was replaced by an ``index`` field. + + In struct :c:type:`v4l2_frequency` the ``port`` + field was replaced by a ``tuner`` field containing the respective + tuner or modulator index number. A tuner ``type`` field was added + and the ``reserved`` field became larger for future extensions + (satellite tuners in particular). + +7. The idea of completely transparent video standards was dropped. + Experience showed that applications must be able to work with video + standards beyond presenting the user a menu. Instead of enumerating + supported standards with an ioctl applications can now refer to + standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols + defined in the ``videodev2.h`` header file. For details see + :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and + :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this + type as argument. :ref:`VIDIOC_QUERYSTD` was + added to autodetect the received standard, if the hardware has this + capability. In struct :c:type:`v4l2_standard` an + ``index`` field was added for + :ref:`VIDIOC_ENUMSTD`. A + :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as + machine readable identifier, also replacing the ``transmission`` + field. The misleading ``framerate`` field was renamed to + ``frameperiod``. The now obsolete ``colorstandard`` information, + originally needed to distguish between variations of standards, were + removed. + + Struct ``v4l2_enumstd`` ceased to be. + :ref:`VIDIOC_ENUMSTD` now takes a pointer to a + struct :c:type:`v4l2_standard` directly. The + information which standards are supported by a particular video + input or output moved into struct :c:type:`v4l2_input` + and struct :c:type:`v4l2_output` fields named ``std``, + respectively. + +8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields + ``category`` and ``group`` did not catch on and/or were not + implemented as expected and therefore removed. + +9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to + negotiate data formats as with + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of + programming the hardware and regardless of I/O in progress. + + In struct :c:type:`v4l2_format` the ``fmt`` union was + extended to contain struct :c:type:`v4l2_window`. All + image format negotiations are now possible with ``VIDIOC_G_FMT``, + ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN`` + and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were + removed. The ``type`` field changed to type enum + :c:type:`v4l2_buf_type` and the buffer type names + changed as follows. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Old defines + - enum :c:type:`v4l2_buf_type` + * - ``V4L2_BUF_TYPE_CAPTURE`` + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + * - ``V4L2_BUF_TYPE_CODECIN`` + - Omitted for now + * - ``V4L2_BUF_TYPE_CODECOUT`` + - Omitted for now + * - ``V4L2_BUF_TYPE_EFFECTSIN`` + - Omitted for now + * - ``V4L2_BUF_TYPE_EFFECTSIN2`` + - Omitted for now + * - ``V4L2_BUF_TYPE_EFFECTSOUT`` + - Omitted for now + * - ``V4L2_BUF_TYPE_VIDEOOUT`` + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + * - ``-`` + - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + * - ``-`` + - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + * - ``-`` + - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + * - ``-`` + - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + * - ``-`` + - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + * - ``V4L2_BUF_TYPE_PRIVATE_BASE`` + - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated) + + +10. In struct :c:type:`v4l2_fmtdesc` a enum + :c:type:`v4l2_buf_type` field named ``type`` was + added as in struct :c:type:`v4l2_format`. The + ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed. + These calls can be replaced by + :ref:`VIDIOC_ENUM_FMT` with type + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. + +11. In struct :c:type:`v4l2_pix_format` the ``depth`` + field was removed, assuming applications which recognize the format + by its four-character-code already know the color depth, and others + do not care about it. The same rationale lead to the removal of the + ``V4L2_FMT_FLAG_COMPRESSED`` flag. The + ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers + are not supposed to convert images in kernel space. A user library + of conversion functions should be provided instead. The + ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can + set the ``bytesperline`` field to zero to get a reasonable default. + Since the remaining flags were replaced as well, the ``flags`` field + itself was removed. + + The interlace flags were replaced by a enum + :c:type:`v4l2_field` value in a newly added ``field`` + field. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Old flag + - enum :c:type:`v4l2_field` + * - ``V4L2_FMT_FLAG_NOT_INTERLACED`` + - ? + * - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED`` + - ``V4L2_FIELD_INTERLACED`` + * - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD`` + - ``V4L2_FIELD_TOP`` + * - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD`` + - ``V4L2_FIELD_BOTTOM`` + * - ``-`` + - ``V4L2_FIELD_SEQ_TB`` + * - ``-`` + - ``V4L2_FIELD_SEQ_BT`` + * - ``-`` + - ``V4L2_FIELD_ALTERNATE`` + + + The color space flags were replaced by a enum + :c:type:`v4l2_colorspace` value in a newly added + ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``, + ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or + ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``. + +12. In struct :c:type:`v4l2_requestbuffers` the + ``type`` field was properly defined as enum + :c:type:`v4l2_buf_type`. Buffer types changed as + mentioned above. A new ``memory`` field of type enum + :c:type:`v4l2_memory` was added to distinguish between + I/O methods using buffers allocated by the driver or the + application. See :ref:`io` for details. + +13. In struct :c:type:`v4l2_buffer` the ``type`` field was + properly defined as enum :c:type:`v4l2_buf_type`. + Buffer types changed as mentioned above. A ``field`` field of type + enum :c:type:`v4l2_field` was added to indicate if a + buffer contains a top or bottom field. The old field flags were + removed. Since no unadjusted system time clock was added to the + kernel as planned, the ``timestamp`` field changed back from type + stamp_t, an unsigned 64 bit integer expressing the sample time in + nanoseconds, to struct :c:type:`timeval`. With the addition + of a second memory mapping method the ``offset`` field moved into + union ``m``, and a new ``memory`` field of type enum + :c:type:`v4l2_memory` was added to distinguish between + I/O methods. See :ref:`io` for details. + + The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility + layer, after changes to this code it was no longer needed. The + ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was + indeed allocated in device memory rather than DMA-able system + memory. It was barely useful and so was removed. + +14. In struct :c:type:`v4l2_framebuffer` the + ``base[3]`` array anticipating double- and triple-buffering in + off-screen video memory, however without defining a synchronization + mechanism, was replaced by a single pointer. The + ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were + removed. Applications can determine this capability more accurately + using the new cropping and scaling interface. The + ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by + ``V4L2_FBUF_CAP_LIST_CLIPPING`` and + ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. + +15. In struct :c:type:`v4l2_clip` the ``x``, ``y``, + ``width`` and ``height`` field moved into a ``c`` substructure of + type struct :c:type:`v4l2_rect`. The ``x`` and ``y`` + fields were renamed to ``left`` and ``top``, i. e. offsets to a + context dependent origin. + +16. In struct :c:type:`v4l2_window` the ``x``, ``y``, + ``width`` and ``height`` field moved into a ``w`` substructure as + above. A ``field`` field of type :c:type:`v4l2_field` was added to + distinguish between field and frame (interlaced) overlay. + +17. The digital zoom interface, including struct + struct ``v4l2_zoomcap``, struct + struct ``v4l2_zoom``, ``V4L2_ZOOM_NONCAP`` and + ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and + scaling interface. The previously unused struct + struct :c:type:`v4l2_cropcap` and struct :c:type:`v4l2_crop` + where redefined for this purpose. See :ref:`crop` for details. + +18. In struct :c:type:`v4l2_vbi_format` the + ``SAMPLE_FORMAT`` field now contains a four-character-code as used + to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces + the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was + extended. + +19. In struct :c:type:`v4l2_captureparm` the type of + the ``timeperframe`` field changed from unsigned long to struct + :c:type:`v4l2_fract`. This allows the accurate + expression of multiples of the NTSC-M frame rate 30000 / 1001. A new + field ``readbuffers`` was added to control the driver behaviour in + read I/O mode. + + Similar changes were made to struct + :c:type:`v4l2_outputparm`. + +20. The struct ``v4l2_performance`` and + ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the + :ref:`read/write I/O method <rw>`, which is limited anyway, this + information is already available to applications. + +21. The example transformation from RGB to YCbCr color space in the old + V4L2 documentation was inaccurate, this has been corrected in + :ref:`pixfmt`. + + +V4L2 2003-06-19 +=============== + +1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices. + Prior to this change radio devices would identify solely by having + exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``. + +2. An optional driver access priority mechanism was added, see + :ref:`app-pri` for details. + +3. The audio input and output interface was found to be incomplete. + + Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would + enumerate the available audio inputs. An ioctl to determine the + current audio input, if more than one combines with the current video + input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to + ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The + :ref:`VIDIOC_ENUMAUDIO` ioctl was added to + enumerate audio inputs, while + :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current + audio input. + + The same changes were made to + :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and + :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`. + + Until further the "videodev" module will automatically translate + between the old and new ioctls, but drivers and applications must be + updated to successfully compile again. + +4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly + defined with write-read parameter. It was changed to write-only, + while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``. + The old ioctl was removed on Kernel 2.6.39. Until further the + "videodev" kernel module will automatically translate to the new + version, so drivers must be recompiled, but not applications. + +5. :ref:`overlay` incorrectly stated that clipping rectangles define + regions where the video can be seen. Correct is that clipping + rectangles define regions where *no* video shall be displayed and so + the graphics surface can be seen. + +6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with + write-only parameter, inconsistent with other ioctls modifying their + argument. They were changed to write-read, while a ``_OLD`` suffix + was added to the write-only versions. The old ioctls were removed on + Kernel 2.6.39. Drivers and applications assuming a constant parameter + need an update. + + +V4L2 2003-11-05 +=============== + +1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly + transferred from Bill Dirks' V4L2 specification. Descriptions below + refer to bytes in memory, in ascending address order. + + + + .. flat-table:: + :header-rows: 1 + :stub-columns: 0 + + * - Symbol + - In this document prior to revision 0.5 + - Corrected + * - ``V4L2_PIX_FMT_RGB24`` + - B, G, R + - R, G, B + * - ``V4L2_PIX_FMT_BGR24`` + - R, G, B + - B, G, R + * - ``V4L2_PIX_FMT_RGB32`` + - B, G, R, X + - R, G, B, X + * - ``V4L2_PIX_FMT_BGR32`` + - R, G, B, X + - B, G, R, X + + + The ``V4L2_PIX_FMT_BGR24`` example was always correct. + + In :ref:`v4l-image-properties` the mapping of the V4L + ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2 + pixel formats was accordingly corrected. + +2. Unrelated to the fixes above, drivers may still interpret some V4L2 + RGB pixel formats differently. These issues have yet to be addressed, + for details see :ref:`pixfmt-rgb`. + + +V4L2 in Linux 2.6.6, 2004-05-09 +=============================== + +1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly + defined with read-only parameter. It is now defined as write-read + ioctl, while the read-only version was renamed to + ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. + + +V4L2 in Linux 2.6.8 +=================== + +1. A new field ``input`` (former ``reserved[0]``) was added to the + struct :c:type:`v4l2_buffer` structure. Purpose of this + field is to alternate between video inputs (e. g. cameras) in step + with the video capturing process. This function must be enabled with + the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no + longer read-only. + + +V4L2 spec erratum 2004-08-01 +============================ + +1. The return value of the :ref:`func-open` function was incorrectly + documented. + +2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT. + +3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took + the wrong argument. + +4. The documentation of the :ref:`VIDIOC_QBUF` and + :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the + struct :c:type:`v4l2_buffer` ``memory`` field. It was + also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` + error code was not documented. + + +V4L2 in Linux 2.6.14 +==================== + +1. A new sliced VBI interface was added. It is documented in + :ref:`sliced` and replaces the interface first proposed in V4L2 + specification 0.8. + + +V4L2 in Linux 2.6.15 +==================== + +1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added. + +2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``, + ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and + ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and + ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60`` + set now includes ``V4L2_STD_NTSC_443``. See also + :ref:`v4l2-std-id`. + +3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to + ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their + argument was replaced by a struct + ``v4l2_mpeg_compression`` pointer. (The + ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed + in Linux 2.6.25.) + + +V4L2 spec erratum 2005-11-27 +============================ + +The capture example in :ref:`capture-example` called the +:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if +cropping is supported. In the video standard selection example in +:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used +the wrong argument type. + + +V4L2 spec erratum 2006-01-10 +============================ + +1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct + :c:type:`v4l2_input` not only indicates if the color + killer is enabled, but also if it is active. (The color killer + disables color decoding when it detects no color in the video signal + to improve the image quality.) + +2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not + write-only as stated on its reference page. The ioctl changed in 2003 + as noted above. + + +V4L2 spec erratum 2006-02-03 +============================ + +1. In struct :c:type:`v4l2_captureparm` and struct + :c:type:`v4l2_outputparm` the ``timeperframe`` + field gives the time in seconds, not microseconds. + + +V4L2 spec erratum 2006-02-04 +============================ + +1. The ``clips`` field in struct :c:type:`v4l2_window` + must point to an array of struct :c:type:`v4l2_clip`, not + a linked list, because drivers ignore the struct + struct :c:type:`v4l2_clip`. ``next`` pointer. + + +V4L2 in Linux 2.6.17 +==================== + +1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M + South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``, + ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and + ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and + ``V4L2_STD_SECAM_LC`` respectively. + +2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both + languages of a bilingual program. The use of + ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See + the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. + + +V4L2 spec erratum 2006-09-23 (Draft 0.15) +========================================= + +1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and + ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were + not mentioned along with other buffer types. + +2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct + :c:type:`v4l2_audio` ``mode`` field is a flags field. + +3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio + capability flags. + +4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications + must initialize the tuner ``type`` field of struct + :c:type:`v4l2_frequency` before calling + :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. + +5. The ``reserved`` array in struct + :c:type:`v4l2_requestbuffers` has 2 elements, + not 32. + +6. In :ref:`output` and :ref:`raw-vbi` the device file names + ``/dev/vout`` which never caught on were replaced by ``/dev/video``. + +7. With Linux 2.6.15 the possible range for VBI device minor numbers was + extended from 224-239 to 224-255. Accordingly device file names + ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. + + +V4L2 in Linux 2.6.18 +==================== + +1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and + :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a + flag to skip unsupported controls with + :ref:`VIDIOC_QUERYCTRL`, new control types + ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS`` + (:c:type:`v4l2_ctrl_type`), and new control flags + ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``, + ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` + (:ref:`control-flags`). See :ref:`extended-controls` for details. + + +V4L2 in Linux 2.6.19 +==================== + +1. In struct :c:type:`v4l2_sliced_vbi_cap` a + buffer type field was added replacing a reserved field. Note on + architectures where the size of enum types differs from int types the + size of the structure changed. The + :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl + was redefined from being read-only to write-read. Applications must + initialize the type field and clear the reserved fields now. These + changes may *break the compatibility* with older drivers and + applications. + +2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES` + and + :ref:`VIDIOC_ENUM_FRAMEINTERVALS` + were added. + +3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`pixfmt-rgb`) was + added. + + +V4L2 spec erratum 2006-10-12 (Draft 0.17) +========================================= + +1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not + 4:2:2 format. + + +V4L2 in Linux 2.6.21 +==================== + +1. The ``videodev2.h`` header file is now dual licensed under GNU + General Public License version two or later, and under a 3-clause + BSD-style license. + + +V4L2 in Linux 2.6.22 +==================== + +1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and + ``V4L2_FIELD_INTERLACED_BT`` were added. See :c:type:`v4l2_field` for + details. + +2. Three new clipping/blending methods with a global or straight or + inverted local alpha value were added to the video overlay interface. + See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` + and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details. + + A new ``global_alpha`` field was added to + :c:type:`v4l2_window`, extending the structure. This + may *break compatibility* with applications using a struct + struct :c:type:`v4l2_window` directly. However the + :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a + pointer to a :c:type:`v4l2_format` parent structure + with padding bytes at the end, are not affected. + +3. The format of the ``chromakey`` field in struct + :c:type:`v4l2_window` changed from "host order RGB32" + to a pixel value in the same format as the framebuffer. This may + *break compatibility* with existing applications. Drivers supporting + the "host order RGB32" format are not known. + + +V4L2 in Linux 2.6.24 +==================== + +1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``, + ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and + ``V4L2_PIX_FMT_YUV32`` were added. + + +V4L2 in Linux 2.6.25 +==================== + +1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and + :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added. + +2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``, + ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``, + ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were + added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``, + ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated. + +3. A :ref:`Camera controls class <camera-controls>` was added, with + the new controls ``V4L2_CID_EXPOSURE_AUTO``, + ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``, + ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``, + ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``, + ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``, + ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and + ``V4L2_CID_FOCUS_AUTO``. + +4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which + were superseded by the :ref:`extended controls <extended-controls>` + interface in Linux 2.6.18, where finally removed from the + ``videodev2.h`` header file. + + +V4L2 in Linux 2.6.26 +==================== + +1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16`` + were added. + +2. Added user controls ``V4L2_CID_CHROMA_AGC`` and + ``V4L2_CID_COLOR_KILLER``. + + +V4L2 in Linux 2.6.27 +==================== + +1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl + and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added. + +2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``, + ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``, + ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, + ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. + + +V4L2 in Linux 2.6.28 +==================== + +1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and + ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings. + +2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding. + +3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and + ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. + + +V4L2 in Linux 2.6.29 +==================== + +1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to + ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was + introduced in its place. The old struct + struct ``v4l2_chip_ident`` was renamed to + struct ``v4l2_chip_ident_old``. + +2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and + ``V4L2_PIX_FMT_NV61`` were added. + +3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``, + ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and + ``V4L2_CID_PRIVACY``. + + +V4L2 in Linux 2.6.30 +==================== + +1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added. + +2. New control ``V4L2_CID_COLORFX`` was added. + + +V4L2 in Linux 2.6.32 +==================== + +1. In order to be easier to compare a V4L2 API and a kernel version, now + V4L2 API is numbered using the Linux Kernel version numeration. + +2. Finalized the RDS capture API. See :ref:`rds` for more information. + +3. Added new capabilities for modulators and RDS encoders. + +4. Add description for libv4l API. + +5. Added support for string controls via new type + ``V4L2_CTRL_TYPE_STRING``. + +6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation. + +7. Added FM Modulator (FM TX) Extended Control Class: + ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs. + +8. Added FM Receiver (FM RX) Extended Control Class: + ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs. + +9. Added Remote Controller chapter, describing the default Remote + Controller mapping for media devices. + + +V4L2 in Linux 2.6.33 +==================== + +1. Added support for Digital Video timings in order to support HDTV + receivers and transmitters. + + +V4L2 in Linux 2.6.34 +==================== + +1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` + controls to the :ref:`Camera controls class <camera-controls>`. + + +V4L2 in Linux 2.6.37 +==================== + +1. Remove the vtx (videotext/teletext) API. This API was no longer used + and no hardware exists to verify the API. Nor were any userspace + applications found that used it. It was originally scheduled for + removal in 2.6.35. + + +V4L2 in Linux 2.6.39 +==================== + +1. The old VIDIOC_*_OLD symbols and V4L1 support were removed. + +2. Multi-planar API added. Does not affect the compatibility of current + drivers and applications. See :ref:`multi-planar API <planar-apis>` + for details. + + +V4L2 in Linux 3.1 +================= + +1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a + per-driver one. + + Standardize an error code for invalid ioctl. + + Added V4L2_CTRL_TYPE_BITMASK. + + +V4L2 in Linux 3.2 +================= + +1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to + userspace. + +2. Add selection API for extended control over cropping and composing. + Does not affect the compatibility of current drivers and + applications. See :ref:`selection API <selection-api>` for details. + + +V4L2 in Linux 3.3 +================= + +1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the + :ref:`User controls class <control>`. + +2. Added the device_caps field to struct v4l2_capabilities and added + the new V4L2_CAP_DEVICE_CAPS capability. + + +V4L2 in Linux 3.4 +================= + +1. Added :ref:`JPEG compression control class <jpeg-controls>`. + +2. Extended the DV Timings API: + :ref:`VIDIOC_ENUM_DV_TIMINGS`, + :ref:`VIDIOC_QUERY_DV_TIMINGS` and + :ref:`VIDIOC_DV_TIMINGS_CAP`. + + +V4L2 in Linux 3.5 +================= + +1. Added integer menus, the new type will be + V4L2_CTRL_TYPE_INTEGER_MENU. + +2. Added selection API for V4L2 subdev interface: + :ref:`VIDIOC_SUBDEV_G_SELECTION` and + :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`. + +3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``, + ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``, + ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and + ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the + ``V4L2_CID_COLORFX`` control. + +4. Added ``V4L2_CID_COLORFX_CBCR`` control. + +5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``, + ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``, + ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``, + ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``, + ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``, + ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, + ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. + + +V4L2 in Linux 3.6 +================= + +1. Replaced ``input`` in struct :c:type:`v4l2_buffer` by + ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. + +2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE + capabilities. + +3. Added support for frequency band enumerations: + :ref:`VIDIOC_ENUM_FREQ_BANDS`. + + +V4L2 in Linux 3.9 +================= + +1. Added timestamp types to ``flags`` field in + struct :c:type:`v4l2_buffer`. See :ref:`buffer-flags`. + +2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See + :ref:`ctrl-changes-flags`. + + +V4L2 in Linux 3.10 +================== + +1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET, + VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and + VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output + capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. + +2. Added new debugging ioctl + :ref:`VIDIOC_DBG_G_CHIP_INFO`. + + +V4L2 in Linux 3.11 +================== + +1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. + + +V4L2 in Linux 3.14 +================== + +1. In struct :c:type:`v4l2_rect`, the type of ``width`` and + ``height`` fields changed from _s32 to _u32. + + +V4L2 in Linux 3.15 +================== + +1. Added Software Defined Radio (SDR) Interface. + + +V4L2 in Linux 3.16 +================== + +1. Added event V4L2_EVENT_SOURCE_CHANGE. + + +V4L2 in Linux 3.17 +================== + +1. Extended struct :c:type:`v4l2_pix_format`. Added + format flags. + +2. Added compound control types and + :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. + + +V4L2 in Linux 3.18 +================== + +1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera + controls. + + +V4L2 in Linux 3.19 +================== + +1. Rewrote Colorspace chapter, added new enum + :c:type:`v4l2_ycbcr_encoding` and enum + :c:type:`v4l2_quantization` fields to struct + :c:type:`v4l2_pix_format`, struct + :c:type:`v4l2_pix_format_mplane` and + struct :c:type:`v4l2_mbus_framefmt`. + + +V4L2 in Linux 4.4 +================= + +1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of + ``V4L2_TUNER_ADC`` is deprecated now. + +2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control. + +3. Added transmitter support for Software Defined Radio (SDR) Interface. + + +.. _other: + +Relation of V4L2 to other Linux multimedia APIs +=============================================== + + +.. _xvideo: + +X Video Extension +----------------- + +The X Video Extension (abbreviated XVideo or just Xv) is an extension of +the X Window system, implemented for example by the XFree86 project. Its +scope is similar to V4L2, an API to video capture and output devices for +X clients. Xv allows applications to display live video in a window, +send window contents to a TV output, and capture or output still images +in XPixmaps [#f1]_. With their implementation XFree86 makes the extension +available across many operating systems and architectures. + +Because the driver is embedded into the X server Xv has a number of +advantages over the V4L2 :ref:`video overlay interface <overlay>`. The +driver can easily determine the overlay target, i. e. visible graphics +memory or off-screen buffers for a destructive overlay. It can program +the RAMDAC for a non-destructive overlay, scaling or color-keying, or +the clipping functions of the video capture hardware, always in sync +with drawing operations or windows moving or changing their stacking +order. + +To combine the advantages of Xv and V4L a special Xv driver exists in +XFree86 and XOrg, just programming any overlay capable Video4Linux +device it finds. To enable it ``/etc/X11/XF86Config`` must contain these +lines: + +:: + + Section "Module" + Load "v4l" + EndSection + +As of XFree86 4.2 this driver still supports only V4L ioctls, however it +should work just fine with all V4L2 devices through the V4L2 +backward-compatibility layer. Since V4L2 permits multiple opens it is +possible (if supported by the V4L2 driver) to capture video while an X +client requested video overlay. Restrictions of simultaneous capturing +and overlay are discussed in :ref:`overlay` apply. + +Only marginally related to V4L2, XFree86 extended Xv to support hardware +YUV to RGB conversion and scaling for faster video playback, and added +an interface to MPEG-2 decoding hardware. This API is useful to display +images captured with V4L2 devices. + + +Digital Video +------------- + +V4L2 does not support digital terrestrial, cable or satellite broadcast. +A separate project aiming at digital receivers exists. You can find its +homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux +DVB API has no connection to the V4L2 API except that drivers for hybrid +hardware may support both. + + +Audio Interfaces +---------------- + +[to do - OSS/ALSA] + + +.. _experimental: + +Experimental API Elements +========================= + +The following V4L2 API elements are currently experimental and may +change in the future. + +- :ref:`VIDIOC_DBG_G_REGISTER` and + :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls. + +- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. + + +.. _obsolete: + +Obsolete API Elements +===================== + +The following V4L2 API elements were superseded by new interfaces and +should not be implemented in new drivers. + +- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended + Controls, :ref:`extended-controls`. + +- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, + VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use + the DV Timings API (:ref:`dv-timings`). + +- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use + ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``, + :ref:`VIDIOC_SUBDEV_G_SELECTION`. + +.. [#f1] + This is not implemented in XFree86. |