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