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