694 lines
26 KiB
ReStructuredText
694 lines
26 KiB
ReStructuredText
|
.. Permission is granted to copy, distribute and/or modify this
|
|||
|
|
.. document under the terms of the GNU Free Documentation License,
|
|||
|
|
.. Version 1.1 or any later version published by the Free Software
|
|||
|
|
.. Foundation, with no Invariant Sections, no Front-Cover Texts
|
|||
|
|
.. and no Back-Cover Texts. A copy of the license is included at
|
|||
|
|
.. Documentation/media/uapi/fdl-appendix.rst.
|
|||
|
|
..
|
|||
|
|
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
|
|||
|
|
|
|||
|
|
.. _diff-v4l:
|
|||
|
|
|
|||
|
|
********************************
|
|||
|
|
Differences between V4L and V4L2
|
|||
|
|
********************************
|
|||
|
|
|
|||
|
|
The Video For Linux API was first introduced in Linux 2.1 to unify and
|
|||
|
|
replace various TV and radio device related interfaces, developed
|
|||
|
|
independently by driver writers in prior years. Starting with Linux 2.5
|
|||
|
|
the much improved V4L2 API replaces the V4L API. The support for the old
|
|||
|
|
V4L calls were removed from Kernel, but the library :ref:`libv4l`
|
|||
|
|
supports the conversion of a V4L API system call into a V4L2 one.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Opening and Closing Devices
|
|||
|
|
===========================
|
|||
|
|
|
|||
|
|
For compatibility reasons the character device file names recommended
|
|||
|
|
for V4L2 video capture, overlay, radio and raw vbi capture devices did
|
|||
|
|
not change from those used by V4L. They are listed in :ref:`devices`
|
|||
|
|
and below in :ref:`v4l-dev`.
|
|||
|
|
|
|||
|
|
The teletext devices (minor range 192-223) have been removed in V4L2 and
|
|||
|
|
no longer exist. There is no hardware available anymore for handling
|
|||
|
|
pure teletext. Instead raw or sliced VBI is used.
|
|||
|
|
|
|||
|
|
The V4L ``videodev`` module automatically assigns minor numbers to
|
|||
|
|
drivers in load order, depending on the registered device type. We
|
|||
|
|
recommend that V4L2 drivers by default register devices with the same
|
|||
|
|
numbers, but the system administrator can assign arbitrary minor numbers
|
|||
|
|
using driver module options. The major device number remains 81.
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. _v4l-dev:
|
|||
|
|
|
|||
|
|
.. flat-table:: V4L Device Types, Names and Numbers
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - Device Type
|
|||
|
|
- File Name
|
|||
|
|
- Minor Numbers
|
|||
|
|
* - Video capture and overlay
|
|||
|
|
- ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to
|
|||
|
|
``/dev/video63``
|
|||
|
|
- 0-63
|
|||
|
|
* - Radio receiver
|
|||
|
|
- ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
|
|||
|
|
- 64-127
|
|||
|
|
* - Raw VBI capture
|
|||
|
|
- ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
|
|||
|
|
- 224-255
|
|||
|
|
|
|||
|
|
|
|||
|
|
V4L prohibits (or used to prohibit) multiple opens of a device file.
|
|||
|
|
V4L2 drivers *may* support multiple opens, see :ref:`open` for details
|
|||
|
|
and consequences.
|
|||
|
|
|
|||
|
|
V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Querying Capabilities
|
|||
|
|
=====================
|
|||
|
|
|
|||
|
|
The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
|
|||
|
|
:ref:`VIDIOC_QUERYCAP`.
|
|||
|
|
|
|||
|
|
The ``name`` field in struct ``video_capability`` became
|
|||
|
|
``card`` in struct :c:type:`v4l2_capability`, ``type``
|
|||
|
|
was replaced by ``capabilities``. Note V4L2 does not distinguish between
|
|||
|
|
device types like this, better think of basic video input, video output
|
|||
|
|
and radio devices supporting a set of related functions like video
|
|||
|
|
capturing, video overlay and VBI capturing. See :ref:`open` for an
|
|||
|
|
introduction.
|
|||
|
|
|
|||
|
|
.. tabularcolumns:: |p{5.5cm}|p{6.5cm}|p{5.5cm}
|
|||
|
|
|
|||
|
|
.. cssclass:: longtable
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - ``struct video_capability`` ``type``
|
|||
|
|
- struct :c:type:`v4l2_capability`
|
|||
|
|
``capabilities`` flags
|
|||
|
|
- Purpose
|
|||
|
|
* - ``VID_TYPE_CAPTURE``
|
|||
|
|
- ``V4L2_CAP_VIDEO_CAPTURE``
|
|||
|
|
- The :ref:`video capture <capture>` interface is supported.
|
|||
|
|
* - ``VID_TYPE_TUNER``
|
|||
|
|
- ``V4L2_CAP_TUNER``
|
|||
|
|
- The device has a :ref:`tuner or modulator <tuner>`.
|
|||
|
|
* - ``VID_TYPE_TELETEXT``
|
|||
|
|
- ``V4L2_CAP_VBI_CAPTURE``
|
|||
|
|
- The :ref:`raw VBI capture <raw-vbi>` interface is supported.
|
|||
|
|
* - ``VID_TYPE_OVERLAY``
|
|||
|
|
- ``V4L2_CAP_VIDEO_OVERLAY``
|
|||
|
|
- The :ref:`video overlay <overlay>` interface is supported.
|
|||
|
|
* - ``VID_TYPE_CHROMAKEY``
|
|||
|
|
- ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
|
|||
|
|
:c:type:`v4l2_framebuffer`
|
|||
|
|
- Whether chromakey overlay is supported. For more information on
|
|||
|
|
overlay see :ref:`overlay`.
|
|||
|
|
* - ``VID_TYPE_CLIPPING``
|
|||
|
|
- ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
|
|||
|
|
``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
|
|||
|
|
struct :c:type:`v4l2_framebuffer`
|
|||
|
|
- Whether clipping the overlaid image is supported, see
|
|||
|
|
:ref:`overlay`.
|
|||
|
|
* - ``VID_TYPE_FRAMERAM``
|
|||
|
|
- ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
|
|||
|
|
of struct :c:type:`v4l2_framebuffer`
|
|||
|
|
- Whether overlay overwrites frame buffer memory, see
|
|||
|
|
:ref:`overlay`.
|
|||
|
|
* - ``VID_TYPE_SCALES``
|
|||
|
|
- ``-``
|
|||
|
|
- This flag indicates if the hardware can scale images. The V4L2 API
|
|||
|
|
implies the scale factor by setting the cropping dimensions and
|
|||
|
|
image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
|
|||
|
|
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
|
|||
|
|
driver returns the closest sizes possible. For more information on
|
|||
|
|
cropping and scaling see :ref:`crop`.
|
|||
|
|
* - ``VID_TYPE_MONOCHROME``
|
|||
|
|
- ``-``
|
|||
|
|
- Applications can enumerate the supported image formats with the
|
|||
|
|
:ref:`VIDIOC_ENUM_FMT` ioctl to determine if
|
|||
|
|
the device supports grey scale capturing only. For more
|
|||
|
|
information on image formats see :ref:`pixfmt`.
|
|||
|
|
* - ``VID_TYPE_SUBCAPTURE``
|
|||
|
|
- ``-``
|
|||
|
|
- Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
|
|||
|
|
ioctl to determine if the device supports capturing a subsection
|
|||
|
|
of the full picture ("cropping" in V4L2). If not, the ioctl
|
|||
|
|
returns the ``EINVAL`` error code. For more information on cropping
|
|||
|
|
and scaling see :ref:`crop`.
|
|||
|
|
* - ``VID_TYPE_MPEG_DECODER``
|
|||
|
|
- ``-``
|
|||
|
|
- Applications can enumerate the supported image formats with the
|
|||
|
|
:ref:`VIDIOC_ENUM_FMT` ioctl to determine if
|
|||
|
|
the device supports MPEG streams.
|
|||
|
|
* - ``VID_TYPE_MPEG_ENCODER``
|
|||
|
|
- ``-``
|
|||
|
|
- See above.
|
|||
|
|
* - ``VID_TYPE_MJPEG_DECODER``
|
|||
|
|
- ``-``
|
|||
|
|
- See above.
|
|||
|
|
* - ``VID_TYPE_MJPEG_ENCODER``
|
|||
|
|
- ``-``
|
|||
|
|
- See above.
|
|||
|
|
|
|||
|
|
|
|||
|
|
The ``audios`` field was replaced by ``capabilities`` flag
|
|||
|
|
``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
|
|||
|
|
outputs. To determine their number applications can enumerate audio
|
|||
|
|
inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
|
|||
|
|
audio ioctls are described in :ref:`audio`.
|
|||
|
|
|
|||
|
|
The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
|
|||
|
|
were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
|
|||
|
|
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
|
|||
|
|
dimensions returns the closest size possible, taking into account the
|
|||
|
|
current video standard, cropping and scaling limitations.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Video Sources
|
|||
|
|
=============
|
|||
|
|
|
|||
|
|
V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
|
|||
|
|
``video_channel`` to enumerate the video inputs of a V4L
|
|||
|
|
device. The equivalent V4L2 ioctls are
|
|||
|
|
:ref:`VIDIOC_ENUMINPUT`,
|
|||
|
|
:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
|
|||
|
|
:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
|
|||
|
|
:c:type:`v4l2_input` as discussed in :ref:`video`.
|
|||
|
|
|
|||
|
|
The ``channel`` field counting inputs was renamed to ``index``, the
|
|||
|
|
video input types were renamed as follows:
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - struct ``video_channel`` ``type``
|
|||
|
|
- struct :c:type:`v4l2_input` ``type``
|
|||
|
|
* - ``VIDEO_TYPE_TV``
|
|||
|
|
- ``V4L2_INPUT_TYPE_TUNER``
|
|||
|
|
* - ``VIDEO_TYPE_CAMERA``
|
|||
|
|
- ``V4L2_INPUT_TYPE_CAMERA``
|
|||
|
|
|
|||
|
|
|
|||
|
|
Unlike the ``tuners`` field expressing the number of tuners of this
|
|||
|
|
input, V4L2 assumes each video input is connected to at most one tuner.
|
|||
|
|
However a tuner can have more than one input, i. e. RF connectors, and a
|
|||
|
|
device can have multiple tuners. The index number of the tuner
|
|||
|
|
associated with the input, if any, is stored in field ``tuner`` of
|
|||
|
|
struct :c:type:`v4l2_input`. Enumeration of tuners is
|
|||
|
|
discussed in :ref:`tuner`.
|
|||
|
|
|
|||
|
|
The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
|
|||
|
|
associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
|
|||
|
|
``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
|
|||
|
|
considers devices with up to 32 audio inputs. Each set bit in the
|
|||
|
|
``audioset`` field represents one audio input this video input combines
|
|||
|
|
with. For information about audio inputs and how to switch between them
|
|||
|
|
see :ref:`audio`.
|
|||
|
|
|
|||
|
|
The ``norm`` field describing the supported video standards was replaced
|
|||
|
|
by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
|
|||
|
|
indicating whether the standard can be changed. This flag was a later
|
|||
|
|
addition together with the ``norm`` field and has been removed in the
|
|||
|
|
meantime. V4L2 has a similar, albeit more comprehensive approach to
|
|||
|
|
video standards, see :ref:`standard` for more information.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Tuning
|
|||
|
|
======
|
|||
|
|
|
|||
|
|
The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
|
|||
|
|
``video_tuner`` can be used to enumerate the tuners of a
|
|||
|
|
V4L TV or radio device. The equivalent V4L2 ioctls are
|
|||
|
|
:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
|
|||
|
|
:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
|
|||
|
|
:c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`.
|
|||
|
|
|
|||
|
|
The ``tuner`` field counting tuners was renamed to ``index``. The fields
|
|||
|
|
``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
|
|||
|
|
|
|||
|
|
The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
|
|||
|
|
flags indicating the supported video standards were dropped. This
|
|||
|
|
information is now contained in the associated struct
|
|||
|
|
:c:type:`v4l2_input`. No replacement exists for the
|
|||
|
|
``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
|
|||
|
|
switched. The ``mode`` field to select a different video standard was
|
|||
|
|
replaced by a whole new set of ioctls and structures described in
|
|||
|
|
:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
|
|||
|
|
driver supports several standards in addition to the regular
|
|||
|
|
``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
|
|||
|
|
``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
|
|||
|
|
Japan with numbers 3-6 (sic).
|
|||
|
|
|
|||
|
|
The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
|
|||
|
|
``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
|
|||
|
|
permits the detection of monaural and bilingual audio, see the
|
|||
|
|
definition of struct :c:type:`v4l2_tuner` for details.
|
|||
|
|
Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
|
|||
|
|
``VIDEO_TUNER_MBS_ON`` flags.
|
|||
|
|
|
|||
|
|
The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
|
|||
|
|
the struct :c:type:`v4l2_tuner` ``capability`` field.
|
|||
|
|
|
|||
|
|
The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
|
|||
|
|
frequency where renamed to
|
|||
|
|
:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
|
|||
|
|
:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
|
|||
|
|
to a struct :c:type:`v4l2_frequency` instead of an
|
|||
|
|
unsigned long integer.
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. _v4l-image-properties:
|
|||
|
|
|
|||
|
|
Image Properties
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
|
|||
|
|
and struct ``video_picture``. The following fields where
|
|||
|
|
replaced by V4L2 controls accessible with the
|
|||
|
|
:ref:`VIDIOC_QUERYCTRL`,
|
|||
|
|
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
|
|||
|
|
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - struct ``video_picture``
|
|||
|
|
- V4L2 Control ID
|
|||
|
|
* - ``brightness``
|
|||
|
|
- ``V4L2_CID_BRIGHTNESS``
|
|||
|
|
* - ``hue``
|
|||
|
|
- ``V4L2_CID_HUE``
|
|||
|
|
* - ``colour``
|
|||
|
|
- ``V4L2_CID_SATURATION``
|
|||
|
|
* - ``contrast``
|
|||
|
|
- ``V4L2_CID_CONTRAST``
|
|||
|
|
* - ``whiteness``
|
|||
|
|
- ``V4L2_CID_WHITENESS``
|
|||
|
|
|
|||
|
|
|
|||
|
|
The V4L picture controls are assumed to range from 0 to 65535 with no
|
|||
|
|
particular reset value. The V4L2 API permits arbitrary limits and
|
|||
|
|
defaults which can be queried with the
|
|||
|
|
:ref:`VIDIOC_QUERYCTRL` ioctl. For general
|
|||
|
|
information about controls see :ref:`control`.
|
|||
|
|
|
|||
|
|
The ``depth`` (average number of bits per pixel) of a video image is
|
|||
|
|
implied by the selected image format. V4L2 does not explicitly provide
|
|||
|
|
such information assuming applications recognizing the format are aware
|
|||
|
|
of the image depth and others need not know. The ``palette`` field moved
|
|||
|
|
into the struct :c:type:`v4l2_pix_format`:
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - struct ``video_picture`` ``palette``
|
|||
|
|
- struct :c:type:`v4l2_pix_format` ``pixfmt``
|
|||
|
|
* - ``VIDEO_PALETTE_GREY``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
|
|||
|
|
* - ``VIDEO_PALETTE_HI240``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_
|
|||
|
|
* - ``VIDEO_PALETTE_RGB565``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
|
|||
|
|
* - ``VIDEO_PALETTE_RGB555``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
|
|||
|
|
* - ``VIDEO_PALETTE_RGB24``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
|
|||
|
|
* - ``VIDEO_PALETTE_RGB32``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_
|
|||
|
|
* - ``VIDEO_PALETTE_YUV422``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
|
|||
|
|
* - ``VIDEO_PALETTE_YUYV``\ [#f5]_
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
|
|||
|
|
* - ``VIDEO_PALETTE_UYVY``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
|
|||
|
|
* - ``VIDEO_PALETTE_YUV420``
|
|||
|
|
- None
|
|||
|
|
* - ``VIDEO_PALETTE_YUV411``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_
|
|||
|
|
* - ``VIDEO_PALETTE_RAW``
|
|||
|
|
- None [#f7]_
|
|||
|
|
* - ``VIDEO_PALETTE_YUV422P``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
|
|||
|
|
* - ``VIDEO_PALETTE_YUV411P``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_
|
|||
|
|
* - ``VIDEO_PALETTE_YUV420P``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
|
|||
|
|
* - ``VIDEO_PALETTE_YUV410P``
|
|||
|
|
- :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
|
|||
|
|
|
|||
|
|
|
|||
|
|
V4L2 image formats are defined in :ref:`pixfmt`. The image format can
|
|||
|
|
be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Audio
|
|||
|
|
=====
|
|||
|
|
|
|||
|
|
The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
|
|||
|
|
``video_audio`` are used to enumerate the audio inputs
|
|||
|
|
of a V4L device. The equivalent V4L2 ioctls are
|
|||
|
|
:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
|
|||
|
|
:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
|
|||
|
|
:c:type:`v4l2_audio` as discussed in :ref:`audio`.
|
|||
|
|
|
|||
|
|
The ``audio`` "channel number" field counting audio inputs was renamed
|
|||
|
|
to ``index``.
|
|||
|
|
|
|||
|
|
On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
|
|||
|
|
``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
|
|||
|
|
``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
|
|||
|
|
standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
|
|||
|
|
``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
|
|||
|
|
specification, there is no way to query the selected mode. On
|
|||
|
|
``VIDIOCGAUDIO`` the driver returns the *actually received* audio
|
|||
|
|
programmes in this field. In the V4L2 API this information is stored in
|
|||
|
|
the struct :c:type:`v4l2_tuner` ``rxsubchans`` and
|
|||
|
|
``audmode`` fields, respectively. See :ref:`tuner` for more
|
|||
|
|
information on tuners. Related to audio modes struct
|
|||
|
|
:c:type:`v4l2_audio` also reports if this is a mono or
|
|||
|
|
stereo input, regardless if the source is a tuner.
|
|||
|
|
|
|||
|
|
The following fields where replaced by V4L2 controls accessible with the
|
|||
|
|
:ref:`VIDIOC_QUERYCTRL`,
|
|||
|
|
:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
|
|||
|
|
:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - struct ``video_audio``
|
|||
|
|
- V4L2 Control ID
|
|||
|
|
* - ``volume``
|
|||
|
|
- ``V4L2_CID_AUDIO_VOLUME``
|
|||
|
|
* - ``bass``
|
|||
|
|
- ``V4L2_CID_AUDIO_BASS``
|
|||
|
|
* - ``treble``
|
|||
|
|
- ``V4L2_CID_AUDIO_TREBLE``
|
|||
|
|
* - ``balance``
|
|||
|
|
- ``V4L2_CID_AUDIO_BALANCE``
|
|||
|
|
|
|||
|
|
|
|||
|
|
To determine which of these controls are supported by a driver V4L
|
|||
|
|
provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
|
|||
|
|
``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
|
|||
|
|
:ref:`VIDIOC_QUERYCTRL` ioctl reports if the
|
|||
|
|
respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
|
|||
|
|
and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
|
|||
|
|
``V4L2_CID_AUDIO_MUTE`` control.
|
|||
|
|
|
|||
|
|
All V4L2 controls have a ``step`` attribute replacing the struct
|
|||
|
|
``video_audio`` ``step`` field. The V4L audio controls
|
|||
|
|
are assumed to range from 0 to 65535 with no particular reset value. The
|
|||
|
|
V4L2 API permits arbitrary limits and defaults which can be queried with
|
|||
|
|
the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
|
|||
|
|
information about controls see :ref:`control`.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Frame Buffer Overlay
|
|||
|
|
====================
|
|||
|
|
|
|||
|
|
The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
|
|||
|
|
:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
|
|||
|
|
:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
|
|||
|
|
``video_buffer`` remained unchanged, except V4L2 defines
|
|||
|
|
a flag to indicate non-destructive overlays instead of a ``NULL``
|
|||
|
|
pointer. All other fields moved into the struct
|
|||
|
|
:c:type:`v4l2_pix_format` ``fmt`` substructure of
|
|||
|
|
struct :c:type:`v4l2_framebuffer`. The ``depth``
|
|||
|
|
field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
|
|||
|
|
list of RGB formats and their respective color depths.
|
|||
|
|
|
|||
|
|
Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
|
|||
|
|
uses the general-purpose data format negotiation ioctls
|
|||
|
|
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
|
|||
|
|
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
|
|||
|
|
:c:type:`v4l2_format` as argument. Here the ``win`` member
|
|||
|
|
of the ``fmt`` union is used, a struct
|
|||
|
|
:c:type:`v4l2_window`.
|
|||
|
|
|
|||
|
|
The ``x``, ``y``, ``width`` and ``height`` fields of struct
|
|||
|
|
``video_window`` moved into struct
|
|||
|
|
:c:type:`v4l2_rect` substructure ``w`` of struct
|
|||
|
|
:c:type:`v4l2_window`. The ``chromakey``, ``clips``, and
|
|||
|
|
``clipcount`` fields remained unchanged. Struct
|
|||
|
|
``video_clip`` was renamed to struct
|
|||
|
|
:c:type:`v4l2_clip`, also containing a struct
|
|||
|
|
:c:type:`v4l2_rect`, but the semantics are still the same.
|
|||
|
|
|
|||
|
|
The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
|
|||
|
|
must set the ``field`` field to ``V4L2_FIELD_ANY`` or
|
|||
|
|
``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
|
|||
|
|
into struct :c:type:`v4l2_framebuffer`, under the new
|
|||
|
|
name ``V4L2_FBUF_FLAG_CHROMAKEY``.
|
|||
|
|
|
|||
|
|
In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
|
|||
|
|
to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
|
|||
|
|
size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`
|
|||
|
|
has a separate ``bitmap`` pointer field for this purpose and the bitmap
|
|||
|
|
size is determined by ``w.width`` and ``w.height``.
|
|||
|
|
|
|||
|
|
The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
|
|||
|
|
:ref:`VIDIOC_OVERLAY`.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Cropping
|
|||
|
|
========
|
|||
|
|
|
|||
|
|
To capture only a subsection of the full picture V4L defines the
|
|||
|
|
``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
|
|||
|
|
``video_capture``. The equivalent V4L2 ioctls are
|
|||
|
|
:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
|
|||
|
|
:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
|
|||
|
|
:c:type:`v4l2_crop`, and the related
|
|||
|
|
:ref:`VIDIOC_CROPCAP` ioctl. This is a rather
|
|||
|
|
complex matter, see :ref:`crop` for details.
|
|||
|
|
|
|||
|
|
The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
|
|||
|
|
:c:type:`v4l2_rect` substructure ``c`` of struct
|
|||
|
|
:c:type:`v4l2_crop`. The ``decimation`` field was dropped. In
|
|||
|
|
the V4L2 API the scaling factor is implied by the size of the cropping
|
|||
|
|
rectangle and the size of the captured or overlaid image.
|
|||
|
|
|
|||
|
|
The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
|
|||
|
|
only the odd or even field, respectively, were replaced by
|
|||
|
|
``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
|
|||
|
|
``field`` of struct :c:type:`v4l2_pix_format` and
|
|||
|
|
struct :c:type:`v4l2_window`. These structures are used to
|
|||
|
|
select a capture or overlay format with the
|
|||
|
|
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Reading Images, Memory Mapping
|
|||
|
|
==============================
|
|||
|
|
|
|||
|
|
|
|||
|
|
Capturing using the read method
|
|||
|
|
-------------------------------
|
|||
|
|
|
|||
|
|
There is no essential difference between reading images from a V4L or
|
|||
|
|
V4L2 device using the :ref:`read() <func-read>` function, however V4L2
|
|||
|
|
drivers are not required to support this I/O method. Applications can
|
|||
|
|
determine if the function is available with the
|
|||
|
|
:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
|
|||
|
|
exchanging data with applications must support the
|
|||
|
|
:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
|
|||
|
|
functions.
|
|||
|
|
|
|||
|
|
To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
|
|||
|
|
``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
|
|||
|
|
negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
|
|||
|
|
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
|
|||
|
|
:c:type:`v4l2_format` as argument, here the struct
|
|||
|
|
:c:type:`v4l2_pix_format` named ``pix`` of its
|
|||
|
|
``fmt`` union is used.
|
|||
|
|
|
|||
|
|
For more information about the V4L2 read interface see :ref:`rw`.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Capturing using memory mapping
|
|||
|
|
------------------------------
|
|||
|
|
|
|||
|
|
Applications can read from V4L devices by mapping buffers in device
|
|||
|
|
memory, or more often just buffers allocated in DMA-able system memory,
|
|||
|
|
into their address space. This avoids the data copying overhead of the
|
|||
|
|
read method. V4L2 supports memory mapping as well, with a few
|
|||
|
|
differences.
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - V4L
|
|||
|
|
- V4L2
|
|||
|
|
* -
|
|||
|
|
- The image format must be selected before buffers are allocated,
|
|||
|
|
with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
|
|||
|
|
format is selected the driver may use the last, possibly by
|
|||
|
|
another application requested format.
|
|||
|
|
* - Applications cannot change the number of buffers. The it is built
|
|||
|
|
into the driver, unless it has a module option to change the
|
|||
|
|
number when the driver module is loaded.
|
|||
|
|
- The :ref:`VIDIOC_REQBUFS` ioctl allocates the
|
|||
|
|
desired number of buffers, this is a required step in the
|
|||
|
|
initialization sequence.
|
|||
|
|
* - Drivers map all buffers as one contiguous range of memory. The
|
|||
|
|
``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
|
|||
|
|
the offset of each buffer from the start of the virtual file, and
|
|||
|
|
the overall amount of memory used, which can be used as arguments
|
|||
|
|
for the :ref:`mmap() <func-mmap>` function.
|
|||
|
|
- Buffers are individually mapped. The offset and size of each
|
|||
|
|
buffer can be determined with the
|
|||
|
|
:ref:`VIDIOC_QUERYBUF` ioctl.
|
|||
|
|
* - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
|
|||
|
|
also determines the image format for this buffer. The ioctl
|
|||
|
|
returns immediately, eventually with an ``EAGAIN`` error code if no
|
|||
|
|
video signal had been detected. When the driver supports more than
|
|||
|
|
one buffer applications can call the ioctl multiple times and thus
|
|||
|
|
have multiple outstanding capture requests.
|
|||
|
|
|
|||
|
|
The ``VIDIOCSYNC`` ioctl suspends execution until a particular
|
|||
|
|
buffer has been filled.
|
|||
|
|
- Drivers maintain an incoming and outgoing queue.
|
|||
|
|
:ref:`VIDIOC_QBUF` enqueues any empty buffer into
|
|||
|
|
the incoming queue. Filled buffers are dequeued from the outgoing
|
|||
|
|
queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
|
|||
|
|
until filled buffers become available this function,
|
|||
|
|
:ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
|
|||
|
|
be used. The :ref:`VIDIOC_STREAMON` ioctl
|
|||
|
|
must be called once after enqueuing one or more buffers to start
|
|||
|
|
capturing. Its counterpart
|
|||
|
|
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
|
|||
|
|
dequeues all buffers from both queues. Applications can query the
|
|||
|
|
signal status, if known, with the
|
|||
|
|
:ref:`VIDIOC_ENUMINPUT` ioctl.
|
|||
|
|
|
|||
|
|
|
|||
|
|
For a more in-depth discussion of memory mapping and examples, see
|
|||
|
|
:ref:`mmap`.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Reading Raw VBI Data
|
|||
|
|
====================
|
|||
|
|
|
|||
|
|
Originally the V4L API did not specify a raw VBI capture interface, only
|
|||
|
|
the device file ``/dev/vbi`` was reserved for this purpose. The only
|
|||
|
|
driver supporting this interface was the BTTV driver, de-facto defining
|
|||
|
|
the V4L VBI interface. Reading from the device yields a raw VBI image
|
|||
|
|
with the following parameters:
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
.. flat-table::
|
|||
|
|
:header-rows: 1
|
|||
|
|
:stub-columns: 0
|
|||
|
|
|
|||
|
|
* - struct :c:type:`v4l2_vbi_format`
|
|||
|
|
- V4L, BTTV driver
|
|||
|
|
* - sampling_rate
|
|||
|
|
- 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
|
|||
|
|
and SECAM (625-line standards)
|
|||
|
|
* - offset
|
|||
|
|
- ?
|
|||
|
|
* - samples_per_line
|
|||
|
|
- 2048
|
|||
|
|
* - sample_format
|
|||
|
|
- V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
|
|||
|
|
integer) contain a frame counter.
|
|||
|
|
* - start[]
|
|||
|
|
- 10, 273 NTSC; 22, 335 PAL and SECAM
|
|||
|
|
* - count[]
|
|||
|
|
- 16, 16 [#f9]_
|
|||
|
|
* - flags
|
|||
|
|
- 0
|
|||
|
|
|
|||
|
|
|
|||
|
|
Undocumented in the V4L specification, in Linux 2.3 the
|
|||
|
|
``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
|
|||
|
|
``vbi_format`` were added to determine the VBI image
|
|||
|
|
parameters. These ioctls are only partially compatible with the V4L2 VBI
|
|||
|
|
interface specified in :ref:`raw-vbi`.
|
|||
|
|
|
|||
|
|
An ``offset`` field does not exist, ``sample_format`` is supposed to be
|
|||
|
|
``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
|
|||
|
|
remaining fields are probably equivalent to struct
|
|||
|
|
:c:type:`v4l2_vbi_format`.
|
|||
|
|
|
|||
|
|
Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
|
|||
|
|
semantics differ from those specified for V4L2 in two ways. The
|
|||
|
|
parameters are reset on :ref:`open() <func-open>` and
|
|||
|
|
``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
|
|||
|
|
are invalid.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Miscellaneous
|
|||
|
|
=============
|
|||
|
|
|
|||
|
|
V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
|
|||
|
|
find the VBI device associated with a video capture device (or vice
|
|||
|
|
versa) by reopening the device and requesting VBI data. For details see
|
|||
|
|
:ref:`open`.
|
|||
|
|
|
|||
|
|
No replacement exists for ``VIDIOCKEY``, and the V4L functions for
|
|||
|
|
microcode programming. A new interface for MPEG compression and playback
|
|||
|
|
devices is documented in :ref:`extended-controls`.
|
|||
|
|
|
|||
|
|
.. [#f1]
|
|||
|
|
According to Documentation/admin-guide/devices.rst these should be symbolic links
|
|||
|
|
to ``/dev/video0``. Note the original bttv interface is not
|
|||
|
|
compatible with V4L or V4L2.
|
|||
|
|
|
|||
|
|
.. [#f2]
|
|||
|
|
According to ``Documentation/admin-guide/devices.rst`` a symbolic link to
|
|||
|
|
``/dev/radio0``.
|
|||
|
|
|
|||
|
|
.. [#f3]
|
|||
|
|
This is a custom format used by the BTTV driver, not one of the V4L2
|
|||
|
|
standard formats.
|
|||
|
|
|
|||
|
|
.. [#f4]
|
|||
|
|
Presumably all V4L RGB formats are little-endian, although some
|
|||
|
|
drivers might interpret them according to machine endianness. V4L2
|
|||
|
|
defines little-endian, big-endian and red/blue swapped variants. For
|
|||
|
|
details see :ref:`pixfmt-rgb`.
|
|||
|
|
|
|||
|
|
.. [#f5]
|
|||
|
|
``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
|
|||
|
|
formats. Some V4L drivers respond to one, some to the other.
|
|||
|
|
|
|||
|
|
.. [#f6]
|
|||
|
|
Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
|
|||
|
|
format.
|
|||
|
|
|
|||
|
|
.. [#f7]
|
|||
|
|
V4L explains this as: "RAW capture (BT848)"
|
|||
|
|
|
|||
|
|
.. [#f8]
|
|||
|
|
Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
|
|||
|
|
format.
|
|||
|
|
|
|||
|
|
.. [#f9]
|
|||
|
|
Old driver versions used different values, eventually the custom
|
|||
|
|
``BTTV_VBISIZE`` ioctl was added to query the correct values.
|