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