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

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