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