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