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