1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_QUERY_DV_TIMINGS:
5
6*****************************
7ioctl VIDIOC_QUERY_DV_TIMINGS
8*****************************
9
10Name
11====
12
13VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
14
15Synopsis
16========
17
18.. c:macro:: VIDIOC_QUERY_DV_TIMINGS
19
20``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
21
22.. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
23
24``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
25
26Arguments
27=========
28
29``fd``
30    File descriptor returned by :c:func:`open()`.
31
32``argp``
33    Pointer to struct :c:type:`v4l2_dv_timings`.
34
35Description
36===========
37
38The hardware may be able to detect the current DV timings automatically,
39similar to sensing the video standard. To do so, applications call
40:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
41:c:type:`v4l2_dv_timings`. Once the hardware detects
42the timings, it will fill in the timings structure.
43
44.. note::
45
46   Drivers shall *not* switch timings automatically if new
47   timings are detected. Instead, drivers should send the
48   ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
49   that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
50   The reason is that new timings usually mean different buffer sizes as
51   well, and you cannot change buffer sizes on the fly. In general,
52   applications that receive the Source Change event will have to call
53   :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
54   will have to stop streaming, set the new timings, allocate new buffers
55   and start streaming again.
56
57If the timings could not be detected because there was no signal, then
58ENOLINK is returned. If a signal was detected, but it was unstable and
59the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
60the receiver could lock to the signal, but the format is unsupported
61(e.g. because the pixelclock is out of range of the hardware
62capabilities), then the driver fills in whatever timings it could find
63and returns ``ERANGE``. In that case the application can call
64:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
65found timings with the hardware's capabilities in order to give more
66precise feedback to the user.
67
68Return Value
69============
70
71On success 0 is returned, on error -1 and the ``errno`` variable is set
72appropriately. The generic error codes are described at the
73:ref:`Generic Error Codes <gen-errors>` chapter.
74
75ENODATA
76    Digital video timings are not supported for this input or output.
77
78ENOLINK
79    No timings could be detected because no signal was found.
80
81ENOLCK
82    The signal was unstable and the hardware could not lock on to it.
83
84ERANGE
85    Timings were found, but they are out of range of the hardware
86    capabilities.
87