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