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