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