1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _diff-v4l: 4 5******************************** 6Differences between V4L and V4L2 7******************************** 8 9The Video For Linux API was first introduced in Linux 2.1 to unify and 10replace various TV and radio device related interfaces, developed 11independently by driver writers in prior years. Starting with Linux 2.5 12the much improved V4L2 API replaces the V4L API. The support for the old 13V4L calls were removed from Kernel, but the library :ref:`libv4l` 14supports the conversion of a V4L API system call into a V4L2 one. 15 16 17Opening and Closing Devices 18=========================== 19 20For compatibility reasons the character device file names recommended 21for V4L2 video capture, overlay, radio and raw vbi capture devices did 22not change from those used by V4L. They are listed in :ref:`devices` 23and below in :ref:`v4l-dev`. 24 25The teletext devices (minor range 192-223) have been removed in V4L2 and 26no longer exist. There is no hardware available anymore for handling 27pure teletext. Instead raw or sliced VBI is used. 28 29The V4L ``videodev`` module automatically assigns minor numbers to 30drivers in load order, depending on the registered device type. We 31recommend that V4L2 drivers by default register devices with the same 32numbers, but the system administrator can assign arbitrary minor numbers 33using 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 57V4L prohibits (or used to prohibit) multiple opens of a device file. 58V4L2 drivers *may* support multiple opens, see :ref:`open` for details 59and consequences. 60 61V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. 62 63 64Querying Capabilities 65===================== 66 67The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's 68:ref:`VIDIOC_QUERYCAP`. 69 70The ``name`` field in struct ``video_capability`` became 71``card`` in struct :c:type:`v4l2_capability`, ``type`` 72was replaced by ``capabilities``. Note V4L2 does not distinguish between 73device types like this, better think of basic video input, video output 74and radio devices supporting a set of related functions like video 75capturing, video overlay and VBI capturing. See :ref:`open` for an 76introduction. 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 155The ``audios`` field was replaced by ``capabilities`` flag 156``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or 157outputs. To determine their number applications can enumerate audio 158inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The 159audio ioctls are described in :ref:`audio`. 160 161The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields 162were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or 163:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired 164dimensions returns the closest size possible, taking into account the 165current video standard, cropping and scaling limitations. 166 167 168Video Sources 169============= 170 171V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct 172``video_channel`` to enumerate the video inputs of a V4L 173device. 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 179The ``channel`` field counting inputs was renamed to ``index``, the 180video 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 196Unlike the ``tuners`` field expressing the number of tuners of this 197input, V4L2 assumes each video input is connected to at most one tuner. 198However a tuner can have more than one input, i. e. RF connectors, and a 199device can have multiple tuners. The index number of the tuner 200associated with the input, if any, is stored in field ``tuner`` of 201struct :c:type:`v4l2_input`. Enumeration of tuners is 202discussed in :ref:`tuner`. 203 204The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs 205associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The 206``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2 207considers devices with up to 32 audio inputs. Each set bit in the 208``audioset`` field represents one audio input this video input combines 209with. For information about audio inputs and how to switch between them 210see :ref:`audio`. 211 212The ``norm`` field describing the supported video standards was replaced 213by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM`` 214indicating whether the standard can be changed. This flag was a later 215addition together with the ``norm`` field and has been removed in the 216meantime. V4L2 has a similar, albeit more comprehensive approach to 217video standards, see :ref:`standard` for more information. 218 219 220Tuning 221====== 222 223The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct 224``video_tuner`` can be used to enumerate the tuners of a 225V4L 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 230The ``tuner`` field counting tuners was renamed to ``index``. The fields 231``name``, ``rangelow`` and ``rangehigh`` remained unchanged. 232 233The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM`` 234flags indicating the supported video standards were dropped. This 235information 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 238switched. The ``mode`` field to select a different video standard was 239replaced by a whole new set of ioctls and structures described in 240:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV 241driver 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 244Japan with numbers 3-6 (sic). 245 246The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became 247``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also 248permits the detection of monaural and bilingual audio, see the 249definition of struct :c:type:`v4l2_tuner` for details. 250Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and 251``VIDEO_TUNER_MBS_ON`` flags. 252 253The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in 254the struct :c:type:`v4l2_tuner` ``capability`` field. 255 256The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner 257frequency where renamed to 258:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and 259:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer 260to a struct :c:type:`v4l2_frequency` instead of an 261unsigned long integer. 262 263 264.. _v4l-image-properties: 265 266Image Properties 267================ 268 269V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl 270and struct ``video_picture``. The following fields where 271replaced 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 296The V4L picture controls are assumed to range from 0 to 65535 with no 297particular reset value. The V4L2 API permits arbitrary limits and 298defaults which can be queried with the 299:ref:`VIDIOC_QUERYCTRL` ioctl. For general 300information about controls see :ref:`control`. 301 302The ``depth`` (average number of bits per pixel) of a video image is 303implied by the selected image format. V4L2 does not explicitly provide 304such information assuming applications recognizing the format are aware 305of the image depth and others need not know. The ``palette`` field moved 306into 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 350V4L2 image formats are defined in :ref:`pixfmt`. The image format can 351be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. 352 353 354Audio 355===== 356 357The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct 358``video_audio`` are used to enumerate the audio inputs 359of 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 364The ``audio`` "channel number" field counting audio inputs was renamed 365to ``index``. 366 367On ``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 370standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and 371``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L 372specification, there is no way to query the selected mode. On 373``VIDIOCGAUDIO`` the driver returns the *actually received* audio 374programmes in this field. In the V4L2 API this information is stored in 375the struct :c:type:`v4l2_tuner` ``rxsubchans`` and 376``audmode`` fields, respectively. See :ref:`tuner` for more 377information on tuners. Related to audio modes struct 378:c:type:`v4l2_audio` also reports if this is a mono or 379stereo input, regardless if the source is a tuner. 380 381The 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 404To determine which of these controls are supported by a driver V4L 405provides 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 408respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE`` 409and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean 410``V4L2_CID_AUDIO_MUTE`` control. 411 412All V4L2 controls have a ``step`` attribute replacing the struct 413``video_audio`` ``step`` field. The V4L audio controls 414are assumed to range from 0 to 65535 with no particular reset value. The 415V4L2 API permits arbitrary limits and defaults which can be queried with 416the :ref:`VIDIOC_QUERYCTRL` ioctl. For general 417information about controls see :ref:`control`. 418 419 420Frame Buffer Overlay 421==================== 422 423The 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 427a flag to indicate non-destructive overlays instead of a ``NULL`` 428pointer. All other fields moved into the struct 429:c:type:`v4l2_pix_format` ``fmt`` substructure of 430struct :c:type:`v4l2_framebuffer`. The ``depth`` 431field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a 432list of RGB formats and their respective color depths. 433 434Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2 435uses 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 439of the ``fmt`` union is used, a struct 440:c:type:`v4l2_window`. 441 442The ``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 451The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications 452must set the ``field`` field to ``V4L2_FIELD_ANY`` or 453``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved 454into struct :c:type:`v4l2_framebuffer`, under the new 455name ``V4L2_FBUF_FLAG_CHROMAKEY``. 456 457In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount`` 458to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed 459size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window` 460has a separate ``bitmap`` pointer field for this purpose and the bitmap 461size is determined by ``w.width`` and ``w.height``. 462 463The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to 464:ref:`VIDIOC_OVERLAY`. 465 466 467Cropping 468======== 469 470To 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 477complex matter, see :ref:`crop` for details. 478 479The ``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 482the V4L2 API the scaling factor is implied by the size of the cropping 483rectangle and the size of the captured or overlaid image. 484 485The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture 486only 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 489struct :c:type:`v4l2_window`. These structures are used to 490select a capture or overlay format with the 491:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. 492 493 494Reading Images, Memory Mapping 495============================== 496 497 498Capturing using the read method 499------------------------------- 500 501There is no essential difference between reading images from a V4L or 502V4L2 device using the :ref:`read() <func-read>` function, however V4L2 503drivers are not required to support this I/O method. Applications can 504determine if the function is available with the 505:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices 506exchanging data with applications must support the 507:ref:`select() <func-select>` and :ref:`poll() <func-poll>` 508functions. 509 510To select an image format and size, V4L provides the ``VIDIOCSPICT`` and 511``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format 512negotiation 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 518For more information about the V4L2 read interface see :ref:`rw`. 519 520 521Capturing using memory mapping 522------------------------------ 523 524Applications can read from V4L devices by mapping buffers in device 525memory, or more often just buffers allocated in DMA-able system memory, 526into their address space. This avoids the data copying overhead of the 527read method. V4L2 supports memory mapping as well, with a few 528differences. 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 581For a more in-depth discussion of memory mapping and examples, see 582:ref:`mmap`. 583 584 585Reading Raw VBI Data 586==================== 587 588Originally the V4L API did not specify a raw VBI capture interface, only 589the device file ``/dev/vbi`` was reserved for this purpose. The only 590driver supporting this interface was the BTTV driver, de-facto defining 591the V4L VBI interface. Reading from the device yields a raw VBI image 592with 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 620Undocumented 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 623parameters. These ioctls are only partially compatible with the V4L2 VBI 624interface specified in :ref:`raw-vbi`. 625 626An ``offset`` field does not exist, ``sample_format`` is supposed to be 627``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The 628remaining fields are probably equivalent to struct 629:c:type:`v4l2_vbi_format`. 630 631Apparently only the Zoran (ZR 36120) driver implements these ioctls. The 632semantics differ from those specified for V4L2 in two ways. The 633parameters are reset on :ref:`open() <func-open>` and 634``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters 635are invalid. 636 637 638Miscellaneous 639============= 640 641V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can 642find the VBI device associated with a video capture device (or vice 643versa) by reopening the device and requesting VBI data. For details see 644:ref:`open`. 645 646No replacement exists for ``VIDIOCKEY``, and the V4L functions for 647microcode programming. A new interface for MPEG compression and playback 648devices 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. 687