1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _diff-v4l:
5
6 ********************************
7 Differences between V4L and V4L2
8 ********************************
9
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.
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 .. _v4l-dev:
36
37 .. flat-table:: V4L Device Types, Names and Numbers
38 :header-rows: 1
39 :stub-columns: 0
40
41 * - Device Type
42 - File Name
43 - Minor Numbers
44 * - Video capture and overlay
45 - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to
46 ``/dev/video63``
47 - 0-63
48 * - Radio receiver
49 - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
50 - 64-127
51 * - Raw VBI capture
52 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
53 - 224-255
54
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
57 and consequences.
58
59 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
60
61 Querying Capabilities
62 =====================
63
64 The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
65 :ref:`VIDIOC_QUERYCAP`.
66
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
73 introduction.
74
75 .. raw:: latex
76
77 \small
78
79 .. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}|
80
81 .. cssclass:: longtable
82
83 .. flat-table::
84 :header-rows: 1
85 :stub-columns: 0
86
87 * - ``struct video_capability`` ``type``
88 - struct :c:type:`v4l2_capability`
89 ``capabilities`` flags
90 - Purpose
91 * - ``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 struct
105 :c:type:`v4l2_framebuffer`
106 - Whether chromakey overlay is supported. For more information on
107 overlay see :ref:`overlay`.
108 * - ``VID_TYPE_CLIPPING``
109 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
110 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
111 struct :c:type:`v4l2_framebuffer`
112 - Whether clipping the overlaid image is supported, see
113 :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, see
118 :ref:`overlay`.
119 * - ``VID_TYPE_SCALES``
120 - ``-``
121 - This flag indicates if the hardware can scale images. The V4L2 API
122 implies the scale factor by setting the cropping dimensions and
123 image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
124 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
125 driver returns the closest sizes possible. For more information on
126 cropping and scaling see :ref:`crop`.
127 * - ``VID_TYPE_MONOCHROME``
128 - ``-``
129 - Applications can enumerate the supported image formats with the
130 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
131 the device supports grey scale capturing only. For more
132 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 subsection
137 of the full picture ("cropping" in V4L2). If not, the ioctl
138 returns the ``EINVAL`` error code. For more information on cropping
139 and scaling see :ref:`crop`.
140 * - ``VID_TYPE_MPEG_DECODER``
141 - ``-``
142 - Applications can enumerate the supported image formats with the
143 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
144 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:: latex
156
157 \normalsize
158
159 The ``audios`` field was replaced by ``capabilities`` flag
160 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
161 outputs. To determine their number applications can enumerate audio
162 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
163 audio ioctls are described in :ref:`audio`.
164
165 The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
166 were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
167 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
168 dimensions returns the closest size possible, taking into account the
169 current video standard, cropping and scaling limitations.
170
171 Video Sources
172 =============
173
174 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
175 ``video_channel`` to enumerate the video inputs of a V4L
176 device. The equivalent V4L2 ioctls are
177 :ref:`VIDIOC_ENUMINPUT`,
178 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
179 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
180 :c:type:`v4l2_input` as discussed in :ref:`video`.
181
182 The ``channel`` field counting inputs was renamed to ``index``, the
183 video input types were renamed as follows:
184
185
186 .. flat-table::
187 :header-rows: 1
188 :stub-columns: 0
189
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
197 Unlike the ``tuners`` field expressing the number of tuners of this
198 input, V4L2 assumes each video input is connected to at most one tuner.
199 However a tuner can have more than one input, i. e. RF connectors, and a
200 device can have multiple tuners. The index number of the tuner
201 associated with the input, if any, is stored in field ``tuner`` of
202 struct :c:type:`v4l2_input`. Enumeration of tuners is
203 discussed in :ref:`tuner`.
204
205 The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
206 associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
207 ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
208 considers devices with up to 32 audio inputs. Each set bit in the
209 ``audioset`` field represents one audio input this video input combines
210 with. For information about audio inputs and how to switch between them
211 see :ref:`audio`.
212
213 The ``norm`` field describing the supported video standards was replaced
214 by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
215 indicating whether the standard can be changed. This flag was a later
216 addition together with the ``norm`` field and has been removed in the
217 meantime. V4L2 has a similar, albeit more comprehensive approach to
218 video standards, see :ref:`standard` for more information.
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 .. _v4l-image-properties:
264
265 Image Properties
266 ================
267
268 V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
269 and struct ``video_picture``. The following fields where
270 replaced by V4L2 controls accessible with the
271 :ref:`VIDIOC_QUERYCTRL`,
272 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
273 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
274
275
276 .. flat-table::
277 :header-rows: 1
278 :stub-columns: 0
279
280 * - struct ``video_picture``
281 - V4L2 Control ID
282 * - ``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
293 The V4L picture controls are assumed to range from 0 to 65535 with no
294 particular reset value. The V4L2 API permits arbitrary limits and
295 defaults which can be queried with the
296 :ref:`VIDIOC_QUERYCTRL` ioctl. For general
297 information about controls see :ref:`control`.
298
299 The ``depth`` (average number of bits per pixel) of a video image is
300 implied by the selected image format. V4L2 does not explicitly provide
301 such information assuming applications recognizing the format are aware
302 of the image depth and others need not know. The ``palette`` field moved
303 into the struct :c:type:`v4l2_pix_format`:
304
305
306 .. flat-table::
307 :header-rows: 1
308 :stub-columns: 0
309
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 - None
332 * - ``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
345 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
346 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
347
348 Audio
349 =====
350
351 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
352 ``video_audio`` are used to enumerate the audio inputs
353 of a V4L device. The equivalent V4L2 ioctls are
354 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
355 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
356 :c:type:`v4l2_audio` as discussed in :ref:`audio`.
357
358 The ``audio`` "channel number" field counting audio inputs was renamed
359 to ``index``.
360
361 On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
362 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
363 ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
364 standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
365 ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
366 specification, there is no way to query the selected mode. On
367 ``VIDIOCGAUDIO`` the driver returns the *actually received* audio
368 programmes in this field. In the V4L2 API this information is stored in
369 the struct :c:type:`v4l2_tuner` ``rxsubchans`` and
370 ``audmode`` fields, respectively. See :ref:`tuner` for more
371 information on tuners. Related to audio modes struct
372 :c:type:`v4l2_audio` also reports if this is a mono or
373 stereo input, regardless if the source is a tuner.
374
375 The following fields where replaced by V4L2 controls accessible with the
376 :ref:`VIDIOC_QUERYCTRL`,
377 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
378 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
379
380
381 .. flat-table::
382 :header-rows: 1
383 :stub-columns: 0
384
385 * - struct ``video_audio``
386 - V4L2 Control ID
387 * - ``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
396 To determine which of these controls are supported by a driver V4L
397 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
398 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
399 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the
400 respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
401 and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
402 ``V4L2_CID_AUDIO_MUTE`` control.
403
404 All V4L2 controls have a ``step`` attribute replacing the struct
405 ``video_audio`` ``step`` field. The V4L audio controls
406 are assumed to range from 0 to 65535 with no particular reset value. The
407 V4L2 API permits arbitrary limits and defaults which can be queried with
408 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
409 information about controls see :ref:`control`.
410
411 Frame Buffer Overlay
412 ====================
413
414 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
415 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
416 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
417 ``video_buffer`` remained unchanged, except V4L2 defines
418 a flag to indicate non-destructive overlays instead of a ``NULL``
419 pointer. All other fields moved into the struct
420 :c:type:`v4l2_pix_format` ``fmt`` substructure of
421 struct :c:type:`v4l2_framebuffer`. The ``depth``
422 field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
423 list of RGB formats and their respective color depths.
424
425 Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
426 uses the general-purpose data format negotiation ioctls
427 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
428 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
429 :c:type:`v4l2_format` as argument. Here the ``win`` member
430 of the ``fmt`` union is used, a struct
431 :c:type:`v4l2_window`.
432
433 The ``x``, ``y``, ``width`` and ``height`` fields of struct
434 ``video_window`` moved into struct
435 :c:type:`v4l2_rect` substructure ``w`` of struct
436 :c:type:`v4l2_window`. The ``chromakey``, ``clips``, and
437 ``clipcount`` fields remained unchanged. Struct
438 ``video_clip`` was renamed to struct
439 :c:type:`v4l2_clip`, also containing a struct
440 :c:type:`v4l2_rect`, but the semantics are still the same.
441
442 The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
443 must set the ``field`` field to ``V4L2_FIELD_ANY`` or
444 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
445 into struct :c:type:`v4l2_framebuffer`, under the new
446 name ``V4L2_FBUF_FLAG_CHROMAKEY``.
447
448 In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
449 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
450 size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`
451 has a separate ``bitmap`` pointer field for this purpose and the bitmap
452 size is determined by ``w.width`` and ``w.height``.
453
454 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
455 :ref:`VIDIOC_OVERLAY`.
456
457 Cropping
458 ========
459
460 To capture only a subsection of the full picture V4L defines the
461 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
462 ``video_capture``. The equivalent V4L2 ioctls are
463 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
464 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
465 :c:type:`v4l2_crop`, and the related
466 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather
467 complex matter, see :ref:`crop` for details.
468
469 The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
470 :c:type:`v4l2_rect` substructure ``c`` of struct
471 :c:type:`v4l2_crop`. The ``decimation`` field was dropped. In
472 the V4L2 API the scaling factor is implied by the size of the cropping
473 rectangle and the size of the captured or overlaid image.
474
475 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
476 only the odd or even field, respectively, were replaced by
477 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
478 ``field`` of struct :c:type:`v4l2_pix_format` and
479 struct :c:type:`v4l2_window`. These structures are used to
480 select a capture or overlay format with the
481 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
482
483 Reading Images, Memory Mapping
484 ==============================
485
486 Capturing using the read method
487 -------------------------------
488
489 There is no essential difference between reading images from a V4L or
490 V4L2 device using the :c:func:`read()` function, however V4L2
491 drivers are not required to support this I/O method. Applications can
492 determine if the function is available with the
493 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
494 exchanging data with applications must support the
495 :c:func:`select()` and :c:func:`poll()`
496 functions.
497
498 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
499 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
500 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
501 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
502 :c:type:`v4l2_format` as argument, here the struct
503 :c:type:`v4l2_pix_format` named ``pix`` of its
504 ``fmt`` union is used.
505
506 For more information about the V4L2 read interface see :ref:`rw`.
507
508 Capturing using memory mapping
509 ------------------------------
510
511 Applications can read from V4L devices by mapping buffers in device
512 memory, or more often just buffers allocated in DMA-able system memory,
513 into their address space. This avoids the data copying overhead of the
514 read method. V4L2 supports memory mapping as well, with a few
515 differences.
516
517
518 .. flat-table::
519 :header-rows: 1
520 :stub-columns: 0
521
522 * - V4L
523 - V4L2
524 * -
525 - The image format must be selected before buffers are allocated,
526 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
527 format is selected the driver may use the last, possibly by
528 another application requested format.
529 * - Applications cannot change the number of buffers. The it is built
530 into the driver, unless it has a module option to change the
531 number when the driver module is loaded.
532 - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
533 desired number of buffers, this is a required step in the
534 initialization sequence.
535 * - Drivers map all buffers as one contiguous range of memory. The
536 ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
537 the offset of each buffer from the start of the virtual file, and
538 the overall amount of memory used, which can be used as arguments
539 for the :c:func:`mmap()` function.
540 - Buffers are individually mapped. The offset and size of each
541 buffer can be determined with the
542 :ref:`VIDIOC_QUERYBUF` ioctl.
543 * - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
544 also determines the image format for this buffer. The ioctl
545 returns immediately, eventually with an ``EAGAIN`` error code if no
546 video signal had been detected. When the driver supports more than
547 one buffer applications can call the ioctl multiple times and thus
548 have multiple outstanding capture requests.
549
550 The ``VIDIOCSYNC`` ioctl suspends execution until a particular
551 buffer has been filled.
552 - Drivers maintain an incoming and outgoing queue.
553 :ref:`VIDIOC_QBUF` enqueues any empty buffer into
554 the incoming queue. Filled buffers are dequeued from the outgoing
555 queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
556 until filled buffers become available this function,
557 :c:func:`select()` or :c:func:`poll()` can
558 be used. The :ref:`VIDIOC_STREAMON` ioctl
559 must be called once after enqueuing one or more buffers to start
560 capturing. Its counterpart
561 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
562 dequeues all buffers from both queues. Applications can query the
563 signal status, if known, with the
564 :ref:`VIDIOC_ENUMINPUT` ioctl.
565
566 For a more in-depth discussion of memory mapping and examples, see
567 :ref:`mmap`.
568
569 Reading Raw VBI Data
570 ====================
571
572 Originally the V4L API did not specify a raw VBI capture interface, only
573 the device file ``/dev/vbi`` was reserved for this purpose. The only
574 driver supporting this interface was the BTTV driver, de-facto defining
575 the V4L VBI interface. Reading from the device yields a raw VBI image
576 with the following parameters:
577
578
579 .. flat-table::
580 :header-rows: 1
581 :stub-columns: 0
582
583 * - struct :c:type:`v4l2_vbi_format`
584 - V4L, BTTV driver
585 * - sampling_rate
586 - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
587 and SECAM (625-line standards)
588 * - offset
589 - ?
590 * - samples_per_line
591 - 2048
592 * - sample_format
593 - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
594 integer) contain a frame counter.
595 * - start[]
596 - 10, 273 NTSC; 22, 335 PAL and SECAM
597 * - count[]
598 - 16, 16 [#f9]_
599 * - flags
600 - 0
601
602 Undocumented in the V4L specification, in Linux 2.3 the
603 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
604 ``vbi_format`` were added to determine the VBI image
605 parameters. These ioctls are only partially compatible with the V4L2 VBI
606 interface specified in :ref:`raw-vbi`.
607
608 An ``offset`` field does not exist, ``sample_format`` is supposed to be
609 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
610 remaining fields are probably equivalent to struct
611 :c:type:`v4l2_vbi_format`.
612
613 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
614 semantics differ from those specified for V4L2 in two ways. The
615 parameters are reset on :c:func:`open()` and
616 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
617 are invalid.
618
619 Miscellaneous
620 =============
621
622 V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
623 find the VBI device associated with a video capture device (or vice
624 versa) by reopening the device and requesting VBI data. For details see
625 :ref:`open`.
626
627 No replacement exists for ``VIDIOCKEY``, and the V4L functions for
628 microcode programming. A new interface for MPEG compression and playback
629 devices is documented in :ref:`extended-controls`.
630
631 .. [#f1]
632 According to Documentation/admin-guide/devices.rst these should be symbolic links
633 to ``/dev/video0``. Note the original bttv interface is not
634 compatible with V4L or V4L2.
635
636 .. [#f2]
637 According to ``Documentation/admin-guide/devices.rst`` a symbolic link to
638 ``/dev/radio0``.
639
640 .. [#f3]
641 This is a custom format used by the BTTV driver, not one of the V4L2
642 standard formats.
643
644 .. [#f4]
645 Presumably all V4L RGB formats are little-endian, although some
646 drivers might interpret them according to machine endianness. V4L2
647 defines little-endian, big-endian and red/blue swapped variants. For
648 details see :ref:`pixfmt-rgb`.
649
650 .. [#f5]
651 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
652 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 planar
656 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 packed
663 format.
664
665 .. [#f9]
666 Old driver versions used different values, eventually the custom
667 ``BTTV_VBISIZE`` ioctl was added to query the correct values.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.