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