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