diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/hist-v4l2.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/hist-v4l2.rst | 1374 |
1 files changed, 0 insertions, 1374 deletions
diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst deleted file mode 100644 index 9e097f34cb74..000000000000 --- a/Documentation/media/uapi/v4l/hist-v4l2.rst +++ /dev/null @@ -1,1374 +0,0 @@ -.. 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/media/uapi/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. |