Documentation/userspace-api/media/v4l/dv-timings.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2
   3 .. _dv-timings:
   4
   5 **************************
   6 Digital Video (DV) Timings
   7 **************************
   8
   9 The video standards discussed so far have been dealing with Analog TV
  10 and the corresponding video timings. Today there are many more different
  11 hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
  12 DVI connectors etc., that carry video signals and there is a need to
  13 extend the API to select the video timings for these interfaces. Since
  14 it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
  15 due to the limited bits available, a new set of ioctls was added to
  16 set/get video timings at the input and output.
  17
  18 These ioctls deal with the detailed digital video timings that define
  19 each video format. This includes parameters such as the active video
  20 width and height, signal polarities, frontporches, backporches, sync
  21 widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
  22 the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
  23 standards.
  24
  25 To enumerate and query the attributes of the DV timings supported by a
  26 device applications use the
  27 :ref:`VIDIOC_ENUM_DV_TIMINGS` and
  28 :ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set
  29 DV timings for the device applications use the
  30 :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get
  31 current DV timings they use the
  32 :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect
  33 the DV timings as seen by the video receiver applications use the
  34 :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.
  35
  36 When the hardware detects a video source change (e.g. the video
  37 signal appears or disappears, or the video resolution changes), then
  38 it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the
  39 :ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the
  40 :ref:`VIDIOC_DQEVENT` to check if this event was reported.
  41
  42 If the video signal changed, then the application has to stop
  43 streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS`
  44 to obtain the new video timings, and if they are valid, it can set
  45 those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`.
  46 This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>`
  47 to obtain the new format. Now the application can allocate new buffers
  48 and start streaming again.
  49
  50 The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the
  51 hardware detects, it will never change the configuration. If the
  52 currently set timings and the actually detected timings differ, then
  53 typically this will mean that you will not be able to capture any
  54 video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE`
  55 event so you know when something changed.
  56
  57 Applications can make use of the :ref:`input-capabilities` and
  58 :ref:`output-capabilities` flags to determine whether the digital
  59 video ioctls can be used with the given input or output.