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