Documentation/media/uapi/v4l/diff-v4l.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _diff-v4l:
   4
   5 ********************************
   6 Differences between V4L and V4L2
   7 ********************************
   8
   9 The Video For Linux API was first introduced in Linux 2.1 to unify and
  10 replace various TV and radio device related interfaces, developed
  11 independently by driver writers in prior years. Starting with Linux 2.5
  12 the much improved V4L2 API replaces the V4L API. The support for the old
  13 V4L calls were removed from Kernel, but the library :ref:`libv4l`
  14 supports the conversion of a V4L API system call into a V4L2 one.
  15
  16
  17 Opening and Closing Devices
  18 ===========================
  19
  20 For compatibility reasons the character device file names recommended
  21 for V4L2 video capture, overlay, radio and raw vbi capture devices did
  22 not change from those used by V4L. They are listed in :ref:`devices`
  23 and below in :ref:`v4l-dev`.
  24
  25 The teletext devices (minor range 192-223) have been removed in V4L2 and
  26 no longer exist. There is no hardware available anymore for handling
  27 pure teletext. Instead raw or sliced VBI is used.
  28
  29 The V4L ``videodev`` module automatically assigns minor numbers to
  30 drivers in load order, depending on the registered device type. We
  31 recommend that V4L2 drivers by default register devices with the same
  32 numbers, but the system administrator can assign arbitrary minor numbers
  33 using driver module options. The major device number remains 81.
  34
  35
  36 .. _v4l-dev:
  37
  38 .. flat-table:: V4L Device Types, Names and Numbers
  39     :header-rows:  1
  40     :stub-columns: 0
  41
  42
  43     -  .. row 1
  44
  45        -  Device Type
  46
  47        -  File Name
  48
  49        -  Minor Numbers
  50
  51     -  .. row 2
  52
  53        -  Video capture and overlay
  54
  55        -  ``/dev/video`` and ``/dev/bttv0``\  [#f1]_, ``/dev/video0`` to
  56           ``/dev/video63``
  57
  58        -  0-63
  59
  60     -  .. row 3
  61
  62        -  Radio receiver
  63
  64        -  ``/dev/radio``\  [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
  65
  66        -  64-127
  67
  68     -  .. row 4
  69
  70        -  Raw VBI capture
  71
  72        -  ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
  73
  74        -  224-255
  75
  76
  77 V4L prohibits (or used to prohibit) multiple opens of a device file.
  78 V4L2 drivers *may* support multiple opens, see :ref:`open` for details
  79 and consequences.
  80
  81 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
  82
  83
  84 Querying Capabilities
  85 =====================
  86
  87 The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
  88 :ref:`VIDIOC_QUERYCAP`.
  89
  90 The ``name`` field in struct :c:type:`struct video_capability` became
  91 ``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type``
  92 was replaced by ``capabilities``. Note V4L2 does not distinguish between
  93 device types like this, better think of basic video input, video output
  94 and radio devices supporting a set of related functions like video
  95 capturing, video overlay and VBI capturing. See :ref:`open` for an
  96 introduction.
  97
  98
  99
 100 .. flat-table::
 101     :header-rows:  1
 102     :stub-columns: 0
 103
 104
 105     -  .. row 1
 106
 107        -  struct :c:type:`struct video_capability` ``type``
 108
 109        -  struct :ref:`v4l2_capability <v4l2-capability>`
 110           ``capabilities`` flags
 111
 112        -  Purpose
 113
 114     -  .. row 2
 115
 116        -  ``VID_TYPE_CAPTURE``
 117
 118        -  ``V4L2_CAP_VIDEO_CAPTURE``
 119
 120        -  The :ref:`video capture <capture>` interface is supported.
 121
 122     -  .. row 3
 123
 124        -  ``VID_TYPE_TUNER``
 125
 126        -  ``V4L2_CAP_TUNER``
 127
 128        -  The device has a :ref:`tuner or modulator <tuner>`.
 129
 130     -  .. row 4
 131
 132        -  ``VID_TYPE_TELETEXT``
 133
 134        -  ``V4L2_CAP_VBI_CAPTURE``
 135
 136        -  The :ref:`raw VBI capture <raw-vbi>` interface is supported.
 137
 138     -  .. row 5
 139
 140        -  ``VID_TYPE_OVERLAY``
 141
 142        -  ``V4L2_CAP_VIDEO_OVERLAY``
 143
 144        -  The :ref:`video overlay <overlay>` interface is supported.
 145
 146     -  .. row 6
 147
 148        -  ``VID_TYPE_CHROMAKEY``
 149
 150        -  ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
 151           :ref:`v4l2_framebuffer <v4l2-framebuffer>`
 152
 153        -  Whether chromakey overlay is supported. For more information on
 154           overlay see :ref:`overlay`.
 155
 156     -  .. row 7
 157
 158        -  ``VID_TYPE_CLIPPING``
 159
 160        -  ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
 161           ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
 162           struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
 163
 164        -  Whether clipping the overlaid image is supported, see
 165           :ref:`overlay`.
 166
 167     -  .. row 8
 168
 169        -  ``VID_TYPE_FRAMERAM``
 170
 171        -  ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
 172           of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
 173
 174        -  Whether overlay overwrites frame buffer memory, see
 175           :ref:`overlay`.
 176
 177     -  .. row 9
 178
 179        -  ``VID_TYPE_SCALES``
 180
 181        -  ``-``
 182
 183        -  This flag indicates if the hardware can scale images. The V4L2 API
 184           implies the scale factor by setting the cropping dimensions and
 185           image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
 186           :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
 187           driver returns the closest sizes possible. For more information on
 188           cropping and scaling see :ref:`crop`.
 189
 190     -  .. row 10
 191
 192        -  ``VID_TYPE_MONOCHROME``
 193
 194        -  ``-``
 195
 196        -  Applications can enumerate the supported image formats with the
 197           :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
 198           the device supports grey scale capturing only. For more
 199           information on image formats see :ref:`pixfmt`.
 200
 201     -  .. row 11
 202
 203        -  ``VID_TYPE_SUBCAPTURE``
 204
 205        -  ``-``
 206
 207        -  Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
 208           ioctl to determine if the device supports capturing a subsection
 209           of the full picture ("cropping" in V4L2). If not, the ioctl
 210           returns the ``EINVAL`` error code. For more information on cropping
 211           and scaling see :ref:`crop`.
 212
 213     -  .. row 12
 214
 215        -  ``VID_TYPE_MPEG_DECODER``
 216
 217        -  ``-``
 218
 219        -  Applications can enumerate the supported image formats with the
 220           :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
 221           the device supports MPEG streams.
 222
 223     -  .. row 13
 224
 225        -  ``VID_TYPE_MPEG_ENCODER``
 226
 227        -  ``-``
 228
 229        -  See above.
 230
 231     -  .. row 14
 232
 233        -  ``VID_TYPE_MJPEG_DECODER``
 234
 235        -  ``-``
 236
 237        -  See above.
 238
 239     -  .. row 15
 240
 241        -  ``VID_TYPE_MJPEG_ENCODER``
 242
 243        -  ``-``
 244
 245        -  See above.
 246
 247
 248 The ``audios`` field was replaced by ``capabilities`` flag
 249 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
 250 outputs. To determine their number applications can enumerate audio
 251 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
 252 audio ioctls are described in :ref:`audio`.
 253
 254 The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
 255 were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
 256 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
 257 dimensions returns the closest size possible, taking into account the
 258 current video standard, cropping and scaling limitations.
 259
 260
 261 Video Sources
 262 =============
 263
 264 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
 265 :c:type:`struct video_channel` to enumerate the video inputs of a V4L
 266 device. The equivalent V4L2 ioctls are
 267 :ref:`VIDIOC_ENUMINPUT`,
 268 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
 269 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
 270 :ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`.
 271
 272 The ``channel`` field counting inputs was renamed to ``index``, the
 273 video input types were renamed as follows:
 274
 275
 276
 277 .. flat-table::
 278     :header-rows:  1
 279     :stub-columns: 0
 280
 281
 282     -  .. row 1
 283
 284        -  struct :c:type:`struct video_channel` ``type``
 285
 286        -  struct :ref:`v4l2_input <v4l2-input>` ``type``
 287
 288     -  .. row 2
 289
 290        -  ``VIDEO_TYPE_TV``
 291
 292        -  ``V4L2_INPUT_TYPE_TUNER``
 293
 294     -  .. row 3
 295
 296        -  ``VIDEO_TYPE_CAMERA``
 297
 298        -  ``V4L2_INPUT_TYPE_CAMERA``
 299
 300
 301 Unlike the ``tuners`` field expressing the number of tuners of this
 302 input, V4L2 assumes each video input is connected to at most one tuner.
 303 However a tuner can have more than one input, i. e. RF connectors, and a
 304 device can have multiple tuners. The index number of the tuner
 305 associated with the input, if any, is stored in field ``tuner`` of
 306 struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is
 307 discussed in :ref:`tuner`.
 308
 309 The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
 310 associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
 311 ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
 312 considers devices with up to 32 audio inputs. Each set bit in the
 313 ``audioset`` field represents one audio input this video input combines
 314 with. For information about audio inputs and how to switch between them
 315 see :ref:`audio`.
 316
 317 The ``norm`` field describing the supported video standards was replaced
 318 by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
 319 indicating whether the standard can be changed. This flag was a later
 320 addition together with the ``norm`` field and has been removed in the
 321 meantime. V4L2 has a similar, albeit more comprehensive approach to
 322 video standards, see :ref:`standard` for more information.
 323
 324
 325 Tuning
 326 ======
 327
 328 The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
 329 :c:type:`struct video_tuner` can be used to enumerate the tuners of a
 330 V4L TV or radio device. The equivalent V4L2 ioctls are
 331 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
 332 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
 333 :ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`.
 334
 335 The ``tuner`` field counting tuners was renamed to ``index``. The fields
 336 ``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
 337
 338 The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
 339 flags indicating the supported video standards were dropped. This
 340 information is now contained in the associated struct
 341 :ref:`v4l2_input <v4l2-input>`. No replacement exists for the
 342 ``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
 343 switched. The ``mode`` field to select a different video standard was
 344 replaced by a whole new set of ioctls and structures described in
 345 :ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
 346 driver supports several standards in addition to the regular
 347 ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
 348 ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
 349 Japan with numbers 3-6 (sic).
 350
 351 The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
 352 ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
 353 permits the detection of monaural and bilingual audio, see the
 354 definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details.
 355 Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
 356 ``VIDEO_TUNER_MBS_ON`` flags.
 357
 358 The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
 359 the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field.
 360
 361 The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
 362 frequency where renamed to
 363 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
 364 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
 365 to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an
 366 unsigned long integer.
 367
 368
 369 .. _v4l-image-properties:
 370
 371 Image Properties
 372 ================
 373
 374 V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
 375 and struct :c:type:`struct video_picture`. The following fields where
 376 replaced by V4L2 controls accessible with the
 377 :ref:`VIDIOC_QUERYCTRL`,
 378 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
 379 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
 380
 381
 382
 383 .. flat-table::
 384     :header-rows:  1
 385     :stub-columns: 0
 386
 387
 388     -  .. row 1
 389
 390        -  struct :c:type:`struct video_picture`
 391
 392        -  V4L2 Control ID
 393
 394     -  .. row 2
 395
 396        -  ``brightness``
 397
 398        -  ``V4L2_CID_BRIGHTNESS``
 399
 400     -  .. row 3
 401
 402        -  ``hue``
 403
 404        -  ``V4L2_CID_HUE``
 405
 406     -  .. row 4
 407
 408        -  ``colour``
 409
 410        -  ``V4L2_CID_SATURATION``
 411
 412     -  .. row 5
 413
 414        -  ``contrast``
 415
 416        -  ``V4L2_CID_CONTRAST``
 417
 418     -  .. row 6
 419
 420        -  ``whiteness``
 421
 422        -  ``V4L2_CID_WHITENESS``
 423
 424
 425 The V4L picture controls are assumed to range from 0 to 65535 with no
 426 particular reset value. The V4L2 API permits arbitrary limits and
 427 defaults which can be queried with the
 428 :ref:`VIDIOC_QUERYCTRL` ioctl. For general
 429 information about controls see :ref:`control`.
 430
 431 The ``depth`` (average number of bits per pixel) of a video image is
 432 implied by the selected image format. V4L2 does not explicitly provide
 433 such information assuming applications recognizing the format are aware
 434 of the image depth and others need not know. The ``palette`` field moved
 435 into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`:
 436
 437
 438
 439 .. flat-table::
 440     :header-rows:  1
 441     :stub-columns: 0
 442
 443
 444     -  .. row 1
 445
 446        -  struct :c:type:`struct video_picture` ``palette``
 447
 448        -  struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt``
 449
 450     -  .. row 2
 451
 452        -  ``VIDEO_PALETTE_GREY``
 453
 454        -  :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
 455
 456     -  .. row 3
 457
 458        -  ``VIDEO_PALETTE_HI240``
 459
 460        -  :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_
 461
 462     -  .. row 4
 463
 464        -  ``VIDEO_PALETTE_RGB565``
 465
 466        -  :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
 467
 468     -  .. row 5
 469
 470        -  ``VIDEO_PALETTE_RGB555``
 471
 472        -  :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
 473
 474     -  .. row 6
 475
 476        -  ``VIDEO_PALETTE_RGB24``
 477
 478        -  :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
 479
 480     -  .. row 7
 481
 482        -  ``VIDEO_PALETTE_RGB32``
 483
 484        -  :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_
 485
 486     -  .. row 8
 487
 488        -  ``VIDEO_PALETTE_YUV422``
 489
 490        -  :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
 491
 492     -  .. row 9
 493
 494        -  ``VIDEO_PALETTE_YUYV``\  [#f5]_
 495
 496        -  :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
 497
 498     -  .. row 10
 499
 500        -  ``VIDEO_PALETTE_UYVY``
 501
 502        -  :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
 503
 504     -  .. row 11
 505
 506        -  ``VIDEO_PALETTE_YUV420``
 507
 508        -  None
 509
 510     -  .. row 12
 511
 512        -  ``VIDEO_PALETTE_YUV411``
 513
 514        -  :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_
 515
 516     -  .. row 13
 517
 518        -  ``VIDEO_PALETTE_RAW``
 519
 520        -  None [#f7]_
 521
 522     -  .. row 14
 523
 524        -  ``VIDEO_PALETTE_YUV422P``
 525
 526        -  :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
 527
 528     -  .. row 15
 529
 530        -  ``VIDEO_PALETTE_YUV411P``
 531
 532        -  :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_
 533
 534     -  .. row 16
 535
 536        -  ``VIDEO_PALETTE_YUV420P``
 537
 538        -  :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
 539
 540     -  .. row 17
 541
 542        -  ``VIDEO_PALETTE_YUV410P``
 543
 544        -  :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
 545
 546
 547 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
 548 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
 549
 550
 551 Audio
 552 =====
 553
 554 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
 555 :c:type:`struct video_audio` are used to enumerate the audio inputs
 556 of a V4L device. The equivalent V4L2 ioctls are
 557 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
 558 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
 559 :ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`.
 560
 561 The ``audio`` "channel number" field counting audio inputs was renamed
 562 to ``index``.
 563
 564 On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
 565 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
 566 ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
 567 standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
 568 ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
 569 specification, there is no way to query the selected mode. On
 570 ``VIDIOCGAUDIO`` the driver returns the *actually received* audio
 571 programmes in this field. In the V4L2 API this information is stored in
 572 the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and
 573 ``audmode`` fields, respectively. See :ref:`tuner` for more
 574 information on tuners. Related to audio modes struct
 575 :ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or
 576 stereo input, regardless if the source is a tuner.
 577
 578 The following fields where replaced by V4L2 controls accessible with the
 579 :ref:`VIDIOC_QUERYCTRL`,
 580 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
 581 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
 582
 583
 584
 585 .. flat-table::
 586     :header-rows:  1
 587     :stub-columns: 0
 588
 589
 590     -  .. row 1
 591
 592        -  struct :c:type:`struct video_audio`
 593
 594        -  V4L2 Control ID
 595
 596     -  .. row 2
 597
 598        -  ``volume``
 599
 600        -  ``V4L2_CID_AUDIO_VOLUME``
 601
 602     -  .. row 3
 603
 604        -  ``bass``
 605
 606        -  ``V4L2_CID_AUDIO_BASS``
 607
 608     -  .. row 4
 609
 610        -  ``treble``
 611
 612        -  ``V4L2_CID_AUDIO_TREBLE``
 613
 614     -  .. row 5
 615
 616        -  ``balance``
 617
 618        -  ``V4L2_CID_AUDIO_BALANCE``
 619
 620
 621 To determine which of these controls are supported by a driver V4L
 622 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
 623 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
 624 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the
 625 respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
 626 and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
 627 ``V4L2_CID_AUDIO_MUTE`` control.
 628
 629 All V4L2 controls have a ``step`` attribute replacing the struct
 630 :c:type:`struct video_audio` ``step`` field. The V4L audio controls
 631 are assumed to range from 0 to 65535 with no particular reset value. The
 632 V4L2 API permits arbitrary limits and defaults which can be queried with
 633 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
 634 information about controls see :ref:`control`.
 635
 636
 637 Frame Buffer Overlay
 638 ====================
 639
 640 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
 641 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
 642 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
 643 :c:type:`struct video_buffer` remained unchanged, except V4L2 defines
 644 a flag to indicate non-destructive overlays instead of a ``NULL``
 645 pointer. All other fields moved into the struct
 646 :ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of
 647 struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth``
 648 field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
 649 list of RGB formats and their respective color depths.
 650
 651 Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
 652 uses the general-purpose data format negotiation ioctls
 653 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
 654 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
 655 :ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member
 656 of the ``fmt`` union is used, a struct
 657 :ref:`v4l2_window <v4l2-window>`.
 658
 659 The ``x``, ``y``, ``width`` and ``height`` fields of struct
 660 :c:type:`struct video_window` moved into struct
 661 :ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct
 662 :c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and
 663 ``clipcount`` fields remained unchanged. Struct
 664 :c:type:`struct video_clip` was renamed to struct
 665 :ref:`v4l2_clip <v4l2-clip>`, also containing a struct
 666 :c:type:`struct v4l2_rect`, but the semantics are still the same.
 667
 668 The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
 669 must set the ``field`` field to ``V4L2_FIELD_ANY`` or
 670 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
 671 into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new
 672 name ``V4L2_FBUF_FLAG_CHROMAKEY``.
 673
 674 In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
 675 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
 676 size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window`
 677 has a separate ``bitmap`` pointer field for this purpose and the bitmap
 678 size is determined by ``w.width`` and ``w.height``.
 679
 680 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
 681 :ref:`VIDIOC_OVERLAY`.
 682
 683
 684 Cropping
 685 ========
 686
 687 To capture only a subsection of the full picture V4L defines the
 688 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
 689 :c:type:`struct video_capture`. The equivalent V4L2 ioctls are
 690 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
 691 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
 692 :ref:`v4l2_crop <v4l2-crop>`, and the related
 693 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather
 694 complex matter, see :ref:`crop` for details.
 695
 696 The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
 697 :ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct
 698 :c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In
 699 the V4L2 API the scaling factor is implied by the size of the cropping
 700 rectangle and the size of the captured or overlaid image.
 701
 702 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
 703 only the odd or even field, respectively, were replaced by
 704 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
 705 ``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
 706 struct :ref:`v4l2_window <v4l2-window>`. These structures are used to
 707 select a capture or overlay format with the
 708 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
 709
 710
 711 Reading Images, Memory Mapping
 712 ==============================
 713
 714
 715 Capturing using the read method
 716 -------------------------------
 717
 718 There is no essential difference between reading images from a V4L or
 719 V4L2 device using the :ref:`read() <func-read>` function, however V4L2
 720 drivers are not required to support this I/O method. Applications can
 721 determine if the function is available with the
 722 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
 723 exchanging data with applications must support the
 724 :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
 725 functions.
 726
 727 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
 728 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
 729 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
 730 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
 731 :ref:`v4l2_format <v4l2-format>` as argument, here the struct
 732 :ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its
 733 ``fmt`` union is used.
 734
 735 For more information about the V4L2 read interface see :ref:`rw`.
 736
 737
 738 Capturing using memory mapping
 739 ------------------------------
 740
 741 Applications can read from V4L devices by mapping buffers in device
 742 memory, or more often just buffers allocated in DMA-able system memory,
 743 into their address space. This avoids the data copying overhead of the
 744 read method. V4L2 supports memory mapping as well, with a few
 745 differences.
 746
 747
 748
 749 .. flat-table::
 750     :header-rows:  1
 751     :stub-columns: 0
 752
 753
 754     -  .. row 1
 755
 756        -  V4L
 757
 758        -  V4L2
 759
 760     -  .. row 2
 761
 762        -
 763        -  The image format must be selected before buffers are allocated,
 764           with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
 765           format is selected the driver may use the last, possibly by
 766           another application requested format.
 767
 768     -  .. row 3
 769
 770        -  Applications cannot change the number of buffers. The it is built
 771           into the driver, unless it has a module option to change the
 772           number when the driver module is loaded.
 773
 774        -  The :ref:`VIDIOC_REQBUFS` ioctl allocates the
 775           desired number of buffers, this is a required step in the
 776           initialization sequence.
 777
 778     -  .. row 4
 779
 780        -  Drivers map all buffers as one contiguous range of memory. The
 781           ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
 782           the offset of each buffer from the start of the virtual file, and
 783           the overall amount of memory used, which can be used as arguments
 784           for the :ref:`mmap() <func-mmap>` function.
 785
 786        -  Buffers are individually mapped. The offset and size of each
 787           buffer can be determined with the
 788           :ref:`VIDIOC_QUERYBUF` ioctl.
 789
 790     -  .. row 5
 791
 792        -  The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
 793           also determines the image format for this buffer. The ioctl
 794           returns immediately, eventually with an ``EAGAIN`` error code if no
 795           video signal had been detected. When the driver supports more than
 796           one buffer applications can call the ioctl multiple times and thus
 797           have multiple outstanding capture requests.
 798
 799           The ``VIDIOCSYNC`` ioctl suspends execution until a particular
 800           buffer has been filled.
 801
 802        -  Drivers maintain an incoming and outgoing queue.
 803           :ref:`VIDIOC_QBUF` enqueues any empty buffer into
 804           the incoming queue. Filled buffers are dequeued from the outgoing
 805           queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
 806           until filled buffers become available this function,
 807           :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
 808           be used. The :ref:`VIDIOC_STREAMON` ioctl
 809           must be called once after enqueuing one or more buffers to start
 810           capturing. Its counterpart
 811           :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
 812           dequeues all buffers from both queues. Applications can query the
 813           signal status, if known, with the
 814           :ref:`VIDIOC_ENUMINPUT` ioctl.
 815
 816
 817 For a more in-depth discussion of memory mapping and examples, see
 818 :ref:`mmap`.
 819
 820
 821 Reading Raw VBI Data
 822 ====================
 823
 824 Originally the V4L API did not specify a raw VBI capture interface, only
 825 the device file ``/dev/vbi`` was reserved for this purpose. The only
 826 driver supporting this interface was the BTTV driver, de-facto defining
 827 the V4L VBI interface. Reading from the device yields a raw VBI image
 828 with the following parameters:
 829
 830
 831
 832 .. flat-table::
 833     :header-rows:  1
 834     :stub-columns: 0
 835
 836
 837     -  .. row 1
 838
 839        -  struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
 840
 841        -  V4L, BTTV driver
 842
 843     -  .. row 2
 844
 845        -  sampling_rate
 846
 847        -  28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
 848           and SECAM (625-line standards)
 849
 850     -  .. row 3
 851
 852        -  offset
 853
 854        -  ?
 855
 856     -  .. row 4
 857
 858        -  samples_per_line
 859
 860        -  2048
 861
 862     -  .. row 5
 863
 864        -  sample_format
 865
 866        -  V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
 867           integer) contain a frame counter.
 868
 869     -  .. row 6
 870
 871        -  start[]
 872
 873        -  10, 273 NTSC; 22, 335 PAL and SECAM
 874
 875     -  .. row 7
 876
 877        -  count[]
 878
 879        -  16, 16 [#f9]_
 880
 881     -  .. row 8
 882
 883        -  flags
 884
 885        -  0
 886
 887
 888 Undocumented in the V4L specification, in Linux 2.3 the
 889 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
 890 :c:type:`struct vbi_format` were added to determine the VBI image
 891 parameters. These ioctls are only partially compatible with the V4L2 VBI
 892 interface specified in :ref:`raw-vbi`.
 893
 894 An ``offset`` field does not exist, ``sample_format`` is supposed to be
 895 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
 896 remaining fields are probably equivalent to struct
 897 :ref:`v4l2_vbi_format <v4l2-vbi-format>`.
 898
 899 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
 900 semantics differ from those specified for V4L2 in two ways. The
 901 parameters are reset on :ref:`open() <func-open>` and
 902 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
 903 are invalid.
 904
 905
 906 Miscellaneous
 907 =============
 908
 909 V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
 910 find the VBI device associated with a video capture device (or vice
 911 versa) by reopening the device and requesting VBI data. For details see
 912 :ref:`open`.
 913
 914 No replacement exists for ``VIDIOCKEY``, and the V4L functions for
 915 microcode programming. A new interface for MPEG compression and playback
 916 devices is documented in :ref:`extended-controls`.
 917
 918 .. [#f1]
 919    According to Documentation/devices.txt these should be symbolic links
 920    to ``/dev/video0``. Note the original bttv interface is not
 921    compatible with V4L or V4L2.
 922
 923 .. [#f2]
 924    According to ``Documentation/devices.txt`` a symbolic link to
 925    ``/dev/radio0``.
 926
 927 .. [#f3]
 928    This is a custom format used by the BTTV driver, not one of the V4L2
 929    standard formats.
 930
 931 .. [#f4]
 932    Presumably all V4L RGB formats are little-endian, although some
 933    drivers might interpret them according to machine endianness. V4L2
 934    defines little-endian, big-endian and red/blue swapped variants. For
 935    details see :ref:`pixfmt-rgb`.
 936
 937 .. [#f5]
 938    ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
 939    formats. Some V4L drivers respond to one, some to the other.
 940
 941 .. [#f6]
 942    Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
 943    format.
 944
 945 .. [#f7]
 946    V4L explains this as: "RAW capture (BT848)"
 947
 948 .. [#f8]
 949    Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
 950    format.
 951
 952 .. [#f9]
 953    Old driver versions used different values, eventually the custom
 954    ``BTTV_VBISIZE`` ioctl was added to query the correct values.