0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _diff-v4l:
0005
0006 ********************************
0007 Differences between V4L and V4L2
0008 ********************************
0009
0010 The Video For Linux API was first introduced in Linux 2.1 to unify and
0011 replace various TV and radio device related interfaces, developed
0012 independently by driver writers in prior years. Starting with Linux 2.5
0013 the much improved V4L2 API replaces the V4L API. The support for the old
0014 V4L calls were removed from Kernel, but the library :ref:`libv4l`
0015 supports the conversion of a V4L API system call into a V4L2 one.
0016
0017 Opening and Closing Devices
0018 ===========================
0019
0020 For compatibility reasons the character device file names recommended
0021 for V4L2 video capture, overlay, radio and raw vbi capture devices did
0022 not change from those used by V4L. They are listed in :ref:`devices`
0023 and below in :ref:`v4l-dev`.
0024
0025 The teletext devices (minor range 192-223) have been removed in V4L2 and
0026 no longer exist. There is no hardware available anymore for handling
0027 pure teletext. Instead raw or sliced VBI is used.
0028
0029 The V4L ``videodev`` module automatically assigns minor numbers to
0030 drivers in load order, depending on the registered device type. We
0031 recommend that V4L2 drivers by default register devices with the same
0032 numbers, but the system administrator can assign arbitrary minor numbers
0033 using driver module options. The major device number remains 81.
0034
0035 .. _v4l-dev:
0036
0037 .. flat-table:: V4L Device Types, Names and Numbers
0038 :header-rows: 1
0039 :stub-columns: 0
0040
0041 * - Device Type
0042 - File Name
0043 - Minor Numbers
0044 * - Video capture and overlay
0045 - ``/dev/video`` and ``/dev/bttv0``\ [#f1]_, ``/dev/video0`` to
0046 ``/dev/video63``
0047 - 0-63
0048 * - Radio receiver
0049 - ``/dev/radio``\ [#f2]_, ``/dev/radio0`` to ``/dev/radio63``
0050 - 64-127
0051 * - Raw VBI capture
0052 - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
0053 - 224-255
0054
0055 V4L prohibits (or used to prohibit) multiple opens of a device file.
0056 V4L2 drivers *may* support multiple opens, see :ref:`open` for details
0057 and consequences.
0058
0059 V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
0060
0061 Querying Capabilities
0062 =====================
0063
0064 The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
0065 :ref:`VIDIOC_QUERYCAP`.
0066
0067 The ``name`` field in struct ``video_capability`` became
0068 ``card`` in struct :c:type:`v4l2_capability`, ``type``
0069 was replaced by ``capabilities``. Note V4L2 does not distinguish between
0070 device types like this, better think of basic video input, video output
0071 and radio devices supporting a set of related functions like video
0072 capturing, video overlay and VBI capturing. See :ref:`open` for an
0073 introduction.
0074
0075 .. raw:: latex
0076
0077 \small
0078
0079 .. tabularcolumns:: |p{5.3cm}|p{6.7cm}|p{5.3cm}|
0080
0081 .. cssclass:: longtable
0082
0083 .. flat-table::
0084 :header-rows: 1
0085 :stub-columns: 0
0086
0087 * - ``struct video_capability`` ``type``
0088 - struct :c:type:`v4l2_capability`
0089 ``capabilities`` flags
0090 - Purpose
0091 * - ``VID_TYPE_CAPTURE``
0092 - ``V4L2_CAP_VIDEO_CAPTURE``
0093 - The :ref:`video capture <capture>` interface is supported.
0094 * - ``VID_TYPE_TUNER``
0095 - ``V4L2_CAP_TUNER``
0096 - The device has a :ref:`tuner or modulator <tuner>`.
0097 * - ``VID_TYPE_TELETEXT``
0098 - ``V4L2_CAP_VBI_CAPTURE``
0099 - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
0100 * - ``VID_TYPE_OVERLAY``
0101 - ``V4L2_CAP_VIDEO_OVERLAY``
0102 - The :ref:`video overlay <overlay>` interface is supported.
0103 * - ``VID_TYPE_CHROMAKEY``
0104 - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
0105 :c:type:`v4l2_framebuffer`
0106 - Whether chromakey overlay is supported. For more information on
0107 overlay see :ref:`overlay`.
0108 * - ``VID_TYPE_CLIPPING``
0109 - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
0110 ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
0111 struct :c:type:`v4l2_framebuffer`
0112 - Whether clipping the overlaid image is supported, see
0113 :ref:`overlay`.
0114 * - ``VID_TYPE_FRAMERAM``
0115 - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
0116 of struct :c:type:`v4l2_framebuffer`
0117 - Whether overlay overwrites frame buffer memory, see
0118 :ref:`overlay`.
0119 * - ``VID_TYPE_SCALES``
0120 - ``-``
0121 - This flag indicates if the hardware can scale images. The V4L2 API
0122 implies the scale factor by setting the cropping dimensions and
0123 image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
0124 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
0125 driver returns the closest sizes possible. For more information on
0126 cropping and scaling see :ref:`crop`.
0127 * - ``VID_TYPE_MONOCHROME``
0128 - ``-``
0129 - Applications can enumerate the supported image formats with the
0130 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
0131 the device supports grey scale capturing only. For more
0132 information on image formats see :ref:`pixfmt`.
0133 * - ``VID_TYPE_SUBCAPTURE``
0134 - ``-``
0135 - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
0136 ioctl to determine if the device supports capturing a subsection
0137 of the full picture ("cropping" in V4L2). If not, the ioctl
0138 returns the ``EINVAL`` error code. For more information on cropping
0139 and scaling see :ref:`crop`.
0140 * - ``VID_TYPE_MPEG_DECODER``
0141 - ``-``
0142 - Applications can enumerate the supported image formats with the
0143 :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
0144 the device supports MPEG streams.
0145 * - ``VID_TYPE_MPEG_ENCODER``
0146 - ``-``
0147 - See above.
0148 * - ``VID_TYPE_MJPEG_DECODER``
0149 - ``-``
0150 - See above.
0151 * - ``VID_TYPE_MJPEG_ENCODER``
0152 - ``-``
0153 - See above.
0154
0155 .. raw:: latex
0156
0157 \normalsize
0158
0159 The ``audios`` field was replaced by ``capabilities`` flag
0160 ``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
0161 outputs. To determine their number applications can enumerate audio
0162 inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
0163 audio ioctls are described in :ref:`audio`.
0164
0165 The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
0166 were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
0167 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
0168 dimensions returns the closest size possible, taking into account the
0169 current video standard, cropping and scaling limitations.
0170
0171 Video Sources
0172 =============
0173
0174 V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
0175 ``video_channel`` to enumerate the video inputs of a V4L
0176 device. The equivalent V4L2 ioctls are
0177 :ref:`VIDIOC_ENUMINPUT`,
0178 :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
0179 :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
0180 :c:type:`v4l2_input` as discussed in :ref:`video`.
0181
0182 The ``channel`` field counting inputs was renamed to ``index``, the
0183 video input types were renamed as follows:
0184
0185
0186 .. flat-table::
0187 :header-rows: 1
0188 :stub-columns: 0
0189
0190 * - struct ``video_channel`` ``type``
0191 - struct :c:type:`v4l2_input` ``type``
0192 * - ``VIDEO_TYPE_TV``
0193 - ``V4L2_INPUT_TYPE_TUNER``
0194 * - ``VIDEO_TYPE_CAMERA``
0195 - ``V4L2_INPUT_TYPE_CAMERA``
0196
0197 Unlike the ``tuners`` field expressing the number of tuners of this
0198 input, V4L2 assumes each video input is connected to at most one tuner.
0199 However a tuner can have more than one input, i. e. RF connectors, and a
0200 device can have multiple tuners. The index number of the tuner
0201 associated with the input, if any, is stored in field ``tuner`` of
0202 struct :c:type:`v4l2_input`. Enumeration of tuners is
0203 discussed in :ref:`tuner`.
0204
0205 The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
0206 associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
0207 ``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
0208 considers devices with up to 32 audio inputs. Each set bit in the
0209 ``audioset`` field represents one audio input this video input combines
0210 with. For information about audio inputs and how to switch between them
0211 see :ref:`audio`.
0212
0213 The ``norm`` field describing the supported video standards was replaced
0214 by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
0215 indicating whether the standard can be changed. This flag was a later
0216 addition together with the ``norm`` field and has been removed in the
0217 meantime. V4L2 has a similar, albeit more comprehensive approach to
0218 video standards, see :ref:`standard` for more information.
0219
0220 Tuning
0221 ======
0222
0223 The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
0224 ``video_tuner`` can be used to enumerate the tuners of a
0225 V4L TV or radio device. The equivalent V4L2 ioctls are
0226 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
0227 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
0228 :c:type:`v4l2_tuner`. Tuners are covered in :ref:`tuner`.
0229
0230 The ``tuner`` field counting tuners was renamed to ``index``. The fields
0231 ``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
0232
0233 The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
0234 flags indicating the supported video standards were dropped. This
0235 information is now contained in the associated struct
0236 :c:type:`v4l2_input`. No replacement exists for the
0237 ``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
0238 switched. The ``mode`` field to select a different video standard was
0239 replaced by a whole new set of ioctls and structures described in
0240 :ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
0241 driver supports several standards in addition to the regular
0242 ``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
0243 ``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
0244 Japan with numbers 3-6 (sic).
0245
0246 The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
0247 ``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
0248 permits the detection of monaural and bilingual audio, see the
0249 definition of struct :c:type:`v4l2_tuner` for details.
0250 Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
0251 ``VIDEO_TUNER_MBS_ON`` flags.
0252
0253 The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
0254 the struct :c:type:`v4l2_tuner` ``capability`` field.
0255
0256 The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
0257 frequency where renamed to
0258 :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
0259 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
0260 to a struct :c:type:`v4l2_frequency` instead of an
0261 unsigned long integer.
0262
0263 .. _v4l-image-properties:
0264
0265 Image Properties
0266 ================
0267
0268 V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
0269 and struct ``video_picture``. The following fields where
0270 replaced by V4L2 controls accessible with the
0271 :ref:`VIDIOC_QUERYCTRL`,
0272 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
0273 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
0274
0275
0276 .. flat-table::
0277 :header-rows: 1
0278 :stub-columns: 0
0279
0280 * - struct ``video_picture``
0281 - V4L2 Control ID
0282 * - ``brightness``
0283 - ``V4L2_CID_BRIGHTNESS``
0284 * - ``hue``
0285 - ``V4L2_CID_HUE``
0286 * - ``colour``
0287 - ``V4L2_CID_SATURATION``
0288 * - ``contrast``
0289 - ``V4L2_CID_CONTRAST``
0290 * - ``whiteness``
0291 - ``V4L2_CID_WHITENESS``
0292
0293 The V4L picture controls are assumed to range from 0 to 65535 with no
0294 particular reset value. The V4L2 API permits arbitrary limits and
0295 defaults which can be queried with the
0296 :ref:`VIDIOC_QUERYCTRL` ioctl. For general
0297 information about controls see :ref:`control`.
0298
0299 The ``depth`` (average number of bits per pixel) of a video image is
0300 implied by the selected image format. V4L2 does not explicitly provide
0301 such information assuming applications recognizing the format are aware
0302 of the image depth and others need not know. The ``palette`` field moved
0303 into the struct :c:type:`v4l2_pix_format`:
0304
0305
0306 .. flat-table::
0307 :header-rows: 1
0308 :stub-columns: 0
0309
0310 * - struct ``video_picture`` ``palette``
0311 - struct :c:type:`v4l2_pix_format` ``pixfmt``
0312 * - ``VIDEO_PALETTE_GREY``
0313 - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
0314 * - ``VIDEO_PALETTE_HI240``
0315 - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [#f3]_
0316 * - ``VIDEO_PALETTE_RGB565``
0317 - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
0318 * - ``VIDEO_PALETTE_RGB555``
0319 - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
0320 * - ``VIDEO_PALETTE_RGB24``
0321 - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
0322 * - ``VIDEO_PALETTE_RGB32``
0323 - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [#f4]_
0324 * - ``VIDEO_PALETTE_YUV422``
0325 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
0326 * - ``VIDEO_PALETTE_YUYV``\ [#f5]_
0327 - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
0328 * - ``VIDEO_PALETTE_UYVY``
0329 - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
0330 * - ``VIDEO_PALETTE_YUV420``
0331 - None
0332 * - ``VIDEO_PALETTE_YUV411``
0333 - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [#f6]_
0334 * - ``VIDEO_PALETTE_RAW``
0335 - None [#f7]_
0336 * - ``VIDEO_PALETTE_YUV422P``
0337 - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
0338 * - ``VIDEO_PALETTE_YUV411P``
0339 - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [#f8]_
0340 * - ``VIDEO_PALETTE_YUV420P``
0341 - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
0342 * - ``VIDEO_PALETTE_YUV410P``
0343 - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
0344
0345 V4L2 image formats are defined in :ref:`pixfmt`. The image format can
0346 be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
0347
0348 Audio
0349 =====
0350
0351 The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
0352 ``video_audio`` are used to enumerate the audio inputs
0353 of a V4L device. The equivalent V4L2 ioctls are
0354 :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
0355 :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
0356 :c:type:`v4l2_audio` as discussed in :ref:`audio`.
0357
0358 The ``audio`` "channel number" field counting audio inputs was renamed
0359 to ``index``.
0360
0361 On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
0362 ``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
0363 ``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
0364 standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
0365 ``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
0366 specification, there is no way to query the selected mode. On
0367 ``VIDIOCGAUDIO`` the driver returns the *actually received* audio
0368 programmes in this field. In the V4L2 API this information is stored in
0369 the struct :c:type:`v4l2_tuner` ``rxsubchans`` and
0370 ``audmode`` fields, respectively. See :ref:`tuner` for more
0371 information on tuners. Related to audio modes struct
0372 :c:type:`v4l2_audio` also reports if this is a mono or
0373 stereo input, regardless if the source is a tuner.
0374
0375 The following fields where replaced by V4L2 controls accessible with the
0376 :ref:`VIDIOC_QUERYCTRL`,
0377 :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
0378 :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
0379
0380
0381 .. flat-table::
0382 :header-rows: 1
0383 :stub-columns: 0
0384
0385 * - struct ``video_audio``
0386 - V4L2 Control ID
0387 * - ``volume``
0388 - ``V4L2_CID_AUDIO_VOLUME``
0389 * - ``bass``
0390 - ``V4L2_CID_AUDIO_BASS``
0391 * - ``treble``
0392 - ``V4L2_CID_AUDIO_TREBLE``
0393 * - ``balance``
0394 - ``V4L2_CID_AUDIO_BALANCE``
0395
0396 To determine which of these controls are supported by a driver V4L
0397 provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
0398 ``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
0399 :ref:`VIDIOC_QUERYCTRL` ioctl reports if the
0400 respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
0401 and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
0402 ``V4L2_CID_AUDIO_MUTE`` control.
0403
0404 All V4L2 controls have a ``step`` attribute replacing the struct
0405 ``video_audio`` ``step`` field. The V4L audio controls
0406 are assumed to range from 0 to 65535 with no particular reset value. The
0407 V4L2 API permits arbitrary limits and defaults which can be queried with
0408 the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
0409 information about controls see :ref:`control`.
0410
0411 Frame Buffer Overlay
0412 ====================
0413
0414 The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
0415 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
0416 :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
0417 ``video_buffer`` remained unchanged, except V4L2 defines
0418 a flag to indicate non-destructive overlays instead of a ``NULL``
0419 pointer. All other fields moved into the struct
0420 :c:type:`v4l2_pix_format` ``fmt`` substructure of
0421 struct :c:type:`v4l2_framebuffer`. The ``depth``
0422 field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
0423 list of RGB formats and their respective color depths.
0424
0425 Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
0426 uses the general-purpose data format negotiation ioctls
0427 :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
0428 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
0429 :c:type:`v4l2_format` as argument. Here the ``win`` member
0430 of the ``fmt`` union is used, a struct
0431 :c:type:`v4l2_window`.
0432
0433 The ``x``, ``y``, ``width`` and ``height`` fields of struct
0434 ``video_window`` moved into struct
0435 :c:type:`v4l2_rect` substructure ``w`` of struct
0436 :c:type:`v4l2_window`. The ``chromakey``, ``clips``, and
0437 ``clipcount`` fields remained unchanged. Struct
0438 ``video_clip`` was renamed to struct
0439 :c:type:`v4l2_clip`, also containing a struct
0440 :c:type:`v4l2_rect`, but the semantics are still the same.
0441
0442 The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
0443 must set the ``field`` field to ``V4L2_FIELD_ANY`` or
0444 ``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
0445 into struct :c:type:`v4l2_framebuffer`, under the new
0446 name ``V4L2_FBUF_FLAG_CHROMAKEY``.
0447
0448 In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
0449 to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
0450 size bitmap of 1024 × 625 bits. Struct :c:type:`v4l2_window`
0451 has a separate ``bitmap`` pointer field for this purpose and the bitmap
0452 size is determined by ``w.width`` and ``w.height``.
0453
0454 The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
0455 :ref:`VIDIOC_OVERLAY`.
0456
0457 Cropping
0458 ========
0459
0460 To capture only a subsection of the full picture V4L defines the
0461 ``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
0462 ``video_capture``. The equivalent V4L2 ioctls are
0463 :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
0464 :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
0465 :c:type:`v4l2_crop`, and the related
0466 :ref:`VIDIOC_CROPCAP` ioctl. This is a rather
0467 complex matter, see :ref:`crop` for details.
0468
0469 The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
0470 :c:type:`v4l2_rect` substructure ``c`` of struct
0471 :c:type:`v4l2_crop`. The ``decimation`` field was dropped. In
0472 the V4L2 API the scaling factor is implied by the size of the cropping
0473 rectangle and the size of the captured or overlaid image.
0474
0475 The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
0476 only the odd or even field, respectively, were replaced by
0477 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
0478 ``field`` of struct :c:type:`v4l2_pix_format` and
0479 struct :c:type:`v4l2_window`. These structures are used to
0480 select a capture or overlay format with the
0481 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
0482
0483 Reading Images, Memory Mapping
0484 ==============================
0485
0486 Capturing using the read method
0487 -------------------------------
0488
0489 There is no essential difference between reading images from a V4L or
0490 V4L2 device using the :c:func:`read()` function, however V4L2
0491 drivers are not required to support this I/O method. Applications can
0492 determine if the function is available with the
0493 :ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
0494 exchanging data with applications must support the
0495 :c:func:`select()` and :c:func:`poll()`
0496 functions.
0497
0498 To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
0499 ``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
0500 negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
0501 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
0502 :c:type:`v4l2_format` as argument, here the struct
0503 :c:type:`v4l2_pix_format` named ``pix`` of its
0504 ``fmt`` union is used.
0505
0506 For more information about the V4L2 read interface see :ref:`rw`.
0507
0508 Capturing using memory mapping
0509 ------------------------------
0510
0511 Applications can read from V4L devices by mapping buffers in device
0512 memory, or more often just buffers allocated in DMA-able system memory,
0513 into their address space. This avoids the data copying overhead of the
0514 read method. V4L2 supports memory mapping as well, with a few
0515 differences.
0516
0517
0518 .. flat-table::
0519 :header-rows: 1
0520 :stub-columns: 0
0521
0522 * - V4L
0523 - V4L2
0524 * -
0525 - The image format must be selected before buffers are allocated,
0526 with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
0527 format is selected the driver may use the last, possibly by
0528 another application requested format.
0529 * - Applications cannot change the number of buffers. The it is built
0530 into the driver, unless it has a module option to change the
0531 number when the driver module is loaded.
0532 - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
0533 desired number of buffers, this is a required step in the
0534 initialization sequence.
0535 * - Drivers map all buffers as one contiguous range of memory. The
0536 ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
0537 the offset of each buffer from the start of the virtual file, and
0538 the overall amount of memory used, which can be used as arguments
0539 for the :c:func:`mmap()` function.
0540 - Buffers are individually mapped. The offset and size of each
0541 buffer can be determined with the
0542 :ref:`VIDIOC_QUERYBUF` ioctl.
0543 * - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
0544 also determines the image format for this buffer. The ioctl
0545 returns immediately, eventually with an ``EAGAIN`` error code if no
0546 video signal had been detected. When the driver supports more than
0547 one buffer applications can call the ioctl multiple times and thus
0548 have multiple outstanding capture requests.
0549
0550 The ``VIDIOCSYNC`` ioctl suspends execution until a particular
0551 buffer has been filled.
0552 - Drivers maintain an incoming and outgoing queue.
0553 :ref:`VIDIOC_QBUF` enqueues any empty buffer into
0554 the incoming queue. Filled buffers are dequeued from the outgoing
0555 queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
0556 until filled buffers become available this function,
0557 :c:func:`select()` or :c:func:`poll()` can
0558 be used. The :ref:`VIDIOC_STREAMON` ioctl
0559 must be called once after enqueuing one or more buffers to start
0560 capturing. Its counterpart
0561 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
0562 dequeues all buffers from both queues. Applications can query the
0563 signal status, if known, with the
0564 :ref:`VIDIOC_ENUMINPUT` ioctl.
0565
0566 For a more in-depth discussion of memory mapping and examples, see
0567 :ref:`mmap`.
0568
0569 Reading Raw VBI Data
0570 ====================
0571
0572 Originally the V4L API did not specify a raw VBI capture interface, only
0573 the device file ``/dev/vbi`` was reserved for this purpose. The only
0574 driver supporting this interface was the BTTV driver, de-facto defining
0575 the V4L VBI interface. Reading from the device yields a raw VBI image
0576 with the following parameters:
0577
0578
0579 .. flat-table::
0580 :header-rows: 1
0581 :stub-columns: 0
0582
0583 * - struct :c:type:`v4l2_vbi_format`
0584 - V4L, BTTV driver
0585 * - sampling_rate
0586 - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
0587 and SECAM (625-line standards)
0588 * - offset
0589 - ?
0590 * - samples_per_line
0591 - 2048
0592 * - sample_format
0593 - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
0594 integer) contain a frame counter.
0595 * - start[]
0596 - 10, 273 NTSC; 22, 335 PAL and SECAM
0597 * - count[]
0598 - 16, 16 [#f9]_
0599 * - flags
0600 - 0
0601
0602 Undocumented in the V4L specification, in Linux 2.3 the
0603 ``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
0604 ``vbi_format`` were added to determine the VBI image
0605 parameters. These ioctls are only partially compatible with the V4L2 VBI
0606 interface specified in :ref:`raw-vbi`.
0607
0608 An ``offset`` field does not exist, ``sample_format`` is supposed to be
0609 ``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
0610 remaining fields are probably equivalent to struct
0611 :c:type:`v4l2_vbi_format`.
0612
0613 Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
0614 semantics differ from those specified for V4L2 in two ways. The
0615 parameters are reset on :c:func:`open()` and
0616 ``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
0617 are invalid.
0618
0619 Miscellaneous
0620 =============
0621
0622 V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
0623 find the VBI device associated with a video capture device (or vice
0624 versa) by reopening the device and requesting VBI data. For details see
0625 :ref:`open`.
0626
0627 No replacement exists for ``VIDIOCKEY``, and the V4L functions for
0628 microcode programming. A new interface for MPEG compression and playback
0629 devices is documented in :ref:`extended-controls`.
0630
0631 .. [#f1]
0632 According to Documentation/admin-guide/devices.rst these should be symbolic links
0633 to ``/dev/video0``. Note the original bttv interface is not
0634 compatible with V4L or V4L2.
0635
0636 .. [#f2]
0637 According to ``Documentation/admin-guide/devices.rst`` a symbolic link to
0638 ``/dev/radio0``.
0639
0640 .. [#f3]
0641 This is a custom format used by the BTTV driver, not one of the V4L2
0642 standard formats.
0643
0644 .. [#f4]
0645 Presumably all V4L RGB formats are little-endian, although some
0646 drivers might interpret them according to machine endianness. V4L2
0647 defines little-endian, big-endian and red/blue swapped variants. For
0648 details see :ref:`pixfmt-rgb`.
0649
0650 .. [#f5]
0651 ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
0652 formats. Some V4L drivers respond to one, some to the other.
0653
0654 .. [#f6]
0655 Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
0656 format.
0657
0658 .. [#f7]
0659 V4L explains this as: "RAW capture (BT848)"
0660
0661 .. [#f8]
0662 Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
0663 format.
0664
0665 .. [#f9]
0666 Old driver versions used different values, eventually the custom
0667 ``BTTV_VBISIZE`` ioctl was added to query the correct values.
