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