Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
080df77f | 3 | .. include:: <isonum.txt> |
5377d91f MH |
4 | .. _v4l2spec: |
5 | ||
6 | ##################################### | |
7 | Video for Linux Two API Specification | |
8 | ##################################### | |
9 | ||
080df77f | 10 | **Revision 4.5** |
5377d91f MH |
11 | |
12 | .. toctree:: | |
c7685f27 | 13 | :numbered: |
5377d91f | 14 | :maxdepth: 1 |
c7685f27 | 15 | :caption: Table of Contents |
5377d91f MH |
16 | |
17 | common | |
18 | pixfmt | |
19 | io | |
20 | devices | |
21 | driver | |
22 | libv4l | |
23 | compat | |
24 | user-func | |
25 | common-defs | |
26 | videodev | |
27 | capture-example | |
28 | v4l2grab-example | |
29 | biblio | |
30 | ||
31 | ||
32 | ********************** | |
33 | Revision and Copyright | |
34 | ********************** | |
35 | ||
080df77f | 36 | Authors, in alphabetical order: |
5377d91f | 37 | |
080df77f | 38 | - Ailus, Sakari <sakari.ailus@iki.fi> |
5377d91f | 39 | |
080df77f | 40 | - Subdev selections API. |
5377d91f | 41 | |
080df77f | 42 | - Carvalho Chehab, Mauro <m.chehab@kernel.org> |
5377d91f | 43 | |
080df77f | 44 | - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. |
5377d91f | 45 | |
080df77f | 46 | - Dirks, Bill |
5377d91f | 47 | |
080df77f | 48 | - Original author of the V4L2 API and documentation. |
5377d91f | 49 | |
080df77f | 50 | - H Schimek, Michael <mschimek@gmx.at> |
5377d91f | 51 | |
080df77f | 52 | - Original author of the V4L2 API and documentation. |
5377d91f | 53 | |
080df77f | 54 | - Karicheri, Muralidharan <m-karicheri2@ti.com> |
5377d91f | 55 | |
080df77f | 56 | - Documented the Digital Video timings API. |
5377d91f | 57 | |
080df77f MCC |
58 | - Osciak, Pawel <pawel@osciak.com> |
59 | ||
60 | - Designed and documented the multi-planar API. | |
61 | ||
62 | - Palosaari, Antti <crope@iki.fi> | |
63 | ||
64 | - SDR API. | |
65 | ||
66 | - Rubli, Martin | |
67 | ||
68 | - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. | |
69 | ||
70 | - Walls, Andy <awalls@md.metrocast.net> | |
71 | ||
72 | - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification. | |
73 | ||
74 | - Verkuil, Hans <hverkuil@xs4all.nl> | |
75 | ||
76 | - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API. | |
77 | ||
78 | **Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari. | |
5377d91f MH |
79 | |
80 | Except when explicitly stated as GPL, programming examples within this | |
81 | part can be used and distributed without restrictions. | |
82 | ||
080df77f MCC |
83 | **************** |
84 | Revision History | |
85 | **************** | |
5377d91f MH |
86 | |
87 | :revision: 4.5 / 2015-10-29 (*rr*) | |
88 | ||
af4a4d0d | 89 | Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with |
5377d91f MH |
90 | ctrl_class and which. Which is used to select the current value of the |
91 | control or the default value. | |
92 | ||
93 | ||
94 | :revision: 4.4 / 2015-05-26 (*ap*) | |
95 | ||
96 | Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added | |
97 | V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for | |
98 | Software Defined Radio (SDR) Interface. | |
99 | ||
100 | ||
101 | :revision: 4.1 / 2015-02-13 (*mcc*) | |
102 | ||
103 | Fix documentation for media controller device nodes and add support for | |
104 | DVB device nodes. Add support for Tuner sub-device. | |
105 | ||
106 | ||
107 | :revision: 3.19 / 2014-12-05 (*hv*) | |
108 | ||
109 | Rewrote Colorspace chapter, added new enum | |
110 | :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum | |
111 | :ref:`v4l2_quantization <v4l2-quantization>` fields to struct | |
112 | :ref:`v4l2_pix_format <v4l2-pix-format>`, struct | |
113 | :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct | |
114 | :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`. | |
115 | ||
116 | ||
117 | :revision: 3.17 / 2014-08-04 (*lp, hv*) | |
118 | ||
119 | Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added | |
120 | format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL. | |
121 | ||
122 | ||
123 | :revision: 3.15 / 2014-02-03 (*hv, ap*) | |
124 | ||
125 | Update several sections of "Common API Elements": "Opening and Closing | |
126 | Devices" "Querying Capabilities", "Application Priority", "Video Inputs | |
127 | and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video | |
128 | Standards" and "Digital Video (DV) Timings". Added SDR API. | |
129 | ||
130 | ||
131 | :revision: 3.14 / 2013-11-25 (*rr*) | |
132 | ||
133 | Set width and height as unsigned on v4l2_rect. | |
134 | ||
135 | ||
136 | :revision: 3.11 / 2013-05-26 (*hv*) | |
137 | ||
138 | Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. | |
139 | ||
140 | ||
141 | :revision: 3.10 / 2013-03-25 (*hv*) | |
142 | ||
143 | Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, | |
144 | VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and | |
145 | VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output | |
146 | capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. | |
147 | Added VIDIOC_DBG_G_CHIP_INFO. | |
148 | ||
149 | ||
150 | :revision: 3.9 / 2012-12-03 (*sa, sn*) | |
151 | ||
152 | Added timestamp types to v4l2_buffer. Added | |
153 | V4L2_EVENT_CTRL_CH_RANGE control event changes flag. | |
154 | ||
155 | ||
156 | :revision: 3.6 / 2012-07-02 (*hv*) | |
157 | ||
158 | Added VIDIOC_ENUM_FREQ_BANDS. | |
159 | ||
160 | ||
161 | :revision: 3.5 / 2012-05-07 (*sa, sn, hv*) | |
162 | ||
163 | Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. | |
164 | Improved the description of V4L2_CID_COLORFX control, added | |
165 | V4L2_CID_COLORFX_CBCR control. Added camera controls | |
166 | V4L2_CID_AUTO_EXPOSURE_BIAS, | |
167 | V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, | |
168 | V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, | |
169 | V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, | |
170 | V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, | |
171 | V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, | |
172 | V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added | |
173 | VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and | |
174 | VIDIOC_DV_TIMINGS_CAP. | |
175 | ||
176 | ||
177 | :revision: 3.4 / 2012-01-25 (*sn*) | |
178 | ||
179 | Added :ref:`JPEG compression control class. <jpeg-controls>` | |
180 | ||
181 | ||
182 | :revision: 3.3 / 2012-01-11 (*hv*) | |
183 | ||
184 | Added device_caps field to struct v4l2_capabilities. | |
185 | ||
186 | ||
187 | :revision: 3.2 / 2011-08-26 (*hv*) | |
188 | ||
189 | Added V4L2_CTRL_FLAG_VOLATILE. | |
190 | ||
191 | ||
192 | :revision: 3.1 / 2011-06-27 (*mcc, po, hv*) | |
193 | ||
194 | Documented that VIDIOC_QUERYCAP now returns a per-subsystem version | |
195 | instead of a per-driver one. Standardize an error code for invalid | |
196 | ioctl. Added V4L2_CTRL_TYPE_BITMASK. | |
197 | ||
198 | ||
199 | :revision: 2.6.39 / 2011-03-01 (*mcc, po*) | |
200 | ||
201 | Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect | |
202 | latest changes. Added the :ref:`multi-planar API <planar-apis>`. | |
203 | ||
204 | ||
205 | :revision: 2.6.37 / 2010-08-06 (*hv*) | |
206 | ||
207 | Removed obsolete vtx (videotext) API. | |
208 | ||
209 | ||
210 | :revision: 2.6.33 / 2009-12-03 (*mk*) | |
211 | ||
212 | Added documentation for the Digital Video timings API. | |
213 | ||
214 | ||
215 | :revision: 2.6.32 / 2009-08-31 (*mcc*) | |
216 | ||
217 | Now, revisions will match the kernel version where the V4L2 API changes | |
218 | will be used by the Linux Kernel. Also added Remote Controller chapter. | |
219 | ||
220 | ||
221 | :revision: 0.29 / 2009-08-26 (*ev*) | |
222 | ||
223 | Added documentation for string controls and for FM Transmitter controls. | |
224 | ||
225 | ||
226 | :revision: 0.28 / 2009-08-26 (*gl*) | |
227 | ||
228 | Added V4L2_CID_BAND_STOP_FILTER documentation. | |
229 | ||
230 | ||
231 | :revision: 0.27 / 2009-08-15 (*mcc*) | |
232 | ||
233 | Added libv4l and Remote Controller documentation; added v4l2grab and | |
234 | keytable application examples. | |
235 | ||
236 | ||
237 | :revision: 0.26 / 2009-07-23 (*hv*) | |
238 | ||
239 | Finalized the RDS capture API. Added modulator and RDS encoder | |
240 | capabilities. Added support for string controls. | |
241 | ||
242 | ||
243 | :revision: 0.25 / 2009-01-18 (*hv*) | |
244 | ||
245 | Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls | |
246 | VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera | |
247 | controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, | |
248 | V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY. | |
249 | ||
250 | ||
251 | :revision: 0.24 / 2008-03-04 (*mhs*) | |
252 | ||
253 | Added pixel formats Y16 and SBGGR16, new controls and a camera controls | |
254 | class. Removed VIDIOC_G/S_MPEGCOMP. | |
255 | ||
256 | ||
257 | :revision: 0.23 / 2007-08-30 (*mhs*) | |
258 | ||
259 | Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of | |
260 | packed pixel formats. | |
261 | ||
262 | ||
263 | :revision: 0.22 / 2007-08-29 (*mhs*) | |
264 | ||
265 | Added the Video Output Overlay interface, new MPEG controls, | |
266 | V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, | |
080df77f | 267 | VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD, |
5377d91f MH |
268 | VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. |
269 | Clarifications in the cropping chapter, about RGB pixel formats, the | |
270 | mmap(), poll(), select(), read() and write() functions. Typographical | |
271 | fixes. | |
272 | ||
273 | ||
274 | :revision: 0.21 / 2006-12-19 (*mhs*) | |
275 | ||
276 | Fixed a link in the VIDIOC_G_EXT_CTRLS section. | |
277 | ||
278 | ||
279 | :revision: 0.20 / 2006-11-24 (*mhs*) | |
280 | ||
281 | Clarified the purpose of the audioset field in struct v4l2_input and | |
282 | v4l2_output. | |
283 | ||
284 | ||
285 | :revision: 0.19 / 2006-10-19 (*mhs*) | |
286 | ||
287 | Documented V4L2_PIX_FMT_RGB444. | |
288 | ||
289 | ||
290 | :revision: 0.18 / 2006-10-18 (*mhs*) | |
291 | ||
292 | Added the description of extended controls by Hans Verkuil. Linked | |
293 | V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE. | |
294 | ||
295 | ||
296 | :revision: 0.17 / 2006-10-12 (*mhs*) | |
297 | ||
298 | Corrected V4L2_PIX_FMT_HM12 description. | |
299 | ||
300 | ||
301 | :revision: 0.16 / 2006-10-08 (*mhs*) | |
302 | ||
303 | VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part | |
304 | of the API. | |
305 | ||
306 | ||
307 | :revision: 0.15 / 2006-09-23 (*mhs*) | |
308 | ||
309 | Cleaned up the bibliography, added BT.653 and BT.1119. | |
310 | capture.c/start_capturing() for user pointer I/O did not initialize the | |
311 | buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and | |
312 | V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See | |
313 | the history chapter for API changes. | |
314 | ||
315 | ||
316 | :revision: 0.14 / 2006-09-14 (*mr*) | |
317 | ||
318 | Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal | |
319 | for frame format enumeration of digital devices. | |
320 | ||
321 | ||
322 | :revision: 0.13 / 2006-04-07 (*mhs*) | |
323 | ||
080df77f | 324 | Corrected the description of struct v4l2_window clips. New V4L2_STD\_ |
5377d91f MH |
325 | and V4L2_TUNER_MODE_LANG1_LANG2 defines. |
326 | ||
327 | ||
328 | :revision: 0.12 / 2006-02-03 (*mhs*) | |
329 | ||
330 | Corrected the description of struct v4l2_captureparm and | |
331 | v4l2_outputparm. | |
332 | ||
333 | ||
334 | :revision: 0.11 / 2006-01-27 (*mhs*) | |
335 | ||
336 | Improved the description of struct v4l2_tuner. | |
337 | ||
338 | ||
339 | :revision: 0.10 / 2006-01-10 (*mhs*) | |
340 | ||
341 | VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications. | |
342 | ||
343 | ||
344 | :revision: 0.9 / 2005-11-27 (*mhs*) | |
345 | ||
346 | Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the | |
347 | sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. | |
348 | Fixed VIDIOC_S_STD call in the video standard selection example. | |
349 | Various updates. | |
350 | ||
351 | ||
352 | :revision: 0.8 / 2004-10-04 (*mhs*) | |
353 | ||
354 | Somehow a piece of junk slipped into the capture example, removed. | |
355 | ||
356 | ||
357 | :revision: 0.7 / 2004-09-19 (*mhs*) | |
358 | ||
359 | Fixed video standard selection, control enumeration, downscaling and | |
360 | aspect example. Added read and user pointer i/o to video capture | |
361 | example. | |
362 | ||
363 | ||
364 | :revision: 0.6 / 2004-08-01 (*mhs*) | |
365 | ||
366 | v4l2_buffer changes, added video capture example, various corrections. | |
367 | ||
368 | ||
369 | :revision: 0.5 / 2003-11-05 (*mhs*) | |
370 | ||
371 | Pixel format erratum. | |
372 | ||
373 | ||
374 | :revision: 0.4 / 2003-09-17 (*mhs*) | |
375 | ||
376 | Corrected source and Makefile to generate a PDF. SGML fixes. Added | |
377 | latest API changes. Closed gaps in the history chapter. | |
378 | ||
379 | ||
380 | :revision: 0.3 / 2003-02-05 (*mhs*) | |
381 | ||
382 | Another draft, more corrections. | |
383 | ||
384 | ||
385 | :revision: 0.2 / 2003-01-15 (*mhs*) | |
386 | ||
387 | Second draft, with corrections pointed out by Gerd Knorr. | |
388 | ||
389 | ||
390 | :revision: 0.1 / 2002-12-01 (*mhs*) | |
391 | ||
392 | First draft, based on documentation by Bill Dirks and discussions on the | |
393 | V4L mailing list. | |
394 | ||
395 | ||
396 | .. ------------------------------------------------------------------------------ | |
397 | .. This file was automatically converted from DocBook-XML with the dbxml | |
398 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes | |
399 | .. from the linux kernel, refer to: | |
400 | .. | |
401 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook | |
402 | .. ------------------------------------------------------------------------------ |