Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _diff-v4l: | |
4 | ||
5 | ******************************** | |
6 | Differences between V4L and V4L2 | |
7 | ******************************** | |
8 | ||
9 | The Video For Linux API was first introduced in Linux 2.1 to unify and | |
10 | replace various TV and radio device related interfaces, developed | |
11 | independently by driver writers in prior years. Starting with Linux 2.5 | |
12 | the much improved V4L2 API replaces the V4L API. The support for the old | |
13 | V4L calls were removed from Kernel, but the library :ref:`libv4l` | |
14 | supports the conversion of a V4L API system call into a V4L2 one. | |
15 | ||
16 | ||
17 | Opening and Closing Devices | |
18 | =========================== | |
19 | ||
20 | For compatibility reasons the character device file names recommended | |
21 | for V4L2 video capture, overlay, radio and raw vbi capture devices did | |
22 | not change from those used by V4L. They are listed in :ref:`devices` | |
23 | and below in :ref:`v4l-dev`. | |
24 | ||
25 | The teletext devices (minor range 192-223) have been removed in V4L2 and | |
26 | no longer exist. There is no hardware available anymore for handling | |
27 | pure teletext. Instead raw or sliced VBI is used. | |
28 | ||
29 | The V4L ``videodev`` module automatically assigns minor numbers to | |
30 | drivers in load order, depending on the registered device type. We | |
31 | recommend that V4L2 drivers by default register devices with the same | |
32 | numbers, but the system administrator can assign arbitrary minor numbers | |
33 | using driver module options. The major device number remains 81. | |
34 | ||
35 | ||
36 | .. _v4l-dev: | |
37 | ||
38 | .. flat-table:: V4L Device Types, Names and Numbers | |
39 | :header-rows: 1 | |
40 | :stub-columns: 0 | |
41 | ||
42 | ||
43 | - .. row 1 | |
44 | ||
45 | - Device Type | |
46 | ||
47 | - File Name | |
48 | ||
49 | - Minor Numbers | |
50 | ||
51 | - .. row 2 | |
52 | ||
53 | - Video capture and overlay | |
54 | ||
4855307b | 55 | - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to |
0579e6e3 | 56 | ``/dev/video63`` |
5377d91f MH |
57 | |
58 | - 0-63 | |
59 | ||
60 | - .. row 3 | |
61 | ||
62 | - Radio receiver | |
63 | ||
4855307b | 64 | - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63`` |
5377d91f MH |
65 | |
66 | - 64-127 | |
67 | ||
68 | - .. row 4 | |
69 | ||
70 | - Raw VBI capture | |
71 | ||
72 | - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31`` | |
73 | ||
74 | - 224-255 | |
75 | ||
76 | ||
77 | V4L prohibits (or used to prohibit) multiple opens of a device file. | |
78 | V4L2 drivers *may* support multiple opens, see :ref:`open` for details | |
79 | and consequences. | |
80 | ||
cdb4af0f | 81 | V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code. |
5377d91f MH |
82 | |
83 | ||
84 | Querying Capabilities | |
85 | ===================== | |
86 | ||
87 | The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's | |
7347081e | 88 | :ref:`VIDIOC_QUERYCAP`. |
5377d91f | 89 | |
6e862f3c | 90 | The ``name`` field in struct ``video_capability`` became |
e8be7e97 | 91 | ``card`` in struct :c:type:`v4l2_capability`, ``type`` |
5377d91f MH |
92 | was replaced by ``capabilities``. Note V4L2 does not distinguish between |
93 | device types like this, better think of basic video input, video output | |
94 | and radio devices supporting a set of related functions like video | |
95 | capturing, video overlay and VBI capturing. See :ref:`open` for an | |
96 | introduction. | |
97 | ||
3532d9d6 | 98 | .. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm} |
5377d91f | 99 | |
3532d9d6 | 100 | .. cssclass:: longtable |
5377d91f MH |
101 | |
102 | .. flat-table:: | |
103 | :header-rows: 1 | |
104 | :stub-columns: 0 | |
105 | ||
106 | ||
107 | - .. row 1 | |
108 | ||
3532d9d6 | 109 | - ``struct video_capability`` ``type`` |
5377d91f | 110 | |
e8be7e97 | 111 | - struct :c:type:`v4l2_capability` |
0579e6e3 | 112 | ``capabilities`` flags |
5377d91f MH |
113 | |
114 | - Purpose | |
115 | ||
116 | - .. row 2 | |
117 | ||
118 | - ``VID_TYPE_CAPTURE`` | |
119 | ||
120 | - ``V4L2_CAP_VIDEO_CAPTURE`` | |
121 | ||
122 | - The :ref:`video capture <capture>` interface is supported. | |
123 | ||
124 | - .. row 3 | |
125 | ||
126 | - ``VID_TYPE_TUNER`` | |
127 | ||
128 | - ``V4L2_CAP_TUNER`` | |
129 | ||
130 | - The device has a :ref:`tuner or modulator <tuner>`. | |
131 | ||
132 | - .. row 4 | |
133 | ||
134 | - ``VID_TYPE_TELETEXT`` | |
135 | ||
136 | - ``V4L2_CAP_VBI_CAPTURE`` | |
137 | ||
138 | - The :ref:`raw VBI capture <raw-vbi>` interface is supported. | |
139 | ||
140 | - .. row 5 | |
141 | ||
142 | - ``VID_TYPE_OVERLAY`` | |
143 | ||
144 | - ``V4L2_CAP_VIDEO_OVERLAY`` | |
145 | ||
146 | - The :ref:`video overlay <overlay>` interface is supported. | |
147 | ||
148 | - .. row 6 | |
149 | ||
150 | - ``VID_TYPE_CHROMAKEY`` | |
151 | ||
152 | - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct | |
e8be7e97 | 153 | :c:type:`v4l2_framebuffer` |
5377d91f MH |
154 | |
155 | - Whether chromakey overlay is supported. For more information on | |
0579e6e3 | 156 | overlay see :ref:`overlay`. |
5377d91f MH |
157 | |
158 | - .. row 7 | |
159 | ||
160 | - ``VID_TYPE_CLIPPING`` | |
161 | ||
162 | - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and | |
0579e6e3 | 163 | ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of |
e8be7e97 | 164 | struct :c:type:`v4l2_framebuffer` |
5377d91f MH |
165 | |
166 | - Whether clipping the overlaid image is supported, see | |
0579e6e3 | 167 | :ref:`overlay`. |
5377d91f MH |
168 | |
169 | - .. row 8 | |
170 | ||
171 | - ``VID_TYPE_FRAMERAM`` | |
172 | ||
173 | - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability`` | |
e8be7e97 | 174 | of struct :c:type:`v4l2_framebuffer` |
5377d91f MH |
175 | |
176 | - Whether overlay overwrites frame buffer memory, see | |
0579e6e3 | 177 | :ref:`overlay`. |
5377d91f MH |
178 | |
179 | - .. row 9 | |
180 | ||
181 | - ``VID_TYPE_SCALES`` | |
182 | ||
183 | - ``-`` | |
184 | ||
185 | - This flag indicates if the hardware can scale images. The V4L2 API | |
0579e6e3 MCC |
186 | implies the scale factor by setting the cropping dimensions and |
187 | image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and | |
188 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The | |
189 | driver returns the closest sizes possible. For more information on | |
190 | cropping and scaling see :ref:`crop`. | |
5377d91f MH |
191 | |
192 | - .. row 10 | |
193 | ||
194 | - ``VID_TYPE_MONOCHROME`` | |
195 | ||
196 | - ``-`` | |
197 | ||
198 | - Applications can enumerate the supported image formats with the | |
0579e6e3 MCC |
199 | :ref:`VIDIOC_ENUM_FMT` ioctl to determine if |
200 | the device supports grey scale capturing only. For more | |
201 | information on image formats see :ref:`pixfmt`. | |
5377d91f MH |
202 | |
203 | - .. row 11 | |
204 | ||
205 | - ``VID_TYPE_SUBCAPTURE`` | |
206 | ||
207 | - ``-`` | |
208 | ||
4e03cb76 | 209 | - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` |
0579e6e3 MCC |
210 | ioctl to determine if the device supports capturing a subsection |
211 | of the full picture ("cropping" in V4L2). If not, the ioctl | |
212 | returns the ``EINVAL`` error code. For more information on cropping | |
213 | and scaling see :ref:`crop`. | |
5377d91f MH |
214 | |
215 | - .. row 12 | |
216 | ||
217 | - ``VID_TYPE_MPEG_DECODER`` | |
218 | ||
219 | - ``-`` | |
220 | ||
221 | - Applications can enumerate the supported image formats with the | |
0579e6e3 MCC |
222 | :ref:`VIDIOC_ENUM_FMT` ioctl to determine if |
223 | the device supports MPEG streams. | |
5377d91f MH |
224 | |
225 | - .. row 13 | |
226 | ||
227 | - ``VID_TYPE_MPEG_ENCODER`` | |
228 | ||
229 | - ``-`` | |
230 | ||
231 | - See above. | |
232 | ||
233 | - .. row 14 | |
234 | ||
235 | - ``VID_TYPE_MJPEG_DECODER`` | |
236 | ||
237 | - ``-`` | |
238 | ||
239 | - See above. | |
240 | ||
241 | - .. row 15 | |
242 | ||
243 | - ``VID_TYPE_MJPEG_ENCODER`` | |
244 | ||
245 | - ``-`` | |
246 | ||
247 | - See above. | |
248 | ||
249 | ||
250 | The ``audios`` field was replaced by ``capabilities`` flag | |
251 | ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or | |
252 | outputs. To determine their number applications can enumerate audio | |
4e03cb76 | 253 | inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The |
5377d91f MH |
254 | audio ioctls are described in :ref:`audio`. |
255 | ||
256 | The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields | |
af4a4d0d MCC |
257 | were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or |
258 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired | |
5377d91f MH |
259 | dimensions returns the closest size possible, taking into account the |
260 | current video standard, cropping and scaling limitations. | |
261 | ||
262 | ||
263 | Video Sources | |
264 | ============= | |
265 | ||
266 | V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct | |
6e862f3c | 267 | ``video_channel`` to enumerate the video inputs of a V4L |
5377d91f | 268 | device. The equivalent V4L2 ioctls are |
7347081e | 269 | :ref:`VIDIOC_ENUMINPUT`, |
4e03cb76 | 270 | :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and |
af4a4d0d | 271 | :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct |
e8be7e97 | 272 | :c:type:`v4l2_input` as discussed in :ref:`video`. |
5377d91f MH |
273 | |
274 | The ``channel`` field counting inputs was renamed to ``index``, the | |
275 | video input types were renamed as follows: | |
276 | ||
277 | ||
278 | ||
279 | .. flat-table:: | |
280 | :header-rows: 1 | |
281 | :stub-columns: 0 | |
282 | ||
283 | ||
284 | - .. row 1 | |
285 | ||
6e862f3c | 286 | - struct ``video_channel`` ``type`` |
5377d91f | 287 | |
e8be7e97 | 288 | - struct :c:type:`v4l2_input` ``type`` |
5377d91f MH |
289 | |
290 | - .. row 2 | |
291 | ||
292 | - ``VIDEO_TYPE_TV`` | |
293 | ||
294 | - ``V4L2_INPUT_TYPE_TUNER`` | |
295 | ||
296 | - .. row 3 | |
297 | ||
298 | - ``VIDEO_TYPE_CAMERA`` | |
299 | ||
300 | - ``V4L2_INPUT_TYPE_CAMERA`` | |
301 | ||
302 | ||
303 | Unlike the ``tuners`` field expressing the number of tuners of this | |
304 | input, V4L2 assumes each video input is connected to at most one tuner. | |
305 | However a tuner can have more than one input, i. e. RF connectors, and a | |
306 | device can have multiple tuners. The index number of the tuner | |
307 | associated with the input, if any, is stored in field ``tuner`` of | |
e8be7e97 | 308 | struct :c:type:`v4l2_input`. Enumeration of tuners is |
5377d91f MH |
309 | discussed in :ref:`tuner`. |
310 | ||
311 | The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs | |
312 | associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The | |
313 | ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2 | |
314 | considers devices with up to 32 audio inputs. Each set bit in the | |
315 | ``audioset`` field represents one audio input this video input combines | |
316 | with. For information about audio inputs and how to switch between them | |
317 | see :ref:`audio`. | |
318 | ||
319 | The ``norm`` field describing the supported video standards was replaced | |
320 | by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM`` | |
321 | indicating whether the standard can be changed. This flag was a later | |
322 | addition together with the ``norm`` field and has been removed in the | |
323 | meantime. V4L2 has a similar, albeit more comprehensive approach to | |
324 | video standards, see :ref:`standard` for more information. | |
325 | ||
326 | ||
327 | Tuning | |
328 | ====== | |
329 | ||
330 | The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct | |
6e862f3c | 331 | ``video_tuner`` can be used to enumerate the tuners of a |
5377d91f | 332 | V4L TV or radio device. The equivalent V4L2 ioctls are |
4e03cb76 | 333 | :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and |
af4a4d0d | 334 | :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct |
e8be7e97 | 335 | :c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`. |
5377d91f MH |
336 | |
337 | The ``tuner`` field counting tuners was renamed to ``index``. The fields | |
338 | ``name``, ``rangelow`` and ``rangehigh`` remained unchanged. | |
339 | ||
340 | The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM`` | |
341 | flags indicating the supported video standards were dropped. This | |
342 | information is now contained in the associated struct | |
e8be7e97 | 343 | :c:type:`v4l2_input`. No replacement exists for the |
5377d91f MH |
344 | ``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be |
345 | switched. The ``mode`` field to select a different video standard was | |
346 | replaced by a whole new set of ioctls and structures described in | |
347 | :ref:`standard`. Due to its ubiquity it should be mentioned the BTTV | |
348 | driver supports several standards in addition to the regular | |
349 | ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and | |
350 | ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC | |
351 | Japan with numbers 3-6 (sic). | |
352 | ||
353 | The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became | |
354 | ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also | |
355 | permits the detection of monaural and bilingual audio, see the | |
e8be7e97 | 356 | definition of struct :c:type:`v4l2_tuner` for details. |
5377d91f MH |
357 | Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and |
358 | ``VIDEO_TUNER_MBS_ON`` flags. | |
359 | ||
360 | The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in | |
e8be7e97 | 361 | the struct :c:type:`v4l2_tuner` ``capability`` field. |
5377d91f MH |
362 | |
363 | The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner | |
364 | frequency where renamed to | |
4e03cb76 | 365 | :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and |
af4a4d0d | 366 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer |
e8be7e97 | 367 | to a struct :c:type:`v4l2_frequency` instead of an |
5377d91f MH |
368 | unsigned long integer. |
369 | ||
370 | ||
371 | .. _v4l-image-properties: | |
372 | ||
373 | Image Properties | |
374 | ================ | |
375 | ||
376 | V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl | |
6e862f3c | 377 | and struct ``video_picture``. The following fields where |
5377d91f | 378 | replaced by V4L2 controls accessible with the |
7347081e | 379 | :ref:`VIDIOC_QUERYCTRL`, |
4e03cb76 | 380 | :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and |
af4a4d0d | 381 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: |
5377d91f MH |
382 | |
383 | ||
384 | ||
385 | .. flat-table:: | |
386 | :header-rows: 1 | |
387 | :stub-columns: 0 | |
388 | ||
389 | ||
390 | - .. row 1 | |
391 | ||
6e862f3c | 392 | - struct ``video_picture`` |
5377d91f MH |
393 | |
394 | - V4L2 Control ID | |
395 | ||
396 | - .. row 2 | |
397 | ||
398 | - ``brightness`` | |
399 | ||
400 | - ``V4L2_CID_BRIGHTNESS`` | |
401 | ||
402 | - .. row 3 | |
403 | ||
404 | - ``hue`` | |
405 | ||
406 | - ``V4L2_CID_HUE`` | |
407 | ||
408 | - .. row 4 | |
409 | ||
410 | - ``colour`` | |
411 | ||
412 | - ``V4L2_CID_SATURATION`` | |
413 | ||
414 | - .. row 5 | |
415 | ||
416 | - ``contrast`` | |
417 | ||
418 | - ``V4L2_CID_CONTRAST`` | |
419 | ||
420 | - .. row 6 | |
421 | ||
422 | - ``whiteness`` | |
423 | ||
424 | - ``V4L2_CID_WHITENESS`` | |
425 | ||
426 | ||
427 | The V4L picture controls are assumed to range from 0 to 65535 with no | |
428 | particular reset value. The V4L2 API permits arbitrary limits and | |
429 | defaults which can be queried with the | |
7347081e | 430 | :ref:`VIDIOC_QUERYCTRL` ioctl. For general |
5377d91f MH |
431 | information about controls see :ref:`control`. |
432 | ||
433 | The ``depth`` (average number of bits per pixel) of a video image is | |
434 | implied by the selected image format. V4L2 does not explicitly provide | |
435 | such information assuming applications recognizing the format are aware | |
436 | of the image depth and others need not know. The ``palette`` field moved | |
e8be7e97 | 437 | into the struct :c:type:`v4l2_pix_format`: |
5377d91f MH |
438 | |
439 | ||
440 | ||
441 | .. flat-table:: | |
442 | :header-rows: 1 | |
443 | :stub-columns: 0 | |
444 | ||
445 | ||
446 | - .. row 1 | |
447 | ||
6e862f3c | 448 | - struct ``video_picture`` ``palette`` |
5377d91f | 449 | |
e8be7e97 | 450 | - struct :c:type:`v4l2_pix_format` ``pixfmt`` |
5377d91f MH |
451 | |
452 | - .. row 2 | |
453 | ||
454 | - ``VIDEO_PALETTE_GREY`` | |
455 | ||
456 | - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>` | |
457 | ||
458 | - .. row 3 | |
459 | ||
460 | - ``VIDEO_PALETTE_HI240`` | |
461 | ||
4855307b | 462 | - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_ |
5377d91f MH |
463 | |
464 | - .. row 4 | |
465 | ||
466 | - ``VIDEO_PALETTE_RGB565`` | |
467 | ||
468 | - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>` | |
469 | ||
470 | - .. row 5 | |
471 | ||
472 | - ``VIDEO_PALETTE_RGB555`` | |
473 | ||
474 | - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>` | |
475 | ||
476 | - .. row 6 | |
477 | ||
478 | - ``VIDEO_PALETTE_RGB24`` | |
479 | ||
480 | - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>` | |
481 | ||
482 | - .. row 7 | |
483 | ||
484 | - ``VIDEO_PALETTE_RGB32`` | |
485 | ||
4855307b | 486 | - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_ |
5377d91f MH |
487 | |
488 | - .. row 8 | |
489 | ||
490 | - ``VIDEO_PALETTE_YUV422`` | |
491 | ||
492 | - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>` | |
493 | ||
494 | - .. row 9 | |
495 | ||
4855307b | 496 | - ``VIDEO_PALETTE_YUYV``\ [#f5]_ |
5377d91f MH |
497 | |
498 | - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>` | |
499 | ||
500 | - .. row 10 | |
501 | ||
502 | - ``VIDEO_PALETTE_UYVY`` | |
503 | ||
504 | - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>` | |
505 | ||
506 | - .. row 11 | |
507 | ||
508 | - ``VIDEO_PALETTE_YUV420`` | |
509 | ||
510 | - None | |
511 | ||
512 | - .. row 12 | |
513 | ||
514 | - ``VIDEO_PALETTE_YUV411`` | |
515 | ||
4855307b | 516 | - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_ |
5377d91f MH |
517 | |
518 | - .. row 13 | |
519 | ||
520 | - ``VIDEO_PALETTE_RAW`` | |
521 | ||
4855307b | 522 | - None [#f7]_ |
5377d91f MH |
523 | |
524 | - .. row 14 | |
525 | ||
526 | - ``VIDEO_PALETTE_YUV422P`` | |
527 | ||
528 | - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>` | |
529 | ||
530 | - .. row 15 | |
531 | ||
532 | - ``VIDEO_PALETTE_YUV411P`` | |
533 | ||
4855307b | 534 | - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_ |
5377d91f MH |
535 | |
536 | - .. row 16 | |
537 | ||
538 | - ``VIDEO_PALETTE_YUV420P`` | |
539 | ||
540 | - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>` | |
541 | ||
542 | - .. row 17 | |
543 | ||
544 | - ``VIDEO_PALETTE_YUV410P`` | |
545 | ||
546 | - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>` | |
547 | ||
548 | ||
549 | V4L2 image formats are defined in :ref:`pixfmt`. The image format can | |
af4a4d0d | 550 | be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
5377d91f MH |
551 | |
552 | ||
553 | Audio | |
554 | ===== | |
555 | ||
556 | The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct | |
6e862f3c | 557 | ``video_audio`` are used to enumerate the audio inputs |
5377d91f | 558 | of a V4L device. The equivalent V4L2 ioctls are |
4e03cb76 | 559 | :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and |
af4a4d0d | 560 | :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct |
e8be7e97 | 561 | :c:type:`v4l2_audio` as discussed in :ref:`audio`. |
5377d91f MH |
562 | |
563 | The ``audio`` "channel number" field counting audio inputs was renamed | |
564 | to ``index``. | |
565 | ||
566 | On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the | |
567 | ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or | |
568 | ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio | |
569 | standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and | |
570 | ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L | |
571 | specification, there is no way to query the selected mode. On | |
572 | ``VIDIOCGAUDIO`` the driver returns the *actually received* audio | |
573 | programmes in this field. In the V4L2 API this information is stored in | |
e8be7e97 | 574 | the struct :c:type:`v4l2_tuner` ``rxsubchans`` and |
5377d91f MH |
575 | ``audmode`` fields, respectively. See :ref:`tuner` for more |
576 | information on tuners. Related to audio modes struct | |
e8be7e97 | 577 | :c:type:`v4l2_audio` also reports if this is a mono or |
5377d91f MH |
578 | stereo input, regardless if the source is a tuner. |
579 | ||
580 | The following fields where replaced by V4L2 controls accessible with the | |
7347081e | 581 | :ref:`VIDIOC_QUERYCTRL`, |
4e03cb76 | 582 | :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and |
af4a4d0d | 583 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls: |
5377d91f MH |
584 | |
585 | ||
586 | ||
587 | .. flat-table:: | |
588 | :header-rows: 1 | |
589 | :stub-columns: 0 | |
590 | ||
591 | ||
592 | - .. row 1 | |
593 | ||
6e862f3c | 594 | - struct ``video_audio`` |
5377d91f MH |
595 | |
596 | - V4L2 Control ID | |
597 | ||
598 | - .. row 2 | |
599 | ||
600 | - ``volume`` | |
601 | ||
602 | - ``V4L2_CID_AUDIO_VOLUME`` | |
603 | ||
604 | - .. row 3 | |
605 | ||
606 | - ``bass`` | |
607 | ||
608 | - ``V4L2_CID_AUDIO_BASS`` | |
609 | ||
610 | - .. row 4 | |
611 | ||
612 | - ``treble`` | |
613 | ||
614 | - ``V4L2_CID_AUDIO_TREBLE`` | |
615 | ||
616 | - .. row 5 | |
617 | ||
618 | - ``balance`` | |
619 | ||
620 | - ``V4L2_CID_AUDIO_BALANCE`` | |
621 | ||
622 | ||
623 | To determine which of these controls are supported by a driver V4L | |
624 | provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``, | |
625 | ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the | |
7347081e | 626 | :ref:`VIDIOC_QUERYCTRL` ioctl reports if the |
5377d91f MH |
627 | respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE`` |
628 | and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean | |
629 | ``V4L2_CID_AUDIO_MUTE`` control. | |
630 | ||
631 | All V4L2 controls have a ``step`` attribute replacing the struct | |
6e862f3c | 632 | ``video_audio`` ``step`` field. The V4L audio controls |
5377d91f MH |
633 | are assumed to range from 0 to 65535 with no particular reset value. The |
634 | V4L2 API permits arbitrary limits and defaults which can be queried with | |
7347081e | 635 | the :ref:`VIDIOC_QUERYCTRL` ioctl. For general |
5377d91f MH |
636 | information about controls see :ref:`control`. |
637 | ||
638 | ||
639 | Frame Buffer Overlay | |
640 | ==================== | |
641 | ||
642 | The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are | |
4e03cb76 | 643 | :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and |
af4a4d0d | 644 | :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct |
6e862f3c | 645 | ``video_buffer`` remained unchanged, except V4L2 defines |
5377d91f MH |
646 | a flag to indicate non-destructive overlays instead of a ``NULL`` |
647 | pointer. All other fields moved into the struct | |
e8be7e97 MCC |
648 | :c:type:`v4l2_pix_format` ``fmt`` substructure of |
649 | struct :c:type:`v4l2_framebuffer`. The ``depth`` | |
5377d91f MH |
650 | field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a |
651 | list of RGB formats and their respective color depths. | |
652 | ||
653 | Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2 | |
654 | uses the general-purpose data format negotiation ioctls | |
4e03cb76 | 655 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
af4a4d0d | 656 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct |
e8be7e97 | 657 | :c:type:`v4l2_format` as argument. Here the ``win`` member |
5377d91f | 658 | of the ``fmt`` union is used, a struct |
e8be7e97 | 659 | :c:type:`v4l2_window`. |
5377d91f MH |
660 | |
661 | The ``x``, ``y``, ``width`` and ``height`` fields of struct | |
6e862f3c | 662 | ``video_window`` moved into struct |
e8be7e97 | 663 | :c:type:`v4l2_rect` substructure ``w`` of struct |
6e862f3c | 664 | :c:type:`v4l2_window`. The ``chromakey``, ``clips``, and |
5377d91f | 665 | ``clipcount`` fields remained unchanged. Struct |
6e862f3c | 666 | ``video_clip`` was renamed to struct |
e8be7e97 | 667 | :c:type:`v4l2_clip`, also containing a struct |
6e862f3c | 668 | :c:type:`v4l2_rect`, but the semantics are still the same. |
5377d91f MH |
669 | |
670 | The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications | |
671 | must set the ``field`` field to ``V4L2_FIELD_ANY`` or | |
672 | ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved | |
e8be7e97 | 673 | into struct :c:type:`v4l2_framebuffer`, under the new |
5377d91f MH |
674 | name ``V4L2_FBUF_FLAG_CHROMAKEY``. |
675 | ||
676 | In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount`` | |
677 | to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed | |
6e862f3c | 678 | size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window` |
5377d91f MH |
679 | has a separate ``bitmap`` pointer field for this purpose and the bitmap |
680 | size is determined by ``w.width`` and ``w.height``. | |
681 | ||
682 | The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to | |
7347081e | 683 | :ref:`VIDIOC_OVERLAY`. |
5377d91f MH |
684 | |
685 | ||
686 | Cropping | |
687 | ======== | |
688 | ||
689 | To capture only a subsection of the full picture V4L defines the | |
690 | ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct | |
6e862f3c | 691 | ``video_capture``. The equivalent V4L2 ioctls are |
4e03cb76 | 692 | :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and |
af4a4d0d | 693 | :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct |
e8be7e97 | 694 | :c:type:`v4l2_crop`, and the related |
7347081e | 695 | :ref:`VIDIOC_CROPCAP` ioctl. This is a rather |
5377d91f MH |
696 | complex matter, see :ref:`crop` for details. |
697 | ||
698 | The ``x``, ``y``, ``width`` and ``height`` fields moved into struct | |
e8be7e97 | 699 | :c:type:`v4l2_rect` substructure ``c`` of struct |
6e862f3c | 700 | :c:type:`v4l2_crop`. The ``decimation`` field was dropped. In |
5377d91f MH |
701 | the V4L2 API the scaling factor is implied by the size of the cropping |
702 | rectangle and the size of the captured or overlaid image. | |
703 | ||
704 | The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture | |
705 | only the odd or even field, respectively, were replaced by | |
706 | ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named | |
e8be7e97 MCC |
707 | ``field`` of struct :c:type:`v4l2_pix_format` and |
708 | struct :c:type:`v4l2_window`. These structures are used to | |
5377d91f | 709 | select a capture or overlay format with the |
af4a4d0d | 710 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
5377d91f MH |
711 | |
712 | ||
713 | Reading Images, Memory Mapping | |
714 | ============================== | |
715 | ||
716 | ||
717 | Capturing using the read method | |
718 | ------------------------------- | |
719 | ||
720 | There is no essential difference between reading images from a V4L or | |
721 | V4L2 device using the :ref:`read() <func-read>` function, however V4L2 | |
722 | drivers are not required to support this I/O method. Applications can | |
723 | determine if the function is available with the | |
7347081e | 724 | :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices |
5377d91f MH |
725 | exchanging data with applications must support the |
726 | :ref:`select() <func-select>` and :ref:`poll() <func-poll>` | |
727 | functions. | |
728 | ||
729 | To select an image format and size, V4L provides the ``VIDIOCSPICT`` and | |
730 | ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format | |
4e03cb76 | 731 | negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
af4a4d0d | 732 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct |
e8be7e97 MCC |
733 | :c:type:`v4l2_format` as argument, here the struct |
734 | :c:type:`v4l2_pix_format` named ``pix`` of its | |
5377d91f MH |
735 | ``fmt`` union is used. |
736 | ||
737 | For more information about the V4L2 read interface see :ref:`rw`. | |
738 | ||
739 | ||
740 | Capturing using memory mapping | |
741 | ------------------------------ | |
742 | ||
743 | Applications can read from V4L devices by mapping buffers in device | |
744 | memory, or more often just buffers allocated in DMA-able system memory, | |
745 | into their address space. This avoids the data copying overhead of the | |
746 | read method. V4L2 supports memory mapping as well, with a few | |
747 | differences. | |
748 | ||
749 | ||
750 | ||
751 | .. flat-table:: | |
752 | :header-rows: 1 | |
753 | :stub-columns: 0 | |
754 | ||
755 | ||
756 | - .. row 1 | |
757 | ||
758 | - V4L | |
759 | ||
760 | - V4L2 | |
761 | ||
762 | - .. row 2 | |
763 | ||
0579e6e3 | 764 | - |
5377d91f | 765 | - The image format must be selected before buffers are allocated, |
0579e6e3 MCC |
766 | with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no |
767 | format is selected the driver may use the last, possibly by | |
768 | another application requested format. | |
5377d91f MH |
769 | |
770 | - .. row 3 | |
771 | ||
772 | - Applications cannot change the number of buffers. The it is built | |
0579e6e3 MCC |
773 | into the driver, unless it has a module option to change the |
774 | number when the driver module is loaded. | |
5377d91f | 775 | |
7347081e | 776 | - The :ref:`VIDIOC_REQBUFS` ioctl allocates the |
0579e6e3 MCC |
777 | desired number of buffers, this is a required step in the |
778 | initialization sequence. | |
5377d91f MH |
779 | |
780 | - .. row 4 | |
781 | ||
782 | - Drivers map all buffers as one contiguous range of memory. The | |
0579e6e3 MCC |
783 | ``VIDIOCGMBUF`` ioctl is available to query the number of buffers, |
784 | the offset of each buffer from the start of the virtual file, and | |
785 | the overall amount of memory used, which can be used as arguments | |
786 | for the :ref:`mmap() <func-mmap>` function. | |
5377d91f MH |
787 | |
788 | - Buffers are individually mapped. The offset and size of each | |
0579e6e3 MCC |
789 | buffer can be determined with the |
790 | :ref:`VIDIOC_QUERYBUF` ioctl. | |
5377d91f MH |
791 | |
792 | - .. row 5 | |
793 | ||
794 | - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It | |
0579e6e3 MCC |
795 | also determines the image format for this buffer. The ioctl |
796 | returns immediately, eventually with an ``EAGAIN`` error code if no | |
797 | video signal had been detected. When the driver supports more than | |
798 | one buffer applications can call the ioctl multiple times and thus | |
799 | have multiple outstanding capture requests. | |
5377d91f | 800 | |
0579e6e3 MCC |
801 | The ``VIDIOCSYNC`` ioctl suspends execution until a particular |
802 | buffer has been filled. | |
5377d91f MH |
803 | |
804 | - Drivers maintain an incoming and outgoing queue. | |
0579e6e3 MCC |
805 | :ref:`VIDIOC_QBUF` enqueues any empty buffer into |
806 | the incoming queue. Filled buffers are dequeued from the outgoing | |
807 | queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait | |
808 | until filled buffers become available this function, | |
809 | :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can | |
810 | be used. The :ref:`VIDIOC_STREAMON` ioctl | |
811 | must be called once after enqueuing one or more buffers to start | |
812 | capturing. Its counterpart | |
813 | :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and | |
814 | dequeues all buffers from both queues. Applications can query the | |
815 | signal status, if known, with the | |
816 | :ref:`VIDIOC_ENUMINPUT` ioctl. | |
5377d91f MH |
817 | |
818 | ||
819 | For a more in-depth discussion of memory mapping and examples, see | |
820 | :ref:`mmap`. | |
821 | ||
822 | ||
823 | Reading Raw VBI Data | |
824 | ==================== | |
825 | ||
826 | Originally the V4L API did not specify a raw VBI capture interface, only | |
827 | the device file ``/dev/vbi`` was reserved for this purpose. The only | |
828 | driver supporting this interface was the BTTV driver, de-facto defining | |
829 | the V4L VBI interface. Reading from the device yields a raw VBI image | |
830 | with the following parameters: | |
831 | ||
832 | ||
833 | ||
834 | .. flat-table:: | |
835 | :header-rows: 1 | |
836 | :stub-columns: 0 | |
837 | ||
838 | ||
839 | - .. row 1 | |
840 | ||
e8be7e97 | 841 | - struct :c:type:`v4l2_vbi_format` |
5377d91f MH |
842 | |
843 | - V4L, BTTV driver | |
844 | ||
845 | - .. row 2 | |
846 | ||
847 | - sampling_rate | |
848 | ||
849 | - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL | |
0579e6e3 | 850 | and SECAM (625-line standards) |
5377d91f MH |
851 | |
852 | - .. row 3 | |
853 | ||
854 | - offset | |
855 | ||
856 | - ? | |
857 | ||
858 | - .. row 4 | |
859 | ||
860 | - samples_per_line | |
861 | ||
862 | - 2048 | |
863 | ||
864 | - .. row 5 | |
865 | ||
866 | - sample_format | |
867 | ||
868 | - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness | |
0579e6e3 | 869 | integer) contain a frame counter. |
5377d91f MH |
870 | |
871 | - .. row 6 | |
872 | ||
873 | - start[] | |
874 | ||
875 | - 10, 273 NTSC; 22, 335 PAL and SECAM | |
876 | ||
877 | - .. row 7 | |
878 | ||
879 | - count[] | |
880 | ||
4855307b | 881 | - 16, 16 [#f9]_ |
5377d91f MH |
882 | |
883 | - .. row 8 | |
884 | ||
885 | - flags | |
886 | ||
887 | - 0 | |
888 | ||
889 | ||
890 | Undocumented in the V4L specification, in Linux 2.3 the | |
891 | ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct | |
6e862f3c | 892 | ``vbi_format`` were added to determine the VBI image |
5377d91f MH |
893 | parameters. These ioctls are only partially compatible with the V4L2 VBI |
894 | interface specified in :ref:`raw-vbi`. | |
895 | ||
896 | An ``offset`` field does not exist, ``sample_format`` is supposed to be | |
897 | ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The | |
898 | remaining fields are probably equivalent to struct | |
e8be7e97 | 899 | :c:type:`v4l2_vbi_format`. |
5377d91f MH |
900 | |
901 | Apparently only the Zoran (ZR 36120) driver implements these ioctls. The | |
902 | semantics differ from those specified for V4L2 in two ways. The | |
903 | parameters are reset on :ref:`open() <func-open>` and | |
cdb4af0f | 904 | ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters |
5377d91f MH |
905 | are invalid. |
906 | ||
907 | ||
908 | Miscellaneous | |
909 | ============= | |
910 | ||
911 | V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can | |
912 | find the VBI device associated with a video capture device (or vice | |
913 | versa) by reopening the device and requesting VBI data. For details see | |
914 | :ref:`open`. | |
915 | ||
916 | No replacement exists for ``VIDIOCKEY``, and the V4L functions for | |
917 | microcode programming. A new interface for MPEG compression and playback | |
918 | devices is documented in :ref:`extended-controls`. | |
919 | ||
4855307b | 920 | .. [#f1] |
5377d91f MH |
921 | According to Documentation/devices.txt these should be symbolic links |
922 | to ``/dev/video0``. Note the original bttv interface is not | |
923 | compatible with V4L or V4L2. | |
924 | ||
4855307b | 925 | .. [#f2] |
5377d91f MH |
926 | According to ``Documentation/devices.txt`` a symbolic link to |
927 | ``/dev/radio0``. | |
928 | ||
4855307b | 929 | .. [#f3] |
5377d91f MH |
930 | This is a custom format used by the BTTV driver, not one of the V4L2 |
931 | standard formats. | |
932 | ||
4855307b | 933 | .. [#f4] |
5377d91f MH |
934 | Presumably all V4L RGB formats are little-endian, although some |
935 | drivers might interpret them according to machine endianness. V4L2 | |
936 | defines little-endian, big-endian and red/blue swapped variants. For | |
937 | details see :ref:`pixfmt-rgb`. | |
938 | ||
4855307b | 939 | .. [#f5] |
5377d91f MH |
940 | ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same |
941 | formats. Some V4L drivers respond to one, some to the other. | |
942 | ||
4855307b | 943 | .. [#f6] |
5377d91f MH |
944 | Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar |
945 | format. | |
946 | ||
4855307b | 947 | .. [#f7] |
5377d91f MH |
948 | V4L explains this as: "RAW capture (BT848)" |
949 | ||
4855307b | 950 | .. [#f8] |
5377d91f MH |
951 | Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed |
952 | format. | |
953 | ||
4855307b | 954 | .. [#f9] |
5377d91f MH |
955 | Old driver versions used different values, eventually the custom |
956 | ``BTTV_VBISIZE`` ioctl was added to query the correct values. |