Debian Codegraph @

Documentation/userspace-api/media/v4l/v4l2.rst

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