668 lines
25 KiB
ReStructuredText
668 lines
25 KiB
ReStructuredText
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
|
||
.. c:namespace:: V4L
|
||
|
||
.. _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.
|
||
|
||
.. raw:: latex
|
||
|
||
\small
|
||
|
||
.. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}|
|
||
|
||
.. 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.
|
||
|
||
.. raw:: latex
|
||
|
||
\normalsize
|
||
|
||
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 :c: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
|
||
:c:func:`select()` and :c: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 :c: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,
|
||
:c:func:`select()` or :c: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 :c: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.
|