.. 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``,