60 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _dv-timings:4 5**************************6Digital Video (DV) Timings7**************************8 9The video standards discussed so far have been dealing with Analog TV10and the corresponding video timings. Today there are many more different11hardware interfaces such as High Definition TV interfaces (HDMI), VGA,12DVI connectors etc., that carry video signals and there is a need to13extend the API to select the video timings for these interfaces. Since14it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`15due to the limited bits available, a new set of ioctls was added to16set/get video timings at the input and output.17 18These ioctls deal with the detailed digital video timings that define19each video format. This includes parameters such as the active video20width and height, signal polarities, frontporches, backporches, sync21widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get22the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`23standards.24 25To enumerate and query the attributes of the DV timings supported by a26device applications use the27:ref:`VIDIOC_ENUM_DV_TIMINGS` and28:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set29DV timings for the device applications use the30:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get31current DV timings they use the32:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect33the DV timings as seen by the video receiver applications use the34:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.35 36When the hardware detects a video source change (e.g. the video37signal appears or disappears, or the video resolution changes), then38it will issue a `V4L2_EVENT_SOURCE_CHANGE` event. Use the39:ref:`ioctl VIDIOC_SUBSCRIBE_EVENT <VIDIOC_SUBSCRIBE_EVENT>` and the40:ref:`VIDIOC_DQEVENT` to check if this event was reported.41 42If the video signal changed, then the application has to stop43streaming, free all buffers, and call the :ref:`VIDIOC_QUERY_DV_TIMINGS`44to obtain the new video timings, and if they are valid, it can set45those by calling the :ref:`ioctl VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`.46This will also update the format, so use the :ref:`ioctl VIDIOC_G_FMT <VIDIOC_G_FMT>`47to obtain the new format. Now the application can allocate new buffers48and start streaming again.49 50The :ref:`VIDIOC_QUERY_DV_TIMINGS` will just report what the51hardware detects, it will never change the configuration. If the52currently set timings and the actually detected timings differ, then53typically this will mean that you will not be able to capture any54video. The correct approach is to rely on the `V4L2_EVENT_SOURCE_CHANGE`55event so you know when something changed.56 57Applications can make use of the :ref:`input-capabilities` and58:ref:`output-capabilities` flags to determine whether the digital59video ioctls can be used with the given input or output.60