0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _capture:
0005
0006 ***********************
0007 Video Capture Interface
0008 ***********************
0009
0010 Video capture devices sample an analog video signal and store the
0011 digitized images in memory. Today nearly all devices can capture at full
0012 25 or 30 frames/second. With this interface applications can control the
0013 capture process and move images from the driver into user space.
0014
0015 Conventionally V4L2 video capture devices are accessed through character
0016 device special files named ``/dev/video`` and ``/dev/video0`` to
0017 ``/dev/video63`` with major number 81 and minor numbers 0 to 63.
0018 ``/dev/video`` is typically a symbolic link to the preferred video
0019 device.
0020
0021 .. note:: The same device file names are used for video output devices.
0022
0023 Querying Capabilities
0024 =====================
0025
0026 Devices supporting the video capture interface set the
0027 ``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
0028 the ``capabilities`` field of struct
0029 :c:type:`v4l2_capability` returned by the
0030 :ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
0031 functions they may also support the :ref:`video overlay <overlay>`
0032 (``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
0033 (``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
0034 streaming I/O methods must be supported. Tuners and audio inputs are
0035 optional.
0036
0037 Supplemental Functions
0038 ======================
0039
0040 Video capture devices shall support :ref:`audio input <audio>`,
0041 :ref:`tuner`, :ref:`controls <control>`,
0042 :ref:`cropping and scaling <crop>` and
0043 :ref:`streaming parameter <streaming-par>` ioctls as needed. The
0044 :ref:`video input <video>` ioctls must be supported by all video
0045 capture devices.
0046
0047 Image Format Negotiation
0048 ========================
0049
0050 The result of a capture operation is determined by cropping and image
0051 format parameters. The former select an area of the video picture to
0052 capture, the latter how images are stored in memory, i. e. in RGB or YUV
0053 format, the number of bits per pixel or width and height. Together they
0054 also define how images are scaled in the process.
0055
0056 As usual these parameters are *not* reset at :c:func:`open()`
0057 time to permit Unix tool chains, programming a device and then reading
0058 from it as if it was a plain file. Well written V4L2 applications ensure
0059 they really get what they want, including cropping and scaling.
0060
0061 Cropping initialization at minimum requires to reset the parameters to
0062 defaults. An example is given in :ref:`crop`.
0063
0064 To query the current image format applications set the ``type`` field of
0065 a struct :c:type:`v4l2_format` to
0066 ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
0067 ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
0068 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
0069 structure. Drivers fill the struct
0070 :c:type:`v4l2_pix_format` ``pix`` or the struct
0071 :c:type:`v4l2_pix_format_mplane` ``pix_mp``
0072 member of the ``fmt`` union.
0073
0074 To request different parameters applications set the ``type`` field of a
0075 struct :c:type:`v4l2_format` as above and initialize all
0076 fields of the struct :c:type:`v4l2_pix_format`
0077 ``vbi`` member of the ``fmt`` union, or better just modify the results
0078 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
0079 ioctl with a pointer to this structure. Drivers may adjust the
0080 parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
0081 does.
0082
0083 Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
0084 can be used to learn about hardware limitations without disabling I/O or
0085 possibly time consuming hardware preparations.
0086
0087 The contents of struct :c:type:`v4l2_pix_format` and
0088 struct :c:type:`v4l2_pix_format_mplane` are
0089 discussed in :ref:`pixfmt`. See also the specification of the
0090 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
0091 details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
0092 and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
0093 requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
0094 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
0095
0096 Reading Images
0097 ==============
0098
0099 A video capture device may support the :ref:`read() function <func-read>`
0100 and/or streaming (:ref:`memory mapping <func-mmap>` or
0101 :ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
