Debian Codegraph @

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

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