1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
6 ********************************
7 Differences between V4L and V4L2
8 ********************************
10 The Video For Linux API was first introduced in Linux 2.1 to unify and
11 replace various TV and radio device related interfaces, developed
12 independently by driver writers in prior years. Starting with Linux 2.5
13 the much improved V4L2 API replaces the V4L API. The support for the old
14 V4L calls were removed from Kernel, but the library :ref:`libv4l`
15 supports the conversion of a V4L API system call into a V4L2 one.
17 Opening and Closing Devices
18 ===========================
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`.
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.
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.
37 .. flat-table:: V4L Device Types, Names and Numbers
44 * - Video capture and overlay
45 - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to
49 - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
52 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
55 V4L prohibits (or used to prohibit) multiple opens of a device file.
56 V4L2 drivers *may* support multiple opens, see :ref:`open` for details
59 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
64 The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
65 :ref:`VIDIOC_QUERYCAP`.
67 The ``name`` field in struct ``video_capability`` became
68 ``card`` in struct :c:type:`v4l2_capability`, ``type``
69 was replaced by ``capabilities``. Note V4L2 does not distinguish between
70 device types like this, better think of basic video input, video output
71 and radio devices supporting a set of related functions like video
72 capturing, video overlay and VBI capturing. See :ref:`open` for an
75 .. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm}
77 .. cssclass:: longtable
83 * - ``struct video_capability`` ``type``
84 - struct :c:type:`v4l2_capability`
85 ``capabilities`` flags
87 * - ``VID_TYPE_CAPTURE``
88 - ``V4L2_CAP_VIDEO_CAPTURE``
89 - The :ref:`video capture <capture>` interface is supported.
90 * - ``VID_TYPE_TUNER``
92 - The device has a :ref:`tuner or modulator <tuner>`.
93 * - ``VID_TYPE_TELETEXT``
94 - ``V4L2_CAP_VBI_CAPTURE``
95 - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
96 * - ``VID_TYPE_OVERLAY``
97 - ``V4L2_CAP_VIDEO_OVERLAY``
98 - The :ref:`video overlay <overlay>` interface is supported.
99 * - ``VID_TYPE_CHROMAKEY``
100 - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
101 :c:type:`v4l2_framebuffer`
102 - Whether chromakey overlay is supported. For more information on
103 overlay see :ref:`overlay`.
104 * - ``VID_TYPE_CLIPPING``
105 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
106 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
107 struct :c:type:`v4l2_framebuffer`
108 - Whether clipping the overlaid image is supported, see
110 * - ``VID_TYPE_FRAMERAM``
111 - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
112 of struct :c:type:`v4l2_framebuffer`
113 - Whether overlay overwrites frame buffer memory, see
115 * - ``VID_TYPE_SCALES``
117 - This flag indicates if the hardware can scale images. The V4L2 API
118 implies the scale factor by setting the cropping dimensions and
119 image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
120 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
121 driver returns the closest sizes possible. For more information on
122 cropping and scaling see :ref:`crop`.
123 * - ``VID_TYPE_MONOCHROME``
125 - Applications can enumerate the supported image formats with the
126 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
127 the device supports grey scale capturing only. For more
128 information on image formats see :ref:`pixfmt`.
129 * - ``VID_TYPE_SUBCAPTURE``
131 - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
132 ioctl to determine if the device supports capturing a subsection
133 of the full picture ("cropping" in V4L2). If not, the ioctl
134 returns the ``EINVAL`` error code. For more information on cropping
135 and scaling see :ref:`crop`.
136 * - ``VID_TYPE_MPEG_DECODER``
138 - Applications can enumerate the supported image formats with the
139 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
140 the device supports MPEG streams.
141 * - ``VID_TYPE_MPEG_ENCODER``
144 * - ``VID_TYPE_MJPEG_DECODER``
147 * - ``VID_TYPE_MJPEG_ENCODER``
151 The ``audios`` field was replaced by ``capabilities`` flag
152 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
153 outputs. To determine their number applications can enumerate audio
154 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
155 audio ioctls are described in :ref:`audio`.
157 The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
158 were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
159 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
160 dimensions returns the closest size possible, taking into account the
161 current video standard, cropping and scaling limitations.
166 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
167 ``video_channel`` to enumerate the video inputs of a V4L
168 device. The equivalent V4L2 ioctls are
169 :ref:`VIDIOC_ENUMINPUT`,
170 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
171 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
172 :c:type:`v4l2_input` as discussed in :ref:`video`.
174 The ``channel`` field counting inputs was renamed to ``index``, the
175 video input types were renamed as follows:
182 * - struct ``video_channel`` ``type``
183 - struct :c:type:`v4l2_input` ``type``
184 * - ``VIDEO_TYPE_TV``
185 - ``V4L2_INPUT_TYPE_TUNER``
186 * - ``VIDEO_TYPE_CAMERA``
187 - ``V4L2_INPUT_TYPE_CAMERA``
189 Unlike the ``tuners`` field expressing the number of tuners of this
190 input, V4L2 assumes each video input is connected to at most one tuner.
191 However a tuner can have more than one input, i. e. RF connectors, and a
192 device can have multiple tuners. The index number of the tuner
193 associated with the input, if any, is stored in field ``tuner`` of
194 struct :c:type:`v4l2_input`. Enumeration of tuners is
195 discussed in :ref:`tuner`.
197 The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
198 associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
199 ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
200 considers devices with up to 32 audio inputs. Each set bit in the
201 ``audioset`` field represents one audio input this video input combines
202 with. For information about audio inputs and how to switch between them
205 The ``norm`` field describing the supported video standards was replaced
206 by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
207 indicating whether the standard can be changed. This flag was a later
208 addition together with the ``norm`` field and has been removed in the
209 meantime. V4L2 has a similar, albeit more comprehensive approach to
210 video standards, see :ref:`standard` for more information.
215 The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
216 ``video_tuner`` can be used to enumerate the tuners of a
217 V4L TV or radio device. The equivalent V4L2 ioctls are
218 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
219 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
220 :c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`.
222 The ``tuner`` field counting tuners was renamed to ``index``. The fields
223 ``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
225 The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
226 flags indicating the supported video standards were dropped. This
227 information is now contained in the associated struct
228 :c:type:`v4l2_input`. No replacement exists for the
229 ``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
230 switched. The ``mode`` field to select a different video standard was
231 replaced by a whole new set of ioctls and structures described in
232 :ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
233 driver supports several standards in addition to the regular
234 ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
235 ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
236 Japan with numbers 3-6 (sic).
238 The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
239 ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
240 permits the detection of monaural and bilingual audio, see the
241 definition of struct :c:type:`v4l2_tuner` for details.
242 Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
243 ``VIDEO_TUNER_MBS_ON`` flags.
245 The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
246 the struct :c:type:`v4l2_tuner` ``capability`` field.
248 The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
249 frequency where renamed to
250 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
251 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
252 to a struct :c:type:`v4l2_frequency` instead of an
253 unsigned long integer.
255 .. _v4l-image-properties:
260 V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
261 and struct ``video_picture``. The following fields where
262 replaced by V4L2 controls accessible with the
263 :ref:`VIDIOC_QUERYCTRL`,
264 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
265 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
272 * - struct ``video_picture``
275 - ``V4L2_CID_BRIGHTNESS``
279 - ``V4L2_CID_SATURATION``
281 - ``V4L2_CID_CONTRAST``
283 - ``V4L2_CID_WHITENESS``
285 The V4L picture controls are assumed to range from 0 to 65535 with no
286 particular reset value. The V4L2 API permits arbitrary limits and
287 defaults which can be queried with the
288 :ref:`VIDIOC_QUERYCTRL` ioctl. For general
289 information about controls see :ref:`control`.
291 The ``depth`` (average number of bits per pixel) of a video image is
292 implied by the selected image format. V4L2 does not explicitly provide
293 such information assuming applications recognizing the format are aware
294 of the image depth and others need not know. The ``palette`` field moved
295 into the struct :c:type:`v4l2_pix_format`:
302 * - struct ``video_picture`` ``palette``
303 - struct :c:type:`v4l2_pix_format` ``pixfmt``
304 * - ``VIDEO_PALETTE_GREY``
305 - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
306 * - ``VIDEO_PALETTE_HI240``
307 - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_
308 * - ``VIDEO_PALETTE_RGB565``
309 - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
310 * - ``VIDEO_PALETTE_RGB555``
311 - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
312 * - ``VIDEO_PALETTE_RGB24``
313 - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
314 * - ``VIDEO_PALETTE_RGB32``
315 - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_
316 * - ``VIDEO_PALETTE_YUV422``
317 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
318 * - ``VIDEO_PALETTE_YUYV``\ [#f5]_
319 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
320 * - ``VIDEO_PALETTE_UYVY``
321 - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
322 * - ``VIDEO_PALETTE_YUV420``
324 * - ``VIDEO_PALETTE_YUV411``
325 - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_
326 * - ``VIDEO_PALETTE_RAW``
328 * - ``VIDEO_PALETTE_YUV422P``
329 - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
330 * - ``VIDEO_PALETTE_YUV411P``
331 - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_
332 * - ``VIDEO_PALETTE_YUV420P``
333 - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
334 * - ``VIDEO_PALETTE_YUV410P``
335 - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
337 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
338 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
343 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
344 ``video_audio`` are used to enumerate the audio inputs
345 of a V4L device. The equivalent V4L2 ioctls are
346 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
347 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
348 :c:type:`v4l2_audio` as discussed in :ref:`audio`.
350 The ``audio`` "channel number" field counting audio inputs was renamed
353 On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
354 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
355 ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
356 standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
357 ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
358 specification, there is no way to query the selected mode. On
359 ``VIDIOCGAUDIO`` the driver returns the *actually received* audio
360 programmes in this field. In the V4L2 API this information is stored in
361 the struct :c:type:`v4l2_tuner` ``rxsubchans`` and
362 ``audmode`` fields, respectively. See :ref:`tuner` for more
363 information on tuners. Related to audio modes struct
364 :c:type:`v4l2_audio` also reports if this is a mono or
365 stereo input, regardless if the source is a tuner.
367 The following fields where replaced by V4L2 controls accessible with the
368 :ref:`VIDIOC_QUERYCTRL`,
369 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
370 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
377 * - struct ``video_audio``
380 - ``V4L2_CID_AUDIO_VOLUME``
382 - ``V4L2_CID_AUDIO_BASS``
384 - ``V4L2_CID_AUDIO_TREBLE``
386 - ``V4L2_CID_AUDIO_BALANCE``
388 To determine which of these controls are supported by a driver V4L
389 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
390 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
391 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the
392 respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
393 and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
394 ``V4L2_CID_AUDIO_MUTE`` control.
396 All V4L2 controls have a ``step`` attribute replacing the struct
397 ``video_audio`` ``step`` field. The V4L audio controls
398 are assumed to range from 0 to 65535 with no particular reset value. The
399 V4L2 API permits arbitrary limits and defaults which can be queried with
400 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
401 information about controls see :ref:`control`.
406 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
407 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
408 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
409 ``video_buffer`` remained unchanged, except V4L2 defines
410 a flag to indicate non-destructive overlays instead of a ``NULL``
411 pointer. All other fields moved into the struct
412 :c:type:`v4l2_pix_format` ``fmt`` substructure of
413 struct :c:type:`v4l2_framebuffer`. The ``depth``
414 field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
415 list of RGB formats and their respective color depths.
417 Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
418 uses the general-purpose data format negotiation ioctls
419 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
420 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
421 :c:type:`v4l2_format` as argument. Here the ``win`` member
422 of the ``fmt`` union is used, a struct
423 :c:type:`v4l2_window`.
425 The ``x``, ``y``, ``width`` and ``height`` fields of struct
426 ``video_window`` moved into struct
427 :c:type:`v4l2_rect` substructure ``w`` of struct
428 :c:type:`v4l2_window`. The ``chromakey``, ``clips``, and
429 ``clipcount`` fields remained unchanged. Struct
430 ``video_clip`` was renamed to struct
431 :c:type:`v4l2_clip`, also containing a struct
432 :c:type:`v4l2_rect`, but the semantics are still the same.
434 The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
435 must set the ``field`` field to ``V4L2_FIELD_ANY`` or
436 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
437 into struct :c:type:`v4l2_framebuffer`, under the new
438 name ``V4L2_FBUF_FLAG_CHROMAKEY``.
440 In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
441 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
442 size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`
443 has a separate ``bitmap`` pointer field for this purpose and the bitmap
444 size is determined by ``w.width`` and ``w.height``.
446 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
447 :ref:`VIDIOC_OVERLAY`.
452 To capture only a subsection of the full picture V4L defines the
453 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
454 ``video_capture``. The equivalent V4L2 ioctls are
455 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
456 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
457 :c:type:`v4l2_crop`, and the related
458 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather
459 complex matter, see :ref:`crop` for details.
461 The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
462 :c:type:`v4l2_rect` substructure ``c`` of struct
463 :c:type:`v4l2_crop`. The ``decimation`` field was dropped. In
464 the V4L2 API the scaling factor is implied by the size of the cropping
465 rectangle and the size of the captured or overlaid image.
467 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
468 only the odd or even field, respectively, were replaced by
469 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
470 ``field`` of struct :c:type:`v4l2_pix_format` and
471 struct :c:type:`v4l2_window`. These structures are used to
472 select a capture or overlay format with the
473 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
475 Reading Images, Memory Mapping
476 ==============================
478 Capturing using the read method
479 -------------------------------
481 There is no essential difference between reading images from a V4L or
482 V4L2 device using the :c:func:`read()` function, however V4L2
483 drivers are not required to support this I/O method. Applications can
484 determine if the function is available with the
485 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
486 exchanging data with applications must support the
487 :c:func:`select()` and :c:func:`poll()`
490 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
491 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
492 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
493 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
494 :c:type:`v4l2_format` as argument, here the struct
495 :c:type:`v4l2_pix_format` named ``pix`` of its
496 ``fmt`` union is used.
498 For more information about the V4L2 read interface see :ref:`rw`.
500 Capturing using memory mapping
501 ------------------------------
503 Applications can read from V4L devices by mapping buffers in device
504 memory, or more often just buffers allocated in DMA-able system memory,
505 into their address space. This avoids the data copying overhead of the
506 read method. V4L2 supports memory mapping as well, with a few
517 - The image format must be selected before buffers are allocated,
518 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
519 format is selected the driver may use the last, possibly by
520 another application requested format.
521 * - Applications cannot change the number of buffers. The it is built
522 into the driver, unless it has a module option to change the
523 number when the driver module is loaded.
524 - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
525 desired number of buffers, this is a required step in the
526 initialization sequence.
527 * - Drivers map all buffers as one contiguous range of memory. The
528 ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
529 the offset of each buffer from the start of the virtual file, and
530 the overall amount of memory used, which can be used as arguments
531 for the :c:func:`mmap()` function.
532 - Buffers are individually mapped. The offset and size of each
533 buffer can be determined with the
534 :ref:`VIDIOC_QUERYBUF` ioctl.
535 * - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
536 also determines the image format for this buffer. The ioctl
537 returns immediately, eventually with an ``EAGAIN`` error code if no
538 video signal had been detected. When the driver supports more than
539 one buffer applications can call the ioctl multiple times and thus
540 have multiple outstanding capture requests.
542 The ``VIDIOCSYNC`` ioctl suspends execution until a particular
543 buffer has been filled.
544 - Drivers maintain an incoming and outgoing queue.
545 :ref:`VIDIOC_QBUF` enqueues any empty buffer into
546 the incoming queue. Filled buffers are dequeued from the outgoing
547 queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
548 until filled buffers become available this function,
549 :c:func:`select()` or :c:func:`poll()` can
550 be used. The :ref:`VIDIOC_STREAMON` ioctl
551 must be called once after enqueuing one or more buffers to start
552 capturing. Its counterpart
553 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
554 dequeues all buffers from both queues. Applications can query the
555 signal status, if known, with the
556 :ref:`VIDIOC_ENUMINPUT` ioctl.
558 For a more in-depth discussion of memory mapping and examples, see
564 Originally the V4L API did not specify a raw VBI capture interface, only
565 the device file ``/dev/vbi`` was reserved for this purpose. The only
566 driver supporting this interface was the BTTV driver, de-facto defining
567 the V4L VBI interface. Reading from the device yields a raw VBI image
568 with the following parameters:
575 * - struct :c:type:`v4l2_vbi_format`
578 - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
579 and SECAM (625-line standards)
585 - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
586 integer) contain a frame counter.
588 - 10, 273 NTSC; 22, 335 PAL and SECAM
594 Undocumented in the V4L specification, in Linux 2.3 the
595 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
596 ``vbi_format`` were added to determine the VBI image
597 parameters. These ioctls are only partially compatible with the V4L2 VBI
598 interface specified in :ref:`raw-vbi`.
600 An ``offset`` field does not exist, ``sample_format`` is supposed to be
601 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
602 remaining fields are probably equivalent to struct
603 :c:type:`v4l2_vbi_format`.
605 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
606 semantics differ from those specified for V4L2 in two ways. The
607 parameters are reset on :c:func:`open()` and
608 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
614 V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
615 find the VBI device associated with a video capture device (or vice
616 versa) by reopening the device and requesting VBI data. For details see
619 No replacement exists for ``VIDIOCKEY``, and the V4L functions for
620 microcode programming. A new interface for MPEG compression and playback
621 devices is documented in :ref:`extended-controls`.
624 According to Documentation/admin-guide/devices.rst these should be symbolic links
625 to ``/dev/video0``. Note the original bttv interface is not
626 compatible with V4L or V4L2.
629 According to ``Documentation/admin-guide/devices.rst`` a symbolic link to
633 This is a custom format used by the BTTV driver, not one of the V4L2
637 Presumably all V4L RGB formats are little-endian, although some
638 drivers might interpret them according to machine endianness. V4L2
639 defines little-endian, big-endian and red/blue swapped variants. For
640 details see :ref:`pixfmt-rgb`.
643 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
644 formats. Some V4L drivers respond to one, some to the other.
647 Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
651 V4L explains this as: "RAW capture (BT848)"
654 Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
658 Old driver versions used different values, eventually the custom
659 ``BTTV_VBISIZE`` ioctl was added to query the correct values.
projects / linux-2.6-microblaze.git / blob