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