668 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _diff-v4l:5 6********************************7Differences between V4L and V4L28********************************9 10The Video For Linux API was first introduced in Linux 2.1 to unify and11replace various TV and radio device related interfaces, developed12independently by driver writers in prior years. Starting with Linux 2.513the much improved V4L2 API replaces the V4L API. The support for the old14V4L calls were removed from Kernel, but the library :ref:`libv4l`15supports the conversion of a V4L API system call into a V4L2 one.16 17Opening and Closing Devices18===========================19 20For compatibility reasons the character device file names recommended21for V4L2 video capture, overlay, radio and raw vbi capture devices did22not 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 and26no longer exist. There is no hardware available anymore for handling27pure teletext. Instead raw or sliced VBI is used.28 29The V4L ``videodev`` module automatically assigns minor numbers to30drivers in load order, depending on the registered device type. We31recommend that V4L2 drivers by default register devices with the same32numbers, but the system administrator can assign arbitrary minor numbers33using driver module options. The major device number remains 81.34 35.. _v4l-dev:36 37.. flat-table:: V4L Device Types, Names and Numbers38 :header-rows: 139 :stub-columns: 040 41 * - Device Type42 - File Name43 - Minor Numbers44 * - Video capture and overlay45 - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to46 ``/dev/video63``47 - 0-6348 * - Radio receiver49 - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``50 - 64-12751 * - Raw VBI capture52 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``53 - 224-25554 55V4L prohibits (or used to prohibit) multiple opens of a device file.56V4L2 drivers *may* support multiple opens, see :ref:`open` for details57and consequences.58 59V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.60 61Querying Capabilities62=====================63 64The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's65:ref:`VIDIOC_QUERYCAP`.66 67The ``name`` field in struct ``video_capability`` became68``card`` in struct :c:type:`v4l2_capability`, ``type``69was replaced by ``capabilities``. Note V4L2 does not distinguish between70device types like this, better think of basic video input, video output71and radio devices supporting a set of related functions like video72capturing, video overlay and VBI capturing. See :ref:`open` for an73introduction.74 75.. raw:: latex76 77 \small78 79.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}|80 81.. cssclass:: longtable82 83.. flat-table::84 :header-rows: 185 :stub-columns: 086 87 * - ``struct video_capability`` ``type``88 - struct :c:type:`v4l2_capability`89 ``capabilities`` flags90 - Purpose91 * - ``VID_TYPE_CAPTURE``92 - ``V4L2_CAP_VIDEO_CAPTURE``93 - The :ref:`video capture <capture>` interface is supported.94 * - ``VID_TYPE_TUNER``95 - ``V4L2_CAP_TUNER``96 - The device has a :ref:`tuner or modulator <tuner>`.97 * - ``VID_TYPE_TELETEXT``98 - ``V4L2_CAP_VBI_CAPTURE``99 - The :ref:`raw VBI capture <raw-vbi>` interface is supported.100 * - ``VID_TYPE_OVERLAY``101 - ``V4L2_CAP_VIDEO_OVERLAY``102 - The :ref:`video overlay <overlay>` interface is supported.103 * - ``VID_TYPE_CHROMAKEY``104 - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct105 :c:type:`v4l2_framebuffer`106 - Whether chromakey overlay is supported. For more information on107 overlay see :ref:`overlay`.108 * - ``VID_TYPE_CLIPPING``109 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and110 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of111 struct :c:type:`v4l2_framebuffer`112 - Whether clipping the overlaid image is supported, see113 :ref:`overlay`.114 * - ``VID_TYPE_FRAMERAM``115 - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``116 of struct :c:type:`v4l2_framebuffer`117 - Whether overlay overwrites frame buffer memory, see118 :ref:`overlay`.119 * - ``VID_TYPE_SCALES``120 - ``-``121 - This flag indicates if the hardware can scale images. The V4L2 API122 implies the scale factor by setting the cropping dimensions and123 image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and124 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The125 driver returns the closest sizes possible. For more information on126 cropping and scaling see :ref:`crop`.127 * - ``VID_TYPE_MONOCHROME``128 - ``-``129 - Applications can enumerate the supported image formats with the130 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if131 the device supports grey scale capturing only. For more132 information on image formats see :ref:`pixfmt`.133 * - ``VID_TYPE_SUBCAPTURE``134 - ``-``135 - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`136 ioctl to determine if the device supports capturing a subsection137 of the full picture ("cropping" in V4L2). If not, the ioctl138 returns the ``EINVAL`` error code. For more information on cropping139 and scaling see :ref:`crop`.140 * - ``VID_TYPE_MPEG_DECODER``141 - ``-``142 - Applications can enumerate the supported image formats with the143 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if144 the device supports MPEG streams.145 * - ``VID_TYPE_MPEG_ENCODER``146 - ``-``147 - See above.148 * - ``VID_TYPE_MJPEG_DECODER``149 - ``-``150 - See above.151 * - ``VID_TYPE_MJPEG_ENCODER``152 - ``-``153 - See above.154 155.. raw:: latex156 157 \normalsize158 159The ``audios`` field was replaced by ``capabilities`` flag160``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or161outputs. To determine their number applications can enumerate audio162inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The163audio ioctls are described in :ref:`audio`.164 165The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields166were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or167:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired168dimensions returns the closest size possible, taking into account the169current video standard, cropping and scaling limitations.170 171Video Sources172=============173 174V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct175``video_channel`` to enumerate the video inputs of a V4L176device. The equivalent V4L2 ioctls are177:ref:`VIDIOC_ENUMINPUT`,178:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and179:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct180:c:type:`v4l2_input` as discussed in :ref:`video`.181 182The ``channel`` field counting inputs was renamed to ``index``, the183video input types were renamed as follows:184 185 186.. flat-table::187 :header-rows: 1188 :stub-columns: 0189 190 * - struct ``video_channel`` ``type``191 - struct :c:type:`v4l2_input` ``type``192 * - ``VIDEO_TYPE_TV``193 - ``V4L2_INPUT_TYPE_TUNER``194 * - ``VIDEO_TYPE_CAMERA``195 - ``V4L2_INPUT_TYPE_CAMERA``196 197Unlike the ``tuners`` field expressing the number of tuners of this198input, V4L2 assumes each video input is connected to at most one tuner.199However a tuner can have more than one input, i. e. RF connectors, and a200device can have multiple tuners. The index number of the tuner201associated with the input, if any, is stored in field ``tuner`` of202struct :c:type:`v4l2_input`. Enumeration of tuners is203discussed in :ref:`tuner`.204 205The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs206associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The207``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2208considers devices with up to 32 audio inputs. Each set bit in the209``audioset`` field represents one audio input this video input combines210with. For information about audio inputs and how to switch between them211see :ref:`audio`.212 213The ``norm`` field describing the supported video standards was replaced214by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``215indicating whether the standard can be changed. This flag was a later216addition together with the ``norm`` field and has been removed in the217meantime. V4L2 has a similar, albeit more comprehensive approach to218video standards, see :ref:`standard` for more information.219 220Tuning221======222 223The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct224``video_tuner`` can be used to enumerate the tuners of a225V4L TV or radio device. The equivalent V4L2 ioctls are226:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and227:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct228:c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`.229 230The ``tuner`` field counting tuners was renamed to ``index``. The fields231``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. This235information is now contained in the associated struct236:c:type:`v4l2_input`. No replacement exists for the237``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be238switched. The ``mode`` field to select a different video standard was239replaced by a whole new set of ioctls and structures described in240:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV241driver supports several standards in addition to the regular242``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and243``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC244Japan with numbers 3-6 (sic).245 246The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became247``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also248permits the detection of monaural and bilingual audio, see the249definition of struct :c:type:`v4l2_tuner` for details.250Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and251``VIDEO_TUNER_MBS_ON`` flags.252 253The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in254the struct :c:type:`v4l2_tuner` ``capability`` field.255 256The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner257frequency where renamed to258:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and259:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer260to a struct :c:type:`v4l2_frequency` instead of an261unsigned long integer.262 263.. _v4l-image-properties:264 265Image Properties266================267 268V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl269and struct ``video_picture``. The following fields where270replaced by V4L2 controls accessible with the271:ref:`VIDIOC_QUERYCTRL`,272:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and273:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:274 275 276.. flat-table::277 :header-rows: 1278 :stub-columns: 0279 280 * - struct ``video_picture``281 - V4L2 Control ID282 * - ``brightness``283 - ``V4L2_CID_BRIGHTNESS``284 * - ``hue``285 - ``V4L2_CID_HUE``286 * - ``colour``287 - ``V4L2_CID_SATURATION``288 * - ``contrast``289 - ``V4L2_CID_CONTRAST``290 * - ``whiteness``291 - ``V4L2_CID_WHITENESS``292 293The V4L picture controls are assumed to range from 0 to 65535 with no294particular reset value. The V4L2 API permits arbitrary limits and295defaults which can be queried with the296:ref:`VIDIOC_QUERYCTRL` ioctl. For general297information about controls see :ref:`control`.298 299The ``depth`` (average number of bits per pixel) of a video image is300implied by the selected image format. V4L2 does not explicitly provide301such information assuming applications recognizing the format are aware302of the image depth and others need not know. The ``palette`` field moved303into the struct :c:type:`v4l2_pix_format`:304 305 306.. flat-table::307 :header-rows: 1308 :stub-columns: 0309 310 * - struct ``video_picture`` ``palette``311 - struct :c:type:`v4l2_pix_format` ``pixfmt``312 * - ``VIDEO_PALETTE_GREY``313 - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`314 * - ``VIDEO_PALETTE_HI240``315 - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_316 * - ``VIDEO_PALETTE_RGB565``317 - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`318 * - ``VIDEO_PALETTE_RGB555``319 - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`320 * - ``VIDEO_PALETTE_RGB24``321 - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`322 * - ``VIDEO_PALETTE_RGB32``323 - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_324 * - ``VIDEO_PALETTE_YUV422``325 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`326 * - ``VIDEO_PALETTE_YUYV``\ [#f5]_327 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`328 * - ``VIDEO_PALETTE_UYVY``329 - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`330 * - ``VIDEO_PALETTE_YUV420``331 - None332 * - ``VIDEO_PALETTE_YUV411``333 - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_334 * - ``VIDEO_PALETTE_RAW``335 - None [#f7]_336 * - ``VIDEO_PALETTE_YUV422P``337 - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`338 * - ``VIDEO_PALETTE_YUV411P``339 - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_340 * - ``VIDEO_PALETTE_YUV420P``341 - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`342 * - ``VIDEO_PALETTE_YUV410P``343 - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`344 345V4L2 image formats are defined in :ref:`pixfmt`. The image format can346be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.347 348Audio349=====350 351The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct352``video_audio`` are used to enumerate the audio inputs353of a V4L device. The equivalent V4L2 ioctls are354:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and355:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct356:c:type:`v4l2_audio` as discussed in :ref:`audio`.357 358The ``audio`` "channel number" field counting audio inputs was renamed359to ``index``.360 361On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the362``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or363``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio364standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and365``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L366specification, there is no way to query the selected mode. On367``VIDIOCGAUDIO`` the driver returns the *actually received* audio368programmes in this field. In the V4L2 API this information is stored in369the struct :c:type:`v4l2_tuner` ``rxsubchans`` and370``audmode`` fields, respectively. See :ref:`tuner` for more371information on tuners. Related to audio modes struct372:c:type:`v4l2_audio` also reports if this is a mono or373stereo input, regardless if the source is a tuner.374 375The following fields where replaced by V4L2 controls accessible with the376:ref:`VIDIOC_QUERYCTRL`,377:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and378:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:379 380 381.. flat-table::382 :header-rows: 1383 :stub-columns: 0384 385 * - struct ``video_audio``386 - V4L2 Control ID387 * - ``volume``388 - ``V4L2_CID_AUDIO_VOLUME``389 * - ``bass``390 - ``V4L2_CID_AUDIO_BASS``391 * - ``treble``392 - ``V4L2_CID_AUDIO_TREBLE``393 * - ``balance``394 - ``V4L2_CID_AUDIO_BALANCE``395 396To determine which of these controls are supported by a driver V4L397provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,398``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the399:ref:`VIDIOC_QUERYCTRL` ioctl reports if the400respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``401and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean402``V4L2_CID_AUDIO_MUTE`` control.403 404All V4L2 controls have a ``step`` attribute replacing the struct405``video_audio`` ``step`` field. The V4L audio controls406are assumed to range from 0 to 65535 with no particular reset value. The407V4L2 API permits arbitrary limits and defaults which can be queried with408the :ref:`VIDIOC_QUERYCTRL` ioctl. For general409information about controls see :ref:`control`.410 411Frame Buffer Overlay412====================413 414The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are415:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and416:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct417``video_buffer`` remained unchanged, except V4L2 defines418a flag to indicate non-destructive overlays instead of a ``NULL``419pointer. All other fields moved into the struct420:c:type:`v4l2_pix_format` ``fmt`` substructure of421struct :c:type:`v4l2_framebuffer`. The ``depth``422field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a423list of RGB formats and their respective color depths.424 425Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2426uses the general-purpose data format negotiation ioctls427:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and428:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct429:c:type:`v4l2_format` as argument. Here the ``win`` member430of the ``fmt`` union is used, a struct431:c:type:`v4l2_window`.432 433The ``x``, ``y``, ``width`` and ``height`` fields of struct434``video_window`` moved into struct435:c:type:`v4l2_rect` substructure ``w`` of struct436:c:type:`v4l2_window`. The ``chromakey``, ``clips``, and437``clipcount`` fields remained unchanged. Struct438``video_clip`` was renamed to struct439:c:type:`v4l2_clip`, also containing a struct440:c:type:`v4l2_rect`, but the semantics are still the same.441 442The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications443must set the ``field`` field to ``V4L2_FIELD_ANY`` or444``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved445into struct :c:type:`v4l2_framebuffer`, under the new446name ``V4L2_FBUF_FLAG_CHROMAKEY``.447 448In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``449to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed450size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`451has a separate ``bitmap`` pointer field for this purpose and the bitmap452size is determined by ``w.width`` and ``w.height``.453 454The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to455:ref:`VIDIOC_OVERLAY`.456 457Cropping458========459 460To capture only a subsection of the full picture V4L defines the461``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct462``video_capture``. The equivalent V4L2 ioctls are463:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and464:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct465:c:type:`v4l2_crop`, and the related466:ref:`VIDIOC_CROPCAP` ioctl. This is a rather467complex matter, see :ref:`crop` for details.468 469The ``x``, ``y``, ``width`` and ``height`` fields moved into struct470:c:type:`v4l2_rect` substructure ``c`` of struct471:c:type:`v4l2_crop`. The ``decimation`` field was dropped. In472the V4L2 API the scaling factor is implied by the size of the cropping473rectangle and the size of the captured or overlaid image.474 475The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture476only the odd or even field, respectively, were replaced by477``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named478``field`` of struct :c:type:`v4l2_pix_format` and479struct :c:type:`v4l2_window`. These structures are used to480select a capture or overlay format with the481:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.482 483Reading Images, Memory Mapping484==============================485 486Capturing using the read method487-------------------------------488 489There is no essential difference between reading images from a V4L or490V4L2 device using the :c:func:`read()` function, however V4L2491drivers are not required to support this I/O method. Applications can492determine if the function is available with the493:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices494exchanging data with applications must support the495:c:func:`select()` and :c:func:`poll()`496functions.497 498To select an image format and size, V4L provides the ``VIDIOCSPICT`` and499``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format500negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and501:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct502:c:type:`v4l2_format` as argument, here the struct503:c:type:`v4l2_pix_format` named ``pix`` of its504``fmt`` union is used.505 506For more information about the V4L2 read interface see :ref:`rw`.507 508Capturing using memory mapping509------------------------------510 511Applications can read from V4L devices by mapping buffers in device512memory, or more often just buffers allocated in DMA-able system memory,513into their address space. This avoids the data copying overhead of the514read method. V4L2 supports memory mapping as well, with a few515differences.516 517 518.. flat-table::519 :header-rows: 1520 :stub-columns: 0521 522 * - V4L523 - V4L2524 * -525 - The image format must be selected before buffers are allocated,526 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no527 format is selected the driver may use the last, possibly by528 another application requested format.529 * - Applications cannot change the number of buffers. The it is built530 into the driver, unless it has a module option to change the531 number when the driver module is loaded.532 - The :ref:`VIDIOC_REQBUFS` ioctl allocates the533 desired number of buffers, this is a required step in the534 initialization sequence.535 * - Drivers map all buffers as one contiguous range of memory. The536 ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,537 the offset of each buffer from the start of the virtual file, and538 the overall amount of memory used, which can be used as arguments539 for the :c:func:`mmap()` function.540 - Buffers are individually mapped. The offset and size of each541 buffer can be determined with the542 :ref:`VIDIOC_QUERYBUF` ioctl.543 * - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It544 also determines the image format for this buffer. The ioctl545 returns immediately, eventually with an ``EAGAIN`` error code if no546 video signal had been detected. When the driver supports more than547 one buffer applications can call the ioctl multiple times and thus548 have multiple outstanding capture requests.549 550 The ``VIDIOCSYNC`` ioctl suspends execution until a particular551 buffer has been filled.552 - Drivers maintain an incoming and outgoing queue.553 :ref:`VIDIOC_QBUF` enqueues any empty buffer into554 the incoming queue. Filled buffers are dequeued from the outgoing555 queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait556 until filled buffers become available this function,557 :c:func:`select()` or :c:func:`poll()` can558 be used. The :ref:`VIDIOC_STREAMON` ioctl559 must be called once after enqueuing one or more buffers to start560 capturing. Its counterpart561 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and562 dequeues all buffers from both queues. Applications can query the563 signal status, if known, with the564 :ref:`VIDIOC_ENUMINPUT` ioctl.565 566For a more in-depth discussion of memory mapping and examples, see567:ref:`mmap`.568 569Reading Raw VBI Data570====================571 572Originally the V4L API did not specify a raw VBI capture interface, only573the device file ``/dev/vbi`` was reserved for this purpose. The only574driver supporting this interface was the BTTV driver, de-facto defining575the V4L VBI interface. Reading from the device yields a raw VBI image576with the following parameters:577 578 579.. flat-table::580 :header-rows: 1581 :stub-columns: 0582 583 * - struct :c:type:`v4l2_vbi_format`584 - V4L, BTTV driver585 * - sampling_rate586 - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL587 and SECAM (625-line standards)588 * - offset589 - ?590 * - samples_per_line591 - 2048592 * - sample_format593 - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness594 integer) contain a frame counter.595 * - start[]596 - 10, 273 NTSC; 22, 335 PAL and SECAM597 * - count[]598 - 16, 16 [#f9]_599 * - flags600 - 0601 602Undocumented in the V4L specification, in Linux 2.3 the603``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct604``vbi_format`` were added to determine the VBI image605parameters. These ioctls are only partially compatible with the V4L2 VBI606interface specified in :ref:`raw-vbi`.607 608An ``offset`` field does not exist, ``sample_format`` is supposed to be609``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The610remaining fields are probably equivalent to struct611:c:type:`v4l2_vbi_format`.612 613Apparently only the Zoran (ZR 36120) driver implements these ioctls. The614semantics differ from those specified for V4L2 in two ways. The615parameters are reset on :c:func:`open()` and616``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters617are invalid.618 619Miscellaneous620=============621 622V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can623find the VBI device associated with a video capture device (or vice624versa) by reopening the device and requesting VBI data. For details see625:ref:`open`.626 627No replacement exists for ``VIDIOCKEY``, and the V4L functions for628microcode programming. A new interface for MPEG compression and playback629devices is documented in :ref:`extended-controls`.630 631.. [#f1]632 According to Documentation/admin-guide/devices.rst these should be symbolic links633 to ``/dev/video0``. Note the original bttv interface is not634 compatible with V4L or V4L2.635 636.. [#f2]637 According to ``Documentation/admin-guide/devices.rst`` a symbolic link to638 ``/dev/radio0``.639 640.. [#f3]641 This is a custom format used by the BTTV driver, not one of the V4L2642 standard formats.643 644.. [#f4]645 Presumably all V4L RGB formats are little-endian, although some646 drivers might interpret them according to machine endianness. V4L2647 defines little-endian, big-endian and red/blue swapped variants. For648 details see :ref:`pixfmt-rgb`.649 650.. [#f5]651 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same652 formats. Some V4L drivers respond to one, some to the other.653 654.. [#f6]655 Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar656 format.657 658.. [#f7]659 V4L explains this as: "RAW capture (BT848)"660 661.. [#f8]662 Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed663 format.664 665.. [#f9]666 Old driver versions used different values, eventually the custom667 ``BTTV_VBISIZE`` ioctl was added to query the correct values.668