1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: V4L 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _capture: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun*********************** 7*4882a593SmuzhiyunVideo Capture Interface 8*4882a593Smuzhiyun*********************** 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunVideo capture devices sample an analog video signal and store the 11*4882a593Smuzhiyundigitized images in memory. Today nearly all devices can capture at full 12*4882a593Smuzhiyun25 or 30 frames/second. With this interface applications can control the 13*4882a593Smuzhiyuncapture process and move images from the driver into user space. 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunConventionally V4L2 video capture devices are accessed through character 16*4882a593Smuzhiyundevice special files named ``/dev/video`` and ``/dev/video0`` to 17*4882a593Smuzhiyun``/dev/video63`` with major number 81 and minor numbers 0 to 63. 18*4882a593Smuzhiyun``/dev/video`` is typically a symbolic link to the preferred video 19*4882a593Smuzhiyundevice. 20*4882a593Smuzhiyun 21*4882a593Smuzhiyun.. note:: The same device file names are used for video output devices. 22*4882a593Smuzhiyun 23*4882a593SmuzhiyunQuerying Capabilities 24*4882a593Smuzhiyun===================== 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunDevices supporting the video capture interface set the 27*4882a593Smuzhiyun``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in 28*4882a593Smuzhiyunthe ``capabilities`` field of struct 29*4882a593Smuzhiyun:c:type:`v4l2_capability` returned by the 30*4882a593Smuzhiyun:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device 31*4882a593Smuzhiyunfunctions they may also support the :ref:`video overlay <overlay>` 32*4882a593Smuzhiyun(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>` 33*4882a593Smuzhiyun(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or 34*4882a593Smuzhiyunstreaming I/O methods must be supported. Tuners and audio inputs are 35*4882a593Smuzhiyunoptional. 36*4882a593Smuzhiyun 37*4882a593SmuzhiyunSupplemental Functions 38*4882a593Smuzhiyun====================== 39*4882a593Smuzhiyun 40*4882a593SmuzhiyunVideo capture devices shall support :ref:`audio input <audio>`, 41*4882a593Smuzhiyun:ref:`tuner`, :ref:`controls <control>`, 42*4882a593Smuzhiyun:ref:`cropping and scaling <crop>` and 43*4882a593Smuzhiyun:ref:`streaming parameter <streaming-par>` ioctls as needed. The 44*4882a593Smuzhiyun:ref:`video input <video>` ioctls must be supported by all video 45*4882a593Smuzhiyuncapture devices. 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunImage Format Negotiation 48*4882a593Smuzhiyun======================== 49*4882a593Smuzhiyun 50*4882a593SmuzhiyunThe result of a capture operation is determined by cropping and image 51*4882a593Smuzhiyunformat parameters. The former select an area of the video picture to 52*4882a593Smuzhiyuncapture, the latter how images are stored in memory, i. e. in RGB or YUV 53*4882a593Smuzhiyunformat, the number of bits per pixel or width and height. Together they 54*4882a593Smuzhiyunalso define how images are scaled in the process. 55*4882a593Smuzhiyun 56*4882a593SmuzhiyunAs usual these parameters are *not* reset at :c:func:`open()` 57*4882a593Smuzhiyuntime to permit Unix tool chains, programming a device and then reading 58*4882a593Smuzhiyunfrom it as if it was a plain file. Well written V4L2 applications ensure 59*4882a593Smuzhiyunthey really get what they want, including cropping and scaling. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunCropping initialization at minimum requires to reset the parameters to 62*4882a593Smuzhiyundefaults. An example is given in :ref:`crop`. 63*4882a593Smuzhiyun 64*4882a593SmuzhiyunTo query the current image format applications set the ``type`` field of 65*4882a593Smuzhiyuna struct :c:type:`v4l2_format` to 66*4882a593Smuzhiyun``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or 67*4882a593Smuzhiyun``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the 68*4882a593Smuzhiyun:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this 69*4882a593Smuzhiyunstructure. Drivers fill the struct 70*4882a593Smuzhiyun:c:type:`v4l2_pix_format` ``pix`` or the struct 71*4882a593Smuzhiyun:c:type:`v4l2_pix_format_mplane` ``pix_mp`` 72*4882a593Smuzhiyunmember of the ``fmt`` union. 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunTo request different parameters applications set the ``type`` field of a 75*4882a593Smuzhiyunstruct :c:type:`v4l2_format` as above and initialize all 76*4882a593Smuzhiyunfields of the struct :c:type:`v4l2_pix_format` 77*4882a593Smuzhiyun``vbi`` member of the ``fmt`` union, or better just modify the results 78*4882a593Smuzhiyunof :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 79*4882a593Smuzhiyunioctl with a pointer to this structure. Drivers may adjust the 80*4882a593Smuzhiyunparameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` 81*4882a593Smuzhiyundoes. 82*4882a593Smuzhiyun 83*4882a593SmuzhiyunLike :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl 84*4882a593Smuzhiyuncan be used to learn about hardware limitations without disabling I/O or 85*4882a593Smuzhiyunpossibly time consuming hardware preparations. 86*4882a593Smuzhiyun 87*4882a593SmuzhiyunThe contents of struct :c:type:`v4l2_pix_format` and 88*4882a593Smuzhiyunstruct :c:type:`v4l2_pix_format_mplane` are 89*4882a593Smuzhiyundiscussed in :ref:`pixfmt`. See also the specification of the 90*4882a593Smuzhiyun:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for 91*4882a593Smuzhiyundetails. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` 92*4882a593Smuzhiyunand :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all 93*4882a593Smuzhiyunrequests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. 94*4882a593Smuzhiyun:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. 95*4882a593Smuzhiyun 96*4882a593SmuzhiyunReading Images 97*4882a593Smuzhiyun============== 98*4882a593Smuzhiyun 99*4882a593SmuzhiyunA video capture device may support the :ref:`read() function <func-read>` 100*4882a593Smuzhiyunand/or streaming (:ref:`memory mapping <func-mmap>` or 101*4882a593Smuzhiyun:ref:`user pointer <userp>`) I/O. See :ref:`io` for details. 102