1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 1 .. Permission is granted to copy, distribute and/or modify this
>> 2 .. document under the terms of the GNU Free Documentation License,
>> 3 .. Version 1.1 or any later version published by the Free Software
>> 4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
>> 5 .. and no Back-Cover Texts. A copy of the license is included at
>> 6 .. Documentation/userspace-api/media/fdl-appendix.rst.
>> 7 ..
>> 8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
2 9
3 .. _dv-timings: 10 .. _dv-timings:
4 11
5 ************************** 12 **************************
6 Digital Video (DV) Timings 13 Digital Video (DV) Timings
7 ************************** 14 **************************
8 15
9 The video standards discussed so far have been 16 The video standards discussed so far have been dealing with Analog TV
10 and the corresponding video timings. Today the 17 and the corresponding video timings. Today there are many more different
11 hardware interfaces such as High Definition TV 18 hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
12 DVI connectors etc., that carry video signals 19 DVI connectors etc., that carry video signals and there is a need to
13 extend the API to select the video timings for 20 extend the API to select the video timings for these interfaces. Since
14 it is not possible to extend the :ref:`v4l2_st 21 it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
15 due to the limited bits available, a new set o 22 due to the limited bits available, a new set of ioctls was added to
16 set/get video timings at the input and output. 23 set/get video timings at the input and output.
17 24
18 These ioctls deal with the detailed digital vi 25 These ioctls deal with the detailed digital video timings that define
19 each video format. This includes parameters su 26 each video format. This includes parameters such as the active video
20 width and height, signal polarities, frontporc 27 width and height, signal polarities, frontporches, backporches, sync
21 widths etc. The ``linux/v4l2-dv-timings.h`` he 28 widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
22 the timings of the formats in the :ref:`cea861 29 the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
23 standards. 30 standards.
24 31
25 To enumerate and query the attributes of the D 32 To enumerate and query the attributes of the DV timings supported by a
26 device applications use the 33 device applications use the
27 :ref:`VIDIOC_ENUM_DV_TIMINGS` and 34 :ref:`VIDIOC_ENUM_DV_TIMINGS` and
28 :ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set 35 :ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set
29 DV timings for the device applications use the 36 DV timings for the device applications use the
30 :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS 37 :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get
31 current DV timings they use the 38 current DV timings they use the
32 :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS 39 :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect
33 the DV timings as seen by the video receiver a 40 the DV timings as seen by the video receiver applications use the
34 :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl. 41 :ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.
35 <<
36 When the hardware detects a video source chang <<
37 signal appears or disappears, or the video res <<
38 it will issue a `V4L2_EVENT_SOURCE_CHANGE` eve <<
39 :ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUB <<
40 :ref:`VIDIOC_DQEVENT` to check if this event w <<
41 <<
42 If the video signal changed, then the applicat <<
43 streaming, free all buffers, and call the :ref <<
44 to obtain the new video timings, and if they a <<
45 those by calling the :ref:`ioctl VIDIOC_S_DV_T <<
46 This will also update the format, so use the : <<
47 to obtain the new format. Now the application <<
48 and start streaming again. <<
49 <<
50 The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just r <<
51 hardware detects, it will never change the con <<
52 currently set timings and the actually detecte <<
53 typically this will mean that you will not be <<
54 video. The correct approach is to rely on the <<
55 event so you know when something changed. <<
56 42
57 Applications can make use of the :ref:`input-c 43 Applications can make use of the :ref:`input-capabilities` and
58 :ref:`output-capabilities` flags to determine 44 :ref:`output-capabilities` flags to determine whether the digital
59 video ioctls can be used with the given input 45 video ioctls can be used with the given input or output.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.