]>
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 | |
12 | :ref:`v4l2_input <v4l2-input>` and struct | |
13 | :ref:`v4l2_output <v4l2-output>` returned by the | |
af4a4d0d MCC |
14 | :ref:`VIDIOC_ENUMINPUT <VIDIOC_ENUMINPUT>` and |
15 | :ref:`VIDIOC_ENUMOUTPUT <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 | |
af4a4d0d | 23 | standards applications use the :ref:`VIDIOC_ENUMSTD <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", | |
36 | "NTSC-M" and "SECAM-D/K". [1]_ | |
37 | ||
38 | To query and select the standard used by the current video input or | |
af4a4d0d MCC |
39 | output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and |
40 | :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The | |
5377d91f | 41 | *received* standard can be sensed with the |
af4a4d0d | 42 | :ref:`VIDIOC_QUERYSTD <VIDIOC_QUERYSTD>` ioctl. Note that the |
5377d91f MH |
43 | parameter of all these ioctls is a pointer to a |
44 | :ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an | |
45 | index into the standard enumeration. Drivers must implement all video | |
46 | standard ioctls when the device has one or more video inputs or outputs. | |
47 | ||
48 | Special rules apply to devices such as USB cameras where the notion of | |
49 | video standards makes little sense. More generally for any capture or | |
50 | output device which is: | |
51 | ||
52 | - incapable of capturing fields or frames at the nominal rate of the | |
53 | video standard, or | |
54 | ||
55 | - that does not support the video standard formats at all. | |
56 | ||
57 | Here the driver shall set the ``std`` field of struct | |
58 | :ref:`v4l2_input <v4l2-input>` and struct | |
59 | :ref:`v4l2_output <v4l2-output>` to zero and the ``VIDIOC_G_STD``, | |
60 | ``VIDIOC_S_STD``, ``VIDIOC_QUERYSTD`` and ``VIDIOC_ENUMSTD`` ioctls | |
61 | shall return the ENOTTY error code or the EINVAL error code. | |
62 | ||
63 | Applications can make use of the :ref:`input-capabilities` and | |
64 | :ref:`output-capabilities` flags to determine whether the video | |
65 | standard ioctls can be used with the given input or output. | |
66 | ||
67 | ||
68 | .. code-block:: c | |
69 | ||
70 | v4l2_std_id std_id; | |
71 | struct v4l2_standard standard; | |
72 | ||
73 | if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) { | |
74 | /* Note when VIDIOC_ENUMSTD always returns ENOTTY this | |
75 | is no video device or it falls under the USB exception, | |
76 | and VIDIOC_G_STD returning ENOTTY is no error. */ | |
77 | ||
78 | perror("VIDIOC_G_STD"); | |
79 | exit(EXIT_FAILURE); | |
80 | } | |
81 | ||
82 | memset(&standard, 0, sizeof(standard)); | |
83 | standard.index = 0; | |
84 | ||
85 | while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { | |
86 | if (standard.id & std_id) { | |
87 | printf("Current video standard: %s\\n", standard.name); | |
88 | exit(EXIT_SUCCESS); | |
89 | } | |
90 | ||
91 | standard.index++; | |
92 | } | |
93 | ||
94 | /* EINVAL indicates the end of the enumeration, which cannot be | |
95 | empty unless this device falls under the USB exception. */ | |
96 | ||
97 | if (errno == EINVAL || standard.index == 0) { | |
98 | perror("VIDIOC_ENUMSTD"); | |
99 | exit(EXIT_FAILURE); | |
100 | } | |
101 | ||
102 | ||
103 | .. code-block:: c | |
104 | ||
105 | struct v4l2_input input; | |
106 | struct v4l2_standard standard; | |
107 | ||
108 | memset(&input, 0, sizeof(input)); | |
109 | ||
110 | if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { | |
111 | perror("VIDIOC_G_INPUT"); | |
112 | exit(EXIT_FAILURE); | |
113 | } | |
114 | ||
115 | if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { | |
116 | perror("VIDIOC_ENUM_INPUT"); | |
117 | exit(EXIT_FAILURE); | |
118 | } | |
119 | ||
120 | printf("Current input %s supports:\\n", input.name); | |
121 | ||
122 | memset(&standard, 0, sizeof(standard)); | |
123 | standard.index = 0; | |
124 | ||
125 | while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) { | |
126 | if (standard.id & input.std) | |
127 | printf("%s\\n", standard.name); | |
128 | ||
129 | standard.index++; | |
130 | } | |
131 | ||
132 | /* EINVAL indicates the end of the enumeration, which cannot be | |
133 | empty unless this device falls under the USB exception. */ | |
134 | ||
135 | if (errno != EINVAL || standard.index == 0) { | |
136 | perror("VIDIOC_ENUMSTD"); | |
137 | exit(EXIT_FAILURE); | |
138 | } | |
139 | ||
140 | ||
141 | .. code-block:: c | |
142 | ||
143 | struct v4l2_input input; | |
144 | v4l2_std_id std_id; | |
145 | ||
146 | memset(&input, 0, sizeof(input)); | |
147 | ||
148 | if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) { | |
149 | perror("VIDIOC_G_INPUT"); | |
150 | exit(EXIT_FAILURE); | |
151 | } | |
152 | ||
153 | if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) { | |
154 | perror("VIDIOC_ENUM_INPUT"); | |
155 | exit(EXIT_FAILURE); | |
156 | } | |
157 | ||
158 | if (0 == (input.std & V4L2_STD_PAL_BG)) { | |
159 | fprintf(stderr, "Oops. B/G PAL is not supported.\\n"); | |
160 | exit(EXIT_FAILURE); | |
161 | } | |
162 | ||
163 | /* Note this is also supposed to work when only B | |
164 | or G/PAL is supported. */ | |
165 | ||
166 | std_id = V4L2_STD_PAL_BG; | |
167 | ||
168 | if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) { | |
169 | perror("VIDIOC_S_STD"); | |
170 | exit(EXIT_FAILURE); | |
171 | } | |
172 | ||
173 | .. [1] | |
174 | Some users are already confused by technical terms PAL, NTSC and | |
175 | SECAM. There is no point asking them to distinguish between B, G, D, | |
176 | or K when the software or hardware can do that automatically. | |
177 | ||
178 | ||
179 | .. ------------------------------------------------------------------------------ | |
180 | .. This file was automatically converted from DocBook-XML with the dbxml | |
181 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
182 | .. from the linux kernel, refer to: | |
183 | .. | |
184 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
185 | .. ------------------------------------------------------------------------------ |