Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _hist-v4l2: | |
4 | ||
5 | *********************** | |
6 | Changes of the V4L2 API | |
7 | *********************** | |
8 | ||
9 | Soon after the V4L API was added to the kernel it was criticised as too | |
10 | inflexible. In August 1998 Bill Dirks proposed a number of improvements | |
11 | and began to work on documentation, example drivers and applications. | |
12 | With the help of other volunteers this eventually became the V4L2 API, | |
13 | not just an extension but a replacement for the V4L API. However it took | |
14 | another four years and two stable kernel releases until the new API was | |
15 | finally accepted for inclusion into the kernel in its present form. | |
16 | ||
17 | ||
18 | Early Versions | |
19 | ============== | |
20 | ||
21 | 1998-08-20: First version. | |
22 | ||
23 | 1998-08-27: The :ref:`select() <func-select>` function was introduced. | |
24 | ||
25 | 1998-09-10: New video standard interface. | |
26 | ||
27 | 1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise | |
28 | meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the | |
29 | aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set | |
30 | this flag if they intend to access controls only, as opposed to capture | |
31 | applications which need exclusive access. The ``VIDEO_STD_XXX`` | |
32 | identifiers are now ordinals instead of flags, and the | |
33 | :c:func:`video_std_construct()` helper function takes id and | |
34 | transmission arguments. | |
35 | ||
36 | 1998-09-28: Revamped video standard. Made video controls individually | |
37 | enumerable. | |
38 | ||
39 | 1998-10-02: The ``id`` field was removed from struct | |
40 | :c:type:`struct video_standard` and the color subcarrier fields were | |
7347081e MCC |
41 | renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was |
42 | renamed to :ref:`VIDIOC_ENUMSTD`, | |
4e03cb76 | 43 | :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to |
7347081e | 44 | :ref:`VIDIOC_ENUMINPUT`. A first draft of the |
5377d91f MH |
45 | Codec API was released. |
46 | ||
47 | 1998-11-08: Many minor changes. Most symbols have been renamed. Some | |
48 | material changes to struct :ref:`v4l2_capability <v4l2-capability>`. | |
49 | ||
50 | 1998-11-12: The read/write directon of some ioctls was misdefined. | |
51 | ||
52 | 1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``, | |
53 | and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio | |
54 | controls are now accessible with the | |
4e03cb76 | 55 | :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and |
af4a4d0d | 56 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting |
5377d91f MH |
57 | with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from |
58 | ``videodev.h`` since it was only used once in the ``videodev`` kernel | |
59 | module. The ``YUV422`` and ``YUV411`` planar image formats were added. | |
60 | ||
61 | 1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video | |
62 | output devices were added. | |
63 | ||
64 | 1999-01-14: A raw VBI capture interface was added. | |
65 | ||
66 | 1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed. | |
67 | ||
68 | ||
69 | V4L2 Version 0.16 1999-01-31 | |
70 | ============================ | |
71 | ||
72 | 1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF | |
73 | are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added | |
74 | digital zoom (cropping) controls. | |
75 | ||
76 | ||
77 | V4L2 Version 0.18 1999-03-16 | |
78 | ============================ | |
79 | ||
80 | Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver | |
81 | writers, this changes how you implement your ioctl handler. See the | |
82 | Driver Writer's Guide. Added some more control id codes. | |
83 | ||
84 | ||
85 | V4L2 Version 0.19 1999-06-05 | |
86 | ============================ | |
87 | ||
88 | 1999-03-18: Fill in the category and catname fields of v4l2_queryctrl | |
89 | objects before passing them to the driver. Required a minor change to | |
90 | the VIDIOC_QUERYCTRL handlers in the sample drivers. | |
91 | ||
92 | 1999-03-31: Better compatibility for v4l memory capture ioctls. Requires | |
93 | changes to drivers to fully support new compatibility features, see | |
94 | Driver Writer's Guide and v4l2cap.c. Added new control IDs: | |
95 | V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, | |
96 | and _YUV411P to _YUV411P. | |
97 | ||
98 | 1999-04-04: Added a few more control IDs. | |
99 | ||
100 | 1999-04-07: Added the button control type. | |
101 | ||
102 | 1999-05-02: Fixed a typo in videodev.h, and added the | |
103 | V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag. | |
104 | ||
105 | 1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a | |
106 | malfunction of this ioctl. | |
107 | ||
108 | 1999-06-05: Changed the value of V4L2_CID_WHITENESS. | |
109 | ||
110 | ||
111 | V4L2 Version 0.20 (1999-09-10) | |
112 | ============================== | |
113 | ||
114 | Version 0.20 introduced a number of changes which were *not backward | |
115 | compatible* with 0.19 and earlier versions. Purpose of these changes was | |
116 | to simplify the API, while making it more extensible and following | |
117 | common Linux driver API conventions. | |
118 | ||
119 | 1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct | |
120 | :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with | |
121 | v4l. (1999-08-30) | |
122 | ||
123 | 2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05) | |
124 | ||
125 | 3. All ioctl() commands that used an integer argument now take a pointer | |
126 | to an integer. Where it makes sense, ioctls will return the actual | |
127 | new value in the integer pointed to by the argument, a common | |
128 | convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW, | |
129 | VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, | |
130 | VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example | |
131 | ||
132 | ||
133 | .. code-block:: c | |
134 | ||
135 | err = ioctl (fd, VIDIOC_XXX, V4L2_XXX); | |
136 | ||
137 | becomes | |
138 | ||
139 | ||
140 | .. code-block:: c | |
141 | ||
142 | int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a); | |
143 | ||
144 | 4. All the different get- and set-format commands were swept into one | |
4e03cb76 | 145 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
af4a4d0d | 146 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a |
5377d91f MH |
147 | type field selecting the union member as parameter. Purpose is to |
148 | simplify the API by eliminating several ioctls and to allow new and | |
149 | driver private data streams without adding new ioctls. | |
150 | ||
151 | This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``, | |
152 | ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``, | |
153 | ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format | |
154 | structure :c:type:`struct v4l2_format` was renamed to struct | |
155 | :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct | |
156 | :ref:`v4l2_format <v4l2-format>` is now the envelopping structure | |
157 | for all format negotiations. | |
158 | ||
159 | 5. Similar to the changes above, the ``VIDIOC_G_PARM`` and | |
160 | ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and | |
161 | ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct | |
162 | :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective | |
163 | union member. | |
164 | ||
165 | This change obsoletes the ``VIDIOC_G_OUTPARM`` and | |
166 | ``VIDIOC_S_OUTPARM`` ioctls. | |
167 | ||
168 | 6. Control enumeration was simplified, and two new control flags were | |
169 | introduced and one dropped. The ``catname`` field was replaced by a | |
170 | ``group`` field. | |
171 | ||
172 | Drivers can now flag unsupported and temporarily unavailable controls | |
173 | with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED`` | |
174 | respectively. The ``group`` name indicates a possibly narrower | |
175 | classification than the ``category``. In other words, there may be | |
176 | multiple groups within a category. Controls within a group would | |
177 | typically be drawn within a group box. Controls in different | |
178 | categories might have a greater separation, or may even appear in | |
179 | separate windows. | |
180 | ||
181 | 7. The struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` was | |
182 | changed to a 64 bit integer, containing the sampling or output time | |
183 | of the frame in nanoseconds. Additionally timestamps will be in | |
184 | absolute system time, not starting from zero at the beginning of a | |
185 | stream. The data type name for timestamps is stamp_t, defined as a | |
186 | signed 64-bit integer. Output devices should not send a buffer out | |
187 | until the time in the timestamp field has arrived. I would like to | |
188 | follow SGI's lead, and adopt a multimedia timestamping system like | |
189 | their UST (Unadjusted System Time). See | |
08047562 | 190 | http://web.archive.org/web/\*/http://reality.sgi.com |
5377d91f MH |
191 | /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are |
192 | 64-bit signed integers (not struct timeval's) and given in nanosecond | |
193 | units. The UST clock starts at zero when the system is booted and | |
194 | runs continuously and uniformly. It takes a little over 292 years for | |
195 | UST to overflow. There is no way to set the UST clock. The regular | |
196 | Linux time-of-day clock can be changed periodically, which would | |
197 | cause errors if it were being used for timestamping a multimedia | |
198 | stream. A real UST style clock will require some support in the | |
199 | kernel that is not there yet. But in anticipation, I will change the | |
200 | timestamp field to a 64-bit integer, and I will change the | |
201 | v4l2_masterclock_gettime() function (used only by drivers) to | |
202 | return a 64-bit integer. | |
203 | ||
204 | 8. A ``sequence`` field was added to struct | |
205 | :ref:`v4l2_buffer <v4l2-buffer>`. The ``sequence`` field counts | |
206 | captured frames, it is ignored by output devices. When a capture | |
207 | driver drops a frame, the sequence number of that frame is skipped. | |
208 | ||
209 | ||
210 | V4L2 Version 0.20 incremental changes | |
211 | ===================================== | |
212 | ||
213 | 1999-12-23: In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the | |
214 | ``reserved1`` field became ``offset``. Previously drivers were required | |
215 | to clear the ``reserved1`` field. | |
216 | ||
217 | 2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added. | |
218 | ||
219 | 2000-07-31: The ``linux/poll.h`` header is now included by | |
220 | ``videodev.h`` for compatibility with the original ``videodev.h`` file. | |
221 | ||
222 | 2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were | |
223 | added. | |
224 | ||
225 | 2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added. | |
226 | ||
227 | 2000-12-04: A couple typos in symbol names were fixed. | |
228 | ||
229 | 2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in | |
230 | the ``videodev.h`` header file was renamed to ``v4l2_fourcc``. | |
231 | ||
232 | 2001-01-25: A possible driver-level compatibility problem between the | |
233 | ``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included | |
234 | in the ``videodevX`` patch was fixed. Users of an earlier version of | |
235 | ``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2 | |
236 | drivers. | |
237 | ||
238 | 2001-01-26: A possible kernel-level incompatibility between the | |
239 | ``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h`` | |
240 | file in Linux 2.2.x with devfs patches applied was fixed. | |
241 | ||
242 | 2001-03-02: Certain V4L ioctls which pass data in both direction | |
243 | although they are defined with read-only parameter, did not work | |
244 | correctly through the backward compatibility layer. [Solution?] | |
245 | ||
246 | 2001-04-13: Big endian 16-bit RGB formats were added. | |
247 | ||
248 | 2001-09-17: New YUV formats and the | |
4e03cb76 | 249 | :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and |
af4a4d0d | 250 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added. |
5377d91f MH |
251 | (The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take |
252 | multiple tuners into account.) | |
253 | ||
254 | 2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break | |
4e03cb76 | 255 | compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
af4a4d0d | 256 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct |
5377d91f MH |
257 | :c:type:`struct v4l2_fmt` ``type`` field does not contain |
258 | ``V4L2_BUF_TYPE_VBI``. In the documentation of the struct | |
259 | :ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the | |
260 | ambiguous phrase "rising edge" was changed to "leading edge". | |
261 | ||
262 | ||
263 | V4L2 Version 0.20 2000-11-23 | |
264 | ============================ | |
265 | ||
266 | A number of changes were made to the raw VBI interface. | |
267 | ||
268 | 1. Figures clarifying the line numbering scheme were added to the V4L2 | |
269 | API specification. The ``start``\ [0] and ``start``\ [1] fields no | |
270 | longer count line numbers beginning at zero. Rationale: a) The | |
271 | previous definition was unclear. b) The ``start``\ [] values are | |
272 | ordinal numbers. c) There is no point in inventing a new line | |
273 | numbering scheme. We now use line number as defined by ITU-R, period. | |
274 | Compatibility: Add one to the start values. Applications depending on | |
275 | the previous semantics may not function correctly. | |
276 | ||
277 | 2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to | |
278 | "(count[0] + count[1]) > 0". Rationale: Drivers may allocate | |
279 | resources at scan line granularity and some data services are | |
280 | transmitted only on the first field. The comment that both ``count`` | |
281 | values will usually be equal is misleading and pointless and has been | |
282 | removed. This change *breaks compatibility* with earlier versions: | |
cdb4af0f | 283 | Drivers may return ``EINVAL``, applications may not function correctly. |
5377d91f MH |
284 | |
285 | 3. Drivers are again permitted to return negative (unknown) start values | |
286 | as proposed earlier. Why this feature was dropped is unclear. This | |
287 | change may *break compatibility* with applications depending on the | |
288 | start values being positive. The use of ``EBUSY`` and ``EINVAL`` | |
af4a4d0d | 289 | error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was |
cdb4af0f | 290 | clarified. The ``EBUSY`` error code was finally documented, and the |
5377d91f MH |
291 | ``reserved2`` field which was previously mentioned only in the |
292 | ``videodev.h`` header file. | |
293 | ||
294 | 4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT`` | |
295 | were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the | |
296 | latter was missing in the ``videodev.h`` file. | |
297 | ||
298 | ||
299 | V4L2 Version 0.20 2002-07-25 | |
300 | ============================ | |
301 | ||
302 | Added sliced VBI interface proposal. | |
303 | ||
304 | ||
305 | V4L2 in Linux 2.5.46, 2002-10 | |
306 | ============================= | |
307 | ||
308 | Around October-November 2002, prior to an announced feature freeze of | |
309 | Linux 2.5, the API was revised, drawing from experience with V4L2 0.20. | |
310 | This unnamed version was finally merged into Linux 2.5.46. | |
311 | ||
312 | 1. As specified in :ref:`related`, drivers must make related device | |
313 | functions available under all minor device numbers. | |
314 | ||
315 | 2. The :ref:`open() <func-open>` function requires access mode | |
316 | ``O_RDWR`` regardless of the device type. All V4L2 drivers | |
317 | exchanging data with applications must support the ``O_NONBLOCK`` | |
318 | flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the | |
319 | meaningless ``O_TRUNC`` to indicate accesses without data exchange | |
320 | (panel applications) was dropped. Drivers must stay in "panel mode" | |
321 | until the application attempts to initiate a data exchange, see | |
322 | :ref:`open`. | |
323 | ||
324 | 3. The struct :ref:`v4l2_capability <v4l2-capability>` changed | |
325 | dramatically. Note that also the size of the structure changed, | |
326 | which is encoded in the ioctl request code, thus older V4L2 devices | |
cdb4af0f | 327 | will respond with an ``EINVAL`` error code to the new |
7347081e | 328 | :ref:`VIDIOC_QUERYCAP` ioctl. |
5377d91f MH |
329 | |
330 | There are new fields to identify the driver, a new RDS device | |
331 | function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag | |
332 | indicates if the device has any audio connectors, another I/O | |
333 | capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these | |
334 | changes the ``type`` field became a bit set and was merged into the | |
335 | ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to | |
336 | ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced | |
337 | ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and | |
338 | ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``. | |
339 | ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into | |
340 | ``V4L2_CAP_READWRITE``. | |
341 | ||
342 | The redundant fields ``inputs``, ``outputs`` and ``audios`` were | |
343 | removed. These properties can be determined as described in | |
344 | :ref:`video` and :ref:`audio`. | |
345 | ||
346 | The somewhat volatile and therefore barely useful fields | |
347 | ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``, | |
348 | ``maxframerate`` were removed. This information is available as | |
349 | described in :ref:`format` and :ref:`standard`. | |
350 | ||
351 | ``V4L2_FLAG_SELECT`` was removed. We believe the select() function | |
352 | is important enough to require support of it in all V4L2 drivers | |
353 | exchanging data with applications. The redundant | |
354 | ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is | |
355 | available as described in :ref:`format`. | |
356 | ||
357 | 4. In struct :ref:`v4l2_input <v4l2-input>` the ``assoc_audio`` | |
358 | field and the ``capability`` field and its only flag | |
359 | ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field. | |
360 | Instead of linking one video input to one audio input this field | |
361 | reports all audio inputs this video input combines with. | |
362 | ||
363 | New fields are ``tuner`` (reversing the former link from tuners to | |
364 | video inputs), ``std`` and ``status``. | |
365 | ||
366 | Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its | |
367 | ``capability`` and ``assoc_audio`` fields. ``audioset``, | |
368 | ``modulator`` and ``std`` where added instead. | |
369 | ||
370 | 5. The struct :ref:`v4l2_audio <v4l2-audio>` field ``audio`` was | |
371 | renamed to ``index``, for consistency with other structures. A new | |
372 | capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the | |
373 | audio input in question supports stereo sound. | |
374 | ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags | |
375 | where removed. This can be easily implemented using controls. | |
376 | (However the same applies to AVL which is still there.) | |
377 | ||
378 | Again for consistency the struct | |
379 | :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed | |
380 | to ``index``. | |
381 | ||
382 | 6. The struct :ref:`v4l2_tuner <v4l2-tuner>` ``input`` field was | |
383 | replaced by an ``index`` field, permitting devices with multiple | |
384 | tuners. The link between video inputs and tuners is now reversed, | |
385 | inputs point to their tuner. The ``std`` substructure became a | |
386 | simple set (more about this below) and moved into struct | |
387 | :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added. | |
388 | ||
389 | Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the | |
390 | ``output`` was replaced by an ``index`` field. | |
391 | ||
392 | In struct :ref:`v4l2_frequency <v4l2-frequency>` the ``port`` | |
393 | field was replaced by a ``tuner`` field containing the respective | |
394 | tuner or modulator index number. A tuner ``type`` field was added | |
395 | and the ``reserved`` field became larger for future extensions | |
396 | (satellite tuners in particular). | |
397 | ||
398 | 7. The idea of completely transparent video standards was dropped. | |
399 | Experience showed that applications must be able to work with video | |
400 | standards beyond presenting the user a menu. Instead of enumerating | |
401 | supported standards with an ioctl applications can now refer to | |
402 | standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols | |
403 | defined in the ``videodev2.h`` header file. For details see | |
4e03cb76 | 404 | :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and |
af4a4d0d | 405 | :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this |
7347081e | 406 | type as argument. :ref:`VIDIOC_QUERYSTD` was |
5377d91f MH |
407 | added to autodetect the received standard, if the hardware has this |
408 | capability. In struct :ref:`v4l2_standard <v4l2-standard>` an | |
409 | ``index`` field was added for | |
7347081e | 410 | :ref:`VIDIOC_ENUMSTD`. A |
5377d91f MH |
411 | :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as |
412 | machine readable identifier, also replacing the ``transmission`` | |
413 | field. The misleading ``framerate`` field was renamed to | |
414 | ``frameperiod``. The now obsolete ``colorstandard`` information, | |
415 | originally needed to distguish between variations of standards, were | |
416 | removed. | |
417 | ||
418 | Struct :c:type:`struct v4l2_enumstd` ceased to be. | |
7347081e | 419 | :ref:`VIDIOC_ENUMSTD` now takes a pointer to a |
5377d91f MH |
420 | struct :ref:`v4l2_standard <v4l2-standard>` directly. The |
421 | information which standards are supported by a particular video | |
422 | input or output moved into struct :ref:`v4l2_input <v4l2-input>` | |
423 | and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``, | |
424 | respectively. | |
425 | ||
426 | 8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields | |
427 | ``category`` and ``group`` did not catch on and/or were not | |
428 | implemented as expected and therefore removed. | |
429 | ||
af4a4d0d | 430 | 9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to |
5377d91f | 431 | negotiate data formats as with |
af4a4d0d | 432 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of |
5377d91f MH |
433 | programming the hardware and regardless of I/O in progress. |
434 | ||
435 | In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was | |
436 | extended to contain struct :ref:`v4l2_window <v4l2-window>`. All | |
437 | image format negotiations are now possible with ``VIDIOC_G_FMT``, | |
438 | ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN`` | |
439 | and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were | |
440 | removed. The ``type`` field changed to type enum | |
441 | :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names | |
442 | changed as follows. | |
443 | ||
444 | ||
445 | ||
446 | .. flat-table:: | |
0579e6e3 MCC |
447 | :header-rows: 1 |
448 | :stub-columns: 0 | |
5377d91f MH |
449 | |
450 | ||
0579e6e3 | 451 | - .. row 1 |
5377d91f | 452 | |
0579e6e3 | 453 | - Old defines |
5377d91f | 454 | |
0579e6e3 | 455 | - enum :ref:`v4l2_buf_type <v4l2-buf-type>` |
5377d91f | 456 | |
0579e6e3 | 457 | - .. row 2 |
5377d91f | 458 | |
0579e6e3 | 459 | - ``V4L2_BUF_TYPE_CAPTURE`` |
5377d91f | 460 | |
0579e6e3 | 461 | - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` |
5377d91f | 462 | |
0579e6e3 | 463 | - .. row 3 |
5377d91f | 464 | |
0579e6e3 | 465 | - ``V4L2_BUF_TYPE_CODECIN`` |
5377d91f | 466 | |
0579e6e3 | 467 | - Omitted for now |
5377d91f | 468 | |
0579e6e3 | 469 | - .. row 4 |
5377d91f | 470 | |
0579e6e3 | 471 | - ``V4L2_BUF_TYPE_CODECOUT`` |
5377d91f | 472 | |
0579e6e3 | 473 | - Omitted for now |
5377d91f | 474 | |
0579e6e3 | 475 | - .. row 5 |
5377d91f | 476 | |
0579e6e3 | 477 | - ``V4L2_BUF_TYPE_EFFECTSIN`` |
5377d91f | 478 | |
0579e6e3 | 479 | - Omitted for now |
5377d91f | 480 | |
0579e6e3 | 481 | - .. row 6 |
5377d91f | 482 | |
0579e6e3 | 483 | - ``V4L2_BUF_TYPE_EFFECTSIN2`` |
5377d91f | 484 | |
0579e6e3 | 485 | - Omitted for now |
5377d91f | 486 | |
0579e6e3 | 487 | - .. row 7 |
5377d91f | 488 | |
0579e6e3 | 489 | - ``V4L2_BUF_TYPE_EFFECTSOUT`` |
5377d91f | 490 | |
0579e6e3 | 491 | - Omitted for now |
5377d91f | 492 | |
0579e6e3 | 493 | - .. row 8 |
5377d91f | 494 | |
0579e6e3 | 495 | - ``V4L2_BUF_TYPE_VIDEOOUT`` |
5377d91f | 496 | |
0579e6e3 | 497 | - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` |
5377d91f | 498 | |
0579e6e3 | 499 | - .. row 9 |
5377d91f | 500 | |
0579e6e3 | 501 | - ``-`` |
5377d91f | 502 | |
0579e6e3 | 503 | - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` |
5377d91f | 504 | |
0579e6e3 | 505 | - .. row 10 |
5377d91f | 506 | |
0579e6e3 | 507 | - ``-`` |
5377d91f | 508 | |
0579e6e3 | 509 | - ``V4L2_BUF_TYPE_VBI_CAPTURE`` |
5377d91f | 510 | |
0579e6e3 | 511 | - .. row 11 |
5377d91f | 512 | |
0579e6e3 | 513 | - ``-`` |
5377d91f | 514 | |
0579e6e3 | 515 | - ``V4L2_BUF_TYPE_VBI_OUTPUT`` |
5377d91f | 516 | |
0579e6e3 | 517 | - .. row 12 |
5377d91f | 518 | |
0579e6e3 | 519 | - ``-`` |
5377d91f | 520 | |
0579e6e3 | 521 | - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` |
5377d91f | 522 | |
0579e6e3 | 523 | - .. row 13 |
5377d91f | 524 | |
0579e6e3 | 525 | - ``-`` |
5377d91f | 526 | |
0579e6e3 | 527 | - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` |
5377d91f | 528 | |
0579e6e3 | 529 | - .. row 14 |
5377d91f | 530 | |
0579e6e3 | 531 | - ``V4L2_BUF_TYPE_PRIVATE_BASE`` |
5377d91f | 532 | |
0579e6e3 | 533 | - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated) |
5377d91f MH |
534 | |
535 | ||
536 | 10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum | |
537 | :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was | |
538 | added as in struct :ref:`v4l2_format <v4l2-format>`. The | |
539 | ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed. | |
540 | These calls can be replaced by | |
7347081e | 541 | :ref:`VIDIOC_ENUM_FMT` with type |
5377d91f MH |
542 | ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. |
543 | ||
544 | 11. In struct :ref:`v4l2_pix_format <v4l2-pix-format>` the ``depth`` | |
545 | field was removed, assuming applications which recognize the format | |
546 | by its four-character-code already know the color depth, and others | |
547 | do not care about it. The same rationale lead to the removal of the | |
548 | ``V4L2_FMT_FLAG_COMPRESSED`` flag. The | |
549 | ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers | |
550 | are not supposed to convert images in kernel space. A user library | |
551 | of conversion functions should be provided instead. The | |
552 | ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can | |
553 | set the ``bytesperline`` field to zero to get a reasonable default. | |
554 | Since the remaining flags were replaced as well, the ``flags`` field | |
555 | itself was removed. | |
556 | ||
557 | The interlace flags were replaced by a enum | |
558 | :ref:`v4l2_field <v4l2-field>` value in a newly added ``field`` | |
559 | field. | |
560 | ||
561 | ||
562 | ||
563 | .. flat-table:: | |
0579e6e3 MCC |
564 | :header-rows: 1 |
565 | :stub-columns: 0 | |
5377d91f MH |
566 | |
567 | ||
0579e6e3 | 568 | - .. row 1 |
5377d91f | 569 | |
0579e6e3 | 570 | - Old flag |
5377d91f | 571 | |
0579e6e3 | 572 | - enum :ref:`v4l2_field <v4l2-field>` |
5377d91f | 573 | |
0579e6e3 | 574 | - .. row 2 |
5377d91f | 575 | |
0579e6e3 | 576 | - ``V4L2_FMT_FLAG_NOT_INTERLACED`` |
5377d91f | 577 | |
0579e6e3 | 578 | - ? |
5377d91f | 579 | |
0579e6e3 | 580 | - .. row 3 |
5377d91f | 581 | |
0579e6e3 | 582 | - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED`` |
5377d91f | 583 | |
0579e6e3 | 584 | - ``V4L2_FIELD_INTERLACED`` |
5377d91f | 585 | |
0579e6e3 | 586 | - .. row 4 |
5377d91f | 587 | |
0579e6e3 | 588 | - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD`` |
5377d91f | 589 | |
0579e6e3 | 590 | - ``V4L2_FIELD_TOP`` |
5377d91f | 591 | |
0579e6e3 | 592 | - .. row 5 |
5377d91f | 593 | |
0579e6e3 | 594 | - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD`` |
5377d91f | 595 | |
0579e6e3 | 596 | - ``V4L2_FIELD_BOTTOM`` |
5377d91f | 597 | |
0579e6e3 | 598 | - .. row 6 |
5377d91f | 599 | |
0579e6e3 | 600 | - ``-`` |
5377d91f | 601 | |
0579e6e3 | 602 | - ``V4L2_FIELD_SEQ_TB`` |
5377d91f | 603 | |
0579e6e3 | 604 | - .. row 7 |
5377d91f | 605 | |
0579e6e3 | 606 | - ``-`` |
5377d91f | 607 | |
0579e6e3 | 608 | - ``V4L2_FIELD_SEQ_BT`` |
5377d91f | 609 | |
0579e6e3 | 610 | - .. row 8 |
5377d91f | 611 | |
0579e6e3 | 612 | - ``-`` |
5377d91f | 613 | |
0579e6e3 | 614 | - ``V4L2_FIELD_ALTERNATE`` |
5377d91f MH |
615 | |
616 | ||
617 | The color space flags were replaced by a enum | |
618 | :ref:`v4l2_colorspace <v4l2-colorspace>` value in a newly added | |
619 | ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``, | |
620 | ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or | |
621 | ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``. | |
622 | ||
623 | 12. In struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the | |
624 | ``type`` field was properly defined as enum | |
625 | :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as | |
626 | mentioned above. A new ``memory`` field of type enum | |
627 | :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between | |
628 | I/O methods using buffers allocated by the driver or the | |
629 | application. See :ref:`io` for details. | |
630 | ||
631 | 13. In struct :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was | |
632 | properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`. | |
633 | Buffer types changed as mentioned above. A ``field`` field of type | |
634 | enum :ref:`v4l2_field <v4l2-field>` was added to indicate if a | |
635 | buffer contains a top or bottom field. The old field flags were | |
636 | removed. Since no unadjusted system time clock was added to the | |
637 | kernel as planned, the ``timestamp`` field changed back from type | |
638 | stamp_t, an unsigned 64 bit integer expressing the sample time in | |
639 | nanoseconds, to struct :c:type:`struct timeval`. With the addition | |
640 | of a second memory mapping method the ``offset`` field moved into | |
641 | union ``m``, and a new ``memory`` field of type enum | |
642 | :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between | |
643 | I/O methods. See :ref:`io` for details. | |
644 | ||
645 | The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility | |
646 | layer, after changes to this code it was no longer needed. The | |
647 | ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was | |
648 | indeed allocated in device memory rather than DMA-able system | |
649 | memory. It was barely useful and so was removed. | |
650 | ||
651 | 14. In struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` the | |
652 | ``base[3]`` array anticipating double- and triple-buffering in | |
653 | off-screen video memory, however without defining a synchronization | |
654 | mechanism, was replaced by a single pointer. The | |
655 | ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were | |
656 | removed. Applications can determine this capability more accurately | |
657 | using the new cropping and scaling interface. The | |
658 | ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by | |
659 | ``V4L2_FBUF_CAP_LIST_CLIPPING`` and | |
660 | ``V4L2_FBUF_CAP_BITMAP_CLIPPING``. | |
661 | ||
662 | 15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``, | |
663 | ``width`` and ``height`` field moved into a ``c`` substructure of | |
664 | type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y`` | |
665 | fields were renamed to ``left`` and ``top``, i. e. offsets to a | |
666 | context dependent origin. | |
667 | ||
668 | 16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``, | |
669 | ``width`` and ``height`` field moved into a ``w`` substructure as | |
670 | above. A ``field`` field of type %v4l2-field; was added to | |
671 | distinguish between field and frame (interlaced) overlay. | |
672 | ||
673 | 17. The digital zoom interface, including struct | |
674 | :c:type:`struct v4l2_zoomcap`, struct | |
675 | :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and | |
676 | ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and | |
677 | scaling interface. The previously unused struct | |
678 | :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop` | |
679 | where redefined for this purpose. See :ref:`crop` for details. | |
680 | ||
681 | 18. In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the | |
682 | ``SAMPLE_FORMAT`` field now contains a four-character-code as used | |
683 | to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces | |
684 | the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was | |
685 | extended. | |
686 | ||
687 | 19. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` the type of | |
688 | the ``timeperframe`` field changed from unsigned long to struct | |
689 | :ref:`v4l2_fract <v4l2-fract>`. This allows the accurate | |
690 | expression of multiples of the NTSC-M frame rate 30000 / 1001. A new | |
691 | field ``readbuffers`` was added to control the driver behaviour in | |
692 | read I/O mode. | |
693 | ||
694 | Similar changes were made to struct | |
695 | :ref:`v4l2_outputparm <v4l2-outputparm>`. | |
696 | ||
697 | 20. The struct :c:type:`struct v4l2_performance` and | |
698 | ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the | |
699 | :ref:`read/write I/O method <rw>`, which is limited anyway, this | |
700 | information is already available to applications. | |
701 | ||
702 | 21. The example transformation from RGB to YCbCr color space in the old | |
703 | V4L2 documentation was inaccurate, this has been corrected in | |
704 | :ref:`pixfmt`. | |
705 | ||
706 | ||
707 | V4L2 2003-06-19 | |
708 | =============== | |
709 | ||
710 | 1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices. | |
711 | Prior to this change radio devices would identify solely by having | |
712 | exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``. | |
713 | ||
714 | 2. An optional driver access priority mechanism was added, see | |
715 | :ref:`app-pri` for details. | |
716 | ||
717 | 3. The audio input and output interface was found to be incomplete. | |
718 | ||
4e03cb76 | 719 | Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would |
5377d91f MH |
720 | enumerate the available audio inputs. An ioctl to determine the |
721 | current audio input, if more than one combines with the current video | |
722 | input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to | |
723 | ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The | |
7347081e | 724 | :ref:`VIDIOC_ENUMAUDIO` ioctl was added to |
5377d91f | 725 | enumerate audio inputs, while |
4e03cb76 | 726 | :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current |
5377d91f MH |
727 | audio input. |
728 | ||
729 | The same changes were made to | |
9f97b306 MCC |
730 | :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and |
731 | :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`. | |
5377d91f MH |
732 | |
733 | Until further the "videodev" module will automatically translate | |
734 | between the old and new ioctls, but drivers and applications must be | |
735 | updated to successfully compile again. | |
736 | ||
7347081e | 737 | 4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly |
5377d91f MH |
738 | defined with write-read parameter. It was changed to write-only, |
739 | while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``. | |
740 | The old ioctl was removed on Kernel 2.6.39. Until further the | |
741 | "videodev" kernel module will automatically translate to the new | |
742 | version, so drivers must be recompiled, but not applications. | |
743 | ||
744 | 5. :ref:`overlay` incorrectly stated that clipping rectangles define | |
745 | regions where the video can be seen. Correct is that clipping | |
746 | rectangles define regions where *no* video shall be displayed and so | |
747 | the graphics surface can be seen. | |
748 | ||
af4a4d0d MCC |
749 | 6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and |
750 | :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with | |
5377d91f MH |
751 | write-only parameter, inconsistent with other ioctls modifying their |
752 | argument. They were changed to write-read, while a ``_OLD`` suffix | |
753 | was added to the write-only versions. The old ioctls were removed on | |
754 | Kernel 2.6.39. Drivers and applications assuming a constant parameter | |
755 | need an update. | |
756 | ||
757 | ||
758 | V4L2 2003-11-05 | |
759 | =============== | |
760 | ||
761 | 1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly | |
762 | transferred from Bill Dirks' V4L2 specification. Descriptions below | |
763 | refer to bytes in memory, in ascending address order. | |
764 | ||
765 | ||
766 | ||
767 | .. flat-table:: | |
768 | :header-rows: 1 | |
769 | :stub-columns: 0 | |
770 | ||
771 | ||
772 | - .. row 1 | |
773 | ||
0579e6e3 | 774 | - Symbol |
5377d91f | 775 | |
0579e6e3 | 776 | - In this document prior to revision 0.5 |
5377d91f | 777 | |
0579e6e3 | 778 | - Corrected |
5377d91f MH |
779 | |
780 | - .. row 2 | |
781 | ||
0579e6e3 | 782 | - ``V4L2_PIX_FMT_RGB24`` |
5377d91f | 783 | |
0579e6e3 | 784 | - B, G, R |
5377d91f | 785 | |
0579e6e3 | 786 | - R, G, B |
5377d91f MH |
787 | |
788 | - .. row 3 | |
789 | ||
0579e6e3 | 790 | - ``V4L2_PIX_FMT_BGR24`` |
5377d91f | 791 | |
0579e6e3 | 792 | - R, G, B |
5377d91f | 793 | |
0579e6e3 | 794 | - B, G, R |
5377d91f MH |
795 | |
796 | - .. row 4 | |
797 | ||
0579e6e3 | 798 | - ``V4L2_PIX_FMT_RGB32`` |
5377d91f | 799 | |
0579e6e3 | 800 | - B, G, R, X |
5377d91f | 801 | |
0579e6e3 | 802 | - R, G, B, X |
5377d91f MH |
803 | |
804 | - .. row 5 | |
805 | ||
0579e6e3 | 806 | - ``V4L2_PIX_FMT_BGR32`` |
5377d91f | 807 | |
0579e6e3 | 808 | - R, G, B, X |
5377d91f | 809 | |
0579e6e3 | 810 | - B, G, R, X |
5377d91f MH |
811 | |
812 | ||
813 | The ``V4L2_PIX_FMT_BGR24`` example was always correct. | |
814 | ||
815 | In :ref:`v4l-image-properties` the mapping of the V4L | |
816 | ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2 | |
817 | pixel formats was accordingly corrected. | |
818 | ||
819 | 2. Unrelated to the fixes above, drivers may still interpret some V4L2 | |
820 | RGB pixel formats differently. These issues have yet to be addressed, | |
821 | for details see :ref:`pixfmt-rgb`. | |
822 | ||
823 | ||
824 | V4L2 in Linux 2.6.6, 2004-05-09 | |
825 | =============================== | |
826 | ||
7347081e | 827 | 1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly |
5377d91f MH |
828 | defined with read-only parameter. It is now defined as write-read |
829 | ioctl, while the read-only version was renamed to | |
830 | ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39. | |
831 | ||
832 | ||
833 | V4L2 in Linux 2.6.8 | |
834 | =================== | |
835 | ||
836 | 1. A new field ``input`` (former ``reserved[0]``) was added to the | |
837 | struct :ref:`v4l2_buffer <v4l2-buffer>` structure. Purpose of this | |
838 | field is to alternate between video inputs (e. g. cameras) in step | |
839 | with the video capturing process. This function must be enabled with | |
840 | the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no | |
841 | longer read-only. | |
842 | ||
843 | ||
844 | V4L2 spec erratum 2004-08-01 | |
845 | ============================ | |
846 | ||
847 | 1. The return value of the :ref:`func-open` function was incorrectly | |
848 | documented. | |
849 | ||
850 | 2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT. | |
851 | ||
852 | 3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took | |
853 | the wrong argument. | |
854 | ||
7347081e | 855 | 4. The documentation of the :ref:`VIDIOC_QBUF` and |
af4a4d0d | 856 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the |
5377d91f | 857 | struct :ref:`v4l2_buffer <v4l2-buffer>` ``memory`` field. It was |
cdb4af0f | 858 | also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO`` |
5377d91f MH |
859 | error code was not documented. |
860 | ||
861 | ||
862 | V4L2 in Linux 2.6.14 | |
863 | ==================== | |
864 | ||
865 | 1. A new sliced VBI interface was added. It is documented in | |
866 | :ref:`sliced` and replaces the interface first proposed in V4L2 | |
867 | specification 0.8. | |
868 | ||
869 | ||
870 | V4L2 in Linux 2.6.15 | |
871 | ==================== | |
872 | ||
7347081e | 873 | 1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added. |
5377d91f MH |
874 | |
875 | 2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``, | |
876 | ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and | |
877 | ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and | |
878 | ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60`` | |
879 | set now includes ``V4L2_STD_NTSC_443``. See also | |
880 | :ref:`v4l2-std-id`. | |
881 | ||
882 | 3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to | |
883 | ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their | |
884 | argument was replaced by a struct | |
885 | :c:type:`struct v4l2_mpeg_compression` pointer. (The | |
886 | ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed | |
887 | in Linux 2.6.25.) | |
888 | ||
889 | ||
890 | V4L2 spec erratum 2005-11-27 | |
891 | ============================ | |
892 | ||
893 | The capture example in :ref:`capture-example` called the | |
af4a4d0d | 894 | :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if |
5377d91f | 895 | cropping is supported. In the video standard selection example in |
af4a4d0d | 896 | :ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used |
5377d91f MH |
897 | the wrong argument type. |
898 | ||
899 | ||
900 | V4L2 spec erratum 2006-01-10 | |
901 | ============================ | |
902 | ||
903 | 1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct | |
904 | :ref:`v4l2_input <v4l2-input>` not only indicates if the color | |
905 | killer is enabled, but also if it is active. (The color killer | |
906 | disables color decoding when it detects no color in the video signal | |
907 | to improve the image quality.) | |
908 | ||
af4a4d0d | 909 | 2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not |
5377d91f MH |
910 | write-only as stated on its reference page. The ioctl changed in 2003 |
911 | as noted above. | |
912 | ||
913 | ||
914 | V4L2 spec erratum 2006-02-03 | |
915 | ============================ | |
916 | ||
917 | 1. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` and struct | |
918 | :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe`` | |
919 | field gives the time in seconds, not microseconds. | |
920 | ||
921 | ||
922 | V4L2 spec erratum 2006-02-04 | |
923 | ============================ | |
924 | ||
925 | 1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>` | |
926 | must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not | |
927 | a linked list, because drivers ignore the struct | |
928 | :c:type:`struct v4l2_clip`. ``next`` pointer. | |
929 | ||
930 | ||
931 | V4L2 in Linux 2.6.17 | |
932 | ==================== | |
933 | ||
934 | 1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M | |
935 | South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``, | |
936 | ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and | |
937 | ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and | |
938 | ``V4L2_STD_SECAM_LC`` respectively. | |
939 | ||
940 | 2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both | |
941 | languages of a bilingual program. The use of | |
942 | ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See | |
4e03cb76 | 943 | the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details. |
5377d91f MH |
944 | |
945 | ||
946 | V4L2 spec erratum 2006-09-23 (Draft 0.15) | |
947 | ========================================= | |
948 | ||
949 | 1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and | |
950 | ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were | |
951 | not mentioned along with other buffer types. | |
952 | ||
4e03cb76 | 953 | 2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct |
5377d91f MH |
954 | :ref:`v4l2_audio <v4l2-audio>` ``mode`` field is a flags field. |
955 | ||
af4a4d0d | 956 | 3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio |
5377d91f MH |
957 | capability flags. |
958 | ||
4e03cb76 | 959 | 4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications |
5377d91f MH |
960 | must initialize the tuner ``type`` field of struct |
961 | :ref:`v4l2_frequency <v4l2-frequency>` before calling | |
af4a4d0d | 962 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. |
5377d91f MH |
963 | |
964 | 5. The ``reserved`` array in struct | |
965 | :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements, | |
966 | not 32. | |
967 | ||
968 | 6. In :ref:`output` and :ref:`raw-vbi` the device file names | |
969 | ``/dev/vout`` which never caught on were replaced by ``/dev/video``. | |
970 | ||
971 | 7. With Linux 2.6.15 the possible range for VBI device minor numbers was | |
972 | extended from 224-239 to 224-255. Accordingly device file names | |
973 | ``/dev/vbi0`` to ``/dev/vbi31`` are possible now. | |
974 | ||
975 | ||
976 | V4L2 in Linux 2.6.18 | |
977 | ==================== | |
978 | ||
4e03cb76 | 979 | 1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, |
af4a4d0d MCC |
980 | :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and |
981 | :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a | |
5377d91f | 982 | flag to skip unsupported controls with |
7347081e | 983 | :ref:`VIDIOC_QUERYCTRL`, new control types |
5377d91f MH |
984 | ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS`` |
985 | (:ref:`v4l2-ctrl-type`), and new control flags | |
986 | ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``, | |
987 | ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER`` | |
988 | (:ref:`control-flags`). See :ref:`extended-controls` for details. | |
989 | ||
990 | ||
991 | V4L2 in Linux 2.6.19 | |
992 | ==================== | |
993 | ||
994 | 1. In struct :ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>` a | |
995 | buffer type field was added replacing a reserved field. Note on | |
996 | architectures where the size of enum types differs from int types the | |
997 | size of the structure changed. The | |
4e03cb76 | 998 | :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl |
5377d91f MH |
999 | was redefined from being read-only to write-read. Applications must |
1000 | initialize the type field and clear the reserved fields now. These | |
1001 | changes may *break the compatibility* with older drivers and | |
1002 | applications. | |
1003 | ||
7347081e | 1004 | 2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES` |
5377d91f | 1005 | and |
7347081e | 1006 | :ref:`VIDIOC_ENUM_FRAMEINTERVALS` |
5377d91f MH |
1007 | were added. |
1008 | ||
1009 | 3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was | |
1010 | added. | |
1011 | ||
1012 | ||
1013 | V4L2 spec erratum 2006-10-12 (Draft 0.17) | |
1014 | ========================================= | |
1015 | ||
1016 | 1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not | |
1017 | 4:2:2 format. | |
1018 | ||
1019 | ||
1020 | V4L2 in Linux 2.6.21 | |
1021 | ==================== | |
1022 | ||
1023 | 1. The ``videodev2.h`` header file is now dual licensed under GNU | |
1024 | General Public License version two or later, and under a 3-clause | |
1025 | BSD-style license. | |
1026 | ||
1027 | ||
1028 | V4L2 in Linux 2.6.22 | |
1029 | ==================== | |
1030 | ||
1031 | 1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and | |
1032 | ``V4L2_FIELD_INTERLACED_BT`` were added. See :ref:`v4l2-field` for | |
1033 | details. | |
1034 | ||
1035 | 2. Three new clipping/blending methods with a global or straight or | |
1036 | inverted local alpha value were added to the video overlay interface. | |
4e03cb76 | 1037 | See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` |
af4a4d0d | 1038 | and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details. |
5377d91f MH |
1039 | |
1040 | A new ``global_alpha`` field was added to | |
1041 | :ref:`v4l2_window <v4l2-window>`, extending the structure. This | |
1042 | may *break compatibility* with applications using a struct | |
1043 | :c:type:`struct v4l2_window` directly. However the | |
af4a4d0d | 1044 | :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a |
5377d91f MH |
1045 | pointer to a :ref:`v4l2_format <v4l2-format>` parent structure |
1046 | with padding bytes at the end, are not affected. | |
1047 | ||
1048 | 3. The format of the ``chromakey`` field in struct | |
1049 | :ref:`v4l2_window <v4l2-window>` changed from "host order RGB32" | |
1050 | to a pixel value in the same format as the framebuffer. This may | |
1051 | *break compatibility* with existing applications. Drivers supporting | |
1052 | the "host order RGB32" format are not known. | |
1053 | ||
1054 | ||
1055 | V4L2 in Linux 2.6.24 | |
1056 | ==================== | |
1057 | ||
1058 | 1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``, | |
1059 | ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and | |
1060 | ``V4L2_PIX_FMT_YUV32`` were added. | |
1061 | ||
1062 | ||
1063 | V4L2 in Linux 2.6.25 | |
1064 | ==================== | |
1065 | ||
1066 | 1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and | |
1067 | :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added. | |
1068 | ||
1069 | 2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``, | |
1070 | ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``, | |
1071 | ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were | |
1072 | added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``, | |
1073 | ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated. | |
1074 | ||
1075 | 3. A :ref:`Camera controls class <camera-controls>` was added, with | |
1076 | the new controls ``V4L2_CID_EXPOSURE_AUTO``, | |
1077 | ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``, | |
1078 | ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``, | |
1079 | ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``, | |
1080 | ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``, | |
1081 | ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and | |
1082 | ``V4L2_CID_FOCUS_AUTO``. | |
1083 | ||
1084 | 4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which | |
1085 | were superseded by the :ref:`extended controls <extended-controls>` | |
1086 | interface in Linux 2.6.18, where finally removed from the | |
1087 | ``videodev2.h`` header file. | |
1088 | ||
1089 | ||
1090 | V4L2 in Linux 2.6.26 | |
1091 | ==================== | |
1092 | ||
1093 | 1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16`` | |
1094 | were added. | |
1095 | ||
1096 | 2. Added user controls ``V4L2_CID_CHROMA_AGC`` and | |
1097 | ``V4L2_CID_COLOR_KILLER``. | |
1098 | ||
1099 | ||
1100 | V4L2 in Linux 2.6.27 | |
1101 | ==================== | |
1102 | ||
7347081e | 1103 | 1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl |
5377d91f MH |
1104 | and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added. |
1105 | ||
1106 | 2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``, | |
1107 | ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``, | |
1108 | ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``, | |
1109 | ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added. | |
1110 | ||
1111 | ||
1112 | V4L2 in Linux 2.6.28 | |
1113 | ==================== | |
1114 | ||
1115 | 1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and | |
1116 | ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings. | |
1117 | ||
1118 | 2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding. | |
1119 | ||
1120 | 3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and | |
1121 | ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added. | |
1122 | ||
1123 | ||
1124 | V4L2 in Linux 2.6.29 | |
1125 | ==================== | |
1126 | ||
1127 | 1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to | |
1128 | ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was | |
1129 | introduced in its place. The old struct | |
1130 | :c:type:`struct v4l2_chip_ident` was renamed to | |
1131 | :c:type:`struct v4l2_chip_ident_old`. | |
1132 | ||
1133 | 2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and | |
1134 | ``V4L2_PIX_FMT_NV61`` were added. | |
1135 | ||
1136 | 3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``, | |
1137 | ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and | |
1138 | ``V4L2_CID_PRIVACY``. | |
1139 | ||
1140 | ||
1141 | V4L2 in Linux 2.6.30 | |
1142 | ==================== | |
1143 | ||
1144 | 1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added. | |
1145 | ||
1146 | 2. New control ``V4L2_CID_COLORFX`` was added. | |
1147 | ||
1148 | ||
1149 | V4L2 in Linux 2.6.32 | |
1150 | ==================== | |
1151 | ||
1152 | 1. In order to be easier to compare a V4L2 API and a kernel version, now | |
1153 | V4L2 API is numbered using the Linux Kernel version numeration. | |
1154 | ||
1155 | 2. Finalized the RDS capture API. See :ref:`rds` for more information. | |
1156 | ||
1157 | 3. Added new capabilities for modulators and RDS encoders. | |
1158 | ||
1159 | 4. Add description for libv4l API. | |
1160 | ||
1161 | 5. Added support for string controls via new type | |
1162 | ``V4L2_CTRL_TYPE_STRING``. | |
1163 | ||
1164 | 6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation. | |
1165 | ||
1166 | 7. Added FM Modulator (FM TX) Extended Control Class: | |
1167 | ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs. | |
1168 | ||
1169 | 8. Added FM Receiver (FM RX) Extended Control Class: | |
1170 | ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs. | |
1171 | ||
1172 | 9. Added Remote Controller chapter, describing the default Remote | |
1173 | Controller mapping for media devices. | |
1174 | ||
1175 | ||
1176 | V4L2 in Linux 2.6.33 | |
1177 | ==================== | |
1178 | ||
1179 | 1. Added support for Digital Video timings in order to support HDTV | |
1180 | receivers and transmitters. | |
1181 | ||
1182 | ||
1183 | V4L2 in Linux 2.6.34 | |
1184 | ==================== | |
1185 | ||
1186 | 1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE`` | |
1187 | controls to the :ref:`Camera controls class <camera-controls>`. | |
1188 | ||
1189 | ||
1190 | V4L2 in Linux 2.6.37 | |
1191 | ==================== | |
1192 | ||
1193 | 1. Remove the vtx (videotext/teletext) API. This API was no longer used | |
1194 | and no hardware exists to verify the API. Nor were any userspace | |
1195 | applications found that used it. It was originally scheduled for | |
1196 | removal in 2.6.35. | |
1197 | ||
1198 | ||
1199 | V4L2 in Linux 2.6.39 | |
1200 | ==================== | |
1201 | ||
1202 | 1. The old VIDIOC_*_OLD symbols and V4L1 support were removed. | |
1203 | ||
1204 | 2. Multi-planar API added. Does not affect the compatibility of current | |
1205 | drivers and applications. See :ref:`multi-planar API <planar-apis>` | |
1206 | for details. | |
1207 | ||
1208 | ||
1209 | V4L2 in Linux 3.1 | |
1210 | ================= | |
1211 | ||
1212 | 1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a | |
1213 | per-driver one. | |
1214 | ||
1215 | Standardize an error code for invalid ioctl. | |
1216 | ||
1217 | Added V4L2_CTRL_TYPE_BITMASK. | |
1218 | ||
1219 | ||
1220 | V4L2 in Linux 3.2 | |
1221 | ================= | |
1222 | ||
1223 | 1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to | |
1224 | userspace. | |
1225 | ||
1226 | 2. Add selection API for extended control over cropping and composing. | |
1227 | Does not affect the compatibility of current drivers and | |
1228 | applications. See :ref:`selection API <selection-api>` for details. | |
1229 | ||
1230 | ||
1231 | V4L2 in Linux 3.3 | |
1232 | ================= | |
1233 | ||
1234 | 1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the | |
1235 | :ref:`User controls class <control>`. | |
1236 | ||
1237 | 2. Added the device_caps field to struct v4l2_capabilities and added | |
1238 | the new V4L2_CAP_DEVICE_CAPS capability. | |
1239 | ||
1240 | ||
1241 | V4L2 in Linux 3.4 | |
1242 | ================= | |
1243 | ||
1244 | 1. Added :ref:`JPEG compression control class <jpeg-controls>`. | |
1245 | ||
1246 | 2. Extended the DV Timings API: | |
7347081e MCC |
1247 | :ref:`VIDIOC_ENUM_DV_TIMINGS`, |
1248 | :ref:`VIDIOC_QUERY_DV_TIMINGS` and | |
1249 | :ref:`VIDIOC_DV_TIMINGS_CAP`. | |
5377d91f MH |
1250 | |
1251 | ||
1252 | V4L2 in Linux 3.5 | |
1253 | ================= | |
1254 | ||
1255 | 1. Added integer menus, the new type will be | |
1256 | V4L2_CTRL_TYPE_INTEGER_MENU. | |
1257 | ||
1258 | 2. Added selection API for V4L2 subdev interface: | |
7347081e | 1259 | :ref:`VIDIOC_SUBDEV_G_SELECTION` and |
af4a4d0d | 1260 | :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`. |
5377d91f MH |
1261 | |
1262 | 3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``, | |
1263 | ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``, | |
1264 | ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and | |
1265 | ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the | |
1266 | ``V4L2_CID_COLORFX`` control. | |
1267 | ||
1268 | 4. Added ``V4L2_CID_COLORFX_CBCR`` control. | |
1269 | ||
1270 | 5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``, | |
1271 | ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``, | |
1272 | ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``, | |
1273 | ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``, | |
1274 | ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``, | |
1275 | ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``, | |
1276 | ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``. | |
1277 | ||
1278 | ||
1279 | V4L2 in Linux 3.6 | |
1280 | ================= | |
1281 | ||
1282 | 1. Replaced ``input`` in :c:type:`struct v4l2_buffer` by | |
1283 | ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``. | |
1284 | ||
1285 | 2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE | |
1286 | capabilities. | |
1287 | ||
1288 | 3. Added support for frequency band enumerations: | |
7347081e | 1289 | :ref:`VIDIOC_ENUM_FREQ_BANDS`. |
5377d91f MH |
1290 | |
1291 | ||
1292 | V4L2 in Linux 3.9 | |
1293 | ================= | |
1294 | ||
1295 | 1. Added timestamp types to ``flags`` field in | |
1296 | :c:type:`struct v4l2_buffer`. See :ref:`buffer-flags`. | |
1297 | ||
1298 | 2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See | |
1299 | :ref:`ctrl-changes-flags`. | |
1300 | ||
1301 | ||
1302 | V4L2 in Linux 3.10 | |
1303 | ================== | |
1304 | ||
1305 | 1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET, | |
1306 | VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and | |
1307 | VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output | |
1308 | capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. | |
1309 | ||
1310 | 2. Added new debugging ioctl | |
7347081e | 1311 | :ref:`VIDIOC_DBG_G_CHIP_INFO`. |
5377d91f MH |
1312 | |
1313 | ||
1314 | V4L2 in Linux 3.11 | |
1315 | ================== | |
1316 | ||
1317 | 1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl. | |
1318 | ||
1319 | ||
1320 | V4L2 in Linux 3.14 | |
1321 | ================== | |
1322 | ||
1323 | 1. In struct :c:type:`struct v4l2_rect`, the type of ``width`` and | |
1324 | ``height`` fields changed from _s32 to _u32. | |
1325 | ||
1326 | ||
1327 | V4L2 in Linux 3.15 | |
1328 | ================== | |
1329 | ||
1330 | 1. Added Software Defined Radio (SDR) Interface. | |
1331 | ||
1332 | ||
1333 | V4L2 in Linux 3.16 | |
1334 | ================== | |
1335 | ||
1336 | 1. Added event V4L2_EVENT_SOURCE_CHANGE. | |
1337 | ||
1338 | ||
1339 | V4L2 in Linux 3.17 | |
1340 | ================== | |
1341 | ||
1342 | 1. Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added | |
1343 | format flags. | |
1344 | ||
1345 | 2. Added compound control types and | |
af4a4d0d | 1346 | :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`. |
5377d91f MH |
1347 | |
1348 | ||
1349 | V4L2 in Linux 3.18 | |
1350 | ================== | |
1351 | ||
1352 | 1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera | |
1353 | controls. | |
1354 | ||
1355 | ||
1356 | V4L2 in Linux 3.19 | |
1357 | ================== | |
1358 | ||
1359 | 1. Rewrote Colorspace chapter, added new enum | |
1360 | :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum | |
1361 | :ref:`v4l2_quantization <v4l2-quantization>` fields to struct | |
1362 | :ref:`v4l2_pix_format <v4l2-pix-format>`, struct | |
1363 | :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and | |
1364 | struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`. | |
1365 | ||
1366 | ||
1367 | V4L2 in Linux 4.4 | |
1368 | ================= | |
1369 | ||
1370 | 1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of | |
1371 | ``V4L2_TUNER_ADC`` is deprecated now. | |
1372 | ||
1373 | 2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control. | |
1374 | ||
1375 | 3. Added transmitter support for Software Defined Radio (SDR) Interface. | |
1376 | ||
1377 | ||
1378 | .. _other: | |
1379 | ||
1380 | Relation of V4L2 to other Linux multimedia APIs | |
1381 | =============================================== | |
1382 | ||
1383 | ||
1384 | .. _xvideo: | |
1385 | ||
1386 | X Video Extension | |
1387 | ----------------- | |
1388 | ||
1389 | The X Video Extension (abbreviated XVideo or just Xv) is an extension of | |
1390 | the X Window system, implemented for example by the XFree86 project. Its | |
1391 | scope is similar to V4L2, an API to video capture and output devices for | |
1392 | X clients. Xv allows applications to display live video in a window, | |
1393 | send window contents to a TV output, and capture or output still images | |
1394 | in XPixmaps [1]_. With their implementation XFree86 makes the extension | |
1395 | available across many operating systems and architectures. | |
1396 | ||
1397 | Because the driver is embedded into the X server Xv has a number of | |
1398 | advantages over the V4L2 :ref:`video overlay interface <overlay>`. The | |
1399 | driver can easily determine the overlay target, i. e. visible graphics | |
1400 | memory or off-screen buffers for a destructive overlay. It can program | |
1401 | the RAMDAC for a non-destructive overlay, scaling or color-keying, or | |
1402 | the clipping functions of the video capture hardware, always in sync | |
1403 | with drawing operations or windows moving or changing their stacking | |
1404 | order. | |
1405 | ||
1406 | To combine the advantages of Xv and V4L a special Xv driver exists in | |
1407 | XFree86 and XOrg, just programming any overlay capable Video4Linux | |
1408 | device it finds. To enable it ``/etc/X11/XF86Config`` must contain these | |
1409 | lines: | |
1410 | ||
5377d91f MH |
1411 | :: |
1412 | ||
1413 | Section "Module" | |
0579e6e3 | 1414 | Load "v4l" |
5377d91f | 1415 | EndSection |
08047562 | 1416 | |
5377d91f MH |
1417 | As of XFree86 4.2 this driver still supports only V4L ioctls, however it |
1418 | should work just fine with all V4L2 devices through the V4L2 | |
1419 | backward-compatibility layer. Since V4L2 permits multiple opens it is | |
1420 | possible (if supported by the V4L2 driver) to capture video while an X | |
1421 | client requested video overlay. Restrictions of simultaneous capturing | |
1422 | and overlay are discussed in :ref:`overlay` apply. | |
1423 | ||
1424 | Only marginally related to V4L2, XFree86 extended Xv to support hardware | |
1425 | YUV to RGB conversion and scaling for faster video playback, and added | |
1426 | an interface to MPEG-2 decoding hardware. This API is useful to display | |
1427 | images captured with V4L2 devices. | |
1428 | ||
1429 | ||
1430 | Digital Video | |
1431 | ------------- | |
1432 | ||
1433 | V4L2 does not support digital terrestrial, cable or satellite broadcast. | |
1434 | A separate project aiming at digital receivers exists. You can find its | |
1435 | homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux | |
1436 | DVB API has no connection to the V4L2 API except that drivers for hybrid | |
1437 | hardware may support both. | |
1438 | ||
1439 | ||
1440 | Audio Interfaces | |
1441 | ---------------- | |
1442 | ||
1443 | [to do - OSS/ALSA] | |
1444 | ||
1445 | ||
1446 | .. _experimental: | |
1447 | ||
1448 | Experimental API Elements | |
1449 | ========================= | |
1450 | ||
1451 | The following V4L2 API elements are currently experimental and may | |
1452 | change in the future. | |
1453 | ||
7347081e | 1454 | - :ref:`VIDIOC_DBG_G_REGISTER` and |
af4a4d0d | 1455 | :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls. |
5377d91f | 1456 | |
7347081e | 1457 | - :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl. |
5377d91f MH |
1458 | |
1459 | ||
1460 | .. _obsolete: | |
1461 | ||
1462 | Obsolete API Elements | |
1463 | ===================== | |
1464 | ||
1465 | The following V4L2 API elements were superseded by new interfaces and | |
1466 | should not be implemented in new drivers. | |
1467 | ||
1468 | - ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended | |
1469 | Controls, :ref:`extended-controls`. | |
1470 | ||
1471 | - VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, | |
1472 | VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use | |
1473 | the DV Timings API (:ref:`dv-timings`). | |
1474 | ||
1475 | - ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use | |
1476 | ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``, | |
af4a4d0d | 1477 | :ref:`VIDIOC_SUBDEV_G_SELECTION`. |
5377d91f MH |
1478 | |
1479 | .. [1] | |
1480 | This is not implemented in XFree86. |