1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/media/uapi/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _standard:
11
12***************
13Video Standards
14***************
15
16Video devices typically support one or more different video standards or
17variations of standards. Each video input and output may support another
18set of standards. This set is reported by the ``std`` field of struct
19:c:type:`v4l2_input` and struct
20:c:type:`v4l2_output` returned by the
21:ref:`VIDIOC_ENUMINPUT` and
22:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.
23
24V4L2 defines one bit for each analog video standard currently in use
25worldwide, and sets aside bits for driver defined standards, e. g.
26hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
27Applications can use the predefined bits to select a particular
28standard, although presenting the user a menu of supported standards is
29preferred. To enumerate and query the attributes of the supported
30standards applications use the :ref:`VIDIOC_ENUMSTD`
31ioctl.
32
33Many of the defined standards are actually just variations of a few
34major standards. The hardware may in fact not distinguish between them,
35or do so internal and switch automatically. Therefore enumerated
36standards also contain sets of one or more standard bits.
37
38Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
39signals. The first enumerated standard is a set of B and G/PAL, switched
40automatically depending on the selected radio frequency in UHF or VHF
41band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
42Composite input may collapse standards, enumerating "PAL-B/G/H/I",
43"NTSC-M" and "SECAM-D/K". [#f1]_
44
45To query and select the standard used by the current video input or
46output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
47:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
48*received* standard can be sensed with the
49:ref:`VIDIOC_QUERYSTD` ioctl.
50
51.. note::
52
53   The parameter of all these ioctls is a pointer to a
54   :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
55   index into the standard enumeration. Drivers must implement all video
56   standard ioctls when the device has one or more video inputs or outputs.
57
58Special rules apply to devices such as USB cameras where the notion of
59video standards makes little sense. More generally for any capture or
60output device which is:
61
62-  incapable of capturing fields or frames at the nominal rate of the
63   video standard, or
64
65-  that does not support the video standard formats at all.
66
67Here the driver shall set the ``std`` field of struct
68:c:type:`v4l2_input` and struct
69:c:type:`v4l2_output` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
70:ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
71shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
72
73Applications can make use of the :ref:`input-capabilities` and
74:ref:`output-capabilities` flags to determine whether the video
75standard ioctls can be used with the given input or output.
76
77Example: Information about the current video standard
78=====================================================
79
80.. code-block:: c
81
82    v4l2_std_id std_id;
83    struct v4l2_standard standard;
84
85    if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
86	/* Note when VIDIOC_ENUMSTD always returns ENOTTY this
87	   is no video device or it falls under the USB exception,
88	   and VIDIOC_G_STD returning ENOTTY is no error. */
89
90	perror("VIDIOC_G_STD");
91	exit(EXIT_FAILURE);
92    }
93
94    memset(&standard, 0, sizeof(standard));
95    standard.index = 0;
96
97    while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
98	if (standard.id & std_id) {
99	       printf("Current video standard: %s\\n", standard.name);
100	       exit(EXIT_SUCCESS);
101	}
102
103	standard.index++;
104    }
105
106    /* EINVAL indicates the end of the enumeration, which cannot be
107       empty unless this device falls under the USB exception. */
108
109    if (errno == EINVAL || standard.index == 0) {
110	perror("VIDIOC_ENUMSTD");
111	exit(EXIT_FAILURE);
112    }
113
114Example: Listing the video standards supported by the current input
115===================================================================
116
117.. code-block:: c
118
119    struct v4l2_input input;
120    struct v4l2_standard standard;
121
122    memset(&input, 0, sizeof(input));
123
124    if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
125	perror("VIDIOC_G_INPUT");
126	exit(EXIT_FAILURE);
127    }
128
129    if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
130	perror("VIDIOC_ENUM_INPUT");
131	exit(EXIT_FAILURE);
132    }
133
134    printf("Current input %s supports:\\n", input.name);
135
136    memset(&standard, 0, sizeof(standard));
137    standard.index = 0;
138
139    while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
140	if (standard.id & input.std)
141	    printf("%s\\n", standard.name);
142
143	standard.index++;
144    }
145
146    /* EINVAL indicates the end of the enumeration, which cannot be
147       empty unless this device falls under the USB exception. */
148
149    if (errno != EINVAL || standard.index == 0) {
150	perror("VIDIOC_ENUMSTD");
151	exit(EXIT_FAILURE);
152    }
153
154Example: Selecting a new video standard
155=======================================
156
157.. code-block:: c
158
159    struct v4l2_input input;
160    v4l2_std_id std_id;
161
162    memset(&input, 0, sizeof(input));
163
164    if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
165	perror("VIDIOC_G_INPUT");
166	exit(EXIT_FAILURE);
167    }
168
169    if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
170	perror("VIDIOC_ENUM_INPUT");
171	exit(EXIT_FAILURE);
172    }
173
174    if (0 == (input.std & V4L2_STD_PAL_BG)) {
175	fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
176	exit(EXIT_FAILURE);
177    }
178
179    /* Note this is also supposed to work when only B
180       or G/PAL is supported. */
181
182    std_id = V4L2_STD_PAL_BG;
183
184    if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
185	perror("VIDIOC_S_STD");
186	exit(EXIT_FAILURE);
187    }
188
189.. [#f1]
190   Some users are already confused by technical terms PAL, NTSC and
191   SECAM. There is no point asking them to distinguish between B, G, D,
192   or K when the software or hardware can do that automatically.
193