0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_QUERY_DV_TIMINGS:
0005
0006 *****************************
0007 ioctl VIDIOC_QUERY_DV_TIMINGS
0008 *****************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_QUERY_DV_TIMINGS
0019
0020 ``int ioctl(int fd, VIDIOC_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
0021
0022 .. c:macro:: VIDIOC_SUBDEV_QUERY_DV_TIMINGS
0023
0024 ``int ioctl(int fd, VIDIOC_SUBDEV_QUERY_DV_TIMINGS, struct v4l2_dv_timings *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_dv_timings`.
0034
0035 Description
0036 ===========
0037
0038 The hardware may be able to detect the current DV timings automatically,
0039 similar to sensing the video standard. To do so, applications call
0040 :ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
0041 :c:type:`v4l2_dv_timings`. Once the hardware detects
0042 the timings, it will fill in the timings structure.
0043
0044 .. note::
0045
0046 Drivers shall *not* switch timings automatically if new
0047 timings are detected. Instead, drivers should send the
0048 ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
0049 that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
0050 The reason is that new timings usually mean different buffer sizes as
0051 well, and you cannot change buffer sizes on the fly. In general,
0052 applications that receive the Source Change event will have to call
0053 :ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
0054 will have to stop streaming, set the new timings, allocate new buffers
0055 and start streaming again.
0056
0057 If the timings could not be detected because there was no signal, then
0058 ENOLINK is returned. If a signal was detected, but it was unstable and
0059 the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
0060 the receiver could lock to the signal, but the format is unsupported
0061 (e.g. because the pixelclock is out of range of the hardware
0062 capabilities), then the driver fills in whatever timings it could find
0063 and returns ``ERANGE``. In that case the application can call
0064 :ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
0065 found timings with the hardware's capabilities in order to give more
0066 precise feedback to the user.
0067
0068 Return Value
0069 ============
0070
0071 On success 0 is returned, on error -1 and the ``errno`` variable is set
0072 appropriately. The generic error codes are described at the
0073 :ref:`Generic Error Codes <gen-errors>` chapter.
0074
0075 ENODATA
0076 Digital video timings are not supported for this input or output.
0077
0078 ENOLINK
0079 No timings could be detected because no signal was found.
0080
0081 ENOLCK
0082 The signal was unstable and the hardware could not lock on to it.
0083
0084 ERANGE
0085 Timings were found, but they are out of range of the hardware
0086 capabilities.
