summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l')
-rw-r--r--Documentation/DocBook/media/v4l/.gitignore1
-rw-r--r--Documentation/DocBook/media/v4l/biblio.xml229
-rw-r--r--Documentation/DocBook/media/v4l/capture.c.xml659
-rw-r--r--Documentation/DocBook/media/v4l/common.xml1207
-rw-r--r--Documentation/DocBook/media/v4l/compat.xml2618
-rw-r--r--Documentation/DocBook/media/v4l/controls.xml4272
-rw-r--r--Documentation/DocBook/media/v4l/crop.pdfbin5846 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/dev-capture.xml110
-rw-r--r--Documentation/DocBook/media/v4l/dev-codec.xml18
-rw-r--r--Documentation/DocBook/media/v4l/dev-effect.xml17
-rw-r--r--Documentation/DocBook/media/v4l/dev-event.xml43
-rw-r--r--Documentation/DocBook/media/v4l/dev-osd.xml156
-rw-r--r--Documentation/DocBook/media/v4l/dev-output.xml106
-rw-r--r--Documentation/DocBook/media/v4l/dev-overlay.xml371
-rw-r--r--Documentation/DocBook/media/v4l/dev-radio.xml49
-rw-r--r--Documentation/DocBook/media/v4l/dev-raw-vbi.xml339
-rw-r--r--Documentation/DocBook/media/v4l/dev-rds.xml196
-rw-r--r--Documentation/DocBook/media/v4l/dev-sliced-vbi.xml699
-rw-r--r--Documentation/DocBook/media/v4l/dev-subdev.xml467
-rw-r--r--Documentation/DocBook/media/v4l/dev-teletext.xml29
-rw-r--r--Documentation/DocBook/media/v4l/driver.xml200
-rw-r--r--Documentation/DocBook/media/v4l/fdl-appendix.xml671
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_bt.pdfbin9185 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_tb.pdfbin9173 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/func-close.xml62
-rw-r--r--Documentation/DocBook/media/v4l/func-ioctl.xml71
-rw-r--r--Documentation/DocBook/media/v4l/func-mmap.xml183
-rw-r--r--Documentation/DocBook/media/v4l/func-munmap.xml76
-rw-r--r--Documentation/DocBook/media/v4l/func-open.xml113
-rw-r--r--Documentation/DocBook/media/v4l/func-poll.xml119
-rw-r--r--Documentation/DocBook/media/v4l/func-read.xml181
-rw-r--r--Documentation/DocBook/media/v4l/func-select.xml130
-rw-r--r--Documentation/DocBook/media/v4l/func-write.xml128
-rw-r--r--Documentation/DocBook/media/v4l/gen-errors.xml78
-rw-r--r--Documentation/DocBook/media/v4l/io.xml1286
-rw-r--r--Documentation/DocBook/media/v4l/keytable.c.xml172
-rw-r--r--Documentation/DocBook/media/v4l/libv4l.xml160
-rw-r--r--Documentation/DocBook/media/v4l/lirc_device_interface.xml253
-rw-r--r--Documentation/DocBook/media/v4l/media-controller.xml89
-rw-r--r--Documentation/DocBook/media/v4l/media-func-close.xml59
-rw-r--r--Documentation/DocBook/media/v4l/media-func-ioctl.xml73
-rw-r--r--Documentation/DocBook/media/v4l/media-func-open.xml94
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-device-info.xml132
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml308
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-links.xml207
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-setup-link.xml84
-rw-r--r--Documentation/DocBook/media/v4l/pipeline.pdfbin20276 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-grey.xml62
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-m420.xml139
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12.xml143
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12m.xml146
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml66
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv16.xml166
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv24.xml121
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml935
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml236
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml83
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml29
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb12.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-uyvy.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-vyuy.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10b.xml43
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y12.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y16.xml81
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y41p.xml149
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv410.xml133
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml147
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420.xml149
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml154
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml153
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuyv.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yvyu.xml120
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml1001
-rw-r--r--Documentation/DocBook/media/v4l/planar-apis.xml62
-rw-r--r--Documentation/DocBook/media/v4l/remote_controllers.xml177
-rw-r--r--Documentation/DocBook/media/v4l/selection-api.xml325
-rw-r--r--Documentation/DocBook/media/v4l/subdev-formats.xml2569
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-crop.dia614
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-crop.svg63
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-full.dia1588
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-full.svg163
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.dia1152
-rw-r--r--Documentation/DocBook/media/v4l/subdev-image-processing-scaling-multi-source.svg116
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml613
-rw-r--r--Documentation/DocBook/media/v4l/v4l2grab.c.xml164
-rw-r--r--Documentation/DocBook/media/v4l/vbi_525.pdfbin3395 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_625.pdfbin3683 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_hsync.pdfbin7405 -> 0 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml146
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-cropcap.xml165
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml266
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml258
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml256
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml271
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml211
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml196
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml234
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml119
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml158
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml259
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml271
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudio.xml76
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml79
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enuminput.xml313
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumoutput.xml198
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumstd.xml383
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audio.xml172
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audioout.xml138
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-crop.xml126
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml129
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml110
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml326
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml196
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml348
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml463
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fmt.xml196
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-frequency.xml140
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-input.xml83
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml175
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-modulator.xml238
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-output.xml85
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-parm.xml316
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-priority.xml135
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-selection.xml308
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml255
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-std.xml90
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-tuner.xml537
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-log-status.xml41
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-overlay.xml74
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml94
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-qbuf.xml177
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml69
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml104
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querybuf.xml102
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querycap.xml317
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-queryctrl.xml480
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querystd.xml66
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-reqbufs.xml135
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml128
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-streamon.xml107
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml152
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml154
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml119
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml158
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml183
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml141
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml228
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml206
154 files changed, 0 insertions, 41003 deletions
diff --git a/Documentation/DocBook/media/v4l/.gitignore b/Documentation/DocBook/media/v4l/.gitignore
deleted file mode 100644
index d7ec32eafac..00000000000
--- a/Documentation/DocBook/media/v4l/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-!*.xml
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
deleted file mode 100644
index 7c49facecd2..00000000000
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ /dev/null
@@ -1,229 +0,0 @@
- <bibliography>
- <title>References</title>
-
- <biblioentry id="eia608">
- <abbrev>EIA&nbsp;608-B</abbrev>
- <authorgroup>
- <corpauthor>Electronic Industries Alliance (<ulink
-url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor>
- </authorgroup>
- <title>EIA 608-B "Recommended Practice for Line 21 Data
-Service"</title>
- </biblioentry>
-
- <biblioentry id="en300294">
- <abbrev>EN&nbsp;300&nbsp;294</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>EN 300 294 "625-line television Wide Screen Signalling
-(WSS)"</title>
- </biblioentry>
-
- <biblioentry id="ets300231">
- <abbrev>ETS&nbsp;300&nbsp;231</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink
-url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>ETS 300 231 "Specification of the domestic video
-Programme Delivery Control system (PDC)"</title>
- </biblioentry>
-
- <biblioentry id="ets300706">
- <abbrev>ETS&nbsp;300&nbsp;706</abbrev>
- <authorgroup>
- <corpauthor>European Telecommunication Standards Institute
-(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
- </authorgroup>
- <title>ETS 300 706 "Enhanced Teletext specification"</title>
- </biblioentry>
-
- <biblioentry id="mpeg2part1">
- <abbrev>ISO&nbsp;13818-1</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>), International
-Organisation for Standardisation (<ulink
-url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information
-technology &mdash; Generic coding of moving pictures and associated
-audio information: Systems"</title>
- </biblioentry>
-
- <biblioentry id="mpeg2part2">
- <abbrev>ISO&nbsp;13818-2</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>), International
-Organisation for Standardisation (<ulink
-url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information
-technology &mdash; Generic coding of moving pictures and associated
-audio information: Video"</title>
- </biblioentry>
-
- <biblioentry id="itu470">
- <abbrev>ITU&nbsp;BT.470</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.470-6 "Conventional Television
-Systems"</title>
- </biblioentry>
-
- <biblioentry id="itu601">
- <abbrev>ITU&nbsp;BT.601</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
-of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
-Ratios"</title>
- </biblioentry>
-
- <biblioentry id="itu653">
- <abbrev>ITU&nbsp;BT.653</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title>
- </biblioentry>
-
- <biblioentry id="itu709">
- <abbrev>ITU&nbsp;BT.709</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.709-5 "Parameter values for the
-HDTV standards for production and international programme
-exchange"</title>
- </biblioentry>
-
- <biblioentry id="itu1119">
- <abbrev>ITU&nbsp;BT.1119</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union (<ulink
-url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-R Recommendation BT.1119 "625-line
-television Wide Screen Signalling (WSS)"</title>
- </biblioentry>
-
- <biblioentry id="jfif">
- <abbrev>JFIF</abbrev>
- <authorgroup>
- <corpauthor>Independent JPEG Group (<ulink
-url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor>
- </authorgroup>
- <title>JPEG File Interchange Format</title>
- <subtitle>Version 1.02</subtitle>
- </biblioentry>
-
- <biblioentry id="itu-t81">
- <abbrev>ITU-T.81</abbrev>
- <authorgroup>
- <corpauthor>International Telecommunication Union
-(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor>
- </authorgroup>
- <title>ITU-T Recommendation T.81
-"Information Technology &mdash; Digital Compression and Coding of Continous-Tone
-Still Images &mdash; Requirements and Guidelines"</title>
- </biblioentry>
-
- <biblioentry id="w3c-jpeg-jfif">
- <abbrev>W3C JPEG JFIF</abbrev>
- <authorgroup>
- <corpauthor>The World Wide Web Consortium (<ulink
-url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor>
- </authorgroup>
- <title>JPEG JFIF</title>
- </biblioentry>
-
- <biblioentry id="smpte12m">
- <abbrev>SMPTE&nbsp;12M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 12M-1999 "Television, Audio and Film - Time and
-Control Code"</title>
- </biblioentry>
-
- <biblioentry id="smpte170m">
- <abbrev>SMPTE&nbsp;170M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 170M-1999 "Television - Composite Analog Video
-Signal - NTSC for Studio Applications"</title>
- </biblioentry>
-
- <biblioentry id="smpte240m">
- <abbrev>SMPTE&nbsp;240M</abbrev>
- <authorgroup>
- <corpauthor>Society of Motion Picture and Television Engineers
-(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
- </authorgroup>
- <title>SMPTE 240M-1999 "Television - Signal Parameters -
-1125-Line High-Definition Production"</title>
- </biblioentry>
-
- <biblioentry id="en50067">
- <abbrev>EN&nbsp;50067</abbrev>
- <authorgroup>
- <corpauthor>European Committee for Electrotechnical Standardization
-(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor>
- </authorgroup>
- <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
-in the frequency range from 87,5 to 108,0 MHz</title>
- </biblioentry>
-
- <biblioentry id="nrsc4">
- <abbrev>NRSC-4</abbrev>
- <authorgroup>
- <corpauthor>National Radio Systems Committee
-(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
- </authorgroup>
- <title>NTSC-4: United States RBDS Standard</title>
- </biblioentry>
-
- <biblioentry id="iso12232">
- <abbrev>ISO&nbsp;12232:2006</abbrev>
- <authorgroup>
- <corpauthor>International Organization for Standardization
-(<ulink url="http://www.iso.org">http://www.iso.org</ulink>)</corpauthor>
- </authorgroup>
- <title>Photography &mdash; Digital still cameras &mdash; Determination
- of exposure index, ISO speed ratings, standard output sensitivity, and
- recommended exposure index</title>
- </biblioentry>
-
- <biblioentry id="cea861">
- <abbrev>CEA-861-E</abbrev>
- <authorgroup>
- <corpauthor>Consumer Electronics Association
-(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>
- </authorgroup>
- <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title>
- </biblioentry>
-
- <biblioentry id="vesadmt">
- <abbrev>VESA&nbsp;DMT</abbrev>
- <authorgroup>
- <corpauthor>Video Electronics Standards Association
-(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>
- </authorgroup>
- <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title>
- </biblioentry>
-
- </bibliography>
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml
deleted file mode 100644
index 1c5c49a2de5..00000000000
--- a/Documentation/DocBook/media/v4l/capture.c.xml
+++ /dev/null
@@ -1,659 +0,0 @@
-<programlisting>
-/*
- * V4L2 video capture example
- *
- * This program can be used and distributed without restrictions.
- *
- * This program is provided with the V4L2 API
- * see http://linuxtv.org/docs.php for more information
- */
-
-#include &lt;stdio.h&gt;
-#include &lt;stdlib.h&gt;
-#include &lt;string.h&gt;
-#include &lt;assert.h&gt;
-
-#include &lt;getopt.h&gt; /* getopt_long() */
-
-#include &lt;fcntl.h&gt; /* low-level i/o */
-#include &lt;unistd.h&gt;
-#include &lt;errno.h&gt;
-#include &lt;sys/stat.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;sys/time.h&gt;
-#include &lt;sys/mman.h&gt;
-#include &lt;sys/ioctl.h&gt;
-
-#include &lt;linux/videodev2.h&gt;
-
-#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
-
-enum io_method {
- IO_METHOD_READ,
- IO_METHOD_MMAP,
- IO_METHOD_USERPTR,
-};
-
-struct buffer {
- void *start;
- size_t length;
-};
-
-static char *dev_name;
-static enum io_method io = IO_METHOD_MMAP;
-static int fd = -1;
-struct buffer *buffers;
-static unsigned int n_buffers;
-static int out_buf;
-static int force_format;
-static int frame_count = 70;
-
-static void errno_exit(const char *s)
-{
- fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno));
- exit(EXIT_FAILURE);
-}
-
-static int xioctl(int fh, int request, void *arg)
-{
- int r;
-
- do {
- r = ioctl(fh, request, arg);
- } while (-1 == r &amp;&amp; EINTR == errno);
-
- return r;
-}
-
-static void process_image(const void *p, int size)
-{
- if (out_buf)
- fwrite(p, size, 1, stdout);
-
- fflush(stderr);
- fprintf(stderr, ".");
- fflush(stdout);
-}
-
-static int read_frame(void)
-{
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("read");
- }
- }
-
- process_image(buffers[0].start, buffers[0].length);
- break;
-
- case IO_METHOD_MMAP:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- assert(buf.index &lt; n_buffers);
-
- process_image(buffers[buf.index].start, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- break;
-
- case IO_METHOD_USERPTR:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- for (i = 0; i &lt; n_buffers; ++i)
- if (buf.m.userptr == (unsigned long)buffers[i].start
- &amp;&amp; buf.length == buffers[i].length)
- break;
-
- assert(i &lt; n_buffers);
-
- process_image((void *)buf.m.userptr, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- break;
- }
-
- return 1;
-}
-
-static void mainloop(void)
-{
- unsigned int count;
-
- count = frame_count;
-
- while (count-- &gt; 0) {
- for (;;) {
- fd_set fds;
- struct timeval tv;
- int r;
-
- FD_ZERO(&amp;fds);
- FD_SET(fd, &amp;fds);
-
- /* Timeout. */
- tv.tv_sec = 2;
- tv.tv_usec = 0;
-
- r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
-
- if (-1 == r) {
- if (EINTR == errno)
- continue;
- errno_exit("select");
- }
-
- if (0 == r) {
- fprintf(stderr, "select timeout\n");
- exit(EXIT_FAILURE);
- }
-
- if (read_frame())
- break;
- /* EAGAIN - continue select loop. */
- }
- }
-}
-
-static void stop_capturing(void)
-{
- enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &amp;type))
- errno_exit("VIDIOC_STREAMOFF");
- break;
- }
-}
-
-static void start_capturing(void)
-{
- unsigned int i;
- enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i &lt; n_buffers; ++i) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = i;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
- errno_exit("VIDIOC_STREAMON");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i &lt; n_buffers; ++i) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
- buf.index = i;
- buf.m.userptr = (unsigned long)buffers[i].start;
- buf.length = buffers[i].length;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
- errno_exit("VIDIOC_STREAMON");
- break;
- }
-}
-
-static void uninit_device(void)
-{
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- free(buffers[0].start);
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i &lt; n_buffers; ++i)
- if (-1 == munmap(buffers[i].start, buffers[i].length))
- errno_exit("munmap");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i &lt; n_buffers; ++i)
- free(buffers[i].start);
- break;
- }
-
- free(buffers);
-}
-
-static void init_read(unsigned int buffer_size)
-{
- buffers = calloc(1, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- buffers[0].length = buffer_size;
- buffers[0].start = malloc(buffer_size);
-
- if (!buffers[0].start) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-}
-
-static void init_mmap(void)
-{
- struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "memory mapping\n", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- if (req.count &lt; 2) {
- fprintf(stderr, "Insufficient buffer memory on %s\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- buffers = calloc(req.count, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
- struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
-
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = n_buffers;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &amp;buf))
- errno_exit("VIDIOC_QUERYBUF");
-
- buffers[n_buffers].length = buf.length;
- buffers[n_buffers].start =
- mmap(NULL /* start anywhere */,
- buf.length,
- PROT_READ | PROT_WRITE /* required */,
- MAP_SHARED /* recommended */,
- fd, buf.m.offset);
-
- if (MAP_FAILED == buffers[n_buffers].start)
- errno_exit("mmap");
- }
-}
-
-static void init_userp(unsigned int buffer_size)
-{
- struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "user pointer i/o\n", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- buffers = calloc(4, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers &lt; 4; ++n_buffers) {
- buffers[n_buffers].length = buffer_size;
- buffers[n_buffers].start = malloc(buffer_size);
-
- if (!buffers[n_buffers].start) {
- fprintf(stderr, "Out of memory\n");
- exit(EXIT_FAILURE);
- }
- }
-}
-
-static void init_device(void)
-{
- struct <link linkend="v4l2-capability">v4l2_capability</link> cap;
- struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap;
- struct <link linkend="v4l2-crop">v4l2_crop</link> crop;
- struct <link linkend="v4l2-format">v4l2_format</link> fmt;
- unsigned int min;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &amp;cap)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s is no V4L2 device\n",
- dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_QUERYCAP");
- }
- }
-
- if (!(cap.capabilities &amp; V4L2_CAP_VIDEO_CAPTURE)) {
- fprintf(stderr, "%s is no video capture device\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- switch (io) {
- case IO_METHOD_READ:
- if (!(cap.capabilities &amp; V4L2_CAP_READWRITE)) {
- fprintf(stderr, "%s does not support read i/o\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- if (!(cap.capabilities &amp; V4L2_CAP_STREAMING)) {
- fprintf(stderr, "%s does not support streaming i/o\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
- }
-
-
- /* Select video input, video standard and tune here. */
-
-
- CLEAR(cropcap);
-
- cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (0 == xioctl(fd, VIDIOC_CROPCAP, &amp;cropcap)) {
- crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- crop.c = cropcap.defrect; /* reset to default */
-
- if (-1 == xioctl(fd, VIDIOC_S_CROP, &amp;crop)) {
- switch (errno) {
- case EINVAL:
- /* Cropping not supported. */
- break;
- default:
- /* Errors ignored. */
- break;
- }
- }
- } else {
- /* Errors ignored. */
- }
-
-
- CLEAR(fmt);
-
- fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (force_format) {
- fmt.fmt.pix.width = 640;
- fmt.fmt.pix.height = 480;
- fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
- fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
-
- if (-1 == xioctl(fd, VIDIOC_S_FMT, &amp;fmt))
- errno_exit("VIDIOC_S_FMT");
-
- /* Note VIDIOC_S_FMT may change width and height. */
- } else {
- /* Preserve original settings as set by v4l2-ctl for example */
- if (-1 == xioctl(fd, VIDIOC_G_FMT, &amp;fmt))
- errno_exit("VIDIOC_G_FMT");
- }
-
- /* Buggy driver paranoia. */
- min = fmt.fmt.pix.width * 2;
- if (fmt.fmt.pix.bytesperline &lt; min)
- fmt.fmt.pix.bytesperline = min;
- min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
- if (fmt.fmt.pix.sizeimage &lt; min)
- fmt.fmt.pix.sizeimage = min;
-
- switch (io) {
- case IO_METHOD_READ:
- init_read(fmt.fmt.pix.sizeimage);
- break;
-
- case IO_METHOD_MMAP:
- init_mmap();
- break;
-
- case IO_METHOD_USERPTR:
- init_userp(fmt.fmt.pix.sizeimage);
- break;
- }
-}
-
-static void close_device(void)
-{
- if (-1 == close(fd))
- errno_exit("close");
-
- fd = -1;
-}
-
-static void open_device(void)
-{
- struct stat st;
-
- if (-1 == stat(dev_name, &amp;st)) {
- fprintf(stderr, "Cannot identify '%s': %d, %s\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-
- if (!S_ISCHR(st.st_mode)) {
- fprintf(stderr, "%s is no device\n", dev_name);
- exit(EXIT_FAILURE);
- }
-
- fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
-
- if (-1 == fd) {
- fprintf(stderr, "Cannot open '%s': %d, %s\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-}
-
-static void usage(FILE *fp, int argc, char **argv)
-{
- fprintf(fp,
- "Usage: %s [options]\n\n"
- "Version 1.3\n"
- "Options:\n"
- "-d | --device name Video device name [%s]\n"
- "-h | --help Print this message\n"
- "-m | --mmap Use memory mapped buffers [default]\n"
- "-r | --read Use read() calls\n"
- "-u | --userp Use application allocated buffers\n"
- "-o | --output Outputs stream to stdout\n"
- "-f | --format Force format to 640x480 YUYV\n"
- "-c | --count Number of frames to grab [%i]\n"
- "",
- argv[0], dev_name, frame_count);
-}
-
-static const char short_options[] = "d:hmruofc:";
-
-static const struct option
-long_options[] = {
- { "device", required_argument, NULL, 'd' },
- { "help", no_argument, NULL, 'h' },
- { "mmap", no_argument, NULL, 'm' },
- { "read", no_argument, NULL, 'r' },
- { "userp", no_argument, NULL, 'u' },
- { "output", no_argument, NULL, 'o' },
- { "format", no_argument, NULL, 'f' },
- { "count", required_argument, NULL, 'c' },
- { 0, 0, 0, 0 }
-};
-
-int main(int argc, char **argv)
-{
- dev_name = "/dev/video0";
-
- for (;;) {
- int idx;
- int c;
-
- c = getopt_long(argc, argv,
- short_options, long_options, &amp;idx);
-
- if (-1 == c)
- break;
-
- switch (c) {
- case 0: /* getopt_long() flag */
- break;
-
- case 'd':
- dev_name = optarg;
- break;
-
- case 'h':
- usage(stdout, argc, argv);
- exit(EXIT_SUCCESS);
-
- case 'm':
- io = IO_METHOD_MMAP;
- break;
-
- case 'r':
- io = IO_METHOD_READ;
- break;
-
- case 'u':
- io = IO_METHOD_USERPTR;
- break;
-
- case 'o':
- out_buf++;
- break;
-
- case 'f':
- force_format++;
- break;
-
- case 'c':
- errno = 0;
- frame_count = strtol(optarg, NULL, 0);
- if (errno)
- errno_exit(optarg);
- break;
-
- default:
- usage(stderr, argc, argv);
- exit(EXIT_FAILURE);
- }
- }
-
- open_device();
- init_device();
- start_capturing();
- mainloop();
- stop_capturing();
- uninit_device();
- close_device();
- fprintf(stderr, "\n");
- return 0;
-}
-</programlisting>
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
deleted file mode 100644
index 4101aeb5654..00000000000
--- a/Documentation/DocBook/media/v4l/common.xml
+++ /dev/null
@@ -1,1207 +0,0 @@
- <title>Common API Elements</title>
-
- <para>Programming a V4L2 device consists of these
-steps:</para>
-
- <itemizedlist>
- <listitem>
- <para>Opening the device</para>
- </listitem>
- <listitem>
- <para>Changing device properties, selecting a video and audio
-input, video standard, picture brightness a.&nbsp;o.</para>
- </listitem>
- <listitem>
- <para>Negotiating a data format</para>
- </listitem>
- <listitem>
- <para>Negotiating an input/output method</para>
- </listitem>
- <listitem>
- <para>The actual input/output loop</para>
- </listitem>
- <listitem>
- <para>Closing the device</para>
- </listitem>
- </itemizedlist>
-
- <para>In practice most steps are optional and can be executed out of
-order. It depends on the V4L2 device type, you can read about the
-details in <xref linkend="devices" />. In this chapter we will discuss
-the basic concepts applicable to all devices.</para>
-
- <section id="open">
- <title>Opening and Closing Devices</title>
-
- <section>
- <title>Device Naming</title>
-
- <para>V4L2 drivers are implemented as kernel modules, loaded
-manually by the system administrator or automatically when a device is
-first opened. The driver modules plug into the "videodev" kernel
-module. It provides helper functions and a common application
-interface specified in this document.</para>
-
- <para>Each driver thus loaded registers one or more device nodes
-with major number 81 and a minor number between 0 and 255. Assigning
-minor numbers to V4L2 devices is entirely up to the system administrator,
-this is primarily intended to solve conflicts between devices.<footnote>
- <para>Access permissions are associated with character
-device special files, hence we must ensure device numbers cannot
-change with the module load order. To this end minor numbers are no
-longer automatically assigned by the "videodev" module as in V4L but
-requested by the driver. The defaults will suffice for most people
-unless two drivers compete for the same minor numbers.</para>
- </footnote> The module options to select minor numbers are named
-after the device special file with a "_nr" suffix. For example "video_nr"
-for <filename>/dev/video</filename> video capture devices. The number is
-an offset to the base minor number associated with the device type.
-<footnote>
- <para>In earlier versions of the V4L2 API the module options
-where named after the device special file with a "unit_" prefix, expressing
-the minor number itself, not an offset. Rationale for this change is unknown.
-Lastly the naming and semantics are just a convention among driver writers,
-the point to note is that minor numbers are not supposed to be hardcoded
-into drivers.</para>
- </footnote> When the driver supports multiple devices of the same
-type more than one minor number can be assigned, separated by commas:
-<informalexample>
- <screen>
-&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
- </informalexample></para>
-
- <para>In <filename>/etc/modules.conf</filename> this may be
-written as: <informalexample>
- <screen>
-alias char-major-81-0 mydriver
-alias char-major-81-1 mydriver
-alias char-major-81-64 mydriver <co id="alias" />
-options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" />
- </screen>
- <calloutlist>
- <callout arearefs="alias">
- <para>When an application attempts to open a device
-special file with major number 81 and minor number 0, 1, or 64, load
-"mydriver" (and the "videodev" module it depends upon).</para>
- </callout>
- <callout arearefs="options">
- <para>Register the first two video capture devices with
-minor number 0 and 1 (base number is 0), the first two radio device
-with minor number 64 and 65 (base 64).</para>
- </callout>
- </calloutlist>
- </informalexample> When no minor number is given as module
-option the driver supplies a default. <xref linkend="devices" />
-recommends the base minor numbers to be used for the various device
-types. Obviously minor numbers must be unique. When the number is
-already in use the <emphasis>offending device</emphasis> will not be
-registered. <!-- Blessed by Linus Torvalds on
-linux-kernel@vger.kernel.org, 2002-11-20. --></para>
-
- <para>By convention system administrators create various
-character device special files with these major and minor numbers in
-the <filename>/dev</filename> directory. The names recommended for the
-different V4L2 device types are listed in <xref linkend="devices" />.
-</para>
-
- <para>The creation of character special files (with
-<application>mknod</application>) is a privileged operation and
-devices cannot be opened by major and minor number. That means
-applications cannot <emphasis>reliable</emphasis> scan for loaded or
-installed drivers. The user must enter a device name, or the
-application can try the conventional device names.</para>
-
- <para>Under the device filesystem (devfs) the minor number
-options are ignored. V4L2 drivers (or by proxy the "videodev" module)
-automatically create the required device files in the
-<filename>/dev/v4l</filename> directory using the conventional device
-names above.</para>
- </section>
-
- <section id="related">
- <title>Related Devices</title>
-
- <para>Devices can support several related functions. For example
-video capturing, video overlay and VBI capturing are related because
-these functions share, amongst other, the same video input and tuner
-frequency. V4L and earlier versions of V4L2 used the same device name
-and minor number for video capturing and overlay, but different ones
-for VBI. Experience showed this approach has several problems<footnote>
- <para>Given a device file name one cannot reliable find
-related devices. For once names are arbitrary and in a system with
-multiple devices, where only some support VBI capturing, a
-<filename>/dev/video2</filename> is not necessarily related to
-<filename>/dev/vbi2</filename>. The V4L
-<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
-device file with a particular major and minor number.</para>
- </footnote>, and to make things worse the V4L videodev module
-used to prohibit multiple opens of a device.</para>
-
- <para>As a remedy the present version of the V4L2 API relaxed the
-concept of device types with specific names and minor numbers. For
-compatibility with old applications drivers must still register different
-minor numbers to assign a default function to the device. But if related
-functions are supported by the driver they must be available under all
-registered minor numbers. The desired function can be selected after
-opening the device as described in <xref linkend="devices" />.</para>
-
- <para>Imagine a driver supporting video capturing, video
-overlay, raw VBI capturing, and FM radio reception. It registers three
-devices with minor number 0, 64 and 224 (this numbering scheme is
-inherited from the V4L API). Regardless if
-<filename>/dev/video</filename> (81, 0) or
-<filename>/dev/vbi</filename> (81, 224) is opened the application can
-select any one of the video capturing, overlay or VBI capturing
-functions. Without programming (e.&nbsp;g. reading from the device
-with <application>dd</application> or <application>cat</application>)
-<filename>/dev/video</filename> captures video images, while
-<filename>/dev/vbi</filename> captures raw VBI data.
-<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
-unrelated to the video functions. Being unrelated does not imply the
-devices can be used at the same time, however. The &func-open;
-function may very well return an &EBUSY;.</para>
-
- <para>Besides video input or output the hardware may also
-support audio sampling or playback. If so, these functions are
-implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
-audio mixer. The V4L2 API makes no provisions yet to find these
-related devices. If you have an idea please write to the linux-media
-mailing list: &v4l-ml;.</para>
- </section>
-
- <section>
- <title>Multiple Opens</title>
-
- <para>In general, V4L2 devices can be opened more than once.
-When this is supported by the driver, users can for example start a
-"panel" application to change controls like brightness or audio
-volume, while another application captures video and audio. In other words, panel
-applications are comparable to an OSS or ALSA audio mixer application.
-When a device supports multiple functions like capturing and overlay
-<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
-use of the device by forked processes or specialized applications.</para>
-
- <para>Multiple opens are optional, although drivers should
-permit at least concurrent accesses without data exchange, &ie; panel
-applications. This implies &func-open; can return an &EBUSY; when the
-device is already in use, as well as &func-ioctl; functions initiating
-data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
-and &func-write; functions.</para>
-
- <para>Mere opening a V4L2 device does not grant exclusive
-access.<footnote>
- <para>Drivers could recognize the
-<constant>O_EXCL</constant> open flag. Presently this is not required,
-so applications cannot know if it really works.</para>
- </footnote> Initiating data exchange however assigns the right
-to read or write the requested type of data, and to change related
-properties, to this file descriptor. Applications can request
-additional access privileges using the priority mechanism described in
-<xref linkend="app-pri" />.</para>
- </section>
-
- <section>
- <title>Shared Data Streams</title>
-
- <para>V4L2 drivers should not support multiple applications
-reading or writing the same data stream on a device by copying
-buffers, time multiplexing or similar means. This is better handled by
-a proxy application in user space. When the driver supports stream
-sharing anyway it must be implemented transparently. The V4L2 API does
-not specify how conflicts are solved. <!-- For example O_EXCL when the
-application does not want to be preempted, PROT_READ mmapped buffers
-which can be mapped twice, what happens when image formats do not
-match etc.--></para>
- </section>
-
- <section>
- <title>Functions</title>
-
- <para>To open and close V4L2 devices applications use the
-&func-open; and &func-close; function, respectively. Devices are
-programmed using the &func-ioctl; function as explained in the
-following sections.</para>
- </section>
- </section>
-
- <section id="querycap">
- <title>Querying Capabilities</title>
-
- <para>Because V4L2 covers a wide variety of devices not all
-aspects of the API are equally applicable to all types of devices.
-Furthermore devices of the same type have different capabilities and
-this specification permits the omission of a few complicated and less
-important parts of the API.</para>
-
- <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
-device is compatible with this specification, and to query the <link
-linkend="devices">functions</link> and <link linkend="io">I/O
-methods</link> supported by the device.</para>
-
- <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
-V4L2 API version used by the driver, with generally matches the Kernel version.
-There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is
-supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide
-support for an ioctl.</para>
-
- <para>Other features can be queried
-by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
-to learn about the number, types and names of video connectors on the
-device. Although abstraction is a major objective of this API, the
-ioctl also allows driver specific applications to reliable identify
-the driver.</para>
-
- <para>All V4L2 drivers must support
-<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
-this ioctl after opening the device.</para>
- </section>
-
- <section id="app-pri">
- <title>Application Priority</title>
-
- <para>When multiple applications share a device it may be
-desirable to assign them different priorities. Contrary to the
-traditional "rm -rf /" school of thought a video recording application
-could for example block other applications from changing video
-controls or switching the current TV channel. Another objective is to
-permit low priority applications working in background, which can be
-preempted by user controlled applications and automatically regain
-control of the device at a later time.</para>
-
- <para>Since these features cannot be implemented entirely in user
-space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
-ioctls to request and query the access priority associate with a file
-descriptor. Opening a device assigns a medium priority, compatible
-with earlier versions of V4L2 and drivers not supporting these ioctls.
-Applications requiring a different priority will usually call
-<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
-the &VIDIOC-QUERYCAP; ioctl.</para>
-
- <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
-return an &EBUSY; after another application obtained higher priority.
-An event mechanism to notify applications about asynchronous property
-changes has been proposed but not added yet.</para>
- </section>
-
- <section id="video">
- <title>Video Inputs and Outputs</title>
-
- <para>Video inputs and outputs are physical connectors of a
-device. These can be for example RF connectors (antenna/cable), CVBS
-a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
-capture devices have inputs, output devices have outputs, at least one
-each. Radio devices have no video inputs or outputs.</para>
-
- <para>To learn about the number and attributes of the
-available inputs and outputs applications can enumerate them with the
-&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
-&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
-ioctl also contains signal status information applicable when the
-current video input is queried.</para>
-
- <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
-index of the current video input or output. To select a different
-input or output applications call the &VIDIOC-S-INPUT; and
-&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
-when the device has one or more inputs, all the output ioctls when the
-device has one or more outputs.</para>
-
- <!--
- <figure id=io-tree>
- <title>Input and output enumeration is the root of most device properties.</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="links.pdf" format="ps" />
- </imageobject>
- <imageobject>
- <imagedata fileref="links.gif" format="gif" />
- </imageobject>
- <textobject>
- <phrase>Links between various device property structures.</phrase>
- </textobject>
- </mediaobject>
- </figure>
- -->
-
- <example>
- <title>Information about the current video input</title>
-
- <programlisting>
-&v4l2-input; input;
-int index;
-
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
- perror ("VIDIOC_G_INPUT");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;input, 0, sizeof (input));
-input.index = index;
-
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror ("VIDIOC_ENUMINPUT");
- exit (EXIT_FAILURE);
-}
-
-printf ("Current input: %s\n", input.name);
- </programlisting>
- </example>
-
- <example>
- <title>Switching to the first video input</title>
-
- <programlisting>
-int index;
-
-index = 0;
-
-if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
- perror ("VIDIOC_S_INPUT");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
-
- <section id="audio">
- <title>Audio Inputs and Outputs</title>
-
- <para>Audio inputs and outputs are physical connectors of a
-device. Video capture devices have inputs, output devices have
-outputs, zero or more each. Radio devices have no audio inputs or
-outputs. They have exactly one tuner which in fact
-<emphasis>is</emphasis> an audio source, but this API associates
-tuners with video inputs or outputs only, and radio devices have
-none of these.<footnote>
- <para>Actually &v4l2-audio; ought to have a
-<structfield>tuner</structfield> field like &v4l2-input;, not only
-making the API more consistent but also permitting radio devices with
-multiple tuners.</para>
- </footnote> A connector on a TV card to loop back the received
-audio signal to a sound card is not considered an audio output.</para>
-
- <para>Audio and video inputs and outputs are associated. Selecting
-a video source also selects an audio source. This is most evident when
-the video and audio source is a tuner. Further audio connectors can
-combine with more than one video input or output. Assumed two
-composite video inputs and two audio inputs exist, there may be up to
-four valid combinations. The relation of video and audio connectors
-is defined in the <structfield>audioset</structfield> field of the
-respective &v4l2-input; or &v4l2-output;, where each bit represents
-the index number, starting at zero, of one audio input or output.</para>
-
- <para>To learn about the number and attributes of the
-available inputs and outputs applications can enumerate them with the
-&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
-&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
-also contains signal status information applicable when the current
-audio input is queried.</para>
-
- <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
-the current audio input and output, respectively. Note that, unlike
-&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
-as <constant>VIDIOC_ENUMAUDIO</constant> and
-<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
-
- <para>To select an audio input and change its properties
-applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
-output (which presently has no changeable properties) applications
-call the &VIDIOC-S-AUDOUT; ioctl.</para>
-
- <para>Drivers must implement all input ioctls when the device
-has one or more inputs, all output ioctls when the device has one
-or more outputs. When the device has any audio inputs or outputs the
-driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
-&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
-
- <example>
- <title>Information about the current audio input</title>
-
- <programlisting>
-&v4l2-audio; audio;
-
-memset (&amp;audio, 0, sizeof (audio));
-
-if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
- perror ("VIDIOC_G_AUDIO");
- exit (EXIT_FAILURE);
-}
-
-printf ("Current input: %s\n", audio.name);
- </programlisting>
- </example>
-
- <example>
- <title>Switching to the first audio input</title>
-
- <programlisting>
-&v4l2-audio; audio;
-
-memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
-
-audio.index = 0;
-
-if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
- perror ("VIDIOC_S_AUDIO");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
-
- <section id="tuner">
- <title>Tuners and Modulators</title>
-
- <section>
- <title>Tuners</title>
-
- <para>Video input devices can have one or more tuners
-demodulating a RF signal. Each tuner is associated with one or more
-video inputs, depending on the number of RF connectors on the tuner.
-The <structfield>type</structfield> field of the respective
-&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
-<constant>V4L2_INPUT_TYPE_TUNER</constant> and its
-<structfield>tuner</structfield> field contains the index number of
-the tuner.</para>
-
- <para>Radio devices have exactly one tuner with index zero, no
-video inputs.</para>
-
- <para>To query and change tuner properties applications use the
-&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
-&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
-contains signal status information applicable when the tuner of the
-current video input, or a radio tuner is queried. Note that
-<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
-when there is more than one at all. The tuner is solely determined by
-the current video input. Drivers must support both ioctls and set the
-<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
-more tuners.</para>
- </section>
-
- <section>
- <title>Modulators</title>
-
- <para>Video output devices can have one or more modulators, uh,
-modulating a video signal for radiation or connection to the antenna
-input of a TV set or video recorder. Each modulator is associated with
-one or more video outputs, depending on the number of RF connectors on
-the modulator. The <structfield>type</structfield> field of the
-respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
-set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
-<structfield>modulator</structfield> field contains the index number
-of the modulator. This specification does not define radio output
-devices.</para>
-
- <para>To query and change modulator properties applications use
-the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
-<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
-modulator, when there is more than one at all. The modulator is solely
-determined by the current video output. Drivers must support both
-ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
-the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
-device has one or more modulators.</para>
- </section>
-
- <section>
- <title>Radio Frequency</title>
-
- <para>To get and set the tuner or modulator radio frequency
-applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
-ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
-are used for TV and radio devices alike. Drivers must support both
-ioctls when the tuner or modulator ioctls are supported, or
-when the device is a radio device.</para>
- </section>
- </section>
-
- <section id="standard">
- <title>Video Standards</title>
-
- <para>Video devices typically support one or more different video
-standards or variations of standards. Each video input and output may
-support another set of standards. This set is reported by the
-<structfield>std</structfield> field of &v4l2-input; and
-&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
-&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
-
- <para>V4L2 defines one bit for each analog video standard
-currently in use worldwide, and sets aside bits for driver defined
-standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
-and vice versa. Applications can use the predefined bits to select a
-particular standard, although presenting the user a menu of supported
-standards is preferred. To enumerate and query the attributes of the
-supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
-
- <para>Many of the defined standards are actually just variations
-of a few major standards. The hardware may in fact not distinguish
-between them, or do so internal and switch automatically. Therefore
-enumerated standards also contain sets of one or more standard
-bits.</para>
-
- <para>Assume a hypothetic tuner capable of demodulating B/PAL,
-G/PAL and I/PAL signals. The first enumerated standard is a set of B
-and G/PAL, switched automatically depending on the selected radio
-frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
-choice. Similar a Composite input may collapse standards, enumerating
-"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
- <para>Some users are already confused by technical terms PAL,
-NTSC and SECAM. There is no point asking them to distinguish between
-B, G, D, or K when the software or hardware can do that
-automatically.</para>
- </footnote></para>
-
- <para>To query and select the standard used by the current video
-input or output applications call the &VIDIOC-G-STD; and
-&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
-standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
- <para>An alternative to the current scheme is to use pointers
-to indices as arguments of <constant>VIDIOC_G_STD</constant> and
-<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
-&v4l2-output; <structfield>std</structfield> field would be a set of
-indices like <structfield>audioset</structfield>.</para>
- <para>Indices are consistent with the rest of the API
-and identify the standard unambiguously. In the present scheme of
-things an enumerated standard is looked up by &v4l2-std-id;. Now the
-standards supported by the inputs of a device can overlap. Just
-assume the tuner and composite input in the example above both
-exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
-a choice which does not exist. We cannot merge or omit sets, because
-applications would be unable to find the standards reported by
-<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
-for each input. Also selecting a standard by &v4l2-std-id; can be
-ambiguous. Advantage of this method is that applications need not
-identify the standard indirectly, after enumerating.</para><para>So in
-summary, the lookup itself is unavoidable. The difference is only
-whether the lookup is necessary to find an enumerated standard or to
-switch to a standard by &v4l2-std-id;.</para>
- </footnote> Drivers must implement all video standard ioctls
-when the device has one or more video inputs or outputs.</para>
-
- <para>Special rules apply to USB cameras where the notion of video
-standards makes little sense. More generally any capture device,
-output devices accordingly, which is <itemizedlist>
- <listitem>
- <para>incapable of capturing fields or frames at the nominal
-rate of the video standard, or</para>
- </listitem>
- <listitem>
- <para>where <link linkend="buffer">timestamps</link> refer
-to the instant the field or frame was received by the driver, not the
-capture time, or</para>
- </listitem>
- <listitem>
- <para>where <link linkend="buffer">sequence numbers</link>
-refer to the frames received by the driver, not the captured
-frames.</para>
- </listitem>
- </itemizedlist> Here the driver shall set the
-<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
-to zero, the <constant>VIDIOC_G_STD</constant>,
-<constant>VIDIOC_S_STD</constant>,
-<constant>VIDIOC_QUERYSTD</constant> and
-<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
-&EINVAL;.<footnote>
- <para>See <xref linkend="buffer" /> for a rationale. Probably
-even USB cameras follow some well known video standard. It might have
-been better to explicitly indicate elsewhere if a device cannot live
-up to normal expectations, instead of this exception.</para>
- </footnote></para>
-
- <example>
- <title>Information about the current video standard</title>
-
- <programlisting>
-&v4l2-std-id; std_id;
-&v4l2-standard; standard;
-
-if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
- /* Note when VIDIOC_ENUMSTD always returns EINVAL this
- is no video device or it falls under the USB exception,
- and VIDIOC_G_STD returning EINVAL is no error. */
-
- perror ("VIDIOC_G_STD");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;standard, 0, sizeof (standard));
-standard.index = 0;
-
-while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
- if (standard.id &amp; std_id) {
- printf ("Current video standard: %s\n", standard.name);
- exit (EXIT_SUCCESS);
- }
-
- standard.index++;
-}
-
-/* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
-if (errno == EINVAL || standard.index == 0) {
- perror ("VIDIOC_ENUMSTD");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Listing the video standards supported by the current
-input</title>
-
- <programlisting>
-&v4l2-input; input;
-&v4l2-standard; standard;
-
-memset (&amp;input, 0, sizeof (input));
-
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
- perror ("VIDIOC_G_INPUT");
- exit (EXIT_FAILURE);
-}
-
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror ("VIDIOC_ENUM_INPUT");
- exit (EXIT_FAILURE);
-}
-
-printf ("Current input %s supports:\n", input.name);
-
-memset (&amp;standard, 0, sizeof (standard));
-standard.index = 0;
-
-while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
- if (standard.id &amp; input.std)
- printf ("%s\n", standard.name);
-
- standard.index++;
-}
-
-/* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
-if (errno != EINVAL || standard.index == 0) {
- perror ("VIDIOC_ENUMSTD");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Selecting a new video standard</title>
-
- <programlisting>
-&v4l2-input; input;
-&v4l2-std-id; std_id;
-
-memset (&amp;input, 0, sizeof (input));
-
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
- perror ("VIDIOC_G_INPUT");
- exit (EXIT_FAILURE);
-}
-
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
- perror ("VIDIOC_ENUM_INPUT");
- exit (EXIT_FAILURE);
-}
-
-if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
- fprintf (stderr, "Oops. B/G PAL is not supported.\n");
- exit (EXIT_FAILURE);
-}
-
-/* Note this is also supposed to work when only B
- <emphasis>or</emphasis> G/PAL is supported. */
-
-std_id = V4L2_STD_PAL_BG;
-
-if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
- perror ("VIDIOC_S_STD");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
- </section>
- <section id="dv-timings">
- <title>Digital Video (DV) Timings</title>
- <para>
- The video standards discussed so far have been dealing with Analog TV and the
-corresponding video timings. Today there are many more different hardware interfaces
-such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
-video signals and there is a need to extend the API to select the video timings
-for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
-the limited bits available, a new set of IOCTLs was added to set/get video timings at
-the input and output: </para><itemizedlist>
- <listitem>
- <para>DV Timings: This will allow applications to define detailed
-video timings for the interface. This includes parameters such as width, height,
-polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
-header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
-<xref linkend="vesadmt" /> standards.
- </para>
- </listitem>
- <listitem>
- <para>DV Presets: Digital Video (DV) presets (<emphasis role="bold">deprecated</emphasis>).
- These are IDs representing a
-video timing at the input/output. Presets are pre-defined timings implemented
-by the hardware according to video standards. A __u32 data type is used to represent
-a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
-to support as many different presets as needed. This API is deprecated in favor of the DV Timings
-API.</para>
- </listitem>
- </itemizedlist>
- <para>To enumerate and query the attributes of the DV timings supported by a device,
- applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
- To set DV timings for the device, applications use the
-&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
-&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
-use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
- <para>To enumerate and query the attributes of DV presets supported by a device,
-applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
-applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
-&VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications
-use the &VIDIOC-QUERY-DV-PRESET; ioctl.</para>
- <para>Applications can make use of the <xref linkend="input-capabilities" /> and
-<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
-video timings for the device.</para>
- </section>
-
- &sub-controls;
-
- <section id="format">
- <title>Data Formats</title>
-
- <section>
- <title>Data Format Negotiation</title>
-
- <para>Different devices exchange different kinds of data with
-applications, for example video images, raw or sliced VBI data, RDS
-datagrams. Even within one kind many different formats are possible,
-in particular an abundance of image formats. Although drivers must
-provide a default and the selection persists across closing and
-reopening a device, applications should always negotiate a data format
-before engaging in data exchange. Negotiation means the application
-asks for a particular format and the driver selects and reports the
-best the hardware can do to satisfy the request. Of course
-applications can also just query the current selection.</para>
-
- <para>A single mechanism exists to negotiate all data formats
-using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
-&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
-used to examine what the hardware <emphasis>could</emphasis> do,
-without actually selecting a new data format. The data formats
-supported by the V4L2 API are covered in the respective device section
-in <xref linkend="devices" />. For a closer look at image formats see
-<xref linkend="pixfmt" />.</para>
-
- <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
-turning-point in the initialization sequence. Prior to this point
-multiple panel applications can access the same device concurrently to
-select the current input, change controls or modify other properties.
-The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
-(video data, VBI data etc.) exclusively to one file descriptor.</para>
-
- <para>Exclusive means no other application, more precisely no
-other file descriptor, can grab this stream or change device
-properties inconsistent with the negotiated parameters. A video
-standard change for example, when the new standard uses a different
-number of scan lines, can invalidate the selected image format.
-Therefore only the file descriptor owning the stream can make
-invalidating changes. Accordingly multiple file descriptors which
-grabbed different logical streams prevent each other from interfering
-with their settings. When for example video overlay is about to start
-or already in progress, simultaneous video capturing may be restricted
-to the same cropping and image size.</para>
-
- <para>When applications omit the
-<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
-implied by the next step, the selection of an I/O method with the
-&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
-&func-write; call.</para>
-
- <para>Generally only one logical stream can be assigned to a
-file descriptor, the exception being drivers permitting simultaneous
-video capturing and overlay using the same file descriptor for
-compatibility with V4L and earlier versions of V4L2. Switching the
-logical stream or returning into "panel mode" is possible by closing
-and reopening the device. Drivers <emphasis>may</emphasis> support a
-switch using <constant>VIDIOC_S_FMT</constant>.</para>
-
- <para>All drivers exchanging data with
-applications must support the <constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
-<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
-optional.</para>
- </section>
-
- <section>
- <title>Image Format Enumeration</title>
-
- <para>Apart of the generic format negotiation functions
-a special ioctl to enumerate all image formats supported by video
-capture, overlay or output devices is available.<footnote>
- <para>Enumerating formats an application has no a-priori
-knowledge of (otherwise it could explicitly ask for them and need not
-enumerate) seems useless, but there are applications serving as proxy
-between drivers and the actual video applications for which this is
-useful.</para>
- </footnote></para>
-
- <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
-by all drivers exchanging image data with applications.</para>
-
- <important>
- <para>Drivers are not supposed to convert image formats in
-kernel space. They must enumerate only formats directly supported by
-the hardware. If necessary driver writers should publish an example
-conversion routine or library for integration into applications.</para>
- </important>
- </section>
- </section>
-
- &sub-planar-apis;
-
- <section id="crop">
- <title>Image Cropping, Insertion and Scaling</title>
-
- <para>Some video capture devices can sample a subsection of the
-picture and shrink or enlarge it to an image of arbitrary size. We
-call these abilities cropping and scaling. Some video output devices
-can scale an image up or down and insert it at an arbitrary scan line
-and horizontal offset into a video signal.</para>
-
- <para>Applications can use the following API to select an area in
-the video signal, query the default area and the hardware limits.
-<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
-and &VIDIOC-S-CROP; ioctls apply to input as well as output
-devices.</emphasis></para>
-
- <para>Scaling requires a source and a target. On a video capture
-or overlay device the source is the video signal, and the cropping
-ioctls determine the area actually sampled. The target are images
-read by the application or overlaid onto the graphics screen. Their
-size (and position for an overlay) is negotiated with the
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
-
- <para>On a video output device the source are the images passed in
-by the application, and their size is again negotiated with the
-<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
-compressed video stream. The target is the video signal, and the
-cropping ioctls determine the area where the images are
-inserted.</para>
-
- <para>Source and target rectangles are defined even if the device
-does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
-ioctls. Their size (and position where applicable) will be fixed in
-this case. <emphasis>All capture and output device must support the
-<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
-determine if scaling takes place.</emphasis></para>
-
- <section>
- <title>Cropping Structures</title>
-
- <figure id="crop-scale">
- <title>Image Cropping, Insertion and Scaling</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="crop.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="crop.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>The cropping, insertion and scaling process</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>For capture devices the coordinates of the top left
-corner, width and height of the area which can be sampled is given by
-the <structfield>bounds</structfield> substructure of the
-&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
-ioctl. To support a wide range of hardware this specification does not
-define an origin or units. However by convention drivers should
-horizontally count unscaled samples relative to 0H (the leading edge
-of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
-Vertically ITU-R line
-numbers of the first field (<xref linkend="vbi-525" />, <xref
-linkend="vbi-625" />), multiplied by two if the driver can capture both
-fields.</para>
-
- <para>The top left corner, width and height of the source
-rectangle, that is the area actually sampled, is given by &v4l2-crop;
-using the same coordinate system as &v4l2-cropcap;. Applications can
-use the <constant>VIDIOC_G_CROP</constant> and
-<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
-rectangle. It must lie completely within the capture boundaries and
-the driver may further adjust the requested size and/or position
-according to hardware limitations.</para>
-
- <para>Each capture device has a default source rectangle, given
-by the <structfield>defrect</structfield> substructure of
-&v4l2-cropcap;. The center of this rectangle shall align with the
-center of the active picture area of the video signal, and cover what
-the driver writer considers the complete picture. Drivers shall reset
-the source rectangle to the default when the driver is first loaded,
-but not later.</para>
-
- <para>For output devices these structures and ioctls are used
-accordingly, defining the <emphasis>target</emphasis> rectangle where
-the images will be inserted into the video signal.</para>
-
- </section>
-
- <section>
- <title>Scaling Adjustments</title>
-
- <para>Video hardware can have various cropping, insertion and
-scaling limitations. It may only scale up or down, support only
-discrete scaling factors, or have different scaling abilities in
-horizontal and vertical direction. Also it may not support scaling at
-all. At the same time the &v4l2-crop; rectangle may have to be
-aligned, and both the source and target rectangles may have arbitrary
-upper and lower size limits. In particular the maximum
-<structfield>width</structfield> and <structfield>height</structfield>
-in &v4l2-crop; may be smaller than the
-&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
-usual, drivers are expected to adjust the requested parameters and
-return the actual values selected.</para>
-
- <para>Applications can change the source or the target rectangle
-first, as they may prefer a particular image size or a certain area in
-the video signal. If the driver has to adjust both to satisfy hardware
-limitations, the last requested rectangle shall take priority, and the
-driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
-ioctl however shall not change the driver state and therefore only
-adjust the requested rectangle.</para>
-
- <para>Suppose scaling on a video capture device is restricted to
-a factor 1:1 or 2:1 in either direction and the target image size must
-be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
-rectangle is set to defaults, which are also the upper limit in this
-example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
-application requests an image size of 300&nbsp;&times;&nbsp;225
-pixels, assuming video will be scaled down from the "full picture"
-accordingly. The driver sets the image size to the closest possible
-values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
-closest to the requested size, that is 608&nbsp;&times;&nbsp;224
-(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
-0,&nbsp;0 is still valid, thus unmodified. Given the default cropping
-rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
-application can easily propose another offset to center the cropping
-rectangle.</para>
-
- <para>Now the application may insist on covering an area using a
-picture aspect ratio closer to the original request, so it asks for a
-cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
-scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
-driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
-the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
-
- </section>
-
- <section>
- <title>Examples</title>
-
- <para>Source and target rectangles shall remain unchanged across
-closing and reopening a device, such that piping data into or out of a
-device will work without special preparations. More advanced
-applications should ensure the parameters are suitable before starting
-I/O.</para>
-
- <example>
- <title>Resetting the cropping parameters</title>
-
- <para>(A video capture device is assumed; change
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
-devices.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-crop.c = cropcap.defrect;
-
-/* Ignore if cropping is not supported (EINVAL). */
-
-if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
- &amp;&amp; errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
-}
- </programlisting>
- </example>
-
- <example>
- <title>Simple downscaling</title>
-
- <para>(A video capture device is assumed.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-format; format;
-
-reset_cropping_parameters ();
-
-/* Scale down to 1/4 size of full picture. */
-
-memset (&amp;format, 0, sizeof (format)); /* defaults */
-
-format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
-format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
-format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
-
-if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
- perror ("VIDIOC_S_FORMAT");
- exit (EXIT_FAILURE);
-}
-
-/* We could check the actual image size now, the actual scaling factor
- or if the driver can scale at all. */
- </programlisting>
- </example>
-
- <example>
- <title>Selecting an output area</title>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
-
-if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-
-crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
-crop.c = cropcap.defrect;
-
-/* Scale the width and height to 50 % of their original size
- and center the output. */
-
-crop.c.width /= 2;
-crop.c.height /= 2;
-crop.c.left += crop.c.width / 2;
-crop.c.top += crop.c.height / 2;
-
-/* Ignore if cropping is not supported (EINVAL). */
-
-if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
- &amp;&amp; errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
-}
-</programlisting>
- </example>
-
- <example>
- <title>Current scaling factor and pixel aspect</title>
-
- <para>(A video capture device is assumed.)</para>
-
- <programlisting>
-&v4l2-cropcap; cropcap;
-&v4l2-crop; crop;
-&v4l2-format; format;
-double hscale, vscale;
-double aspect;
-int dwidth, dheight;
-
-memset (&amp;cropcap, 0, sizeof (cropcap));
-cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
-}
-
-memset (&amp;crop, 0, sizeof (crop));
-crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
- if (errno != EINVAL) {
- perror ("VIDIOC_G_CROP");
- exit (EXIT_FAILURE);
- }
-
- /* Cropping not supported. */
- crop.c = cropcap.defrect;
-}
-
-memset (&amp;format, 0, sizeof (format));
-format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
-if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
- perror ("VIDIOC_G_FMT");
- exit (EXIT_FAILURE);
-}
-
-/* The scaling applied by the driver. */
-
-hscale = format.fmt.pix.width / (double) crop.c.width;
-vscale = format.fmt.pix.height / (double) crop.c.height;
-
-aspect = cropcap.pixelaspect.numerator /
- (double) cropcap.pixelaspect.denominator;
-aspect = aspect * hscale / vscale;
-
-/* Devices following ITU-R BT.601 do not capture
- square pixels. For playback on a computer monitor
- we should scale the images to this size. */
-
-dwidth = format.fmt.pix.width / aspect;
-dheight = format.fmt.pix.height;
- </programlisting>
- </example>
- </section>
- </section>
-
- &sub-selection-api;
-
- <section id="streaming-par">
- <title>Streaming Parameters</title>
-
- <para>Streaming parameters are intended to optimize the video
-capture process as well as I/O. Presently applications can request a
-high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
-
- <para>The current video standard determines a nominal number of
-frames per second. If less than this number of frames is to be
-captured or output, applications can request frame skipping or
-duplicating on the driver side. This is especially useful when using
-the &func-read; or &func-write;, which are not augmented by timestamps
-or sequence counters, and to avoid unnecessary data copying.</para>
-
- <para>Finally these ioctls can be used to determine the number of
-buffers used internally by a driver in read/write mode. For
-implications see the section discussing the &func-read;
-function.</para>
-
- <para>To get and set the streaming parameters applications call
-the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
-a pointer to a &v4l2-streamparm;, which contains a union holding
-separate parameters for input and output devices.</para>
-
- <para>These ioctls are optional, drivers need not implement
-them. If so, they return the &EINVAL;.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
deleted file mode 100644
index ea42ef82494..00000000000
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ /dev/null
@@ -1,2618 +0,0 @@
- <title>Changes</title>
-
- <para>The following chapters document the evolution of the V4L2 API,
-errata or extensions. They are also intended to help application and
-driver writers to port or update their code.</para>
-
- <section id="diff-v4l">
- <title>Differences between V4L and V4L2</title>
-
- <para>The Video For Linux API was first introduced in Linux 2.1 to
-unify and replace various TV and radio device related interfaces,
-developed independently by driver writers in prior years. Starting
-with Linux 2.5 the much improved V4L2 API replaces the V4L API.
-The support for the old V4L calls were removed from Kernel, but the
-library <xref linkend="libv4l" /> supports the conversion of a V4L
-API system call into a V4L2 one.</para>
-
- <section>
- <title>Opening and Closing Devices</title>
-
- <para>For compatibility reasons the character device file names
-recommended for V4L2 video capture, overlay, radio and raw
-vbi capture devices did not change from those used by V4L. They are
-listed in <xref linkend="devices" /> and below in <xref
- linkend="v4l-dev" />.</para>
-
- <para>The teletext devices (minor range 192-223) have been removed in
-V4L2 and no longer exist. There is no hardware available anymore for handling
-pure teletext. Instead raw or sliced VBI is used.</para>
-
- <para>The V4L <filename>videodev</filename> module automatically
-assigns minor numbers to drivers in load order, depending on the
-registered device type. We recommend that V4L2 drivers by default
-register devices with the same numbers, but the system administrator
-can assign arbitrary minor numbers using driver module options. The
-major device number remains 81.</para>
-
- <table id="v4l-dev">
- <title>V4L Device Types, Names and Numbers</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Device Type</entry>
- <entry>File Name</entry>
- <entry>Minor Numbers</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Video capture and overlay</entry>
- <entry><para><filename>/dev/video</filename> and
-<filename>/dev/bttv0</filename><footnote> <para>According to
-Documentation/devices.txt these should be symbolic links to
-<filename>/dev/video0</filename>. Note the original bttv interface is
-not compatible with V4L or V4L2.</para> </footnote>,
-<filename>/dev/video0</filename> to
-<filename>/dev/video63</filename></para></entry>
- <entry>0-63</entry>
- </row>
- <row>
- <entry>Radio receiver</entry>
- <entry><para><filename>/dev/radio</filename><footnote>
- <para>According to
-<filename>Documentation/devices.txt</filename> a symbolic link to
-<filename>/dev/radio0</filename>.</para>
- </footnote>, <filename>/dev/radio0</filename> to
-<filename>/dev/radio63</filename></para></entry>
- <entry>64-127</entry>
- </row>
- <row>
- <entry>Raw VBI capture</entry>
- <entry><para><filename>/dev/vbi</filename>,
-<filename>/dev/vbi0</filename> to
-<filename>/dev/vbi31</filename></para></entry>
- <entry>224-255</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>V4L prohibits (or used to prohibit) multiple opens of a
-device file. V4L2 drivers <emphasis>may</emphasis> support multiple
-opens, see <xref linkend="open" /> for details and consequences.</para>
-
- <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;.</para>
- </section>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
-equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
-
- <para>The <structfield>name</structfield> field in struct
-<structname>video_capability</structname> became
-<structfield>card</structfield> in &v4l2-capability;,
-<structfield>type</structfield> was replaced by
-<structfield>capabilities</structfield>. Note V4L2 does not
-distinguish between device types like this, better think of basic
-video input, video output and radio devices supporting a set of
-related functions like video capturing, video overlay and VBI
-capturing. See <xref linkend="open" /> for an
-introduction.<informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>struct
-<structname>video_capability</structname>
-<structfield>type</structfield></entry>
- <entry>&v4l2-capability;
-<structfield>capabilities</structfield> flags</entry>
- <entry>Purpose</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VID_TYPE_CAPTURE</constant></entry>
- <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
- <entry>The <link linkend="capture">video
-capture</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_TUNER</constant></entry>
- <entry><constant>V4L2_CAP_TUNER</constant></entry>
- <entry>The device has a <link linkend="tuner">tuner or
-modulator</link>.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_TELETEXT</constant></entry>
- <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
- <entry>The <link linkend="raw-vbi">raw VBI
-capture</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_OVERLAY</constant></entry>
- <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
- <entry>The <link linkend="overlay">video
-overlay</link> interface is supported.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
-field <structfield>capability</structfield> of
-&v4l2-framebuffer;</entry>
- <entry>Whether chromakey overlay is supported. For
-more information on overlay see
-<xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_CLIPPING</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
-and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
-<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
- <entry>Whether clipping the overlaid image is
-supported, see <xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_FRAMERAM</constant></entry>
- <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
-<emphasis>not set</emphasis> in field
-<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
- <entry>Whether overlay overwrites frame buffer memory,
-see <xref linkend="overlay" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_SCALES</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>This flag indicates if the hardware can scale
-images. The V4L2 API implies the scale factor by setting the cropping
-dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
-ioctl, respectively. The driver returns the closest sizes possible.
-For more information on cropping and scaling see <xref
- linkend="crop" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MONOCHROME</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can enumerate the supported image
-formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
-supports grey scale capturing only. For more information on image
-formats see <xref linkend="pixfmt" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can call the &VIDIOC-G-CROP; ioctl
-to determine if the device supports capturing a subsection of the full
-picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
-For more information on cropping and scaling see <xref
- linkend="crop" />.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>Applications can enumerate the supported image
-formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
-supports MPEG streams.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- <row>
- <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
- <entry><constant>-</constant></entry>
- <entry>See above.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The <structfield>audios</structfield> field was replaced
-by <structfield>capabilities</structfield> flag
-<constant>V4L2_CAP_AUDIO</constant>, indicating
-<emphasis>if</emphasis> the device has any audio inputs or outputs. To
-determine their number applications can enumerate audio inputs with
-the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
- linkend="audio" />.</para>
-
- <para>The <structfield>maxwidth</structfield>,
-<structfield>maxheight</structfield>,
-<structfield>minwidth</structfield> and
-<structfield>minheight</structfield> fields were removed. Calling the
-&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
-returns the closest size possible, taking into account the current
-video standard, cropping and scaling limitations.</para>
- </section>
-
- <section>
- <title>Video Sources</title>
-
- <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
-<constant>VIDIOCSCHAN</constant> ioctl using struct
-<structname>video_channel</structname> to enumerate
-the video inputs of a V4L device. The equivalent V4L2 ioctls
-are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
-using &v4l2-input; as discussed in <xref linkend="video" />.</para>
-
- <para>The <structfield>channel</structfield> field counting
-inputs was renamed to <structfield>index</structfield>, the video
-input types were renamed as follows: <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_channel</structname>
-<structfield>type</structfield></entry>
- <entry>&v4l2-input;
-<structfield>type</structfield></entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VIDEO_TYPE_TV</constant></entry>
- <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
- </row>
- <row>
- <entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
- <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>Unlike the <structfield>tuners</structfield> field
-expressing the number of tuners of this input, V4L2 assumes each video
-input is connected to at most one tuner. However a tuner can have more
-than one input, &ie; RF connectors, and a device can have multiple
-tuners. The index number of the tuner associated with the input, if
-any, is stored in field <structfield>tuner</structfield> of
-&v4l2-input;. Enumeration of tuners is discussed in <xref
- linkend="tuner" />.</para>
-
- <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
-dropped. Video inputs associated with a tuner are of type
-<constant>V4L2_INPUT_TYPE_TUNER</constant>. The
-<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
-<structfield>audioset</structfield> field. V4L2 considers devices with
-up to 32 audio inputs. Each set bit in the
-<structfield>audioset</structfield> field represents one audio input
-this video input combines with. For information about audio inputs and
-how to switch between them see <xref linkend="audio" />.</para>
-
- <para>The <structfield>norm</structfield> field describing the
-supported video standards was replaced by
-<structfield>std</structfield>. The V4L specification mentions a flag
-<constant>VIDEO_VC_NORM</constant> indicating whether the standard can
-be changed. This flag was a later addition together with the
-<structfield>norm</structfield> field and has been removed in the
-meantime. V4L2 has a similar, albeit more comprehensive approach
-to video standards, see <xref linkend="standard" /> for more
-information.</para>
- </section>
-
- <section>
- <title>Tuning</title>
-
- <para>The V4L <constant>VIDIOCGTUNER</constant> and
-<constant>VIDIOCSTUNER</constant> ioctl and struct
-<structname>video_tuner</structname> can be used to enumerate the
-tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
-&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
-covered in <xref linkend="tuner" />.</para>
-
- <para>The <structfield>tuner</structfield> field counting tuners
-was renamed to <structfield>index</structfield>. The fields
-<structfield>name</structfield>, <structfield>rangelow</structfield>
-and <structfield>rangehigh</structfield> remained unchanged.</para>
-
- <para>The <constant>VIDEO_TUNER_PAL</constant>,
-<constant>VIDEO_TUNER_NTSC</constant> and
-<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
-video standards were dropped. This information is now contained in the
-associated &v4l2-input;. No replacement exists for the
-<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
-video standard can be switched. The <structfield>mode</structfield>
-field to select a different video standard was replaced by a whole new
-set of ioctls and structures described in <xref linkend="standard" />.
-Due to its ubiquity it should be mentioned the BTTV driver supports
-several standards in addition to the regular
-<constant>VIDEO_MODE_PAL</constant> (0),
-<constant>VIDEO_MODE_NTSC</constant>,
-<constant>VIDEO_MODE_SECAM</constant> and
-<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
-M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
-
- <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
-indicating stereo reception became
-<constant>V4L2_TUNER_SUB_STEREO</constant> in field
-<structfield>rxsubchans</structfield>. This field also permits the
-detection of monaural and bilingual audio, see the definition of
-&v4l2-tuner; for details. Presently no replacement exists for the
-<constant>VIDEO_TUNER_RDS_ON</constant> and
-<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
-
- <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
-to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
-<structfield>capability</structfield> field.</para>
-
- <para>The <constant>VIDIOCGFREQ</constant> and
-<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
-where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They
-take a pointer to a &v4l2-frequency; instead of an unsigned long
-integer.</para>
- </section>
-
- <section id="v4l-image-properties">
- <title>Image Properties</title>
-
- <para>V4L2 has no equivalent of the
-<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
-ioctl and struct <structname>video_picture</structname>. The following
-fields where replaced by V4L2 controls accessible with the
-&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_picture</structname></entry>
- <entry>V4L2 Control ID</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><structfield>brightness</structfield></entry>
- <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
- </row>
- <row>
- <entry><structfield>hue</structfield></entry>
- <entry><constant>V4L2_CID_HUE</constant></entry>
- </row>
- <row>
- <entry><structfield>colour</structfield></entry>
- <entry><constant>V4L2_CID_SATURATION</constant></entry>
- </row>
- <row>
- <entry><structfield>contrast</structfield></entry>
- <entry><constant>V4L2_CID_CONTRAST</constant></entry>
- </row>
- <row>
- <entry><structfield>whiteness</structfield></entry>
- <entry><constant>V4L2_CID_WHITENESS</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The V4L picture controls are assumed to range from 0 to
-65535 with no particular reset value. The V4L2 API permits arbitrary
-limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
-ioctl. For general information about controls see <xref
-linkend="control" />.</para>
-
- <para>The <structfield>depth</structfield> (average number of
-bits per pixel) of a video image is implied by the selected image
-format. V4L2 does not explicitely provide such information assuming
-applications recognizing the format are aware of the image depth and
-others need not know. The <structfield>palette</structfield> field
-moved into the &v4l2-pix-format;:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct <structname>video_picture</structname>
-<structfield>palette</structfield></entry>
- <entry>&v4l2-pix-format;
-<structfield>pixfmt</structfield></entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>VIDEO_PALETTE_GREY</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_HI240</constant></entry>
- <entry><para><link
-linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
- <para>This is a custom format used by the BTTV
-driver, not one of the V4L2 standard formats.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
- <entry><para><link
-linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
- <para>Presumably all V4L RGB formats are
-little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue
-swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
- </row>
- <row>
- <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
- <para><constant>VIDEO_PALETTE_YUV422</constant>
-and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
-V4L drivers respond to one, some to the other.</para>
- </footnote></para></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
- <para>Not to be confused with
-<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
-format.</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_RAW</constant></entry>
- <entry><para>None<footnote> <para>V4L explains this
-as: "RAW capture (BT848)"</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
- <para>Not to be confused with
-<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
-format.</para> </footnote></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
- </row>
- <row>
- <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
- <entry><para><link
-linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>V4L2 image formats are defined in <xref
-linkend="pixfmt" />. The image format can be selected with the
-&VIDIOC-S-FMT; ioctl.</para>
- </section>
-
- <section>
- <title>Audio</title>
-
- <para>The <constant>VIDIOCGAUDIO</constant> and
-<constant>VIDIOCSAUDIO</constant> ioctl and struct
-<structname>video_audio</structname> are used to enumerate the
-audio inputs of a V4L device. The equivalent V4L2 ioctls are
-&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
-discussed in <xref linkend="audio" />.</para>
-
- <para>The <structfield>audio</structfield> "channel number"
-field counting audio inputs was renamed to
-<structfield>index</structfield>.</para>
-
- <para>On <constant>VIDIOCSAUDIO</constant> the
-<structfield>mode</structfield> field selects <emphasis>one</emphasis>
-of the <constant>VIDEO_SOUND_MONO</constant>,
-<constant>VIDEO_SOUND_STEREO</constant>,
-<constant>VIDEO_SOUND_LANG1</constant> or
-<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
-the current audio standard is BTSC
-<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
-<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
-undocumented in the V4L specification, there is no way to query the
-selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
-the <emphasis>actually received</emphasis> audio programmes in this
-field. In the V4L2 API this information is stored in the &v4l2-tuner;
-<structfield>rxsubchans</structfield> and
-<structfield>audmode</structfield> fields, respectively. See <xref
-linkend="tuner" /> for more information on tuners. Related to audio
-modes &v4l2-audio; also reports if this is a mono or stereo
-input, regardless if the source is a tuner.</para>
-
- <para>The following fields where replaced by V4L2 controls
-accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
-&VIDIOC-S-CTRL; ioctls:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>struct
-<structname>video_audio</structname></entry>
- <entry>V4L2 Control ID</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><structfield>volume</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
- </row>
- <row>
- <entry><structfield>bass</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
- </row>
- <row>
- <entry><structfield>treble</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
- </row>
- <row>
- <entry><structfield>balance</structfield></entry>
- <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>To determine which of these controls are supported by a
-driver V4L provides the <structfield>flags</structfield>
-<constant>VIDEO_AUDIO_VOLUME</constant>,
-<constant>VIDEO_AUDIO_BASS</constant>,
-<constant>VIDEO_AUDIO_TREBLE</constant> and
-<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
-&VIDIOC-QUERYCTRL; ioctl reports if the respective control is
-supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
-and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
-boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
-
- <para>All V4L2 controls have a <structfield>step</structfield>
-attribute replacing the struct <structname>video_audio</structname>
-<structfield>step</structfield> field. The V4L audio controls are
-assumed to range from 0 to 65535 with no particular reset value. The
-V4L2 API permits arbitrary limits and defaults which can be queried
-with the &VIDIOC-QUERYCTRL; ioctl. For general information about
-controls see <xref linkend="control" />.</para>
- </section>
-
- <section>
- <title>Frame Buffer Overlay</title>
-
- <para>The V4L2 ioctls equivalent to
-<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
-are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
-<structfield>base</structfield> field of struct
-<structname>video_buffer</structname> remained unchanged, except V4L2
-defines a flag to indicate non-destructive overlays instead of a
-<constant>NULL</constant> pointer. All other fields moved into the
-&v4l2-pix-format; <structfield>fmt</structfield> substructure of
-&v4l2-framebuffer;. The <structfield>depth</structfield> field was
-replaced by <structfield>pixelformat</structfield>. See <xref
- linkend="pixfmt-rgb" /> for a list of RGB formats and their
-respective color depths.</para>
-
- <para>Instead of the special ioctls
-<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
-V4L2 uses the general-purpose data format negotiation ioctls
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
-&v4l2-format; as argument. Here the <structfield>win</structfield>
-member of the <structfield>fmt</structfield> union is used, a
-&v4l2-window;.</para>
-
- <para>The <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> fields of struct
-<structname>video_window</structname> moved into &v4l2-rect;
-substructure <structfield>w</structfield> of struct
-<structname>v4l2_window</structname>. The
-<structfield>chromakey</structfield>,
-<structfield>clips</structfield>, and
-<structfield>clipcount</structfield> fields remained unchanged. Struct
-<structname>video_clip</structname> was renamed to &v4l2-clip;, also
-containing a struct <structname>v4l2_rect</structname>, but the
-semantics are still the same.</para>
-
- <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
-dropped. Instead applications must set the
-<structfield>field</structfield> field to
-<constant>V4L2_FIELD_ANY</constant> or
-<constant>V4L2_FIELD_INTERLACED</constant>. The
-<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
-&v4l2-framebuffer;, under the new name
-<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
-
- <para>In V4L, storing a bitmap pointer in
-<structfield>clips</structfield> and setting
-<structfield>clipcount</structfield> to
-<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
-clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
-<structname>v4l2_window</structname> has a separate
-<structfield>bitmap</structfield> pointer field for this purpose and
-the bitmap size is determined by <structfield>w.width</structfield> and
-<structfield>w.height</structfield>.</para>
-
- <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
-disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
- </section>
-
- <section>
- <title>Cropping</title>
-
- <para>To capture only a subsection of the full picture V4L
-defines the <constant>VIDIOCGCAPTURE</constant> and
-<constant>VIDIOCSCAPTURE</constant> ioctls using struct
-<structname>video_capture</structname>. The equivalent V4L2 ioctls are
-&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
-&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
-<xref linkend="crop" /> for details.</para>
-
- <para>The <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> fields moved into &v4l2-rect;
-substructure <structfield>c</structfield> of struct
-<structname>v4l2_crop</structname>. The
-<structfield>decimation</structfield> field was dropped. In the V4L2
-API the scaling factor is implied by the size of the cropping
-rectangle and the size of the captured or overlaid image.</para>
-
- <para>The <constant>VIDEO_CAPTURE_ODD</constant>
-and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
-odd or even field, respectively, were replaced by
-<constant>V4L2_FIELD_TOP</constant> and
-<constant>V4L2_FIELD_BOTTOM</constant> in the field named
-<structfield>field</structfield> of &v4l2-pix-format; and
-&v4l2-window;. These structures are used to select a capture or
-overlay format with the &VIDIOC-S-FMT; ioctl.</para>
- </section>
-
- <section>
- <title>Reading Images, Memory Mapping</title>
-
- <section>
- <title>Capturing using the read method</title>
-
- <para>There is no essential difference between reading images
-from a V4L or V4L2 device using the &func-read; function, however V4L2
-drivers are not required to support this I/O method. Applications can
-determine if the function is available with the &VIDIOC-QUERYCAP;
-ioctl. All V4L2 devices exchanging data with applications must support
-the &func-select; and &func-poll; functions.</para>
-
- <para>To select an image format and size, V4L provides the
-<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
-ioctls. V4L2 uses the general-purpose data format negotiation ioctls
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
-&v4l2-format; as argument, here the &v4l2-pix-format; named
-<structfield>pix</structfield> of its <structfield>fmt</structfield>
-union is used.</para>
-
- <para>For more information about the V4L2 read interface see
-<xref linkend="rw" />.</para>
- </section>
- <section>
- <title>Capturing using memory mapping</title>
-
- <para>Applications can read from V4L devices by mapping
-buffers in device memory, or more often just buffers allocated in
-DMA-able system memory, into their address space. This avoids the data
-copying overhead of the read method. V4L2 supports memory mapping as
-well, with a few differences.</para>
-
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>V4L</entry>
- <entry>V4L2</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry></entry>
- <entry>The image format must be selected before
-buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
-is selected the driver may use the last, possibly by another
-application requested format.</entry>
- </row>
- <row>
- <entry><para>Applications cannot change the number of
-buffers. The it is built into the driver, unless it has a module
-option to change the number when the driver module is
-loaded.</para></entry>
- <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
-desired number of buffers, this is a required step in the initialization
-sequence.</para></entry>
- </row>
- <row>
- <entry><para>Drivers map all buffers as one contiguous
-range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
-available to query the number of buffers, the offset of each buffer
-from the start of the virtual file, and the overall amount of memory
-used, which can be used as arguments for the &func-mmap;
-function.</para></entry>
- <entry><para>Buffers are individually mapped. The
-offset and size of each buffer can be determined with the
-&VIDIOC-QUERYBUF; ioctl.</para></entry>
- </row>
- <row>
- <entry><para>The <constant>VIDIOCMCAPTURE</constant>
-ioctl prepares a buffer for capturing. It also determines the image
-format for this buffer. The ioctl returns immediately, eventually with
-an &EAGAIN; if no video signal had been detected. When the driver
-supports more than one buffer applications can call the ioctl multiple
-times and thus have multiple outstanding capture
-requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
-suspends execution until a particular buffer has been
-filled.</para></entry>
- <entry><para>Drivers maintain an incoming and outgoing
-queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
-queue. Filled buffers are dequeued from the outgoing queue with the
-&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
-function, &func-select; or &func-poll; can be used. The
-&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
-more buffers to start capturing. Its counterpart
-&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
-queues. Applications can query the signal status, if known, with the
-&VIDIOC-ENUMINPUT; ioctl.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>For a more in-depth discussion of memory mapping and
-examples, see <xref linkend="mmap" />.</para>
- </section>
- </section>
-
- <section>
- <title>Reading Raw VBI Data</title>
-
- <para>Originally the V4L API did not specify a raw VBI capture
-interface, only the device file <filename>/dev/vbi</filename> was
-reserved for this purpose. The only driver supporting this interface
-was the BTTV driver, de-facto defining the V4L VBI interface. Reading
-from the device yields a raw VBI image with the following
-parameters:<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>&v4l2-vbi-format;</entry>
- <entry>V4L, BTTV driver</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>sampling_rate</entry>
- <entry>28636363&nbsp;Hz NTSC (or any other 525-line
-standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
- </row>
- <row>
- <entry>offset</entry>
- <entry>?</entry>
- </row>
- <row>
- <entry>samples_per_line</entry>
- <entry>2048</entry>
- </row>
- <row>
- <entry>sample_format</entry>
- <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
-machine endianness integer) contain a frame counter.</entry>
- </row>
- <row>
- <entry>start[]</entry>
- <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
- </row>
- <row>
- <entry>count[]</entry>
- <entry><para>16, 16<footnote><para>Old driver
-versions used different values, eventually the custom
-<constant>BTTV_VBISIZE</constant> ioctl was added to query the
-correct values.</para></footnote></para></entry>
- </row>
- <row>
- <entry>flags</entry>
- <entry>0</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>Undocumented in the V4L specification, in Linux 2.3 the
-<constant>VIDIOCGVBIFMT</constant> and
-<constant>VIDIOCSVBIFMT</constant> ioctls using struct
-<structname>vbi_format</structname> were added to determine the VBI
-image parameters. These ioctls are only partially compatible with the
-V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
-
- <para>An <structfield>offset</structfield> field does not
-exist, <structfield>sample_format</structfield> is supposed to be
-<constant>VIDEO_PALETTE_RAW</constant>, equivalent to
-<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
-probably equivalent to &v4l2-vbi-format;.</para>
-
- <para>Apparently only the Zoran (ZR 36120) driver implements
-these ioctls. The semantics differ from those specified for V4L2 in two
-ways. The parameters are reset on &func-open; and
-<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
-parameters are invalid.</para>
- </section>
-
- <section>
- <title>Miscellaneous</title>
-
- <para>V4L2 has no equivalent of the
-<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI
-device associated with a video capture device (or vice versa) by
-reopening the device and requesting VBI data. For details see
-<xref linkend="open" />.</para>
-
- <para>No replacement exists for <constant>VIDIOCKEY</constant>,
-and the V4L functions for microcode programming. A new interface for
-MPEG compression and playback devices is documented in <xref
- linkend="extended-controls" />.</para>
- </section>
-
- </section>
-
- <section id="hist-v4l2">
- <title>Changes of the V4L2 API</title>
-
- <para>Soon after the V4L API was added to the kernel it was
-criticised as too inflexible. In August 1998 Bill Dirks proposed a
-number of improvements and began to work on documentation, example
-drivers and applications. With the help of other volunteers this
-eventually became the V4L2 API, not just an extension but a
-replacement for the V4L API. However it took another four years and
-two stable kernel releases until the new API was finally accepted for
-inclusion into the kernel in its present form.</para>
-
- <section>
- <title>Early Versions</title>
- <para>1998-08-20: First version.</para>
-
- <para>1998-08-27: The &func-select; function was introduced.</para>
-
- <para>1998-09-10: New video standard interface.</para>
-
- <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
-was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
-&func-open; flag, and the aliases <constant>O_NONCAP</constant> and
-<constant>O_NOIO</constant> were defined. Applications can set this
-flag if they intend to access controls only, as opposed to capture
-applications which need exclusive access. The
-<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
-instead of flags, and the <function>video_std_construct()</function>
-helper function takes id and transmission arguments.</para>
-
- <para>1998-09-28: Revamped video standard. Made video controls
-individually enumerable.</para>
-
- <para>1998-10-02: The <structfield>id</structfield> field was
-removed from struct <structname>video_standard</structname> and the
-color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
-renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
-first draft of the Codec API was released.</para>
-
- <para>1998-11-08: Many minor changes. Most symbols have been
-renamed. Some material changes to &v4l2-capability;.</para>
-
- <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
-
- <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
-changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
-<constant>V4L2_PIX_FMT_RGB32</constant> changed to
-<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
-accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
-names starting with <constant>V4L2_CID_AUDIO</constant>. The
-<constant>V4L2_MAJOR</constant> define was removed from
-<filename>videodev.h</filename> since it was only used once in the
-<filename>videodev</filename> kernel module. The
-<constant>YUV422</constant> and <constant>YUV411</constant> planar
-image formats were added.</para>
-
- <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
-video output devices were added.</para>
-
- <para>1999-01-14: A raw VBI capture interface was added.</para>
-
- <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
- was removed.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.16 1999-01-31</title>
- <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
-are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
-digital zoom (cropping) controls.</para>
- </section>
-
- <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
- forgot to bump the version number or never released it. -->
-
- <section>
- <title>V4L2 Version 0.18 1999-03-16</title>
- <para>Added a v4l to V4L2 ioctl compatibility layer to
-videodev.c. Driver writers, this changes how you implement your ioctl
-handler. See the Driver Writer's Guide. Added some more control id
-codes.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.19 1999-06-05</title>
- <para>1999-03-18: Fill in the category and catname fields of
-v4l2_queryctrl objects before passing them to the driver. Required a
-minor change to the VIDIOC_QUERYCTRL handlers in the sample
-drivers.</para>
- <para>1999-03-31: Better compatibility for v4l memory capture
-ioctls. Requires changes to drivers to fully support new compatibility
-features, see Driver Writer's Guide and v4l2cap.c. Added new control
-IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
-and _YUV411P to _YUV411P.</para>
- <para>1999-04-04: Added a few more control IDs.</para>
- <para>1999-04-07: Added the button control type.</para>
- <para>1999-05-02: Fixed a typo in videodev.h, and added the
-V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
- <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
-a malfunction of this ioctl.</para>
- <para>1999-06-05: Changed the value of
-V4L2_CID_WHITENESS.</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 (1999-09-10)</title>
-
- <para>Version 0.20 introduced a number of changes which were
-<emphasis>not backward compatible</emphasis> with 0.19 and earlier
-versions. Purpose of these changes was to simplify the API, while
-making it more extensible and following common Linux driver API
-conventions.</para>
-
- <orderedlist>
- <listitem>
- <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
-symbols were fixed. &v4l2-clip; was changed for compatibility with
-v4l. (1999-08-30)</para>
- </listitem>
-
- <listitem>
- <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
-(1999-09-05)</para>
- </listitem>
-
- <listitem>
- <para>All ioctl() commands that used an integer argument now
-take a pointer to an integer. Where it makes sense, ioctls will return
-the actual new value in the integer pointed to by the argument, a
-common convention in the V4L2 API. The affected ioctls are:
-VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
-VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
-<programlisting>
-err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
-</programlisting> becomes <programlisting>
-int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
-</programlisting>
- </para>
- </listitem>
-
- <listitem>
- <para>All the different get- and set-format commands were
-swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
-and a type field selecting the union member as parameter. Purpose is to
-simplify the API by eliminating several ioctls and to allow new and
-driver private data streams without adding new ioctls.</para>
-
- <para>This change obsoletes the following ioctls:
-<constant>VIDIOC_S_INFMT</constant>,
-<constant>VIDIOC_G_INFMT</constant>,
-<constant>VIDIOC_S_OUTFMT</constant>,
-<constant>VIDIOC_G_OUTFMT</constant>,
-<constant>VIDIOC_S_VBIFMT</constant> and
-<constant>VIDIOC_G_VBIFMT</constant>. The image format structure
-<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
-while &v4l2-format; is now the envelopping structure for all format
-negotiations.</para>
- </listitem>
-
- <listitem>
- <para>Similar to the changes above, the
-<constant>VIDIOC_G_PARM</constant> and
-<constant>VIDIOC_S_PARM</constant> ioctls were merged with
-<constant>VIDIOC_G_OUTPARM</constant> and
-<constant>VIDIOC_S_OUTPARM</constant>. A
-<structfield>type</structfield> field in the new &v4l2-streamparm;
-selects the respective union member.</para>
-
- <para>This change obsoletes the
-<constant>VIDIOC_G_OUTPARM</constant> and
-<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
- </listitem>
-
- <listitem>
- <para>Control enumeration was simplified, and two new
-control flags were introduced and one dropped. The
-<structfield>catname</structfield> field was replaced by a
-<structfield>group</structfield> field.</para>
-
- <para>Drivers can now flag unsupported and temporarily
-unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
-and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
-<structfield>group</structfield> name indicates a possibly narrower
-classification than the <structfield>category</structfield>. In other
-words, there may be multiple groups within a category. Controls within
-a group would typically be drawn within a group box. Controls in
-different categories might have a greater separation, or may even
-appear in separate windows.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-buffer; <structfield>timestamp</structfield>
-was changed to a 64 bit integer, containing the sampling or output
-time of the frame in nanoseconds. Additionally timestamps will be in
-absolute system time, not starting from zero at the beginning of a
-stream. The data type name for timestamps is stamp_t, defined as a
-signed 64-bit integer. Output devices should not send a buffer out
-until the time in the timestamp field has arrived. I would like to
-follow SGI's lead, and adopt a multimedia timestamping system like
-their UST (Unadjusted System Time). See
-http://web.archive.org/web/*/http://reality.sgi.com
-/cpirazzi_engr/lg/time/intro.html.
-UST uses timestamps that are 64-bit signed integers
-(not struct timeval's) and given in nanosecond units. The UST clock
-starts at zero when the system is booted and runs continuously and
-uniformly. It takes a little over 292 years for UST to overflow. There
-is no way to set the UST clock. The regular Linux time-of-day clock
-can be changed periodically, which would cause errors if it were being
-used for timestamping a multimedia stream. A real UST style clock will
-require some support in the kernel that is not there yet. But in
-anticipation, I will change the timestamp field to a 64-bit integer,
-and I will change the v4l2_masterclock_gettime() function (used only
-by drivers) to return a 64-bit integer.</para>
- </listitem>
-
- <listitem>
- <para>A <structfield>sequence</structfield> field was added
-to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
-captured frames, it is ignored by output devices. When a capture
-driver drops a frame, the sequence number of that frame is
-skipped.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 incremental changes</title>
- <!-- Version number didn't change anymore, reason unknown. -->
-
- <para>1999-12-23: In &v4l2-vbi-format; the
-<structfield>reserved1</structfield> field became
-<structfield>offset</structfield>. Previously drivers were required to
-clear the <structfield>reserved1</structfield> field.</para>
-
- <para>2000-01-13: The
- <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
-
- <para>2000-07-31: The <filename>linux/poll.h</filename> header
-is now included by <filename>videodev.h</filename> for compatibility
-with the original <filename>videodev.h</filename> file.</para>
-
- <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
-<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
-
- <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
-added.</para>
-
- <para>2000-12-04: A couple typos in symbol names were fixed.</para>
-
- <para>2001-01-18: To avoid namespace conflicts the
-<constant>fourcc</constant> macro defined in the
-<filename>videodev.h</filename> header file was renamed to
-<constant>v4l2_fourcc</constant>.</para>
-
- <para>2001-01-25: A possible driver-level compatibility problem
-between the <filename>videodev.h</filename> file in Linux 2.4.0 and
-the <filename>videodev.h</filename> file included in the
-<filename>videodevX</filename> patch was fixed. Users of an earlier
-version of <filename>videodevX</filename> on Linux 2.4.0 should
-recompile their V4L and V4L2 drivers.</para>
-
- <para>2001-01-26: A possible kernel-level incompatibility
-between the <filename>videodev.h</filename> file in the
-<filename>videodevX</filename> patch and the
-<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
-applied was fixed.</para>
-
- <para>2001-03-02: Certain V4L ioctls which pass data in both
-direction although they are defined with read-only parameter, did not
-work correctly through the backward compatibility layer.
-[Solution?]</para>
-
- <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
-
- <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
-&VIDIOC-S-FREQUENCY; ioctls were added. (The old
-<constant>VIDIOC_G_FREQ</constant> and
-<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
-into account.)</para>
-
- <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
-added. This may <emphasis>break compatibility</emphasis> as the
-&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
-<structname>v4l2_fmt</structname> <structfield>type</structfield>
-field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
-documentation of the &v4l2-vbi-format;
-<structfield>offset</structfield> field the ambiguous phrase "rising
-edge" was changed to "leading edge".</para>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 2000-11-23</title>
-
- <para>A number of changes were made to the raw VBI
-interface.</para>
-
- <orderedlist>
- <listitem>
- <para>Figures clarifying the line numbering scheme were
-added to the V4L2 API specification. The
-<structfield>start</structfield>[0] and
-<structfield>start</structfield>[1] fields no longer count line
-numbers beginning at zero. Rationale: a) The previous definition was
-unclear. b) The <structfield>start</structfield>[] values are ordinal
-numbers. c) There is no point in inventing a new line numbering
-scheme. We now use line number as defined by ITU-R, period.
-Compatibility: Add one to the start values. Applications depending on
-the previous semantics may not function correctly.</para>
- </listitem>
-
- <listitem>
- <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
-has been relaxed to "(count[0] + count[1]) &gt; 0". Rationale:
-Drivers may allocate resources at scan line granularity and some data
-services are transmitted only on the first field. The comment that
-both <structfield>count</structfield> values will usually be equal is
-misleading and pointless and has been removed. This change
-<emphasis>breaks compatibility</emphasis> with earlier versions:
-Drivers may return EINVAL, applications may not function
-correctly.</para>
- </listitem>
-
- <listitem>
- <para>Drivers are again permitted to return negative
-(unknown) start values as proposed earlier. Why this feature was
-dropped is unclear. This change may <emphasis>break
-compatibility</emphasis> with applications depending on the start
-values being positive. The use of <constant>EBUSY</constant> and
-<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
-was clarified. The &EBUSY; was finally documented, and the
-<structfield>reserved2</structfield> field which was previously
-mentioned only in the <filename>videodev.h</filename> header
-file.</para>
- </listitem>
-
- <listitem>
- <para>New buffer types
-<constant>V4L2_TYPE_VBI_INPUT</constant> and
-<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
-alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
-missing in the <filename>videodev.h</filename> file.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 Version 0.20 2002-07-25</title>
- <para>Added sliced VBI interface proposal.</para>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.5.46, 2002-10</title>
-
- <para>Around October-November 2002, prior to an announced
-feature freeze of Linux 2.5, the API was revised, drawing from
-experience with V4L2 0.20. This unnamed version was finally merged
-into Linux 2.5.46.</para>
-
- <orderedlist>
- <listitem>
- <para>As specified in <xref linkend="related" />, drivers
-must make related device functions available under all minor device
-numbers.</para>
- </listitem>
-
- <listitem>
- <para>The &func-open; function requires access mode
-<constant>O_RDWR</constant> regardless of the device type. All V4L2
-drivers exchanging data with applications must support the
-<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
-flag, a V4L2 symbol which aliased the meaningless
-<constant>O_TRUNC</constant> to indicate accesses without data
-exchange (panel applications) was dropped. Drivers must stay in "panel
-mode" until the application attempts to initiate a data exchange, see
-<xref linkend="open" />.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-capability; changed dramatically. Note that
-also the size of the structure changed, which is encoded in the ioctl
-request code, thus older V4L2 devices will respond with an &EINVAL; to
-the new &VIDIOC-QUERYCAP; ioctl.</para>
-
- <para>There are new fields to identify the driver, a new RDS
-device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
-<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
-any audio connectors, another I/O capability
-<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
-these changes the <structfield>type</structfield> field became a bit
-set and was merged into the <structfield>flags</structfield> field.
-<constant>V4L2_FLAG_TUNER</constant> was renamed to
-<constant>V4L2_CAP_TUNER</constant>,
-<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
-<constant>V4L2_FLAG_PREVIEW</constant> and
-<constant>V4L2_CAP_VBI_CAPTURE</constant> and
-<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
-<constant>V4L2_FLAG_DATA_SERVICE</constant>.
-<constant>V4L2_FLAG_READ</constant> and
-<constant>V4L2_FLAG_WRITE</constant> were merged into
-<constant>V4L2_CAP_READWRITE</constant>.</para>
-
- <para>The redundant fields
-<structfield>inputs</structfield>, <structfield>outputs</structfield>
-and <structfield>audios</structfield> were removed. These properties
-can be determined as described in <xref linkend="video" /> and <xref
-linkend="audio" />.</para>
-
- <para>The somewhat volatile and therefore barely useful
-fields <structfield>maxwidth</structfield>,
-<structfield>maxheight</structfield>,
-<structfield>minwidth</structfield>,
-<structfield>minheight</structfield>,
-<structfield>maxframerate</structfield> were removed. This information
-is available as described in <xref linkend="format" /> and
-<xref linkend="standard" />.</para>
-
- <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
-believe the select() function is important enough to require support
-of it in all V4L2 drivers exchanging data with applications. The
-redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
-this information is available as described in <xref
- linkend="format" />.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-input; the
-<structfield>assoc_audio</structfield> field and the
-<structfield>capability</structfield> field and its only flag
-<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
-<structfield>audioset</structfield> field. Instead of linking one
-video input to one audio input this field reports all audio inputs
-this video input combines with.</para>
-
- <para>New fields are <structfield>tuner</structfield>
-(reversing the former link from tuners to video inputs),
-<structfield>std</structfield> and
-<structfield>status</structfield>.</para>
-
- <para>Accordingly &v4l2-output; lost its
-<structfield>capability</structfield> and
-<structfield>assoc_audio</structfield> fields.
-<structfield>audioset</structfield>,
-<structfield>modulator</structfield> and
-<structfield>std</structfield> where added instead.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-audio; field
-<structfield>audio</structfield> was renamed to
-<structfield>index</structfield>, for consistency with other
-structures. A new capability flag
-<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
-audio input in question supports stereo sound.
-<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
-<constant>V4L2_AUDMODE</constant> flags where removed. This can be
-easily implemented using controls. (However the same applies to AVL
-which is still there.)</para>
-
- <para>Again for consistency the &v4l2-audioout; field
-<structfield>audio</structfield> was renamed to
-<structfield>index</structfield>.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-tuner;
-<structfield>input</structfield> field was replaced by an
-<structfield>index</structfield> field, permitting devices with
-multiple tuners. The link between video inputs and tuners is now
-reversed, inputs point to their tuner. The
-<structfield>std</structfield> substructure became a
-simple set (more about this below) and moved into &v4l2-input;. A
-<structfield>type</structfield> field was added.</para>
-
- <para>Accordingly in &v4l2-modulator; the
-<structfield>output</structfield> was replaced by an
-<structfield>index</structfield> field.</para>
-
- <para>In &v4l2-frequency; the
-<structfield>port</structfield> field was replaced by a
-<structfield>tuner</structfield> field containing the respective tuner
-or modulator index number. A tuner <structfield>type</structfield>
-field was added and the <structfield>reserved</structfield> field
-became larger for future extensions (satellite tuners in
-particular).</para>
- </listitem>
-
- <listitem>
- <para>The idea of completely transparent video standards was
-dropped. Experience showed that applications must be able to work with
-video standards beyond presenting the user a menu. Instead of
-enumerating supported standards with an ioctl applications can now
-refer to standards by &v4l2-std-id; and symbols defined in the
-<filename>videodev2.h</filename> header file. For details see <xref
- linkend="standard" />. The &VIDIOC-G-STD; and
-&VIDIOC-S-STD; now take a pointer to this type as argument.
-&VIDIOC-QUERYSTD; was added to autodetect the received standard, if
-the hardware has this capability. In &v4l2-standard; an
-<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
-A &v4l2-std-id; field named <structfield>id</structfield> was added as
-machine readable identifier, also replacing the
-<structfield>transmission</structfield> field. The misleading
-<structfield>framerate</structfield> field was renamed
-to <structfield>frameperiod</structfield>. The now obsolete
-<structfield>colorstandard</structfield> information, originally
-needed to distguish between variations of standards, were
-removed.</para>
-
- <para>Struct <structname>v4l2_enumstd</structname> ceased to
-be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
-directly. The information which standards are supported by a
-particular video input or output moved into &v4l2-input; and
-&v4l2-output; fields named <structfield>std</structfield>,
-respectively.</para>
- </listitem>
-
- <listitem>
- <para>The &v4l2-queryctrl; fields
-<structfield>category</structfield> and
-<structfield>group</structfield> did not catch on and/or were not
-implemented as expected and therefore removed.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
-formats as with &VIDIOC-S-FMT;, but without the overhead of
-programming the hardware and regardless of I/O in progress.</para>
-
- <para>In &v4l2-format; the <structfield>fmt</structfield>
-union was extended to contain &v4l2-window;. All image format
-negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
-<constant>VIDIOC_S_FMT</constant> and
-<constant>VIDIOC_TRY_FMT</constant>; ioctl. The
-<constant>VIDIOC_G_WIN</constant> and
-<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
-overlay were removed. The <structfield>type</structfield> field
-changed to type &v4l2-buf-type; and the buffer type names changed as
-follows.<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Old defines</entry>
- <entry>&v4l2-buf-type;</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
- <entry>Omitted for now</entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
- <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
-<structfield>type</structfield> was added as in &v4l2-format;. The
-<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
-was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
-type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-pix-format; the
-<structfield>depth</structfield> field was removed, assuming
-applications which recognize the format by its four-character-code
-already know the color depth, and others do not care about it. The
-same rationale lead to the removal of the
-<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
-<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
-because drivers are not supposed to convert images in kernel space. A
-user library of conversion functions should be provided instead. The
-<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
-Applications can set the <structfield>bytesperline</structfield> field
-to zero to get a reasonable default. Since the remaining flags were
-replaced as well, the <structfield>flags</structfield> field itself
-was removed.</para>
- <para>The interlace flags were replaced by a &v4l2-field;
-value in a newly added <structfield>field</structfield>
-field.<informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Old flag</entry>
- <entry>&v4l2-field;</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
- <entry>?</entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
-= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
- <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
-= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
- <entry><constant>V4L2_FIELD_TOP</constant></entry>
- </row>
- <row>
- <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
-= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
- <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
- </row>
- <row>
- <entry><constant>-</constant></entry>
- <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable></para>
-
- <para>The color space flags were replaced by a
-&v4l2-colorspace; value in a newly added
-<structfield>colorspace</structfield> field, where one of
-<constant>V4L2_COLORSPACE_SMPTE170M</constant>,
-<constant>V4L2_COLORSPACE_BT878</constant>,
-<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
-<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
-<constant>V4L2_FMT_CS_601YUV</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-requestbuffers; the
-<structfield>type</structfield> field was properly defined as
-&v4l2-buf-type;. Buffer types changed as mentioned above. A new
-<structfield>memory</structfield> field of type &v4l2-memory; was
-added to distinguish between I/O methods using buffers allocated
-by the driver or the application. See <xref linkend="io" /> for
-details.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-buffer; the <structfield>type</structfield>
-field was properly defined as &v4l2-buf-type;. Buffer types changed as
-mentioned above. A <structfield>field</structfield> field of type
-&v4l2-field; was added to indicate if a buffer contains a top or
-bottom field. The old field flags were removed. Since no unadjusted
-system time clock was added to the kernel as planned, the
-<structfield>timestamp</structfield> field changed back from type
-stamp_t, an unsigned 64 bit integer expressing the sample time in
-nanoseconds, to struct <structname>timeval</structname>. With the
-addition of a second memory mapping method the
-<structfield>offset</structfield> field moved into union
-<structfield>m</structfield>, and a new
-<structfield>memory</structfield> field of type &v4l2-memory; was
-added to distinguish between I/O methods. See <xref linkend="io" />
-for details.</para>
-
- <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
-flag was used by the V4L compatibility layer, after changes to this
-code it was no longer needed. The
-<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
-the buffer was indeed allocated in device memory rather than DMA-able
-system memory. It was barely useful and so was removed.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-framebuffer; the
-<structfield>base[3]</structfield> array anticipating double- and
-triple-buffering in off-screen video memory, however without defining
-a synchronization mechanism, was replaced by a single pointer. The
-<constant>V4L2_FBUF_CAP_SCALEUP</constant> and
-<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
-Applications can determine this capability more accurately using the
-new cropping and scaling interface. The
-<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
-<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
-<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-clip; the <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> field moved into a
-<structfield>c</structfield> substructure of type &v4l2-rect;. The
-<structfield>x</structfield> and <structfield>y</structfield> fields
-were renamed to <structfield>left</structfield> and
-<structfield>top</structfield>, &ie; offsets to a context dependent
-origin.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-window; the <structfield>x</structfield>,
-<structfield>y</structfield>, <structfield>width</structfield> and
-<structfield>height</structfield> field moved into a
-<structfield>w</structfield> substructure as above. A
-<structfield>field</structfield> field of type %v4l2-field; was added
-to distinguish between field and frame (interlaced) overlay.</para>
- </listitem>
-
- <listitem>
- <para>The digital zoom interface, including struct
-<structname>v4l2_zoomcap</structname>, struct
-<structname>v4l2_zoom</structname>,
-<constant>V4L2_ZOOM_NONCAP</constant> and
-<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
-cropping and scaling interface. The previously unused struct
-<structname>v4l2_cropcap</structname> and
-<structname>v4l2_crop</structname> where redefined for this purpose.
-See <xref linkend="crop" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-vbi-format; the
-<structfield>SAMPLE_FORMAT</structfield> field now contains a
-four-character-code as used to identify video image formats and
-<constant>V4L2_PIX_FMT_GREY</constant> replaces the
-<constant>V4L2_VBI_SF_UBYTE</constant> define. The
-<structfield>reserved</structfield> field was extended.</para>
- </listitem>
-
- <listitem>
- <para>In &v4l2-captureparm; the type of the
-<structfield>timeperframe</structfield> field changed from unsigned
-long to &v4l2-fract;. This allows the accurate expression of multiples
-of the NTSC-M frame rate 30000 / 1001. A new field
-<structfield>readbuffers</structfield> was added to control the driver
-behaviour in read I/O mode.</para>
-
- <para>Similar changes were made to &v4l2-outputparm;.</para>
- </listitem>
-
- <listitem>
- <para>The struct <structname>v4l2_performance</structname>
-and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
-using the <link linkend="rw">read/write I/O method</link>, which is
-limited anyway, this information is already available to
-applications.</para>
- </listitem>
-
- <listitem>
- <para>The example transformation from RGB to YCbCr color
-space in the old V4L2 documentation was inaccurate, this has been
-corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
-0.587, and 127/112 != 255/224 --></para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 2003-06-19</title>
-
- <orderedlist>
- <listitem>
- <para>A new capability flag
-<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
-to this change radio devices would identify solely by having exactly one
-tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
- </listitem>
-
- <listitem>
- <para>An optional driver access priority mechanism was
-added, see <xref linkend="app-pri" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>The audio input and output interface was found to be
-incomplete.</para>
- <para>Previously the &VIDIOC-G-AUDIO;
-ioctl would enumerate the available audio inputs. An ioctl to
-determine the current audio input, if more than one combines with the
-current video input, did not exist. So
-<constant>VIDIOC_G_AUDIO</constant> was renamed to
-<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on
-Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
-audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
-input.</para>
- <para>The same changes were made to &VIDIOC-G-AUDOUT; and
-&VIDIOC-ENUMAUDOUT;.</para>
- <para>Until further the "videodev" module will automatically
-translate between the old and new ioctls, but drivers and applications
-must be updated to successfully compile again.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
-write-read parameter. It was changed to write-only, while the write-read
-version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
-ioctl was removed on Kernel 2.6.39. Until further the "videodev"
-kernel module will automatically translate to the new version, so drivers
-must be recompiled, but not applications.</para>
- </listitem>
-
- <listitem>
- <para><xref linkend="overlay" /> incorrectly stated that
-clipping rectangles define regions where the video can be seen.
-Correct is that clipping rectangles define regions where
-<emphasis>no</emphasis> video shall be displayed and so the graphics
-surface can be seen.</para>
- </listitem>
-
- <listitem>
- <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
-defined with write-only parameter, inconsistent with other ioctls
-modifying their argument. They were changed to write-read, while a
-<constant>_OLD</constant> suffix was added to the write-only versions.
-The old ioctls were removed on Kernel 2.6.39. Drivers and
-applications assuming a constant parameter need an update.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 2003-11-05</title>
- <orderedlist>
- <listitem>
- <para>In <xref linkend="pixfmt-rgb" /> the following pixel
-formats were incorrectly transferred from Bill Dirks' V4L2
-specification. Descriptions below refer to bytes in memory, in
-ascending address order.<informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Symbol</entry>
- <entry>In this document prior to revision
-0.5</entry>
- <entry>Corrected</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
- <entry>B, G, R</entry>
- <entry>R, G, B</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
- <entry>R, G, B</entry>
- <entry>B, G, R</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
- <entry>B, G, R, X</entry>
- <entry>R, G, B, X</entry>
- </row>
- <row>
- <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
- <entry>R, G, B, X</entry>
- <entry>B, G, R, X</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable> The
-<constant>V4L2_PIX_FMT_BGR24</constant> example was always
-correct.</para>
- <para>In <xref linkend="v4l-image-properties" /> the mapping
-of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
-<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
-was accordingly corrected.</para>
- </listitem>
-
- <listitem>
- <para>Unrelated to the fixes above, drivers may still
-interpret some V4L2 RGB pixel formats differently. These issues have
-yet to be addressed, for details see <xref
- linkend="pixfmt-rgb" />.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
-with read-only parameter. It is now defined as write-read ioctl, while
-the read-only version was renamed to
-<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed
-on Kernel 2.6.39.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.8</title>
- <orderedlist>
- <listitem>
- <para>A new field <structfield>input</structfield> (former
-<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
-structure. Purpose of this field is to alternate between video inputs
-(&eg; cameras) in step with the video capturing process. This function
-must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
-flag. The <structfield>flags</structfield> field is no longer
-read-only.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2004-08-01</title>
-
- <orderedlist>
- <listitem>
- <para>The return value of the
-<xref linkend="func-open" /> function was incorrectly documented.</para>
- </listitem>
-
- <listitem>
- <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
- </listitem>
-
- <listitem>
- <para>In the Current Audio Input example the
-<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
-argument.</para>
- </listitem>
-
- <listitem>
- <para>The documentation of the &VIDIOC-QBUF; and
-&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
-<structfield>memory</structfield> field. It was also missing from
-examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
-was not documented.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.14</title>
- <orderedlist>
- <listitem>
- <para>A new sliced VBI interface was added. It is documented
-in <xref linkend="sliced" /> and replaces the interface first
-proposed in V4L2 specification 0.8.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.15</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
- </listitem>
-
- <listitem>
- <para>New video standards
-<constant>V4L2_STD_NTSC_443</constant>,
-<constant>V4L2_STD_SECAM_LC</constant>,
-<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
-and <constant>V4L2_STD_ATSC</constant> (a set of
-<constant>V4L2_STD_ATSC_8_VSB</constant> and
-<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
-<constant>V4L2_STD_525_60</constant> set now includes
-<constant>V4L2_STD_NTSC_443</constant>. See also <xref
- linkend="v4l2-std-id" />.</para>
- </listitem>
-
- <listitem>
- <para>The <constant>VIDIOC_G_COMP</constant> and
-<constant>VIDIOC_S_COMP</constant> ioctl were renamed to
-<constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
-was replaced by a struct
-<structname>v4l2_mpeg_compression</structname> pointer. (The
-<constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
-2.6.25.)</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2005-11-27</title>
- <para>The capture example in <xref linkend="capture-example" />
-called the &VIDIOC-S-CROP; ioctl without checking if cropping is
-supported. In the video standard selection example in
-<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
-argument type.</para>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-01-10</title>
- <orderedlist>
- <listitem>
- <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
-&v4l2-input; not only indicates if the color killer is enabled, but
-also if it is active. (The color killer disables color decoding when
-it detects no color in the video signal to improve the image
-quality.)</para>
- </listitem>
-
- <listitem>
- <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
-stated on its reference page. The ioctl changed in 2003 as noted above.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-02-03</title>
- <orderedlist>
- <listitem>
- <para>In &v4l2-captureparm; and &v4l2-outputparm; the
-<structfield>timeperframe</structfield> field gives the time in
-seconds, not microseconds.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-02-04</title>
- <orderedlist>
- <listitem>
- <para>The <structfield>clips</structfield> field in
-&v4l2-window; must point to an array of &v4l2-clip;, not a linked
-list, because drivers ignore the struct
-<structname>v4l2_clip</structname>.<structfield>next</structfield>
-pointer.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.17</title>
- <orderedlist>
- <listitem>
- <para>New video standard macros were added:
-<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
-sets <constant>V4L2_STD_MN</constant>,
-<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
-<constant>V4L2_STD_DK</constant>. The
-<constant>V4L2_STD_NTSC</constant> and
-<constant>V4L2_STD_SECAM</constant> sets now include
-<constant>V4L2_STD_NTSC_M_KR</constant> and
-<constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
- </listitem>
-
- <listitem>
- <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
-was defined to record both languages of a bilingual program. The
-use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
-is deprecated now. See the &VIDIOC-G-TUNER; section for
-details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
- <orderedlist>
- <listitem>
- <para>In various places
-<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
-<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
-interface were not mentioned along with other buffer types.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="vidioc-g-audio" /> it was clarified
-that the &v4l2-audio; <structfield>mode</structfield> field is a flags
-field.</para>
- </listitem>
-
- <listitem>
- <para><xref linkend="vidioc-querycap" /> did not mention the
-sliced VBI and radio capability flags.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="vidioc-g-frequency" /> it was
-clarified that applications must initialize the tuner
-<structfield>type</structfield> field of &v4l2-frequency; before
-calling &VIDIOC-S-FREQUENCY;.</para>
- </listitem>
-
- <listitem>
- <para>The <structfield>reserved</structfield> array
-in &v4l2-requestbuffers; has 2 elements, not 32.</para>
- </listitem>
-
- <listitem>
- <para>In <xref linkend="output" /> and <xref
- linkend="raw-vbi" /> the device file names
-<filename>/dev/vout</filename> which never caught on were replaced
-by <filename>/dev/video</filename>.</para>
- </listitem>
-
- <listitem>
- <para>With Linux 2.6.15 the possible range for VBI device minor
-numbers was extended from 224-239 to 224-255. Accordingly device file names
-<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
-possible now.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.18</title>
- <orderedlist>
- <listitem>
- <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
-and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
-controls with &VIDIOC-QUERYCTRL;, new control types
-<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
-<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
- linkend="v4l2-ctrl-type" />), and new control flags
-<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
-<constant>V4L2_CTRL_FLAG_UPDATE</constant>,
-<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
-<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
- linkend="control-flags" />). See <xref
- linkend="extended-controls" /> for details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.19</title>
- <orderedlist>
- <listitem>
- <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
-replacing a reserved field. Note on architectures where the size of
-enum types differs from int types the size of the structure changed.
-The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
-to write-read. Applications must initialize the type field and clear
-the reserved fields now. These changes may <emphasis>break the
-compatibility</emphasis> with older drivers and applications.</para>
- </listitem>
-
- <listitem>
- <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
-&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
- </listitem>
-
- <listitem>
- <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
-linkend="rgb-formats" />) was added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
- <orderedlist>
- <listitem>
- <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
-linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.21</title>
- <orderedlist>
- <listitem>
- <para>The <filename>videodev2.h</filename> header file is
-now dual licensed under GNU General Public License version two or
-later, and under a 3-clause BSD-style license.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.22</title>
- <orderedlist>
- <listitem>
- <para>Two new field orders
- <constant>V4L2_FIELD_INTERLACED_TB</constant> and
- <constant>V4L2_FIELD_INTERLACED_BT</constant> were
- added. See <xref linkend="v4l2-field" /> for details.</para>
- </listitem>
-
- <listitem>
- <para>Three new clipping/blending methods with a global or
-straight or inverted local alpha value were added to the video overlay
-interface. See the description of the &VIDIOC-G-FBUF; and
-&VIDIOC-S-FBUF; ioctls for details.</para>
- <para>A new <structfield>global_alpha</structfield> field
-was added to <link
-linkend="v4l2-window"><structname>v4l2_window</structname></link>,
-extending the structure. This may <emphasis>break
-compatibility</emphasis> with applications using a struct
-<structname>v4l2_window</structname> directly. However the <link
-linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
-pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
-structure with padding bytes at the end, are not affected.</para>
- </listitem>
-
- <listitem>
- <para>The format of the <structfield>chromakey</structfield>
-field in &v4l2-window; changed from "host order RGB32" to a pixel
-value in the same format as the framebuffer. This may <emphasis>break
-compatibility</emphasis> with existing applications. Drivers
-supporting the "host order RGB32" format are not known.</para>
- </listitem>
-
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.24</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_PAL8</constant>,
-<constant>V4L2_PIX_FMT_YUV444</constant>,
-<constant>V4L2_PIX_FMT_YUV555</constant>,
-<constant>V4L2_PIX_FMT_YUV565</constant> and
-<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.25</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
-<constant>V4L2_PIX_FMT_Y16</constant></link> and <link
-linkend="V4L2-PIX-FMT-SBGGR16">
-<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
- </listitem>
- <listitem>
- <para>New <link linkend="control">controls</link>
-<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
-<constant>V4L2_CID_HUE_AUTO</constant>,
-<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
-<constant>V4L2_CID_SHARPNESS</constant> and
-<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
-controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
-<constant>V4L2_CID_WHITENESS</constant>,
-<constant>V4L2_CID_HCENTER</constant> and
-<constant>V4L2_CID_VCENTER</constant> were deprecated.
-</para>
- </listitem>
- <listitem>
- <para>A <link linkend="camera-controls">Camera controls
-class</link> was added, with the new controls
-<constant>V4L2_CID_EXPOSURE_AUTO</constant>,
-<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
-<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
-<constant>V4L2_CID_PAN_RELATIVE</constant>,
-<constant>V4L2_CID_TILT_RELATIVE</constant>,
-<constant>V4L2_CID_PAN_RESET</constant>,
-<constant>V4L2_CID_TILT_RESET</constant>,
-<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
-<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
-<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
-<constant>V4L2_CID_FOCUS_RELATIVE</constant> and
-<constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
- </listitem>
- <listitem>
- <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
-by the <link linkend="extended-controls">extended controls</link>
-interface in Linux 2.6.18, where finally removed from the
-<filename>videodev2.h</filename> header file.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.26</title>
- <orderedlist>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_Y16</constant> and
-<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
- </listitem>
- <listitem>
- <para>Added user controls
-<constant>V4L2_CID_CHROMA_AGC</constant> and
-<constant>V4L2_CID_COLOR_KILLER</constant>.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.27</title>
- <orderedlist>
- <listitem>
- <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
-<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_YVYU</constant>,
-<constant>V4L2_PIX_FMT_PCA501</constant>,
-<constant>V4L2_PIX_FMT_PCA505</constant>,
-<constant>V4L2_PIX_FMT_PCA508</constant>,
-<constant>V4L2_PIX_FMT_PCA561</constant>,
-<constant>V4L2_PIX_FMT_SGBRG8</constant>,
-<constant>V4L2_PIX_FMT_PAC207</constant> and
-<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.28</title>
- <orderedlist>
- <listitem>
- <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
-<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
- </listitem>
- <listitem>
- <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
-video encoding.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_SGRBG10</constant> and
-<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 2.6.29</title>
- <orderedlist>
- <listitem>
- <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
-to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT;
-was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
-was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
- </listitem>
- <listitem>
- <para>The pixel formats
-<constant>V4L2_PIX_FMT_VYUY</constant>,
-<constant>V4L2_PIX_FMT_NV16</constant> and
-<constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
- </listitem>
- <listitem>
- <para>Added camera controls
-<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
-<constant>V4L2_CID_ZOOM_RELATIVE</constant>,
-<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
-<constant>V4L2_CID_PRIVACY</constant>.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.30</title>
- <orderedlist>
- <listitem>
- <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
- </listitem>
- <listitem>
- <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.32</title>
- <orderedlist>
- <listitem>
- <para>In order to be easier to compare a V4L2 API and a kernel
-version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
- </listitem>
- <listitem>
- <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
-more information.</para>
- </listitem>
- <listitem>
- <para>Added new capabilities for modulators and RDS encoders.</para>
- </listitem>
- <listitem>
- <para>Add description for libv4l API.</para>
- </listitem>
- <listitem>
- <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
- </listitem>
- <listitem>
- <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
- </listitem>
- <listitem>
- <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
- </listitem>
- <listitem>
- <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.33</title>
- <orderedlist>
- <listitem>
- <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.34</title>
- <orderedlist>
- <listitem>
- <para>Added
-<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and
-<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the
- <link linkend="camera-controls">Camera controls class</link>.
- </para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.37</title>
- <orderedlist>
- <listitem>
- <para>Remove the vtx (videotext/teletext) API. This API was no longer
-used and no hardware exists to verify the API. Nor were any userspace applications found
-that used it. It was originally scheduled for removal in 2.6.35.
- </para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 2.6.39</title>
- <orderedlist>
- <listitem>
- <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para>
- </listitem>
- <listitem>
- <para>Multi-planar API added. Does not affect the compatibility of
- current drivers and applications. See
- <link linkend="planar-apis">multi-planar API</link>
- for details.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 3.1</title>
- <orderedlist>
- <listitem>
- <para>VIDIOC_QUERYCAP now returns a per-subsystem version instead of a per-driver one.</para>
- <para>Standardize an error code for invalid ioctl.</para>
- <para>Added V4L2_CTRL_TYPE_BITMASK.</para>
- </listitem>
- </orderedlist>
- </section>
- <section>
- <title>V4L2 in Linux 3.2</title>
- <orderedlist>
- <listitem>
- <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>
- </listitem>
- <listitem>
- <para>Add selection API for extended control over cropping and
-composing. Does not affect the compatibility of current drivers and
-applications. See <link linkend="selection-api"> selection API </link> for
-details.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.3</title>
- <orderedlist>
- <listitem>
- <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control
- to the <link linkend="control">User controls class</link>.
- </para>
- </listitem>
- <listitem>
- <para>Added the device_caps field to struct v4l2_capabilities and added the new
- V4L2_CAP_DEVICE_CAPS capability.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.4</title>
- <orderedlist>
- <listitem>
- <para>Added <link linkend="jpeg-controls">JPEG compression control
- class</link>.</para>
- </listitem>
- <listitem>
- <para>Extended the DV Timings API:
- &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
- &VIDIOC-DV-TIMINGS-CAP;.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>V4L2 in Linux 3.5</title>
- <orderedlist>
- <listitem>
- <para>Added integer menus, the new type will be
- V4L2_CTRL_TYPE_INTEGER_MENU.</para>
- </listitem>
- <listitem>
- <para>Added selection API for V4L2 subdev interface:
- &VIDIOC-SUBDEV-G-SELECTION; and
- &VIDIOC-SUBDEV-S-SELECTION;.</para>
- </listitem>
- <listitem>
- <para> Added <constant>V4L2_COLORFX_ANTIQUE</constant>,
- <constant>V4L2_COLORFX_ART_FREEZE</constant>,
- <constant>V4L2_COLORFX_AQUA</constant>,
- <constant>V4L2_COLORFX_SILHOUETTE</constant>,
- <constant>V4L2_COLORFX_SOLARIZATION</constant>,
- <constant>V4L2_COLORFX_VIVID</constant> and
- <constant>V4L2_COLORFX_ARBITRARY_CBCR</constant> menu items
- to the <constant>V4L2_CID_COLORFX</constant> control.</para>
- </listitem>
- <listitem>
- <para> Added <constant>V4L2_CID_COLORFX_CBCR</constant> control.</para>
- </listitem>
- <listitem>
- <para> Added camera controls <constant>V4L2_CID_AUTO_EXPOSURE_BIAS</constant>,
- <constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>,
- <constant>V4L2_CID_IMAGE_STABILIZATION</constant>,
- <constant>V4L2_CID_ISO_SENSITIVITY</constant>,
- <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>,
- <constant>V4L2_CID_EXPOSURE_METERING</constant>,
- <constant>V4L2_CID_SCENE_MODE</constant>,
- <constant>V4L2_CID_3A_LOCK</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_START</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_STOP</constant>,
- <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> and
- <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>.
- </para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="other">
- <title>Relation of V4L2 to other Linux multimedia APIs</title>
-
- <section id="xvideo">
- <title>X Video Extension</title>
-
- <para>The X Video Extension (abbreviated XVideo or just Xv) is
-an extension of the X Window system, implemented for example by the
-XFree86 project. Its scope is similar to V4L2, an API to video capture
-and output devices for X clients. Xv allows applications to display
-live video in a window, send window contents to a TV output, and
-capture or output still images in XPixmaps<footnote>
- <para>This is not implemented in XFree86.</para>
- </footnote>. With their implementation XFree86 makes the
-extension available across many operating systems and
-architectures.</para>
-
- <para>Because the driver is embedded into the X server Xv has a
-number of advantages over the V4L2 <link linkend="overlay">video
-overlay interface</link>. The driver can easily determine the overlay
-target, &ie; visible graphics memory or off-screen buffers for a
-destructive overlay. It can program the RAMDAC for a non-destructive
-overlay, scaling or color-keying, or the clipping functions of the
-video capture hardware, always in sync with drawing operations or
-windows moving or changing their stacking order.</para>
-
- <para>To combine the advantages of Xv and V4L a special Xv
-driver exists in XFree86 and XOrg, just programming any overlay capable
-Video4Linux device it finds. To enable it
-<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
- <para><screen>
-Section "Module"
- Load "v4l"
-EndSection</screen></para>
-
- <para>As of XFree86 4.2 this driver still supports only V4L
-ioctls, however it should work just fine with all V4L2 devices through
-the V4L2 backward-compatibility layer. Since V4L2 permits multiple
-opens it is possible (if supported by the V4L2 driver) to capture
-video while an X client requested video overlay. Restrictions of
-simultaneous capturing and overlay are discussed in <xref
- linkend="overlay" /> apply.</para>
-
- <para>Only marginally related to V4L2, XFree86 extended Xv to
-support hardware YUV to RGB conversion and scaling for faster video
-playback, and added an interface to MPEG-2 decoding hardware. This API
-is useful to display images captured with V4L2 devices.</para>
- </section>
-
- <section>
- <title>Digital Video</title>
-
- <para>V4L2 does not support digital terrestrial, cable or
-satellite broadcast. A separate project aiming at digital receivers
-exists. You can find its homepage at <ulink
-url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
-has no connection to the V4L2 API except that drivers for hybrid
-hardware may support both.</para>
- </section>
-
- <section>
- <title>Audio Interfaces</title>
-
- <para>[to do - OSS/ALSA]</para>
- </section>
- </section>
-
- <section id="experimental">
- <title>Experimental API Elements</title>
-
- <para>The following V4L2 API elements are currently experimental
-and may change in the future.</para>
-
- <itemizedlist>
- <listitem>
- <para>Video Output Overlay (OSD) Interface, <xref
- linkend="osd" />.</para>
- </listitem>
- <listitem>
- <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>,
- &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para>
- </listitem>
- <listitem>
- <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>,
-&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-ENUM-FRAMESIZES; and
-&VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-G-ENC-INDEX; ioctl.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD;
-ioctls.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD;
-ioctls.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
-ioctls.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
- &VIDIOC-DV-TIMINGS-CAP; ioctls.</para>
- </listitem>
- <listitem>
- <para>Flash API. <xref linkend="flash-controls" /></para>
- </listitem>
- <listitem>
- <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para>
- </listitem>
- <listitem>
- <para>Selection API. <xref linkend="selection-api" /></para>
- </listitem>
- <listitem>
- <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION;
- and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para>
- </listitem>
- <listitem>
- <para><link linkend="v4l2-auto-focus-area"><constant>
- V4L2_CID_AUTO_FOCUS_AREA</constant></link> control.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section id="obsolete">
- <title>Obsolete API Elements</title>
-
- <para>The following V4L2 API elements were superseded by new
-interfaces and should not be implemented in new drivers.</para>
-
- <itemizedlist>
- <listitem>
- <para><constant>VIDIOC_G_MPEGCOMP</constant> and
-<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
-<xref linkend="extended-controls" />.</para>
- </listitem>
- <listitem>
- <para>&VIDIOC-G-DV-PRESET;, &VIDIOC-S-DV-PRESET;, &VIDIOC-ENUM-DV-PRESETS; and
- &VIDIOC-QUERY-DV-PRESET; ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para>
- </listitem>
- <listitem>
- <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and
- <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use
- <constant>VIDIOC_SUBDEV_G_SELECTION</constant> and
- <constant>VIDIOC_SUBDEV_S_SELECTION</constant>, <xref
- linkend="vidioc-subdev-g-selection" />.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
deleted file mode 100644
index 676bc46f9c5..00000000000
--- a/Documentation/DocBook/media/v4l/controls.xml
+++ /dev/null
@@ -1,4272 +0,0 @@
- <section id="control">
- <title>User Controls</title>
-
- <para>Devices typically have a number of user-settable controls
-such as brightness, saturation and so on, which would be presented to
-the user on a graphical user interface. But, different devices
-will have different controls available, and furthermore, the range of
-possible values, and the default value will vary from device to
-device. The control ioctls provide the information and a mechanism to
-create a nice user interface for these controls that will work
-correctly with any device.</para>
-
- <para>All controls are accessed using an ID value. V4L2 defines
-several IDs for specific purposes. Drivers can also implement their
-own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
-and higher values. The pre-defined control IDs have the prefix
-<constant>V4L2_CID_</constant>, and are listed in <xref
-linkend="control-id" />. The ID is used when querying the attributes of
-a control, and when getting or setting the current value.</para>
-
- <para>Generally applications should present controls to the user
-without assumptions about their purpose. Each control comes with a
-name string the user is supposed to understand. When the purpose is
-non-intuitive the driver writer should provide a user manual, a user
-interface plug-in or a driver specific panel application. Predefined
-IDs were introduced to change a few controls programmatically, for
-example to mute a device during a channel switch.</para>
-
- <para>Drivers may enumerate different controls after switching
-the current video input or output, tuner or modulator, or audio input
-or output. Different in the sense of other bounds, another default and
-current value, step size or other menu items. A control with a certain
-<emphasis>custom</emphasis> ID can also change name and
-type.<footnote>
- <para>It will be more convenient for applications if drivers
-make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but
-that was never required.</para>
- </footnote> Control values are stored globally, they do not
-change when switching except to stay within the reported bounds. They
-also do not change &eg; when the device is opened or closed, when the
-tuner radio frequency is changed or generally never without
-application request. Since V4L2 specifies no event mechanism, panel
-applications intended to cooperate with other panel applications (be
-they built into a larger application, as a TV viewer) may need to
-regularly poll control values to update their user
-interface.<footnote>
- <para>Applications could call an ioctl to request events.
-After another process called &VIDIOC-S-CTRL; or another ioctl changing
-shared properties the &func-select; function would indicate
-readability until any ioctl (querying the properties) is
-called.</para>
- </footnote></para>
-
- <para>
- All controls use machine endianness.
- </para>
-
- <table pgwide="1" frame="none" id="control-id">
- <title>Control IDs</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry>ID</entry>
- <entry>Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_BASE</constant></entry>
- <entry></entry>
- <entry>First predefined ID, equal to
-<constant>V4L2_CID_BRIGHTNESS</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_USER_BASE</constant></entry>
- <entry></entry>
- <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
- <entry>integer</entry>
- <entry>Picture brightness, or more precisely, the black
-level.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CONTRAST</constant></entry>
- <entry>integer</entry>
- <entry>Picture contrast or luma gain.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_SATURATION</constant></entry>
- <entry>integer</entry>
- <entry>Picture color saturation or chroma gain.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HUE</constant></entry>
- <entry>integer</entry>
- <entry>Hue or color balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
- <entry>integer</entry>
- <entry>Overall audio volume. Note some drivers also
-provide an OSS or ALSA mixer interface.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Audio stereo balance. Minimum corresponds to all
-the way left, maximum to right.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
- <entry>integer</entry>
- <entry>Audio bass adjustment.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
- <entry>integer</entry>
- <entry>Audio treble adjustment.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry>
- <entry>boolean</entry>
- <entry>Mute audio, &ie; set the volume to zero, however
-without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like
-ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
-noise. Actually the entire device should be reset to a low power
-consumption state.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry>
- <entry>boolean</entry>
- <entry>Loudness mode (bass boost).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry>
- <entry>integer</entry>
- <entry>Another name for brightness (not a synonym of
-<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated
-and should not be used in new drivers and applications.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry>
- <entry>boolean</entry>
- <entry>Automatic white balance (cameras).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry>
- <entry>button</entry>
- <entry>This is an action control. When set (the value is
-ignored), the device will do a white balance and then hold the current
-setting. Contrast this with the boolean
-<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when
-activated, keeps adjusting the white balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_RED_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Red chroma balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry>
- <entry>integer</entry>
- <entry>Blue chroma balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_GAMMA</constant></entry>
- <entry>integer</entry>
- <entry>Gamma adjust.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_WHITENESS</constant></entry>
- <entry>integer</entry>
- <entry>Whiteness for grey-scale devices. This is a synonym
-for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated
-and should not be used in new drivers and applications.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_EXPOSURE</constant></entry>
- <entry>integer</entry>
- <entry>Exposure (cameras). [Unit?]</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_AUTOGAIN</constant></entry>
- <entry>boolean</entry>
- <entry>Automatic gain/exposure control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_GAIN</constant></entry>
- <entry>integer</entry>
- <entry>Gain control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HFLIP</constant></entry>
- <entry>boolean</entry>
- <entry>Mirror the picture horizontally.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_VFLIP</constant></entry>
- <entry>boolean</entry>
- <entry>Mirror the picture vertically.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry>
- <entry>integer</entry>
- <entry>Horizontal image centering. This control is
-deprecated. New drivers and applications should use the <link
-linkend="camera-controls">Camera class controls</link>
-<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
-<constant>V4L2_CID_PAN_RELATIVE</constant> and
-<constant>V4L2_CID_PAN_RESET</constant> instead.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant>
- (formerly <constant>V4L2_CID_VCENTER</constant>)</entry>
- <entry>integer</entry>
- <entry>Vertical image centering. Centering is intended to
-<emphasis>physically</emphasis> adjust cameras. For image cropping see
-<xref linkend="crop" />, for clipping <xref linkend="overlay" />. This
-control is deprecated. New drivers and applications should use the
-<link linkend="camera-controls">Camera class controls</link>
-<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
-<constant>V4L2_CID_TILT_RELATIVE</constant> and
-<constant>V4L2_CID_TILT_RESET</constant> instead.</entry>
- </row>
- <row id="v4l2-power-line-frequency">
- <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry>
- <entry>enum</entry>
- <entry>Enables a power line frequency filter to avoid
-flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are:
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0),
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1),
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and
-<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_HUE_AUTO</constant></entry>
- <entry>boolean</entry>
- <entry>Enables automatic hue control by the device. The
-effect of setting <constant>V4L2_CID_HUE</constant> while automatic
-hue control is enabled is undefined, drivers should ignore such
-request.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry>
- <entry>integer</entry>
- <entry>This control specifies the white balance settings
-as a color temperature in Kelvin. A driver should have a minimum of
-2800 (incandescent) to 6500 (daylight). For more information about
-color temperature see <ulink
-url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_SHARPNESS</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the sharpness filters in a camera. The
-minimum value disables the filters, higher values give a sharper
-picture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the backlight compensation in a camera. The
-minimum value disables backlight compensation.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry>
- <entry>boolean</entry>
- <entry>Chroma automatic gain control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry>
- <entry>integer</entry>
- <entry>Adjusts the Chroma gain control (for use when chroma AGC
- is disabled).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry>
- <entry>boolean</entry>
- <entry>Enable the color killer (&ie; force a black &amp; white image in case of a weak video signal).</entry>
- </row>
- <row id="v4l2-colorfx">
- <entry><constant>V4L2_CID_COLORFX</constant></entry>
- <entry>enum</entry>
- <entry>Selects a color effect. The following values are defined:
- </entry>
- </row><row>
- <entry></entry>
- <entry></entry>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_COLORFX_NONE</constant>&nbsp;</entry>
- <entry>Color effect is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_ANTIQUE</constant>&nbsp;</entry>
- <entry>An aging (old photo) effect.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_ART_FREEZE</constant>&nbsp;</entry>
- <entry>Frost color effect.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_AQUA</constant>&nbsp;</entry>
- <entry>Water color, cool tone.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_BW</constant>&nbsp;</entry>
- <entry>Black and white.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_EMBOSS</constant>&nbsp;</entry>
- <entry>Emboss, the highlights and shadows replace light/dark boundaries
- and low contrast areas are set to a gray background.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_GRASS_GREEN</constant>&nbsp;</entry>
- <entry>Grass green.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_NEGATIVE</constant>&nbsp;</entry>
- <entry>Negative.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SEPIA</constant>&nbsp;</entry>
- <entry>Sepia tone.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKETCH</constant>&nbsp;</entry>
- <entry>Sketch.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKIN_WHITEN</constant>&nbsp;</entry>
- <entry>Skin whiten.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SKY_BLUE</constant>&nbsp;</entry>
- <entry>Sky blue.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SOLARIZATION</constant>&nbsp;</entry>
- <entry>Solarization, the image is partially reversed in tone,
- only color values above or below a certain threshold are inverted.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SILHOUETTE</constant>&nbsp;</entry>
- <entry>Silhouette (outline).</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_VIVID</constant>&nbsp;</entry>
- <entry>Vivid colors.</entry>
- </row>
- <row>
- <entry><constant>V4L2_COLORFX_SET_CBCR</constant>&nbsp;</entry>
- <entry>The Cb and Cr chroma components are replaced by fixed
- coefficients determined by <constant>V4L2_CID_COLORFX_CBCR</constant>
- control.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry><constant>V4L2_CID_COLORFX_CBCR</constant></entry>
- <entry>integer</entry>
- <entry>Determines the Cb and Cr coefficients for <constant>V4L2_COLORFX_SET_CBCR</constant>
- color effect. Bits [7:0] of the supplied 32 bit value are interpreted as
- Cr component, bits [15:8] as Cb component and bits [31:16] must be zero.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ROTATE</constant></entry>
- <entry>integer</entry>
- <entry>Rotates the image by specified angle. Common angles are 90,
- 270 and 180. Rotating the image to 90 and 270 will reverse the height
- and width of the display window. It is necessary to set the new height and
- width of the picture using the &VIDIOC-S-FMT; ioctl according to
- the rotation angle selected.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_BG_COLOR</constant></entry>
- <entry>integer</entry>
- <entry>Sets the background color on the current output device.
- Background color needs to be specified in the RGB24 format. The
- supplied 32 bit value is interpreted as bits 0-7 Red color information,
- bits 8-15 Green color information, bits 16-23 Blue color
- information and bits 24-31 must be zero.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ILLUMINATORS_1</constant>
- <constant>V4L2_CID_ILLUMINATORS_2</constant></entry>
- <entry>boolean</entry>
- <entry>Switch on or off the illuminator 1 or 2 of the device
- (usually a microscope).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry>
- <entry>integer</entry>
- <entry>This is a read-only control that can be read by the application
-and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS.
-The value is the minimum number of CAPTURE buffers that is necessary for hardware
-to work.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_OUTPUT</constant></entry>
- <entry>integer</entry>
- <entry>This is a read-only control that can be read by the application
-and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS.
-The value is the minimum number of OUTPUT buffers that is necessary for hardware
-to work.</entry>
- </row>
- <row id="v4l2-alpha-component">
- <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>
- <entry>integer</entry>
- <entry> Sets the alpha color component on the capture device or on
- the capture buffer queue of a mem-to-mem device. When a mem-to-mem
- device produces frame format that includes an alpha component
- (e.g. <link linkend="rgb-formats">packed RGB image formats</link>)
- and the alpha value is not defined by the mem-to-mem input data
- this control lets you select the alpha component value of all
- pixels. It is applicable to any pixel format that contains an alpha
- component.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_LASTP1</constant></entry>
- <entry></entry>
- <entry>End of the predefined control IDs (currently
- <constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>
- <entry></entry>
- <entry>ID of the first custom (driver specific) control.
-Applications depending on particular custom controls should check the
-driver name and version, see <xref linkend="querycap" />.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Applications can enumerate the available controls with the
-&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a
-control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
-Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
-<constant>VIDIOC_G_CTRL</constant> and
-<constant>VIDIOC_S_CTRL</constant> when the device has one or more
-controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
-more menu type controls.</para>
-
- <example>
- <title>Enumerating all controls</title>
-
- <programlisting>
-&v4l2-queryctrl; queryctrl;
-&v4l2-querymenu; querymenu;
-
-static void
-enumerate_menu (void)
-{
- printf (" Menu items:\n");
-
- memset (&amp;querymenu, 0, sizeof (querymenu));
- querymenu.id = queryctrl.id;
-
- for (querymenu.index = queryctrl.minimum;
- querymenu.index &lt;= queryctrl.maximum;
- querymenu.index++) {
- if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
- printf (" %s\n", querymenu.name);
- }
- }
-}
-
-memset (&amp;queryctrl, 0, sizeof (queryctrl));
-
-for (queryctrl.id = V4L2_CID_BASE;
- queryctrl.id &lt; V4L2_CID_LASTP1;
- queryctrl.id++) {
- if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf ("Control %s\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu ();
- } else {
- if (errno == EINVAL)
- continue;
-
- perror ("VIDIOC_QUERYCTRL");
- exit (EXIT_FAILURE);
- }
-}
-
-for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
- queryctrl.id++) {
- if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf ("Control %s\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu ();
- } else {
- if (errno == EINVAL)
- break;
-
- perror ("VIDIOC_QUERYCTRL");
- exit (EXIT_FAILURE);
- }
-}
-</programlisting>
- </example>
-
- <example>
- <title>Changing controls</title>
-
- <programlisting>
-&v4l2-queryctrl; queryctrl;
-&v4l2-control; control;
-
-memset (&amp;queryctrl, 0, sizeof (queryctrl));
-queryctrl.id = V4L2_CID_BRIGHTNESS;
-
-if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
- if (errno != EINVAL) {
- perror ("VIDIOC_QUERYCTRL");
- exit (EXIT_FAILURE);
- } else {
- printf ("V4L2_CID_BRIGHTNESS is not supported\n");
- }
-} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
- printf ("V4L2_CID_BRIGHTNESS is not supported\n");
-} else {
- memset (&amp;control, 0, sizeof (control));
- control.id = V4L2_CID_BRIGHTNESS;
- control.value = queryctrl.default_value;
-
- if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)) {
- perror ("VIDIOC_S_CTRL");
- exit (EXIT_FAILURE);
- }
-}
-
-memset (&amp;control, 0, sizeof (control));
-control.id = V4L2_CID_CONTRAST;
-
-if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;control)) {
- control.value += 1;
-
- /* The driver may clamp the value or return ERANGE, ignored here */
-
- if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)
- &amp;&amp; errno != ERANGE) {
- perror ("VIDIOC_S_CTRL");
- exit (EXIT_FAILURE);
- }
-/* Ignore if V4L2_CID_CONTRAST is unsupported */
-} else if (errno != EINVAL) {
- perror ("VIDIOC_G_CTRL");
- exit (EXIT_FAILURE);
-}
-
-control.id = V4L2_CID_AUDIO_MUTE;
-control.value = TRUE; /* silence */
-
-/* Errors ignored */
-ioctl (fd, VIDIOC_S_CTRL, &amp;control);
-</programlisting>
- </example>
- </section>
-
- <section id="extended-controls">
- <title>Extended Controls</title>
-
- <section>
- <title>Introduction</title>
-
- <para>The control mechanism as originally designed was meant
-to be used for user settings (brightness, saturation, etc). However,
-it turned out to be a very useful model for implementing more
-complicated driver APIs where each driver implements only a subset of
-a larger API.</para>
-
- <para>The MPEG encoding API was the driving force behind
-designing and implementing this extended control mechanism: the MPEG
-standard is quite large and the currently supported hardware MPEG
-encoders each only implement a subset of this standard. Further more,
-many parameters relating to how the video is encoded into an MPEG
-stream are specific to the MPEG encoding chip since the MPEG standard
-only defines the format of the resulting MPEG stream, not how the
-video is actually encoded into that format.</para>
-
- <para>Unfortunately, the original control API lacked some
-features needed for these new uses and so it was extended into the
-(not terribly originally named) extended control API.</para>
-
- <para>Even though the MPEG encoding API was the first effort
-to use the Extended Control API, nowadays there are also other classes
-of Extended Controls, such as Camera Controls and FM Transmitter Controls.
-The Extended Controls API as well as all Extended Controls classes are
-described in the following text.</para>
- </section>
-
- <section>
- <title>The Extended Control API</title>
-
- <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,
-&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on
-arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
-&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
-since it is often required to atomically change several controls at
-once.</para>
-
- <para>Each of the new ioctls expects a pointer to a
-&v4l2-ext-controls;. This structure contains a pointer to the control
-array, a count of the number of controls in that array and a control
-class. Control classes are used to group similar controls into a
-single class. For example, control class
-<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls
-(&ie; all controls that can also be set using the old
-<constant>VIDIOC_S_CTRL</constant> ioctl). Control class
-<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls
-relating to MPEG encoding, etc.</para>
-
- <para>All controls in the control array must belong to the
-specified control class. An error is returned if this is not the
-case.</para>
-
- <para>It is also possible to use an empty control array (count
-== 0) to check whether the specified control class is
-supported.</para>
-
- <para>The control array is a &v4l2-ext-control; array. The
-<structname>v4l2_ext_control</structname> structure is very similar to
-&v4l2-control;, except for the fact that it also allows for 64-bit
-values and pointers to be passed.</para>
-
- <para>It is important to realize that due to the flexibility of
-controls it is necessary to check whether the control you want to set
-actually is supported in the driver and what the valid range of values
-is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
-check this. Also note that it is possible that some of the menu
-indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
-may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
-return an error). A good example is the list of supported MPEG audio
-bitrates. Some drivers only support one or two bitrates, others
-support a wider range.</para>
-
- <para>
- All controls use machine endianness.
- </para>
- </section>
-
- <section>
- <title>Enumerating Extended Controls</title>
-
- <para>The recommended way to enumerate over the extended
-controls is by using &VIDIOC-QUERYCTRL; in combination with the
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>
-
- <informalexample>
- <programlisting>
-&v4l2-queryctrl; qctrl;
-
-qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
-while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
-}
-</programlisting>
- </informalexample>
-
- <para>The initial control ID is set to 0 ORed with the
-<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The
-<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first
-control with a higher ID than the specified one. When no such controls
-are found an error is returned.</para>
-
- <para>If you want to get all controls within a specific control
-class, then you can set the initial
-<structfield>qctrl.id</structfield> value to the control class and add
-an extra check to break out of the loop when a control of another
-control class is found:</para>
-
- <informalexample>
- <programlisting>
-qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
-while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
- if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
- break;
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
- }
-</programlisting>
- </informalexample>
-
- <para>The 32-bit <structfield>qctrl.id</structfield> value is
-subdivided into three bit ranges: the top 4 bits are reserved for
-flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
-actually part of the ID. The remaining 28 bits form the control ID, of
-which the most significant 12 bits define the control class and the
-least significant 16 bits identify the control within the control
-class. It is guaranteed that these last 16 bits are always non-zero
-for controls. The range of 0x1000 and up are reserved for
-driver-specific controls. The macro
-<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
-ID based on a control ID.</para>
-
- <para>If the driver does not support extended controls, then
-<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
-combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
-that case the old method of enumerating control should be used (see
-1.8). But if it is supported, then it is guaranteed to enumerate over
-all controls, including driver-private controls.</para>
- </section>
-
- <section>
- <title>Creating Control Panels</title>
-
- <para>It is possible to create control panels for a graphical
-user interface where the user can select the various controls.
-Basically you will have to iterate over all controls using the method
-described above. Each control class starts with a control of type
-<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.
-<constant>VIDIOC_QUERYCTRL</constant> will return the name of this
-control class which can be used as the title of a tab page within a
-control panel.</para>
-
- <para>The flags field of &v4l2-queryctrl; also contains hints on
-the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
-for more details.</para>
- </section>
-
- <section id="mpeg-controls">
- <title>MPEG Control Reference</title>
-
- <para>Below all controls within the MPEG control class are
-described. First the generic controls, then controls specific for
-certain hardware.</para>
-
- <section>
- <title>Generic MPEG Controls</title>
-
- <table pgwide="1" frame="none" id="mpeg-control-id">
- <title>MPEG Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The MPEG class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class. This description can be used as the
-caption of a Tab page in a GUI, for example.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-stream-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_stream_type</entry>
- </row><row><entry spanname="descr">The MPEG-1, -2 or -4
-output stream type. One cannot assume anything here. Each hardware
-MPEG encoder tends to support different subsets of the available MPEG
-stream types. This control is specific to multiplexed MPEG streams.
-The currently defined stream types are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant>&nbsp;</entry>
- <entry>MPEG-2 program stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant>&nbsp;</entry>
- <entry>MPEG-2 transport stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant>&nbsp;</entry>
- <entry>MPEG-1 system stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant>&nbsp;</entry>
- <entry>MPEG-2 DVD-compatible stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant>&nbsp;</entry>
- <entry>MPEG-1 VCD-compatible stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant>&nbsp;</entry>
- <entry>MPEG-2 SVCD-compatible stream</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Program Map Table
-Packet ID for the MPEG transport stream (default 16)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Audio Packet ID for
-the MPEG transport stream (default 256)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video Packet ID for
-the MPEG transport stream (default 260)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Packet ID for the
-MPEG transport stream carrying PCR fields (default 259)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Audio ID for MPEG
-PES</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video ID for MPEG
-PES</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-stream-vbi-fmt">
- <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_stream_vbi_fmt</entry>
- </row><row><entry spanname="descr">Some cards can embed
-VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
-control selects whether VBI data should be embedded, and if so, what
-embedding method should be used. The list of possible VBI formats
-depends on the driver. The currently defined VBI format types
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant>&nbsp;</entry>
- <entry>No VBI in the MPEG stream</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant>&nbsp;</entry>
- <entry>VBI in private packets, IVTV format (documented
-in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-sampling-freq">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_sampling_freq</entry>
- </row><row><entry spanname="descr">MPEG Audio sampling
-frequency. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant>&nbsp;</entry>
- <entry>44.1 kHz</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant>&nbsp;</entry>
- <entry>48 kHz</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant>&nbsp;</entry>
- <entry>32 kHz</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-encoding">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_encoding</entry>
- </row><row><entry spanname="descr">MPEG Audio encoding.
-This control is specific to multiplexed MPEG streams.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer I encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer II encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant>&nbsp;</entry>
- <entry>MPEG-1/2 Layer III encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant>&nbsp;</entry>
- <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant>&nbsp;</entry>
- <entry>AC-3 aka ATSC A/52 encoding</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l1-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l1_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry></row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant>&nbsp;</entry>
- <entry>288 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant>&nbsp;</entry>
- <entry>352 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant>&nbsp;</entry>
- <entry>416 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant>&nbsp;</entry>
- <entry>448 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l2-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l2_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-l3-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_l3_bitrate</entry>
- </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant>&nbsp;</entry>
- <entry>40 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-ac3-bitrate">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_ac3_bitrate</entry>
- </row><row><entry spanname="descr">AC-3 bitrate.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant>&nbsp;</entry>
- <entry>32 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant>&nbsp;</entry>
- <entry>40 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant>&nbsp;</entry>
- <entry>48 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant>&nbsp;</entry>
- <entry>56 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant>&nbsp;</entry>
- <entry>64 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant>&nbsp;</entry>
- <entry>80 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant>&nbsp;</entry>
- <entry>96 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant>&nbsp;</entry>
- <entry>112 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant>&nbsp;</entry>
- <entry>128 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant>&nbsp;</entry>
- <entry>160 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant>&nbsp;</entry>
- <entry>192 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant>&nbsp;</entry>
- <entry>224 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant>&nbsp;</entry>
- <entry>256 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant>&nbsp;</entry>
- <entry>320 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant>&nbsp;</entry>
- <entry>384 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant>&nbsp;</entry>
- <entry>448 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant>&nbsp;</entry>
- <entry>512 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant>&nbsp;</entry>
- <entry>576 kbit/s</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant>&nbsp;</entry>
- <entry>640 kbit/s</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_mode</entry>
- </row><row><entry spanname="descr">MPEG Audio mode.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant>&nbsp;</entry>
- <entry>Stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant>&nbsp;</entry>
- <entry>Joint Stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant>&nbsp;</entry>
- <entry>Bilingual</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant>&nbsp;</entry>
- <entry>Mono</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-mode-extension">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_mode_extension</entry>
- </row><row><entry spanname="descr">Joint Stereo
-audio mode extension. In Layer I and II they indicate which subbands
-are in intensity stereo. All other subbands are coded in stereo. Layer
-III is not (yet) supported. Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant>&nbsp;</entry>
- <entry>Subbands 4-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant>&nbsp;</entry>
- <entry>Subbands 8-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant>&nbsp;</entry>
- <entry>Subbands 12-31 in intensity stereo</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant>&nbsp;</entry>
- <entry>Subbands 16-31 in intensity stereo</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-emphasis">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_emphasis</entry>
- </row><row><entry spanname="descr">Audio Emphasis.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant>&nbsp;</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant>&nbsp;</entry>
- <entry>50/15 microsecond emphasis</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant>&nbsp;</entry>
- <entry>CCITT J.17</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-crc">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_crc</entry>
- </row><row><entry spanname="descr">CRC method. Possible
-values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant>&nbsp;</entry>
- <entry>None</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant>&nbsp;</entry>
- <entry>16 bit parity check</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Mutes the audio when
-capturing. This is not done by muting audio hardware, which can still
-produce a slight hiss, but in the encoder itself, guaranteeing a fixed
-and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-dec-playback">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_dec_playback</entry>
- </row><row><entry spanname="descr">Determines how monolingual audio should be played back.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant>&nbsp;</entry>
- <entry>Automatically determines the best playback mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant>&nbsp;</entry>
- <entry>Stereo playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant>&nbsp;</entry>
- <entry>Left channel playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant>&nbsp;</entry>
- <entry>Right channel playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant>&nbsp;</entry>
- <entry>Mono playback.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant>&nbsp;</entry>
- <entry>Stereo playback with swapped left and right channels.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-audio-dec-multilingual-playback">
- <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_audio_dec_playback</entry>
- </row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-encoding">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_encoding</entry>
- </row><row><entry spanname="descr">MPEG Video encoding
-method. This control is specific to multiplexed MPEG streams.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant>&nbsp;</entry>
- <entry>MPEG-1 Video encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant>&nbsp;</entry>
- <entry>MPEG-2 Video encoding</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant>&nbsp;</entry>
- <entry>MPEG-4 AVC (H.264) Video encoding</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-aspect">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_aspect</entry>
- </row><row><entry spanname="descr">Video aspect.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant>&nbsp;</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant>&nbsp;</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Number of B-Frames
-(default 2)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">GOP size (default
-12)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">GOP closure (default
-1)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enable 3:2 pulldown
-(default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-bitrate-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_bitrate_mode</entry>
- </row><row><entry spanname="descr">Video bitrate mode.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant>&nbsp;</entry>
- <entry>Variable bitrate</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant>&nbsp;</entry>
- <entry>Constant bitrate</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Video bitrate in bits
-per second.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Peak video bitrate in
-bits per second. Must be larger or equal to the average video bitrate.
-It is ignored if the video bitrate mode is set to constant
-bitrate.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">For every captured
-frame, skip this many subsequent frames (default 0).</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">"Mutes" the video to a
-fixed color when capturing. This is useful for testing, to produce a
-fixed video bitstream. 0 = unmuted, 1 = muted.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Sets the "mute" color
-of the video. The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:7</entry>
- <entry>V chrominance information</entry>
- </row>
- <row>
- <entry>Bit 8:15</entry>
- <entry>U chrominance information</entry>
- </row>
- <row>
- <entry>Bit 16:23</entry>
- <entry>Y luminance information</entry>
- </row>
- <row>
- <entry>Bit 24:31</entry>
- <entry>Must be zero.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-dec-pts">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant>&nbsp;</entry>
- <entry>integer64</entry>
- </row><row><entry spanname="descr">This read-only control returns the
-33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of
-the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-dec-frame">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant>&nbsp;</entry>
- <entry>integer64</entry>
- </row><row><entry spanname="descr">This read-only control returns the
-frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever
-the decoder is started.</entry>
- </row>
-
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">If enabled the decoder expects to receive a single slice per buffer, otherwise
-the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs.
-</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable writing sample aspect ratio in the Video Usability Information.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-vui-sar-idc">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_vui_sar_idc</entry>
- </row>
- <row><entry spanname="descr">VUI sample aspect ratio indicator for H.264 encoding. The value
-is defined in the table E-1 in the standard. Applicable to the H264 encoder.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
-
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED</constant>&nbsp;</entry>
- <entry>Unspecified</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1</constant>&nbsp;</entry>
- <entry>1x1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11</constant>&nbsp;</entry>
- <entry>12x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11</constant>&nbsp;</entry>
- <entry>10x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11</constant>&nbsp;</entry>
- <entry>16x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33</constant>&nbsp;</entry>
- <entry>40x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11</constant>&nbsp;</entry>
- <entry>24x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11</constant>&nbsp;</entry>
- <entry>20x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11</constant>&nbsp;</entry>
- <entry>32x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33</constant>&nbsp;</entry>
- <entry>80x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11</constant>&nbsp;</entry>
- <entry>18x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11</constant>&nbsp;</entry>
- <entry>15x11</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33</constant>&nbsp;</entry>
- <entry>64x33</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99</constant>&nbsp;</entry>
- <entry>160x99</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3</constant>&nbsp;</entry>
- <entry>4x3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2</constant>&nbsp;</entry>
- <entry>3x2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1</constant>&nbsp;</entry>
- <entry>2x1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED</constant>&nbsp;</entry>
- <entry>Extended SAR</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Extended sample aspect ratio width for H.264 VUI encoding.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Extended sample aspect ratio height for H.264 VUI encoding.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-level">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_level</entry>
- </row>
- <row><entry spanname="descr">The level information for the H264 video elementary stream.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_0</constant>&nbsp;</entry>
- <entry>Level 1.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1B</constant>&nbsp;</entry>
- <entry>Level 1B</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_1</constant>&nbsp;</entry>
- <entry>Level 1.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_2</constant>&nbsp;</entry>
- <entry>Level 1.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_3</constant>&nbsp;</entry>
- <entry>Level 1.3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_0</constant>&nbsp;</entry>
- <entry>Level 2.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_1</constant>&nbsp;</entry>
- <entry>Level 2.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_2</constant>&nbsp;</entry>
- <entry>Level 2.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_0</constant>&nbsp;</entry>
- <entry>Level 3.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_1</constant>&nbsp;</entry>
- <entry>Level 3.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_2</constant>&nbsp;</entry>
- <entry>Level 3.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_0</constant>&nbsp;</entry>
- <entry>Level 4.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_1</constant>&nbsp;</entry>
- <entry>Level 4.1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_2</constant>&nbsp;</entry>
- <entry>Level 4.2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_0</constant>&nbsp;</entry>
- <entry>Level 5.0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_1</constant>&nbsp;</entry>
- <entry>Level 5.1</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-mpeg4-level">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_mpeg4_level</entry>
- </row>
- <row><entry spanname="descr">The level information for the MPEG4 elementary stream.
-Applicable to the MPEG4 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0</constant>&nbsp;</entry>
- <entry>Level 0</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_0B</constant>&nbsp;</entry>
- <entry>Level 0b</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_1</constant>&nbsp;</entry>
- <entry>Level 1</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_2</constant>&nbsp;</entry>
- <entry>Level 2</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3</constant>&nbsp;</entry>
- <entry>Level 3</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_3B</constant>&nbsp;</entry>
- <entry>Level 3b</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_4</constant>&nbsp;</entry>
- <entry>Level 4</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_LEVEL_5</constant>&nbsp;</entry>
- <entry>Level 5</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-profile">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_profile</entry>
- </row>
- <row><entry spanname="descr">The profile information for H264.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE</constant>&nbsp;</entry>
- <entry>Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE</constant>&nbsp;</entry>
- <entry>Constrained Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MAIN</constant>&nbsp;</entry>
- <entry>Main profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED</constant>&nbsp;</entry>
- <entry>Extended profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH</constant>&nbsp;</entry>
- <entry>High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10</constant>&nbsp;</entry>
- <entry>High 10 profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422</constant>&nbsp;</entry>
- <entry>High 422 profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE</constant>&nbsp;</entry>
- <entry>High 444 Predictive profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA</constant>&nbsp;</entry>
- <entry>High 10 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA</constant>&nbsp;</entry>
- <entry>High 422 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA</constant>&nbsp;</entry>
- <entry>High 444 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA</constant>&nbsp;</entry>
- <entry>CAVLC 444 Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE</constant>&nbsp;</entry>
- <entry>Scalable Baseline profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH</constant>&nbsp;</entry>
- <entry>Scalable High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA</constant>&nbsp;</entry>
- <entry>Scalable High Intra profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH</constant>&nbsp;</entry>
- <entry>Stereo High profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH</constant>&nbsp;</entry>
- <entry>Multiview High profile</entry>
- </row>
-
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-mpeg4-profile">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_mpeg4_profile</entry>
- </row>
- <row><entry spanname="descr">The profile information for MPEG4.
-Applicable to the MPEG4 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE</constant>&nbsp;</entry>
- <entry>Simple profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE</constant>&nbsp;</entry>
- <entry>Advanced Simple profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_CORE</constant>&nbsp;</entry>
- <entry>Core profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE</constant>&nbsp;</entry>
- <entry>Simple Scalable profile</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY</constant>&nbsp;</entry>
- <entry></entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MAX_REF_PIC</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum number of reference pictures used for encoding.
-Applicable to the encoder.
-</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-multi-slice-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_multi_slice_mode</entry>
- </row>
- <row><entry spanname="descr">Determines how the encoder should handle division of frame into slices.
-Applicable to the encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE</constant>&nbsp;</entry>
- <entry>Single slice per frame.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>&nbsp;</entry>
- <entry>Multiple slices with set maximum number of macroblocks per slice.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>&nbsp;</entry>
- <entry>Multiple slice with set maximum size in bytes per slice.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum number of macroblocks in a slice. Used when
-<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>.
-Applicable to the encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The maximum size of a slice in bytes. Used when
-<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>.
-Applicable to the encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-loop-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_loop_filter_mode</entry>
- </row>
- <row><entry spanname="descr">Loop filter mode for H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED</constant>&nbsp;</entry>
- <entry>Loop filter is enabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED</constant>&nbsp;</entry>
- <entry>Loop filter is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY</constant>&nbsp;</entry>
- <entry>Loop filter is disabled at the slice boundary.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Loop filter alpha coefficient, defined in the H264 standard.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Loop filter beta coefficient, defined in the H264 standard.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-h264-entropy-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_h264_entropy_mode</entry>
- </row>
- <row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC.
-Applicable to the H264 encoder.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC</constant>&nbsp;</entry>
- <entry>Use CAVLC entropy coding.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC</constant>&nbsp;</entry>
- <entry>Use CABAC entropy coding.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable 8X8 transform for H264. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks
-refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the
-top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Frame level rate control enable.
-If this control is disabled then the quantization parameter for each frame type is constant and set with appropriate controls
-(e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>).
-If frame rate control is enabled then quantization parameter is adjusted to meet the chosen bitrate. Minimum and maximum value
-for the quantization parameter can be set with appropriate controls (e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>).
-Applicable to encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Macroblock level rate control enable.
-Applicable to the MPEG4 and H264 encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_QPEL</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for H263. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for H264. Valid range: from 0 to 51.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an P frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip.
-The VBV is defined in the standard as a mean to verify that the produced stream will be successfully decoded.
-The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the
-output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an
-encoder or editing process may produce.".
-Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip.
-The CPB is defined in the H264 standard as a mean to verify that the produced stream will be successfully decoded.
-Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_PERIOD</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Period between I-frames in the open GOP for H264. In case of an open GOP
-this is the period between two I-frames. The period between IDR (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE control.
-An IDR frame, which stands for Instantaneous Decoding Refresh is an I-frame after which no prior frames are
-referenced. This means that a stream can be restarted from an IDR frame without the need to store or decode any
-previous frames. Applicable to the H264 encoder.</entry>
- </row>
-
- <row><entry></entry></row>
- <row id="v4l2-mpeg-video-header-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_video_header_mode</entry>
- </row>
- <row><entry spanname="descr">Determines whether the header is returned as the first buffer or is
-it returned together with the first frame. Applicable to encoders.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE</constant>&nbsp;</entry>
- <entry>The stream header is returned separately in the first buffer.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME</constant>&nbsp;</entry>
- <entry>The stream header is returned together with the first encoded frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder.
-Applicable to the MPEG4 decoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">vop_time_increment_resolution value for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>MFC 5.1 MPEG Controls</title>
-
- <para>The following MPEG class controls deal with MPEG
-decoding and encoding settings that are specific to the Multi Format Codec 5.1 device present
-in the S5P family of SoCs by Samsung.
-</para>
-
- <table pgwide="1" frame="none" id="mfc51-control-id">
- <title>MFC 5.1 Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">If the display delay is enabled then the decoder has to return a
-CAPTURE buffer after processing a certain number of OUTPUT buffers. If this number is low, then it may result in
-buffers not being dequeued in display order. In addition hardware may still use those buffers as reference, thus
-application should not write to those buffers. This feature can be used for example for generating thumbnails of videos.
-Applicable to the H264 decoder.
- </entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Display delay value for H264 decoder.
-The decoder is forced to return a decoded frame after the set 'display delay' number of frames. If this number is
-low it may result in frames returned out of dispaly order, in addition the hardware may still be using the returned buffer
-as a reference picture for subsequent frames.
-</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">The number of reference pictures used for encoding a P picture.
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Padding enable in the encoder - use a color instead of repeating border pixels.
-Applicable to encoders.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Padding color in the encoder. Applicable to encoders. The supplied 32-bit integer is interpreted as follows (bit
-0 = least significant bit):</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry>Bit 0:7</entry>
- <entry>V chrominance information</entry>
- </row>
- <row>
- <entry>Bit 8:15</entry>
- <entry>U chrominance information</entry>
- </row>
- <row>
- <entry>Bit 16:23</entry>
- <entry>Y luminance information</entry>
- </row>
- <row>
- <entry>Bit 24:31</entry>
- <entry>Must be zero.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Reaction coefficient for MFC rate control. Applicable to encoders.
-<para>Note 1: Valid only when the frame level RC is enabled.</para>
-<para>Note 2: For tight CBR, this field must be small (ex. 2 ~ 10).
-For VBR, this field must be large (ex. 100 ~ 1000).</para>
-<para>Note 3: It is not recommended to use the greater number than FRAME_RATE * (10^9 / BIT_RATE).</para>
-</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for dark region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for smooth region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for static region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Adaptive rate control for activity region.
-Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
-Applicable to the H264 encoder.</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-mfc51-video-frame-skip-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_mfc51_video_frame_skip_mode</entry>
- </row>
- <row><entry spanname="descr">
-Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then
-a chosen data limit then the frame will be skipped.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED</constant>&nbsp;</entry>
- <entry>Frame skip mode is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT</constant>&nbsp;</entry>
- <entry>Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT</constant>&nbsp;</entry>
- <entry>Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Enable rate-control with fixed target bit.
-If this setting is enabled, then the rate control logic of the encoder will calculate the average bitrate
-for a GOP and keep it below or equal the set bitrate target. Otherwise the rate control logic calculates the
-overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case
-the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the
-average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that
-the stream will meet tight bandwidth contraints. Applicable to encoders.
-</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-mfc51-video-force-frame-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_mfc51_video_force_frame_type</entry>
- </row>
- <row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders.
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED</constant>&nbsp;</entry>
- <entry>Forcing a specific frame type disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME</constant>&nbsp;</entry>
- <entry>Force an I-frame.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED</constant>&nbsp;</entry>
- <entry>Force a non-coded frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>CX2341x MPEG Controls</title>
-
- <para>The following MPEG class controls deal with MPEG
-encoding settings that are specific to the Conexant CX23415 and
-CX23416 MPEG encoding chips.</para>
-
- <table pgwide="1" frame="none" id="cx2341x-control-id">
- <title>CX2341x Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
- </row><row><entry spanname="descr">Sets the Spatial
-Filter mode (default <constant>MANUAL</constant>). Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
- <entry>Choose the filter manually</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
- <entry>Choose the filter automatically</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-15)</entry>
- </row><row><entry spanname="descr">The setting for the
-Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>
- </row>
- <row><entry></entry></row>
- <row id="luma-spatial-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
- </row><row><entry spanname="descr">Select the algorithm
-to use for the Luma Spatial Filter (default
-<constant>1D_HOR</constant>). Possible values:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
- <entry>One-dimensional horizontal</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant>&nbsp;</entry>
- <entry>One-dimensional vertical</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant>&nbsp;</entry>
- <entry>Two-dimensional separable</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant>&nbsp;</entry>
- <entry>Two-dimensional symmetrical
-non-separable</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="chroma-spatial-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
- </row><row><entry spanname="descr">Select the algorithm
-for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
-Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
- <entry>One-dimensional horizontal</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
- </row><row><entry spanname="descr">Sets the Temporal
-Filter mode (default <constant>MANUAL</constant>). Possible values
-are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
- <entry>Choose the filter manually</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
- <entry>Choose the filter automatically</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-31)</entry>
- </row><row><entry spanname="descr">The setting for the
-Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
-capturing and 0 for scaled capturing.)</entry>
- </row>
- <row><entry></entry></row>
- <row id="v4l2-mpeg-cx2341x-video-median-filter-type">
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_median_filter_type</entry>
- </row><row><entry spanname="descr">Median Filter Type
-(default <constant>OFF</constant>). Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant>&nbsp;</entry>
- <entry>No filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant>&nbsp;</entry>
- <entry>Horizontal filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant>&nbsp;</entry>
- <entry>Vertical filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant>&nbsp;</entry>
- <entry>Horizontal and vertical filter</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant>&nbsp;</entry>
- <entry>Diagonal filter</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold above which
-the luminance median filter is enabled (default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold below which
-the luminance median filter is enabled (default 255)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold above which
-the chroma median filter is enabled (default 0)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
- <entry>integer&nbsp;(0-255)</entry>
- </row><row><entry spanname="descr">Threshold below which
-the chroma median filter is enabled (default 255)</entry>
- </row>
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">The CX2341X MPEG encoder
-can insert one empty MPEG-2 PES packet into the stream between every
-four video frames. The packet size is 2048 bytes, including the
-packet_start_code_prefix and stream_id fields. The stream_id is 0xBF
-(private stream 2). The payload consists of 0x00 bytes, to be filled
-in by the application. 0 = do not insert, 1 = insert packets.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
- </section>
-
- <section id="camera-controls">
- <title>Camera Control Reference</title>
-
- <para>The Camera class includes controls for mechanical (or
-equivalent digital) features of a device such as controllable lenses
-or sensors.</para>
-
- <table pgwide="1" frame="none" id="camera-control-id">
- <title>Camera Control IDs</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The Camera class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-exposure-auto-type">
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_exposure_auto_type</entry>
- </row><row><entry spanname="descr">Enables automatic
-adjustments of the exposure time and/or iris aperture. The effect of
-manual changes of the exposure time or iris aperture while these
-features are enabled is undefined, drivers should ignore such
-requests. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EXPOSURE_AUTO</constant>&nbsp;</entry>
- <entry>Automatic exposure time, automatic iris
-aperture.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_MANUAL</constant>&nbsp;</entry>
- <entry>Manual exposure time, manual iris.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant>&nbsp;</entry>
- <entry>Manual exposure time, auto iris.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant>&nbsp;</entry>
- <entry>Auto exposure time, manual iris.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Determines the exposure
-time of the camera sensor. The exposure time is limited by the frame
-interval. Drivers should interpret the values as 100 &micro;s units,
-where the value 1 stands for 1/10000th of a second, 10000 for 1 second
-and 100000 for 10 seconds.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">When
-<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to
-<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,
-this control determines if the device may dynamically vary the frame
-rate. By default this feature is disabled (0) and the frame rate must
-remain constant.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_BIAS</constant>&nbsp;</entry>
- <entry>integer menu</entry>
- </row><row><entry spanname="descr"> Determines the automatic
-exposure compensation, it is effective only when <constant>V4L2_CID_EXPOSURE_AUTO</constant>
-control is set to <constant>AUTO</constant>, <constant>SHUTTER_PRIORITY </constant>
-or <constant>APERTURE_PRIORITY</constant>.
-It is expressed in terms of EV, drivers should interpret the values as 0.001 EV
-units, where the value 1000 stands for +1 EV.
-<para>Increasing the exposure compensation value is equivalent to decreasing
-the exposure value (EV) and will increase the amount of light at the image
-sensor. The camera performs the exposure compensation by adjusting absolute
-exposure time and/or aperture.</para></entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-exposure-metering">
- <entry spanname="id"><constant>V4L2_CID_EXPOSURE_METERING</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_exposure_metering</entry>
- </row><row><entry spanname="descr">Determines how the camera measures
-the amount of light available for the frame exposure. Possible values are:</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_AVERAGE</constant>&nbsp;</entry>
- <entry>Use the light information coming from the entire frame
-and average giving no weighting to any particular portion of the metered area.
- </entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_CENTER_WEIGHTED</constant>&nbsp;</entry>
- <entry>Average the light information coming from the entire frame
-giving priority to the center of the metered area.</entry>
- </row>
- <row>
- <entry><constant>V4L2_EXPOSURE_METERING_SPOT</constant>&nbsp;</entry>
- <entry>Measure only very small area at the center of the frame.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera horizontally by the specified amount. The unit is undefined. A
-positive value moves the camera to the right (clockwise when viewed
-from above), a negative value to the left. A value of zero does not
-cause motion. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control turns the
-camera vertically by the specified amount. The unit is undefined. A
-positive value moves the camera up, a negative value down. A value of
-zero does not cause motion. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">When this control is set,
-the camera moves horizontally to the default position.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">When this control is set,
-the camera moves vertically to the default position.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control
-turns the camera horizontally to the specified position. Positive
-values move the camera to the right (clockwise when viewed from above),
-negative values to the left. Drivers should interpret the values as arc
-seconds, with valid values between -180 * 3600 and +180 * 3600
-inclusive.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control
-turns the camera vertically to the specified position. Positive values
-move the camera up, negative values down. Drivers should interpret the
-values as arc seconds, with valid values between -180 * 3600 and +180
-* 3600 inclusive.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control sets the
-focal point of the camera to the specified position. The unit is
-undefined. Positive values set the focus closer to the camera,
-negative values towards infinity.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control moves the
-focal point of the camera by the specified amount. The unit is
-undefined. Positive values move the focus closer to the camera,
-negative values towards infinity. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Enables continuous automatic
-focus adjustments. The effect of manual focus adjustments while this feature
-is enabled is undefined, drivers should ignore such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_START</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">Starts single auto focus process.
-The effect of setting this control when <constant>V4L2_CID_FOCUS_AUTO</constant>
-is set to <constant>TRUE</constant> (1) is undefined, drivers should ignore
-such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_STOP</constant>&nbsp;</entry>
- <entry>button</entry>
- </row><row><entry spanname="descr">Aborts automatic focusing
-started with <constant>V4L2_CID_AUTO_FOCUS_START</constant> control. It is
-effective only when the continuous autofocus is disabled, that is when
-<constant>V4L2_CID_FOCUS_AUTO</constant> control is set to <constant>FALSE
-</constant> (0).</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-focus-status">
- <entry spanname="id">
- <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant>&nbsp;</entry>
- <entry>bitmask</entry>
- </row>
- <row><entry spanname="descr">The automatic focus status. This is a read-only
- control.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_IDLE</constant>&nbsp;</entry>
- <entry>Automatic focus is not active.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_BUSY</constant>&nbsp;</entry>
- <entry>Automatic focusing is in progress.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_REACHED</constant>&nbsp;</entry>
- <entry>Focus has been reached.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_STATUS_FAILED</constant>&nbsp;</entry>
- <entry>Automatic focus has failed, the driver will not
- transition from this state until another action is
- performed by an application.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry spanname="descr">
-Setting <constant>V4L2_LOCK_FOCUS</constant> lock bit of the <constant>V4L2_CID_3A_LOCK
-</constant> control may stop updates of the <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant>
-control value.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-focus-range">
- <entry spanname="id">
- <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_auto_focus_range</entry>
- </row>
- <row><entry spanname="descr">Determines auto focus distance range
-for which lens may be adjusted. </entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_AUTO</constant>&nbsp;</entry>
- <entry>The camera automatically selects the focus range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_NORMAL</constant>&nbsp;</entry>
- <entry>Normal distance range, limited for best automatic focus
-performance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_MACRO</constant>&nbsp;</entry>
- <entry>Macro (close-up) auto focus. The camera will
-use its minimum possible distance for auto focus.</entry>
- </row>
- <row>
- <entry><constant>V4L2_AUTO_FOCUS_RANGE_INFINITY</constant>&nbsp;</entry>
- <entry>The lens is set to focus on an object at infinite distance.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specify the objective lens
-focal length as an absolute value. The zoom unit is driver-specific and its
-value should be a positive integer.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Specify the objective lens
-focal length relatively to the current value. Positive values move the zoom
-lens group towards the telephoto direction, negative values towards the
-wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Move the objective lens group
-at the specified speed until it reaches physical device limits or until an
-explicit request to stop the movement. A positive value moves the zoom lens
-group towards the telephoto direction. A value of zero stops the zoom lens
-group movement. A negative value moves the zoom lens group towards the
-wide-angle direction. The zoom speed unit is driver-specific.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control sets the
-camera's aperture to the specified value. The unit is undefined.
-Larger values open the iris wider, smaller values close it.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">This control modifies the
-camera's aperture by the specified amount. The unit is undefined.
-Positive values open the iris one step further, negative values close
-it one step further. This is a write-only control.</entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row><row><entry spanname="descr">Prevent video from being acquired
-by the camera. When this control is set to <constant>TRUE</constant> (1), no
-image can be captured by the camera. Common means to enforce privacy are
-mechanical obturation of the sensor and firmware image processing, but the
-device is not restricted to these methods. Devices that implement the privacy
-control must support read access and may support write access.</entry>
- </row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row><row><entry spanname="descr">Switch the band-stop filter of a
-camera sensor on or off, or specify its strength. Such band-stop filters can
-be used, for example, to filter out the fluorescent light component.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-auto-n-preset-white-balance">
- <entry spanname="id"><constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_auto_n_preset_white_balance</entry>
- </row><row><entry spanname="descr">Sets white balance to automatic,
-manual or a preset. The presets determine color temperature of the light as
-a hint to the camera for white balance adjustments resulting in most accurate
-color representation. The following white balance presets are listed in order
-of increasing color temperature.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_MANUAL</constant>&nbsp;</entry>
- <entry>Manual white balance.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_AUTO</constant>&nbsp;</entry>
- <entry>Automatic white balance adjustments.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_INCANDESCENT</constant>&nbsp;</entry>
- <entry>White balance setting for incandescent (tungsten) lighting.
-It generally cools down the colors and corresponds approximately to 2500...3500 K
-color temperature range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT</constant>&nbsp;</entry>
- <entry>White balance preset for fluorescent lighting.
-It corresponds approximately to 4000...5000 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT_H</constant>&nbsp;</entry>
- <entry>With this setting the camera will compensate for
-fluorescent H lighting.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_HORIZON</constant>&nbsp;</entry>
- <entry>White balance setting for horizon daylight.
-It corresponds approximately to 5000 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_DAYLIGHT</constant>&nbsp;</entry>
- <entry>White balance preset for daylight (with clear sky).
-It corresponds approximately to 5000...6500 K color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_FLASH</constant>&nbsp;</entry>
- <entry>With this setting the camera will compensate for the flash
-light. It slightly warms up the colors and corresponds roughly to 5000...5500 K
-color temperature.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_CLOUDY</constant>&nbsp;</entry>
- <entry>White balance preset for moderately overcast sky.
-This option corresponds approximately to 6500...8000 K color temperature
-range.</entry>
- </row>
- <row>
- <entry><constant>V4L2_WHITE_BALANCE_SHADE</constant>&nbsp;</entry>
- <entry>White balance preset for shade or heavily overcast
-sky. It corresponds approximately to 9000...10000 K color temperature.
-</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-wide-dynamic-range">
- <entry spanname="id"><constant>V4L2_CID_WIDE_DYNAMIC_RANGE</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables or disables the camera's wide dynamic
-range feature. This feature allows to obtain clear images in situations where
-intensity of the illumination varies significantly throughout the scene, i.e.
-there are simultaneously very dark and very bright areas. It is most commonly
-realized in cameras by combining two subsequent frames with different exposure
-times. <footnote id="ctypeconv"><para> This control may be changed to a menu
-control in the future, if more options are required.</para></footnote></entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-image-stabilization">
- <entry spanname="id"><constant>V4L2_CID_IMAGE_STABILIZATION</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Enables or disables image stabilization.
- <footnoteref linkend="ctypeconv"/></entry>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY</constant>&nbsp;</entry>
- <entry>integer menu</entry>
- </row><row><entry spanname="descr">Determines ISO equivalent of an
-image sensor indicating the sensor's sensitivity to light. The numbers are
-expressed in arithmetic scale, as per <xref linkend="iso12232" /> standard,
-where doubling the sensor sensitivity is represented by doubling the numerical
-ISO value. Applications should interpret the values as standard ISO values
-multiplied by 1000, e.g. control value 800 stands for ISO 0.8. Drivers will
-usually support only a subset of standard ISO values. The effect of setting
-this control while the <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>
-control is set to a value other than <constant>V4L2_CID_ISO_SENSITIVITY_MANUAL
-</constant> is undefined, drivers should ignore such requests.</entry>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-iso-sensitivity-auto-type">
- <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_iso_sensitivity_type</entry>
- </row><row><entry spanname="descr">Enables or disables automatic ISO
-sensitivity adjustments.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_CID_ISO_SENSITIVITY_MANUAL</constant>&nbsp;</entry>
- <entry>Manual ISO sensitivity.</entry>
- </row>
- <row>
- <entry><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>&nbsp;</entry>
- <entry>Automatic ISO sensitivity adjustments.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row id="v4l2-scene-mode">
- <entry spanname="id"><constant>V4L2_CID_SCENE_MODE</constant>&nbsp;</entry>
- <entry>enum&nbsp;v4l2_scene_mode</entry>
- </row><row><entry spanname="descr">This control allows to select
-scene programs as the camera automatic modes optimized for common shooting
-scenes. Within these modes the camera determines best exposure, aperture,
-focusing, light metering, white balance and equivalent sensitivity. The
-controls of those parameters are influenced by the scene mode control.
-An exact behavior in each mode is subject to the camera specification.
-
-<para>When the scene mode feature is not used, this control should be set to
-<constant>V4L2_SCENE_MODE_NONE</constant> to make sure the other possibly
-related controls are accessible. The following scene programs are defined:
-</para>
-</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SCENE_MODE_NONE</constant>&nbsp;</entry>
- <entry>The scene mode feature is disabled.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_BACKLIGHT</constant>&nbsp;</entry>
- <entry>Backlight. Compensates for dark shadows when light is
- coming from behind a subject, also by automatically turning
- on the flash.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_BEACH_SNOW</constant>&nbsp;</entry>
- <entry>Beach and snow. This mode compensates for all-white or
-bright scenes, which tend to look gray and low contrast, when camera's automatic
-exposure is based on an average scene brightness. To compensate, this mode
-automatically slightly overexposes the frames. The white balance may also be
-adjusted to compensate for the fact that reflected snow looks bluish rather
-than white.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_CANDLELIGHT</constant>&nbsp;</entry>
- <entry>Candle light. The camera generally raises the ISO
-sensitivity and lowers the shutter speed. This mode compensates for relatively
-close subject in the scene. The flash is disabled in order to preserve the
-ambiance of the light.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_DAWN_DUSK</constant>&nbsp;</entry>
- <entry>Dawn and dusk. Preserves the colors seen in low
-natural light before dusk and after down. The camera may turn off the flash,
-and automatically focus at infinity. It will usually boost saturation and
-lower the shutter speed.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_FALL_COLORS</constant>&nbsp;</entry>
- <entry>Fall colors. Increases saturation and adjusts white
-balance for color enhancement. Pictures of autumn leaves get saturated reds
-and yellows.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_FIREWORKS</constant>&nbsp;</entry>
- <entry>Fireworks. Long exposure times are used to capture
-the expanding burst of light from a firework. The camera may invoke image
-stabilization.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_LANDSCAPE</constant>&nbsp;</entry>
- <entry>Landscape. The camera may choose a small aperture to
-provide deep depth of field and long exposure duration to help capture detail
-in dim light conditions. The focus is fixed at infinity. Suitable for distant
-and wide scenery.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_NIGHT</constant>&nbsp;</entry>
- <entry>Night, also known as Night Landscape. Designed for low
-light conditions, it preserves detail in the dark areas without blowing out bright
-objects. The camera generally sets itself to a medium-to-high ISO sensitivity,
-with a relatively long exposure time, and turns flash off. As such, there will be
-increased image noise and the possibility of blurred image.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_PARTY_INDOOR</constant>&nbsp;</entry>
- <entry>Party and indoor. Designed to capture indoor scenes
-that are lit by indoor background lighting as well as the flash. The camera
-usually increases ISO sensitivity, and adjusts exposure for the low light
-conditions.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_PORTRAIT</constant>&nbsp;</entry>
- <entry>Portrait. The camera adjusts the aperture so that the
-depth of field is reduced, which helps to isolate the subject against a smooth
-background. Most cameras recognize the presence of faces in the scene and focus
-on them. The color hue is adjusted to enhance skin tones. The intensity of the
-flash is often reduced.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_SPORTS</constant>&nbsp;</entry>
- <entry>Sports. Significantly increases ISO and uses a fast
-shutter speed to freeze motion of rapidly-moving subjects. Increased image
-noise may be seen in this mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_SUNSET</constant>&nbsp;</entry>
- <entry>Sunset. Preserves deep hues seen in sunsets and
-sunrises. It bumps up the saturation.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SCENE_MODE_TEXT</constant>&nbsp;</entry>
- <entry>Text. It applies extra contrast and sharpness, it is
-typically a black-and-white mode optimized for readability. Automatic focus
-may be switched to close-up mode and this setting may also involve some
-lens-distortion correction.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
-
- <row>
- <entry spanname="id"><constant>V4L2_CID_3A_LOCK</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">This control locks or unlocks the automatic
-focus, exposure and white balance. The automatic adjustments can be paused
-independently by setting the corresponding lock bit to 1. The camera then retains
-the settings until the lock bit is cleared. The following lock bits are defined:
-</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_LOCK_EXPOSURE</constant></entry>
- <entry>Automatic exposure adjustments lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_LOCK_WHITE_BALANCE</constant></entry>
- <entry>Automatic white balance adjustments lock.</entry>
- </row>
- <row>
- <entry><constant>V4L2_LOCK_FOCUS</constant></entry>
- <entry>Automatic focus lock.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry spanname="descr">
-When a given algorithm is not enabled, drivers should ignore requests
-to lock it and should return no error. An example might be an application
-setting bit <constant>V4L2_LOCK_WHITE_BALANCE</constant> when the
-<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant> control is set to
-<constant>FALSE</constant>. The value of this control may be changed
-by exposure, white balance or focus controls.</entry>
- </row>
- <row><entry></entry></row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="fm-tx-controls">
- <title>FM Transmitter Control Reference</title>
-
- <para>The FM Transmitter (FM_TX) class includes controls for common features of
-FM transmissions capable devices. Currently this class includes parameters for audio
-compression, pilot tone generation, audio deviation limiter, RDS transmission and
-tuning power features.</para>
-
- <table pgwide="1" frame="none" id="fm-tx-control-id">
- <title>FM_TX Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The FM_TX class
-descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
-description of this control class.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
-The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the RDS Programme Identification field
-for transmission.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
-This encodes up to 31 pre-defined programme types.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
-It is intended for static display on a receiver. It is the primary aid to listeners in programme service
-identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,
-there is a full description of the correct character encoding for Programme Service name strings.
-Also from RDS specification, PS is usually a single eight character text. However, it is also possible
-to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
-with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant>&nbsp;</entry>
- <entry>string</entry>
- </row>
- <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of
-what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
-programme-related information or any other text. In these cases, RadioText should be used in addition to
-<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
-in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being
-used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
-to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
-with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
-The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
-distortion and prevent overmodulation.
-</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the audio deviation limiter feature release time.
-Unit is in useconds. Step and range are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures audio frequency deviation level in Hz.
-The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the audio compression feature.
-This feature amplifies signals below the threshold by a fixed gain and compresses audio
-signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the gain for audio compression feature. It is
-a dB value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the threshold level for audio compression freature.
-It is a dB value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the attack time for audio compression feature.
-It is a useconds value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the release time for audio compression feature.
-It is a useconds value. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant>&nbsp;</entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
-in Hz. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Configures pilot tone frequency value. Unit is
-in Hz. The range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
-A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
-Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_preemphasis
-defines possible values for pre-emphasis. Here they are:</entry>
- </row><row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant>&nbsp;</entry>
- <entry>No pre-emphasis is applied.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PREEMPHASIS_50_uS</constant>&nbsp;</entry>
- <entry>A pre-emphasis of 50 uS is used.</entry>
- </row>
- <row>
- <entry><constant>V4L2_PREEMPHASIS_75_uS</constant>&nbsp;</entry>
- <entry>A pre-emphasis of 75 uS is used.</entry>
- </row>
- </tbody>
- </entrytbl>
-
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">Sets the output power level for signal transmission.
-Unit is in dBuV. Range and step are driver-specific.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant>&nbsp;</entry>
- <entry>integer</entry>
- </row>
- <row><entry spanname="descr">This selects the value of antenna tuning capacitor
-manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
-<para>For more details about RDS specification, refer to
-<xref linkend="en50067" /> document, from CENELEC.</para>
- </section>
-
- <section id="flash-controls">
- <title>Flash Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <para>
- The V4L2 flash controls are intended to provide generic access
- to flash controller devices. Flash controller devices are
- typically used in digital cameras.
- </para>
-
- <para>
- The interface can support both LED and xenon flash devices. As
- of writing this, there is no xenon flash driver using this
- interface.
- </para>
-
- <section id="flash-controls-use-cases">
- <title>Supported use cases</title>
-
- <section>
- <title>Unsynchronised LED flash (software strobe)</title>
-
- <para>
- Unsynchronised LED flash is controlled directly by the
- host as the sensor. The flash must be enabled by the host
- before the exposure of the image starts and disabled once
- it ends. The host is fully responsible for the timing of
- the flash.
- </para>
-
- <para>Example of such device: Nokia N900.</para>
- </section>
-
- <section>
- <title>Synchronised LED flash (hardware strobe)</title>
-
- <para>
- The synchronised LED flash is pre-programmed by the host
- (power and timeout) but controlled by the sensor through a
- strobe signal from the sensor to the flash.
- </para>
-
- <para>
- The sensor controls the flash duration and timing. This
- information typically must be made available to the
- sensor.
- </para>
-
- </section>
-
- <section>
- <title>LED flash as torch</title>
-
- <para>
- LED flash may be used as torch in conjunction with another
- use case involving camera or individually.
- </para>
-
- </section>
-
- </section>
-
- <table pgwide="1" frame="none" id="flash-control-id">
- <title>Flash Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The FLASH class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-flash-led-mode">
- <entry spanname="descr">Defines the mode of the flash LED,
- the high-power white LED attached to the flash controller.
- Setting this control may not be possible in presence of
- some faults. See V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry>
- <entry>Off.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry>
- <entry>Flash mode.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry>
- <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-flash-strobe-source"><entry
- spanname="descr">Defines the source of the flash LED
- strobe.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry>
- <entry>The flash strobe is triggered by using
- the V4L2_CID_FLASH_STROBE control.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry>
- <entry>The flash strobe is triggered by an
- external source. Typically this is a sensor,
- which makes it possible to synchronises the
- flash strobe start to exposure start.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry>
- <entry>button</entry>
- </row>
- <row>
- <entry spanname="descr">Strobe flash. Valid when
- V4L2_CID_FLASH_LED_MODE is set to
- V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
- is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
- control may not be possible in presence of some faults.
- See V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry>
- <entry>button</entry>
- </row>
- <row><entry spanname="descr">Stop flash strobe immediately.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Strobe status: whether the flash
- is strobing at the moment or not. This is a read-only
- control.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Hardware timeout for flash. The
- flash strobe is stopped after this period of time has
- passed from the start of the strobe.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the flash strobe when
- the flash LED is in flash mode
- (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps
- (mA) if possible.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the flash LED in
- torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be
- milliamps (mA) if possible. Setting this control may not
- be possible in presence of some faults. See
- V4L2_CID_FLASH_FAULT.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Intensity of the indicator LED.
- The indicator LED may be fully independent of the flash
- LED. The unit should be microamps (uA) if possible.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Faults related to the flash. The
- faults tell about specific problems in the flash chip
- itself or the LEDs attached to it. Faults may prevent
- further use of some of the flash controls. In particular,
- V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
- if the fault affects the flash LED. Exactly which faults
- have such an effect is chip dependent. Reading the faults
- resets the control and returns the chip to a usable state
- if possible.</entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry>
- <entry>Flash controller voltage to the flash LED
- has exceeded the limit specific to the flash
- controller.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry>
- <entry>The flash strobe was still on when
- the timeout set by the user ---
- V4L2_CID_FLASH_TIMEOUT control --- has expired.
- Not all flash controllers may set this in all
- such conditions.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry>
- <entry>The flash controller has overheated.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry>
- <entry>The short circuit protection of the flash
- controller has been triggered.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry>
- <entry>Current in the LED power supply has exceeded the limit
- specific to the flash controller.</entry>
- </row>
- <row>
- <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry>
- <entry>The flash controller has detected a short or open
- circuit condition on the indicator LED.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry>
- <entry>boolean</entry>
- </row>
- <row><entry spanname="descr">Enable or disable charging of the xenon
- flash capacitor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry>
- <entry>boolean</entry>
- </row>
- <row>
- <entry spanname="descr">Is the flash ready to strobe?
- Xenon flashes require their capacitors charged before
- strobing. LED flashes often require a cooldown period
- after strobe during which another strobe will not be
- possible. This is a read-only control.</entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section id="jpeg-controls">
- <title>JPEG Control Reference</title>
- <para>The JPEG class includes controls for common features of JPEG
- encoders and decoders. Currently it includes features for codecs
- implementing progressive baseline DCT compression process with
- Huffman entrophy coding.</para>
- <table pgwide="1" frame="none" id="jpeg-control-id">
- <title>JPEG Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant>&nbsp;</entry>
- <entry>class</entry>
- </row><row><entry spanname="descr">The JPEG class descriptor. Calling
- &VIDIOC-QUERYCTRL; for this control will return a description of this
- control class.
-
- </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry>
- <entry>menu</entry>
- </row>
- <row id="v4l2-jpeg-chroma-subsampling">
- <entry spanname="descr">The chroma subsampling factors describe how
- each component of an input image is sampled, in respect to maximum
- sample rate in each spatial dimension. See <xref linkend="itu-t81"/>,
- clause A.1.1. for more details. The <constant>
- V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how
- Cb and Cr components are downsampled after coverting an input image
- from RGB to Y'CbCr color space.
- </entry>
- </row>
- <row id = "v4l2-jpeg-chroma-subsampling">
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant>
- </entry><entry>No chroma subsampling, each pixel has
- Y, Cr and Cb values.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant>
- </entry><entry>Horizontally subsample Cr, Cb components
- by a factor of 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant>
- </entry><entry>Subsample Cr, Cb components horizontally
- and vertically by 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant>
- </entry><entry>Horizontally subsample Cr, Cb components
- by a factor of 4.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant>
- </entry><entry>Subsample Cr, Cb components horizontally
- by 4 and vertically by 2.</entry>
- </row>
- <row>
- <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant>
- </entry><entry>Use only luminance component.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant>
- </entry><entry>integer</entry>
- </row>
- <row><entry spanname="descr">
- The restart interval determines an interval of inserting RSTm
- markers (m = 0..7). The purpose of these markers is to additionally
- reinitialize the encoder process, in order to process blocks of
- an image independently.
- For the lossy compression processes the restart interval unit is
- MCU (Minimum Coded Unit) and its value is contained in DRI
- (Define Restart Interval) marker. If <constant>
- V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0,
- DRI and RSTm markers will not be inserted.
- </entry>
- </row>
- <row id="jpeg-quality-control">
- <entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">
- <constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control
- determines trade-off between image quality and size.
- It provides simpler method for applications to control image quality,
- without a need for direct reconfiguration of luminance and chrominance
- quantization tables.
-
- In cases where a driver uses quantization tables configured directly
- by an application, using interfaces defined elsewhere, <constant>
- V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control should be set
- by driver to 0.
-
- <para>The value range of this control is driver-specific. Only
- positive, non-zero values are meaningful. The recommended range
- is 1 - 100, where larger values correspond to better image quality.
- </para>
- </entry>
- </row>
- <row id="jpeg-active-marker-control">
- <entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry>
- <entry>bitmask</entry>
- </row>
- <row>
- <entry spanname="descr">Specify which JPEG markers are included
- in compressed stream. This control is valid only for encoders.
- </entry>
- </row>
- <row>
- <entrytbl spanname="descr" cols="2">
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry>
- <entry>Application data segment APP<subscript>0</subscript>.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry>
- <entry>Application data segment APP<subscript>1</subscript>.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry>
- <entry>Comment segment.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry>
- <entry>Quantization tables segment.</entry>
- </row><row>
- <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry>
- <entry>Huffman tables segment.</entry>
- </row>
- </tbody>
- </entrytbl>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
- <para>For more details about JPEG specification, refer
- to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>,
- <xref linkend="w3c-jpeg-jfif"/>.</para>
- </section>
-
- <section id="image-source-controls">
- <title>Image Source Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
- linkend="experimental">experimental</link> interface and may
- change in the future.</para>
- </note>
-
- <para>
- The Image Source control class is intended for low-level
- control of image source devices such as image sensors. The
- devices feature an analogue to digital converter and a bus
- transmitter to transmit the image data out of the device.
- </para>
-
- <table pgwide="1" frame="none" id="image-source-control-id">
- <title>Image Source Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The IMAGE_SOURCE class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_VBLANK</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Vertical blanking. The idle period
- after every frame during which no image data is produced.
- The unit of vertical blanking is a line. Every line has
- length of the image width plus horizontal blanking at the
- pixel rate defined by
- <constant>V4L2_CID_PIXEL_RATE</constant> control in the
- same sub-device.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_HBLANK</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Horizontal blanking. The idle
- period after every line of image data during which no
- image data is produced. The unit of horizontal blanking is
- pixels.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_ANALOGUE_GAIN</constant></entry>
- <entry>integer</entry>
- </row>
- <row>
- <entry spanname="descr">Analogue gain is gain affecting
- all colour components in the pixel matrix. The gain
- operation is performed in the analogue domain before A/D
- conversion.
- </entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section id="image-process-controls">
- <title>Image Process Control Reference</title>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link
- linkend="experimental">experimental</link> interface and may
- change in the future.</para>
- </note>
-
- <para>
- The Image Source control class is intended for low-level control of
- image processing functions. Unlike
- <constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant>, the controls in
- this class affect processing the image, and do not control capturing
- of it.
- </para>
-
- <table pgwide="1" frame="none" id="image-process-control-id">
- <title>Image Source Control IDs</title>
-
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="6*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="6*" />
- <spanspec namest="c1" nameend="c2" spanname="id" />
- <spanspec namest="c2" nameend="c4" spanname="descr" />
- <thead>
- <row>
- <entry spanname="id" align="left">ID</entry>
- <entry align="left">Type</entry>
- </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row><entry></entry></row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_IMAGE_PROC_CLASS</constant></entry>
- <entry>class</entry>
- </row>
- <row>
- <entry spanname="descr">The IMAGE_PROC class descriptor.</entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_LINK_FREQ</constant></entry>
- <entry>integer menu</entry>
- </row>
- <row>
- <entry spanname="descr">Data bus frequency. Together with the
- media bus pixel code, bus type (clock cycles per sample), the
- data bus frequency defines the pixel rate
- (<constant>V4L2_CID_PIXEL_RATE</constant>) in the
- pixel array (or possibly elsewhere, if the device is not an
- image sensor). The frame rate can be calculated from the pixel
- clock, image width and height and horizontal and vertical
- blanking. While the pixel rate control may be defined elsewhere
- than in the subdev containing the pixel array, the frame rate
- cannot be obtained from that information. This is because only
- on the pixel array it can be assumed that the vertical and
- horizontal blanking information is exact: no other blanking is
- allowed in the pixel array. The selection of frame rate is
- performed by selecting the desired horizontal and vertical
- blanking. The unit of this control is Hz. </entry>
- </row>
- <row>
- <entry spanname="id"><constant>V4L2_CID_PIXEL_RATE</constant></entry>
- <entry>64-bit integer</entry>
- </row>
- <row>
- <entry spanname="descr">Pixel rate in the source pads of
- the subdev. This control is read-only and its unit is
- pixels / second.
- </entry>
- </row>
- <row><entry></entry></row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-</section>
diff --git a/Documentation/DocBook/media/v4l/crop.pdf b/Documentation/DocBook/media/v4l/crop.pdf
deleted file mode 100644
index c9fb81cd32f..00000000000
--- a/Documentation/DocBook/media/v4l/crop.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml
deleted file mode 100644
index e1c5f9406d6..00000000000
--- a/Documentation/DocBook/media/v4l/dev-capture.xml
+++ /dev/null
@@ -1,110 +0,0 @@
- <title>Video Capture Interface</title>
-
- <para>Video capture devices sample an analog video signal and store
-the digitized images in memory. Today nearly all devices can capture
-at full 25 or 30 frames/second. With this interface applications can
-control the capture process and move images from the driver into user
-space.</para>
-
- <para>Conventionally V4L2 video capture devices are accessed through
-character device special files named <filename>/dev/video</filename>
-and <filename>/dev/video0</filename> to
-<filename>/dev/video63</filename> with major number 81 and minor
-numbers 0 to 63. <filename>/dev/video</filename> is typically a
-symbolic link to the preferred video device. Note the same device
-files are used for video output devices.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video capture interface set the
-<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
-<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
-they may also support the <link linkend="overlay">video overlay</link>
-(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
-linkend="raw-vbi">raw VBI capture</link>
-(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
-the read/write or streaming I/O methods must be supported. Tuners and
-audio inputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video capture devices shall support <link
-linkend="audio">audio input</link>, <link
-linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video input</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video capture devices.</para>
- </section>
-
- <section>
- <title>Image Format Negotiation</title>
-
- <para>The result of a capture operation is determined by
-cropping and image format parameters. The former select an area of the
-video picture to capture, the latter how images are stored in memory,
-&ie; in RGB or YUV format, the number of bits per pixel or width and
-height. Together they also define how images are scaled in the
-process.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis> reset
-at &func-open; time to permit Unix tool chains, programming a device
-and then reading from it as if it was a plain file. Well written V4L2
-applications ensure they really get what they want, including cropping
-and scaling.</para>
-
- <para>Cropping initialization at minimum requires to reset the
-parameters to defaults. An example is given in <xref
-linkend="crop" />.</para>
-
- <para>To query the current image format applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> or the
-&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-pix-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
-adjust the parameters and finally return the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does.</para>
-
- <para>Like <constant>VIDIOC_S_FMT</constant> the
-&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
-without disabling I/O or possibly time consuming hardware
-preparations.</para>
-
- <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-are discussed in <xref linkend="pixfmt" />. See also the specification of the
-<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
-and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
-capture devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
- </section>
-
- <section>
- <title>Reading Images</title>
-
- <para>A video capture device may support the <link
-linkend="rw">read() function</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> or <link
-linkend="userp">user pointer</link>) I/O. See <xref
-linkend="io" /> for details.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml
deleted file mode 100644
index dca0ecd54dc..00000000000
--- a/Documentation/DocBook/media/v4l/dev-codec.xml
+++ /dev/null
@@ -1,18 +0,0 @@
- <title>Codec Interface</title>
-
- <note>
- <title>Suspended</title>
-
- <para>This interface has been be suspended from the V4L2 API
-implemented in Linux 2.6 until we have more experience with codec
-device interfaces.</para>
- </note>
-
- <para>A V4L2 codec can compress, decompress, transform, or otherwise
-convert video data from one format into another format, in memory.
-Applications send data to be converted to the driver through a
-&func-write; call, and receive the converted data through a
-&func-read; call. For efficiency a driver may also support streaming
-I/O.</para>
-
- <para>[to do]</para>
diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml
deleted file mode 100644
index 2350a67c071..00000000000
--- a/Documentation/DocBook/media/v4l/dev-effect.xml
+++ /dev/null
@@ -1,17 +0,0 @@
- <title>Effect Devices Interface</title>
-
- <note>
- <title>Suspended</title>
-
- <para>This interface has been be suspended from the V4L2 API
-implemented in Linux 2.6 until we have more experience with effect
-device interfaces.</para>
- </note>
-
- <para>A V4L2 video effect device can do image effects, filtering, or
-combine two or more images or image streams. For example video
-transitions or wipes. Applications send data to be processed and
-receive the result data either with &func-read; and &func-write;
-functions, or through the streaming I/O mechanism.</para>
-
- <para>[to do]</para>
diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml
deleted file mode 100644
index 19f4becfae3..00000000000
--- a/Documentation/DocBook/media/v4l/dev-event.xml
+++ /dev/null
@@ -1,43 +0,0 @@
- <title>Event Interface</title>
-
- <para>The V4L2 event interface provides a means for a user to get
- immediately notified on certain conditions taking place on a device.
- This might include start of frame or loss of signal events, for
- example. Changes in the value or state of a V4L2 control can also be
- reported through events.
- </para>
-
- <para>To receive events, the events the user is interested in first must
- be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is
- subscribed, the events of subscribed types are dequeueable using the
- &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using
- VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may
- be used to unsubscribe all the events the driver supports.</para>
-
- <para>The event subscriptions and event queues are specific to file
- handles. Subscribing an event on one file handle does not affect
- other file handles.</para>
-
- <para>The information on dequeueable events is obtained by using select or
- poll system calls on video devices. The V4L2 events use POLLPRI events on
- poll system call and exceptions on select system call.</para>
-
- <para>Starting with kernel 3.1 certain guarantees can be given with
- regards to events:<orderedlist>
- <listitem>
- <para>Each subscribed event has its own internal dedicated event queue.
-This means that flooding of one event type will not interfere with other
-event types.</para>
- </listitem>
- <listitem>
- <para>If the internal event queue for a particular subscribed event
-becomes full, then the oldest event in that queue will be dropped.</para>
- </listitem>
- <listitem>
- <para>Where applicable, certain event types can ensure that the payload
-of the oldest event that is about to be dropped will be merged with the payload
-of the next oldest event. Thus ensuring that no information is lost, but only an
-intermediate step leading up to that information. See the documentation for the
-event you want to subscribe to whether this is applicable for that event or not.</para>
- </listitem>
- </orderedlist></para>
diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml
deleted file mode 100644
index 479d9433869..00000000000
--- a/Documentation/DocBook/media/v4l/dev-osd.xml
+++ /dev/null
@@ -1,156 +0,0 @@
- <title>Video Output Overlay Interface</title>
- <subtitle>Also known as On-Screen Display (OSD)</subtitle>
-
- <note>
- <title>Experimental</title>
-
- <para>This is an <link linkend="experimental">experimental</link>
-interface and may change in the future.</para>
- </note>
-
- <para>Some video output devices can overlay a framebuffer image onto
-the outgoing video signal. Applications can set up such an overlay
-using this interface, which borrows structures and ioctls of the <link
-linkend="overlay">Video Overlay</link> interface.</para>
-
- <para>The OSD function is accessible through the same character
-special file as the <link linkend="capture">Video Output</link> function.
-Note the default function of such a <filename>/dev/video</filename> device
-is video capturing or output. The OSD function is only available after
-calling the &VIDIOC-S-FMT; ioctl.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the <wordasword>Video Output
-Overlay</wordasword> interface set the
-<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl.</para>
- </section>
-
- <section>
- <title>Framebuffer</title>
-
- <para>Contrary to the <wordasword>Video Overlay</wordasword>
-interface the framebuffer is normally implemented on the TV card and
-not the graphics card. On Linux it is accessible as a framebuffer
-device (<filename>/dev/fbN</filename>). Given a V4L2 device,
-applications can find the corresponding framebuffer device by calling
-the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
-physical address of the framebuffer in the
-<structfield>base</structfield> field of &v4l2-framebuffer;. The
-framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
-returns the same address in the <structfield>smem_start</structfield>
-field of struct <structname>fb_fix_screeninfo</structname>. The
-<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
-<structname>fb_fix_screeninfo</structname> are defined in the
-<filename>linux/fb.h</filename> header file.</para>
-
- <para>The width and height of the framebuffer depends on the
-current video standard. A V4L2 driver may reject attempts to change
-the video standard (or any other ioctl which would imply a framebuffer
-size change) with an &EBUSY; until all applications closed the
-framebuffer device.</para>
-
- <example>
- <title>Finding a framebuffer device for OSD</title>
-
- <programlisting>
-#include &lt;linux/fb.h&gt;
-
-&v4l2-framebuffer; fbuf;
-unsigned int i;
-int fb_fd;
-
-if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
- perror ("VIDIOC_G_FBUF");
- exit (EXIT_FAILURE);
-}
-
-for (i = 0; i &gt; 30; ++i) {
- char dev_name[16];
- struct fb_fix_screeninfo si;
-
- snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
-
- fb_fd = open (dev_name, O_RDWR);
- if (-1 == fb_fd) {
- switch (errno) {
- case ENOENT: /* no such file */
- case ENXIO: /* no driver */
- continue;
-
- default:
- perror ("open");
- exit (EXIT_FAILURE);
- }
- }
-
- if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
- if (si.smem_start == (unsigned long) fbuf.base)
- break;
- } else {
- /* Apparently not a framebuffer device. */
- }
-
- close (fb_fd);
- fb_fd = -1;
-}
-
-/* fb_fd is the file descriptor of the framebuffer device
- for the video output overlay, or -1 if no device was found. */
-</programlisting>
- </example>
- </section>
-
- <section>
- <title>Overlay Window and Scaling</title>
-
- <para>The overlay is controlled by source and target rectangles.
-The source rectangle selects a subsection of the framebuffer image to
-be overlaid, the target rectangle an area in the outgoing video signal
-where the image will appear. Drivers may or may not support scaling,
-and arbitrary sizes and positions of these rectangles. Further drivers
-may support any (or none) of the clipping/blending methods defined for
-the <link linkend="overlay">Video Overlay</link> interface.</para>
-
- <para>A &v4l2-window; defines the size of the source rectangle,
-its position in the framebuffer and the clipping/blending method to be
-used for the overlay. To get the current parameters applications set
-the <structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
-&VIDIOC-G-FMT; ioctl. The driver fills the
-<structname>v4l2_window</structname> substructure named
-<structfield>win</structfield>. It is not possible to retrieve a
-previously programmed clipping list or bitmap.</para>
-
- <para>To program the source rectangle applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
-the <structfield>win</structfield> substructure and call the
-&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
-hardware limits and returns the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does. Like
-<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
-used to learn about driver capabilities without actually changing
-driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
-after the overlay has been enabled.</para>
-
- <para>A &v4l2-crop; defines the size and position of the target
-rectangle. The scaling factor of the overlay is implied by the width
-and height given in &v4l2-window; and &v4l2-crop;. The cropping API
-applies to <wordasword>Video Output</wordasword> and <wordasword>Video
-Output Overlay</wordasword> devices in the same way as to
-<wordasword>Video Capture</wordasword> and <wordasword>Video
-Overlay</wordasword> devices, merely reversing the direction of the
-data flow. For more information see <xref linkend="crop" />.</para>
- </section>
-
- <section>
- <title>Enabling Overlay</title>
-
- <para>There is no V4L2 ioctl to enable or disable the overlay,
-however the framebuffer interface of the driver may support the
-<constant>FBIOBLANK</constant> ioctl.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml
deleted file mode 100644
index 9130a3dc788..00000000000
--- a/Documentation/DocBook/media/v4l/dev-output.xml
+++ /dev/null
@@ -1,106 +0,0 @@
- <title>Video Output Interface</title>
-
- <para>Video output devices encode stills or image sequences as
-analog video signal. With this interface applications can
-control the encoding process and move images from user space to
-the driver.</para>
-
- <para>Conventionally V4L2 video output devices are accessed through
-character device special files named <filename>/dev/video</filename>
-and <filename>/dev/video0</filename> to
-<filename>/dev/video63</filename> with major number 81 and minor
-numbers 0 to 63. <filename>/dev/video</filename> is typically a
-symbolic link to the preferred video device. Note the same device
-files are used for video capture devices.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video output interface set the
-<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
-<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
-they may also support the <link linkend="raw-vbi">raw VBI
-output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
-least one of the read/write or streaming I/O methods must be
-supported. Modulators and audio outputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video output devices shall support <link
-linkend="audio">audio output</link>, <link
-linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video output</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video output devices.</para>
- </section>
-
- <section>
- <title>Image Format Negotiation</title>
-
- <para>The output is determined by cropping and image format
-parameters. The former select an area of the video picture where the
-image will appear, the latter how images are stored in memory, &ie; in
-RGB or YUV format, the number of bits per pixel or width and height.
-Together they also define how images are scaled in the process.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis> reset
-at &func-open; time to permit Unix tool chains, programming a device
-and then writing to it as if it was a plain file. Well written V4L2
-applications ensure they really get what they want, including cropping
-and scaling.</para>
-
- <para>Cropping initialization at minimum requires to reset the
-parameters to defaults. An example is given in <xref
-linkend="crop" />.</para>
-
- <para>To query the current image format applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
-<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-pix-format; <structfield>pix</structfield> or the
-&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-pix-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
-adjust the parameters and finally return the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does.</para>
-
- <para>Like <constant>VIDIOC_S_FMT</constant> the
-&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
-without disabling I/O or possibly time consuming hardware
-preparations.</para>
-
- <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
-are discussed in <xref linkend="pixfmt" />. See also the specification of the
-<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
-and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
-output devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
- </section>
-
- <section>
- <title>Writing Images</title>
-
- <para>A video output device may support the <link
-linkend="rw">write() function</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> or <link
-linkend="userp">user pointer</link>) I/O. See <xref
-linkend="io" /> for details.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml
deleted file mode 100644
index 40d1d768143..00000000000
--- a/Documentation/DocBook/media/v4l/dev-overlay.xml
+++ /dev/null
@@ -1,371 +0,0 @@
- <title>Video Overlay Interface</title>
- <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>
-
- <para>Video overlay devices have the ability to genlock (TV-)video
-into the (VGA-)video signal of a graphics card, or to store captured
-images directly in video memory of a graphics card, typically with
-clipping. This can be considerable more efficient than capturing
-images and displaying them by other means. In the old days when only
-nuclear power plants needed cooling towers this used to be the only
-way to put live video into a window.</para>
-
- <para>Video overlay devices are accessed through the same character
-special files as <link linkend="capture">video capture</link> devices.
-Note the default function of a <filename>/dev/video</filename> device
-is video capturing. The overlay function is only available after
-calling the &VIDIOC-S-FMT; ioctl.</para>
-
- <para>The driver may support simultaneous overlay and capturing
-using the read/write and streaming I/O methods. If so, operation at
-the nominal frame rate of the video standard is not guaranteed. Frames
-may be directed away from overlay to capture, or one field may be used
-for overlay and the other for capture if the capture parameters permit
-this.</para>
-
- <para>Applications should use different file descriptors for
-capturing and overlay. This must be supported by all drivers capable
-of simultaneous capturing and overlay. Optionally these drivers may
-also permit capturing and overlay with a single file descriptor for
-compatibility with V4L and earlier versions of V4L2.<footnote>
- <para>A common application of two file descriptors is the
-XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
-a V4L2 application. While the X server controls video overlay, the
-application can take advantage of memory mapping and DMA.</para>
- <para>In the opinion of the designers of this API, no driver
-writer taking the efforts to support simultaneous capturing and
-overlay will restrict this ability by requiring a single file
-descriptor, as in V4L and earlier versions of V4L2. Making this
-optional means applications depending on two file descriptors need
-backup routines to be compatible with all drivers, which is
-considerable more work than using two fds in applications which do
-not. Also two fd's fit the general concept of one file descriptor for
-each logical stream. Hence as a complexity trade-off drivers
-<emphasis>must</emphasis> support two file descriptors and
-<emphasis>may</emphasis> support single fd operation.</para>
- </footnote></para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the video overlay interface set the
-<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
-below must be supported. Tuners and audio inputs are optional.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Video overlay devices shall support <link
-linkend="audio">audio input</link>, <link
-linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
-<link linkend="crop">cropping and scaling</link> and <link
-linkend="streaming-par">streaming parameter</link> ioctls as needed.
-The <link linkend="video">video input</link> and <link
-linkend="standard">video standard</link> ioctls must be supported by
-all video overlay devices.</para>
- </section>
-
- <section>
- <title>Setup</title>
-
- <para>Before overlay can commence applications must program the
-driver with frame buffer parameters, namely the address and size of
-the frame buffer and the image format, for example RGB 5:6:5. The
-&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
-and set these parameters, respectively. The
-<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
-allows to set up DMA into physical memory, bypassing the memory
-protection mechanisms of the kernel. Only the superuser can change the
-frame buffer address and size. Users are not supposed to run TV
-applications as root or with SUID bit set. A small helper application
-with suitable privileges should query the graphics system and program
-the V4L2 driver at the appropriate time.</para>
-
- <para>Some devices add the video overlay to the output signal
-of the graphics card. In this case the frame buffer is not modified by
-the video device, and the frame buffer address and pixel format are
-not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
-is not privileged. An application can check for this type of device by
-calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
-
- <para>A driver may support any (or none) of five clipping/blending
-methods:<orderedlist>
- <listitem>
- <para>Chroma-keying displays the overlaid image only where
-pixels in the primary graphics surface assume a certain color.</para>
- </listitem>
- <listitem>
- <para>A bitmap can be specified where each bit corresponds
-to a pixel in the overlaid image. When the bit is set, the
-corresponding video pixel is displayed, otherwise a pixel of the
-graphics surface.</para>
- </listitem>
- <listitem>
- <para>A list of clipping rectangles can be specified. In
-these regions <emphasis>no</emphasis> video is displayed, so the
-graphics surface can be seen here.</para>
- </listitem>
- <listitem>
- <para>The framebuffer has an alpha channel that can be used
-to clip or blend the framebuffer with the video.</para>
- </listitem>
- <listitem>
- <para>A global alpha value can be specified to blend the
-framebuffer contents with video images.</para>
- </listitem>
- </orderedlist></para>
-
- <para>When simultaneous capturing and overlay is supported and
-the hardware prohibits different image and frame buffer formats, the
-format requested first takes precedence. The attempt to capture
-(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
-&EBUSY; or return accordingly modified parameters..</para>
- </section>
-
- <section>
- <title>Overlay Window</title>
-
- <para>The overlaid image is determined by cropping and overlay
-window parameters. The former select an area of the video picture to
-capture, the latter how images are overlaid and clipped. Cropping
-initialization at minimum requires to reset the parameters to
-defaults. An example is given in <xref linkend="crop" />.</para>
-
- <para>The overlay window is described by a &v4l2-window;. It
-defines the size of the image, its position over the graphics surface
-and the clipping to be applied. To get the current parameters
-applications set the <structfield>type</structfield> field of a
-&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
-call the &VIDIOC-G-FMT; ioctl. The driver fills the
-<structname>v4l2_window</structname> substructure named
-<structfield>win</structfield>. It is not possible to retrieve a
-previously programmed clipping list or bitmap.</para>
-
- <para>To program the overlay window applications set the
-<structfield>type</structfield> field of a &v4l2-format; to
-<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the
-<structfield>win</structfield> substructure and call the
-&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
-hardware limits and returns the actual parameters as
-<constant>VIDIOC_G_FMT</constant> does. Like
-<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
-used to learn about driver capabilities without actually changing
-driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
-after the overlay has been enabled.</para>
-
- <para>The scaling factor of the overlaid image is implied by the
-width and height given in &v4l2-window; and the size of the cropping
-rectangle. For more information see <xref linkend="crop" />.</para>
-
- <para>When simultaneous capturing and overlay is supported and
-the hardware prohibits different image and window sizes, the size
-requested first takes precedence. The attempt to capture or overlay as
-well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
-modified parameters.</para>
-
- <table pgwide="1" frame="none" id="v4l2-window">
- <title>struct <structname>v4l2_window</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>w</structfield></entry>
- <entry>Size and position of the window relative to the
-top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
-window can extend the frame buffer width and height, the
-<structfield>x</structfield> and <structfield>y</structfield>
-coordinates can be negative, and it can lie completely outside the
-frame buffer. The driver clips the window accordingly, or if that is
-not possible, modifies its size and/or position.</entry>
- </row>
- <row>
- <entry>&v4l2-field;</entry>
- <entry><structfield>field</structfield></entry>
- <entry>Applications set this field to determine which
-video field shall be overlaid, typically one of
-<constant>V4L2_FIELD_ANY</constant> (0),
-<constant>V4L2_FIELD_TOP</constant>,
-<constant>V4L2_FIELD_BOTTOM</constant> or
-<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
-a different field order and return the actual setting here.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>chromakey</structfield></entry>
- <entry>When chroma-keying has been negotiated with
-&VIDIOC-S-FBUF; applications set this field to the desired pixel value
-for the chroma key. The format is the same as the pixel format of the
-framebuffer (&v4l2-framebuffer;
-<structfield>fmt.pixelformat</structfield> field), with bytes in host
-order. E.&nbsp;g. for <link
-linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
-the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
-endian host.</entry>
- </row>
- <row>
- <entry>&v4l2-clip; *</entry>
- <entry><structfield>clips</structfield></entry>
- <entry>When chroma-keying has <emphasis>not</emphasis>
-been negotiated and &VIDIOC-G-FBUF; indicated this capability,
-applications can set this field to point to an array of
-clipping rectangles.</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Like the window coordinates
-<structfield>w</structfield>, clipping rectangles are defined relative
-to the top, left corner of the frame buffer. However clipping
-rectangles must not extend the frame buffer width and height, and they
-must not overlap. If possible applications should merge adjacent
-rectangles. Whether this must create x-y or y-x bands, or the order of
-rectangles, is not defined. When clip lists are not supported the
-driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
-are undefined.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>clipcount</structfield></entry>
- <entry>When the application set the
-<structfield>clips</structfield> field, this field must contain the
-number of clipping rectangles in the list. When clip lists are not
-supported the driver ignores this field, its contents after calling
-<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
-supported but no clipping is desired this field must be set to
-zero.</entry>
- </row>
- <row>
- <entry>void *</entry>
- <entry><structfield>bitmap</structfield></entry>
- <entry>When chroma-keying has
-<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
-this capability, applications can set this field to point to a
-clipping bit mask.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>It must be of the same size
-as the window, <structfield>w.width</structfield> and
-<structfield>w.height</structfield>. Each bit corresponds to a pixel
-in the overlaid image, which is displayed only when the bit is
-<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
-<programlisting>
-((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
-<structfield>w.width</structfield> and <structfield>0</structfield> &le;
-y &lt;<structfield>w.height</structfield>.<footnote>
- <para>Should we require
- <structfield>w.width</structfield> to be a multiple of
- eight?</para>
- </footnote></para><para>When a clipping
-bit mask is not supported the driver ignores this field, its contents
-after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
-but no clipping is desired this field must be set to
-<constant>NULL</constant>.</para><para>Applications need not create a
-clip list or bit mask. When they pass both, or despite negotiating
-chroma-keying, the results are undefined. Regardless of the chosen
-method, the clipping abilities of the hardware may be limited in
-quantity or quality. The results when these limits are exceeded are
-undefined.<footnote>
- <para>When the image is written into frame buffer
-memory it will be undesirable if the driver clips out less pixels
-than expected, because the application and graphics system are not
-aware these regions need to be refreshed. The driver should clip out
-more pixels or not write the image at all.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>global_alpha</structfield></entry>
- <entry>The global alpha value used to blend the
-framebuffer with video images, if global alpha blending has been
-negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
-&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Note this field was added in Linux 2.6.23, extending the structure. However
-the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
-which take a pointer to a <link
-linkend="v4l2-format">v4l2_format</link> parent structure with padding
-bytes at the end, are not affected.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="v4l2-clip">
- <title>struct <structname>v4l2_clip</structname><footnote>
- <para>The X Window system defines "regions" which are
-vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
-x1 and height = y2 - y1, so one cannot pass X11 clip lists
-directly.</para>
- </footnote></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>&v4l2-rect;</entry>
- <entry><structfield>c</structfield></entry>
- <entry>Coordinates of the clipping rectangle, relative to
-the top, left corner of the frame buffer. Only window pixels
-<emphasis>outside</emphasis> all clipping rectangles are
-displayed.</entry>
- </row>
- <row>
- <entry>&v4l2-clip; *</entry>
- <entry><structfield>next</structfield></entry>
- <entry>Pointer to the next clipping rectangle, NULL when
-this is the last rectangle. Drivers ignore this field, it cannot be
-used to pass a linked list of clipping rectangles.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- NB for easier reading this table is duplicated
- in the vidioc-cropcap chapter.-->
-
- <table pgwide="1" frame="none" id="v4l2-rect">
- <title>struct <structname>v4l2_rect</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__s32</entry>
- <entry><structfield>left</structfield></entry>
- <entry>Horizontal offset of the top, left corner of the
-rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>top</structfield></entry>
- <entry>Vertical offset of the top, left corner of the
-rectangle, in pixels. Offsets increase to the right and down.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>width</structfield></entry>
- <entry>Width of the rectangle, in pixels.</entry>
- </row>
- <row>
- <entry>__s32</entry>
- <entry><structfield>height</structfield></entry>
- <entry>Height of the rectangle, in pixels. Width and
-height cannot be negative, the fields are signed for hysterical
-reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
-"Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Enabling Overlay</title>
-
- <para>To start or stop the frame buffer overlay applications call
-the &VIDIOC-OVERLAY; ioctl.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml
deleted file mode 100644
index 3e6ac73b36a..00000000000
--- a/Documentation/DocBook/media/v4l/dev-radio.xml
+++ /dev/null
@@ -1,49 +0,0 @@
- <title>Radio Interface</title>
-
- <para>This interface is intended for AM and FM (analog) radio
-receivers and transmitters.</para>
-
- <para>Conventionally V4L2 radio devices are accessed through
-character device special files named <filename>/dev/radio</filename>
-and <filename>/dev/radio0</filename> to
-<filename>/dev/radio63</filename> with major number 81 and minor
-numbers 64 to 127.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the radio interface set the
-<constant>V4L2_CAP_RADIO</constant> and
-<constant>V4L2_CAP_TUNER</constant> or
-<constant>V4L2_CAP_MODULATOR</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
-capability flags are reserved for future extensions.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Radio devices can support <link
-linkend="control">controls</link>, and must support the <link
-linkend="tuner">tuner or modulator</link> ioctls.</para>
-
- <para>They do not support the video input or output, audio input
-or output, video standard, cropping and scaling, compression and
-streaming parameter, or overlay ioctls. All other ioctls and I/O
-methods are reserved for future extensions.</para>
- </section>
-
- <section>
- <title>Programming</title>
-
- <para>Radio devices may have a couple audio controls (as discussed
-in <xref linkend="control" />) such as a volume control, possibly custom
-controls. Further all radio devices have one tuner or modulator (these are
-discussed in <xref linkend="tuner" />) with index number zero to select
-the radio frequency and to determine if a monaural or FM stereo
-program is received/emitted. Drivers switch automatically between AM and FM
-depending on the selected frequency. The &VIDIOC-G-TUNER; or
-&VIDIOC-G-MODULATOR; ioctl
-reports the supported frequency range.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
deleted file mode 100644
index b788c72c885..00000000000
--- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
+++ /dev/null
@@ -1,339 +0,0 @@
- <title>Raw VBI Data Interface</title>
-
- <para>VBI is an abbreviation of Vertical Blanking Interval, a gap
-in the sequence of lines of an analog video signal. During VBI
-no picture information is transmitted, allowing some time while the
-electron beam of a cathode ray tube TV returns to the top of the
-screen. Using an oscilloscope you will find here the vertical
-synchronization pulses and short data packages ASK
-modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal
-level represents a '1' bit, a low level a '0' bit.</para></footnote>
-onto the video signal. These are transmissions of services such as
-Teletext or Closed Caption.</para>
-
- <para>Subject of this interface type is raw VBI data, as sampled off
-a video signal, or to be added to a signal for output.
-The data format is similar to uncompressed video images, a number of
-lines times a number of samples per line, we call this a VBI image.</para>
-
- <para>Conventionally V4L2 VBI devices are accessed through character
-device special files named <filename>/dev/vbi</filename> and
-<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with
-major number 81 and minor numbers 224 to 255.
-<filename>/dev/vbi</filename> is typically a symbolic link to the
-preferred VBI device. This convention applies to both input and output
-devices.</para>
-
- <para>To address the problems of finding related video and VBI
-devices VBI capturing and output is also available as device function
-under <filename>/dev/video</filename>. To capture or output raw VBI
-data with these devices applications must call the &VIDIOC-S-FMT;
-ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing
-or output is the default device function.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the raw VBI capturing or output API set
-the <constant>V4L2_CAP_VBI_CAPTURE</constant> or
-<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
-read/write, streaming or asynchronous I/O methods must be
-supported. VBI devices may or may not have a tuner or modulator.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>VBI devices shall support <link linkend="video">video
-input or output</link>, <link linkend="tuner">tuner or
-modulator</link>, and <link linkend="control">controls</link> ioctls
-as needed. The <link linkend="standard">video standard</link> ioctls provide
-information vital to program a VBI device, therefore must be
-supported.</para>
- </section>
-
- <section>
- <title>Raw VBI Format Negotiation</title>
-
- <para>Raw VBI sampling abilities can vary, in particular the
-sampling frequency. To properly interpret the data V4L2 specifies an
-ioctl to query the sampling parameters. Moreover, to allow for some
-flexibility applications can also suggest different parameters.</para>
-
- <para>As usual these parameters are <emphasis>not</emphasis>
-reset at &func-open; time to permit Unix tool chains, programming a
-device and then reading from it as if it was a plain file. Well
-written V4L2 applications should always ensure they really get what
-they want, requesting reasonable parameters and then checking if the
-actual parameters are suitable.</para>
-
- <para>To query the current raw VBI capture parameters
-applications set the <structfield>type</structfield> field of a
-&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or
-<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the
-&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
-the &v4l2-vbi-format; <structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union.</para>
-
- <para>To request different parameters applications set the
-<structfield>type</structfield> field of a &v4l2-format; as above and
-initialize all fields of the &v4l2-vbi-format;
-<structfield>vbi</structfield> member of the
-<structfield>fmt</structfield> union, or better just modify the
-results of <constant>VIDIOC_G_FMT</constant>, and call the
-&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return
-an &EINVAL; only when the given parameters are ambiguous, otherwise
-they modify the parameters according to the hardware capabilites and
-return the actual parameters. When the driver allocates resources at
-this point, it may return an &EBUSY; to indicate the returned
-parameters are valid but the required resources are currently not
-available. That may happen for instance when the video and VBI areas
-to capture would overlap, or when the driver supports multiple opens
-and another process already requested VBI capturing or output. Anyway,
-applications must expect other resource allocation points which may
-return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl
-and the first read(), write() and select() call.</para>
-
- <para>VBI devices must implement both the
-<constant>VIDIOC_G_FMT</constant> and
-<constant>VIDIOC_S_FMT</constant> ioctl, even if
-<constant>VIDIOC_S_FMT</constant> ignores all requests and always
-returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
-<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
-
- <table pgwide="1" frame="none" id="v4l2-vbi-format">
- <title>struct <structname>v4l2_vbi_format</structname></title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>sampling_rate</structfield></entry>
- <entry>Samples per second, i.&nbsp;e. unit 1 Hz.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>offset</structfield></entry>
- <entry><para>Horizontal offset of the VBI image,
-relative to the leading edge of the line synchronization pulse and
-counted in samples: The first sample in the VBI image will be located
-<structfield>offset</structfield> /
-<structfield>sampling_rate</structfield> seconds following the leading
-edge. See also <xref linkend="vbi-hsync" />.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>samples_per_line</structfield></entry>
- <entry></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>sample_format</structfield></entry>
- <entry><para>Defines the sample format as in <xref
-linkend="pixfmt" />, a four-character-code.<footnote>
- <para>A few devices may be unable to
-sample VBI data at all but can extend the video capture window to the
-VBI region.</para>
- </footnote> Usually this is
-<constant>V4L2_PIX_FMT_GREY</constant>, i.&nbsp;e. each sample
-consists of 8 bits with lower values oriented towards the black level.
-Do not assume any other correlation of values with the signal level.
-For example, the MSB does not necessarily indicate if the signal is
-'high' or 'low' because 128 may not be the mean value of the
-signal. Drivers shall not convert the sample format by software.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>start</structfield>[2]</entry>
- <entry>This is the scanning system line number
-associated with the first line of the VBI image, of the first and the
-second field respectively. See <xref linkend="vbi-525" /> and
-<xref linkend="vbi-625" /> for valid values. VBI input drivers can
-return start values 0 if the hardware cannot reliable identify
-scanning lines, VBI acquisition may not require this
-information.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>count</structfield>[2]</entry>
- <entry>The number of lines in the first and second
-field image, respectively.</entry>
- </row>
- <row>
- <entry spanname="hspan"><para>Drivers should be as
-flexibility as possible. For example, it may be possible to extend or
-move the VBI capture window down to the picture area, implementing a
-'full field mode' to capture data service transmissions embedded in
-the picture.</para><para>An application can set the first or second
-<structfield>count</structfield> value to zero if no data is required
-from the respective field; <structfield>count</structfield>[1] if the
-scanning system is progressive, &ie; not interlaced. The
-corresponding start value shall be ignored by the application and
-driver. Anyway, drivers may not support single field capturing and
-return both count values non-zero.</para><para>Both
-<structfield>count</structfield> values set to zero, or line numbers
-outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
- linkend="vbi-625" />, or a field image covering
-lines of two fields, are invalid and shall not be returned by the
-driver.</para><para>To initialize the <structfield>start</structfield>
-and <structfield>count</structfield> fields, applications must first
-determine the current video standard selection. The &v4l2-std-id; or
-the <structfield>framelines</structfield> field of &v4l2-standard; can
-be evaluated for this purpose.</para></entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>flags</structfield></entry>
- <entry>See <xref linkend="vbifmt-flags" /> below. Currently
-only drivers set flags, applications must set this field to
-zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry>This array is reserved for future extensions.
-Drivers and applications must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table pgwide="1" frame="none" id="vbifmt-flags">
- <title>Raw VBI Format Flags</title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_VBI_UNSYNC</constant></entry>
- <entry>0x0001</entry>
- <entry><para>This flag indicates hardware which does not
-properly distinguish between fields. Normally the VBI image stores the
-first field (lower scanning line numbers) first in memory. This may be
-a top or bottom field depending on the video standard. When this flag
-is set the first or second field may be stored first, however the
-fields are still in correct temporal order with the older field first
-in memory.<footnote>
- <para>Most VBI services transmit on both fields, but
-some have different semantics depending on the field number. These
-cannot be reliable decoded or encoded when
-<constant>V4L2_VBI_UNSYNC</constant> is set.</para>
- </footnote></para></entry>
- </row>
- <row>
- <entry><constant>V4L2_VBI_INTERLACED</constant></entry>
- <entry>0x0002</entry>
- <entry>By default the two field images will be passed
-sequentially; all lines of the first field followed by all lines of
-the second field (compare <xref linkend="field-order" />
-<constant>V4L2_FIELD_SEQ_TB</constant> and
-<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom
-field is first in memory depends on the video standard). When this
-flag is set, the two fields are interlaced (cf.
-<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
-first field followed by the first line of the second field, then the
-two second lines, and so on. Such a layout may be necessary when the
-hardware has been programmed to capture or output interlaced video
-images and is unable to separate the fields for VBI capturing at
-the same time. For simplicity setting this flag implies that both
-<structfield>count</structfield> values are equal and non-zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <figure id="vbi-hsync">
- <title>Line synchronization</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_hsync.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_hsync.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>Line synchronization diagram</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <figure id="vbi-525">
- <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_525.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_525.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>NTSC field synchronization diagram</phrase>
- </textobject>
- <caption>
- <para>(1) For the purpose of this specification field 2
-starts in line 264 and not 263.5 because half line capturing is not
-supported.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <figure id="vbi-625">
- <title>ITU-R 625 line numbering</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="vbi_625.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="vbi_625.gif" format="GIF" />
- </imageobject>
- <textobject>
- <phrase>PAL/SECAM field synchronization diagram</phrase>
- </textobject>
- <caption>
- <para>(1) For the purpose of this specification field 2
-starts in line 314 and not 313.5 because half line capturing is not
-supported.</para>
- </caption>
- </mediaobject>
- </figure>
-
- <para>Remember the VBI image format depends on the selected
-video standard, therefore the application must choose a new standard or
-query the current standard first. Attempts to read or write data ahead
-of format negotiation, or after switching the video standard which may
-invalidate the negotiated VBI parameters, should be refused by the
-driver. A format change during active I/O is not permitted.</para>
- </section>
-
- <section>
- <title>Reading and writing VBI images</title>
-
- <para>To assure synchronization with the field number and easier
-implementation, the smallest unit of data passed at a time is one
-frame, consisting of two fields of VBI images immediately following in
-memory.</para>
-
- <para>The total size of a frame computes as follows:</para>
-
- <programlisting>
-(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) *
-<structfield>samples_per_line</structfield> * sample size in bytes</programlisting>
-
- <para>The sample size is most likely always one byte,
-applications must check the <structfield>sample_format</structfield>
-field though, to function properly with other drivers.</para>
-
- <para>A VBI device may support <link
- linkend="rw">read/write</link> and/or streaming (<link
- linkend="mmap">memory mapping</link> or <link
- linkend="userp">user pointer</link>) I/O. The latter bears the
-possibility of synchronizing video and
-VBI data by using buffer timestamps.</para>
-
- <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
-write() and select() call can be resource allocation points returning
-an &EBUSY; if the required hardware resources are temporarily
-unavailable, for example the device is already in use by another
-process.</para>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml
deleted file mode 100644
index 38883a419e6..00000000000
--- a/Documentation/DocBook/media/v4l/dev-rds.xml
+++ /dev/null
@@ -1,196 +0,0 @@
- <title>RDS Interface</title>
-
- <para>The Radio Data System transmits supplementary
-information in binary format, for example the station name or travel
-information, on an inaudible audio subcarrier of a radio program. This
-interface is aimed at devices capable of receiving and/or transmitting RDS
-information.</para>
-
- <para>For more information see the core RDS standard <xref linkend="en50067" />
-and the RBDS standard <xref linkend="nrsc4" />.</para>
-
- <para>Note that the RBDS standard as is used in the USA is almost identical
-to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the
-fields have slightly different meanings. See the RBDS standard for more
-information.</para>
-
- <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
-This is a proprietary format which seems to be discontinued. The RDS interface does not
-support this format. Should support for MMBS (or the so-called 'E blocks' in general)
-be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the RDS capturing API set
-the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS
-will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
-the <structfield>capability</structfield> field of &v4l2-tuner;. If
-the driver only passes RDS blocks without interpreting the data
-the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be
-set, see <link linkend="reading-rds-data">Reading RDS data</link>.
-For future use the
-flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been
-defined. However, a driver for a radio tuner with this capability does
-not yet exist, so if you are planning to write such a driver you
-should discuss this on the linux-media mailing list: &v4l-ml;.</para>
-
- <para> Whether an RDS signal is present can be detected by looking
-at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;:
-the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data
-was detected.</para>
-
- <para>Devices supporting the RDS output API
-set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl.
-Any modulator that supports RDS will set the
-<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
-field of &v4l2-modulator;.
-In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
-bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
-If the driver only passes RDS blocks without interpreting the data
-the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the
-tuner is capable of handling RDS entities like program identification codes and radio
-text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set,
-see <link linkend="writing-rds-data">Writing RDS data</link> and
-<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
- </section>
-
- <section id="reading-rds-data">
- <title>Reading RDS data</title>
-
- <para>RDS data can be read from the radio device
-with the &func-read; function. The data is packed in groups of three bytes.</para>
- </section>
-
- <section id="writing-rds-data">
- <title>Writing RDS data</title>
-
- <para>RDS data can be written to the radio device
-with the &func-write; function. The data is packed in groups of three bytes,
-as follows:</para>
- </section>
-
- <section>
- <title>RDS datastructures</title>
- <table frame="none" pgwide="1" id="v4l2-rds-data">
- <title>struct
-<structname>v4l2_rds_data</structname></title>
- <tgroup cols="3">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>lsb</structfield></entry>
- <entry>Least Significant Byte of RDS Block</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>msb</structfield></entry>
- <entry>Most Significant Byte of RDS Block</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>block</structfield></entry>
- <entry>Block description</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <table frame="none" pgwide="1" id="v4l2-rds-block">
- <title>Block description</title>
- <tgroup cols="2">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>Bits 0-2</entry>
- <entry>Block (aka offset) of the received data.</entry>
- </row>
- <row>
- <entry>Bits 3-5</entry>
- <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
- </row>
- <row>
- <entry>Bit 6</entry>
- <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
- </row>
- <row>
- <entry>Bit 7</entry>
- <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
- <title>Block defines</title>
- <tgroup cols="4">
- <colspec colname="c1" colwidth="1*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="5*" />
- <tbody valign="top">
- <row>
- <entry>V4L2_RDS_BLOCK_MSK</entry>
- <entry> </entry>
- <entry>7</entry>
- <entry>Mask for bits 0-2 to get the block ID.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_A</entry>
- <entry> </entry>
- <entry>0</entry>
- <entry>Block A.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_B</entry>
- <entry> </entry>
- <entry>1</entry>
- <entry>Block B.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_C</entry>
- <entry> </entry>
- <entry>2</entry>
- <entry>Block C.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_D</entry>
- <entry> </entry>
- <entry>3</entry>
- <entry>Block D.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_C_ALT</entry>
- <entry> </entry>
- <entry>4</entry>
- <entry>Block C'.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_INVALID</entry>
- <entry>read-only</entry>
- <entry>7</entry>
- <entry>An invalid block.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
- <entry>read-only</entry>
- <entry>0x40</entry>
- <entry>A bit error was detected but corrected.</entry>
- </row>
- <row>
- <entry>V4L2_RDS_BLOCK_ERROR</entry>
- <entry>read-only</entry>
- <entry>0x80</entry>
- <entry>An uncorrectable error occurred.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
deleted file mode 100644
index 548f8ea28de..00000000000
--- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
+++ /dev/null
@@ -1,699 +0,0 @@
- <title>Sliced VBI Data Interface</title>
-
- <para>VBI stands for Vertical Blanking Interval, a gap in the
-sequence of lines of an analog video signal. During VBI no picture
-information is transmitted, allowing some time while the electron beam
-of a cathode ray tube TV returns to the top of the screen.</para>
-
- <para>Sliced VBI devices use hardware to demodulate data transmitted
-in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
-software, see also the <link linkend="raw-vbi">raw VBI
-interface</link>. The data is passed as short packets of fixed size,
-covering one scan line each. The number of packets per video frame is
-variable.</para>
-
- <para>Sliced VBI capture and output devices are accessed through the
-same character special files as raw VBI devices. When a driver
-supports both interfaces, the default function of a
-<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
-capturing or output, and the sliced VBI function is only available
-after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
-<filename>/dev/video</filename> device may support the sliced VBI API,
-however the default function here is video capturing or output.
-Different file descriptors must be used to pass raw and sliced VBI
-data simultaneously, if this is supported by the driver.</para>
-
- <section>
- <title>Querying Capabilities</title>
-
- <para>Devices supporting the sliced VBI capturing or output API
-set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
-<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
-read/write, streaming or asynchronous <link linkend="io">I/O
-methods</link> must be supported. Sliced VBI devices may have a tuner
-or modulator.</para>
- </section>
-
- <section>
- <title>Supplemental Functions</title>
-
- <para>Sliced VBI devices shall support <link linkend="video">video
-input or output</link> and <link linkend="tuner">tuner or
-modulator</link> ioctls if they have these capabilities, and they may
-support <link linkend="control">control</link> ioctls. The <link
-linkend="standard">video standard</link> ioctls provide information
-vital to program a sliced VBI device, therefore must be
-supported.</para>
- </section>
-
- <section id="sliced-vbi-format-negotitation">
- <title>Sliced VBI Format Negotiation</title>
-
- <para>To find out which data services are supported by the
-hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
-All drivers implementing the sliced VBI interface must support this
-ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
-when the number of VBI lines the hardware can capture or output per
-frame, or the number of services it can identify on a given line are
-limited. For example on PAL line 16 the hardware may be able to look
-for a VPS or Teletext signal, but not both at the same time.</para>
-
- <para>To determine the currently selected services applications
-set the <structfield>type </structfield> field of &v4l2-format; to
-<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
-V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
-ioctl fills the <structfield>fmt.sliced</structfield> member, a
-&v4l2-sliced-vbi-format;.</para>
-
- <para>Applications can request different parameters by
-initializing or modifying the <structfield>fmt.sliced</structfield>
-member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
-<structname>v4l2_format</structname> structure.</para>
-
- <para>The sliced VBI API is more complicated than the raw VBI API
-because the hardware must be told which VBI service to expect on each
-scan line. Not all services may be supported by the hardware on all
-lines (this is especially true for VBI output where Teletext is often
-unsupported and other services can only be inserted in one specific
-line). In many cases, however, it is sufficient to just set the
-<structfield>service_set</structfield> field to the required services
-and let the driver fill the <structfield>service_lines</structfield>
-array according to hardware capabilities. Only if more precise control
-is needed should the programmer set the
-<structfield>service_lines</structfield> array explicitly.</para>
-
- <para>The &VIDIOC-S-FMT; ioctl modifies the parameters
-according to hardware capabilities. When the driver allocates
-resources at this point, it may return an &EBUSY; if the required
-resources are temporarily unavailable. Other resource allocation
-points which may return <errorcode>EBUSY</errorcode> can be the
-&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
-&func-select; call.</para>
-
- <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format">
- <title>struct
-<structname>v4l2_sliced_vbi_format</structname></title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="3*" />
- <colspec colname="c2" colwidth="3*" />
- <colspec colname="c3" colwidth="2*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec namest="c3" nameend="c5" spanname="hspan" />
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>service_set</structfield></entry>
- <entry spanname="hspan"><para>If
-<structfield>service_set</structfield> is non-zero when passed with
-&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
-<structfield>service_lines</structfield> array will be filled by the
-driver according to the services specified in this field. For example,
-if <structfield>service_set</structfield> is initialized with
-<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
-driver for the cx25840 video decoder sets lines 7-22 of both
-fields<footnote><para>According to <link
-linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
-first field and lines 5-22 of the second field may carry Teletext
-data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
-and line 23 of the first field to
-<constant>V4L2_SLICED_WSS_625</constant>. If
-<structfield>service_set</structfield> is set to zero, then the values
-of <structfield>service_lines</structfield> will be used instead.
-</para><para>On return the driver sets this field to the union of all
-elements of the returned <structfield>service_lines</structfield>
-array. It may contain less services than requested, perhaps just one,
-if the hardware cannot handle more services simultaneously. It may be
-empty (zero) if none of the requested services are supported by the
-hardware.</para></entry>
- </row>
- <row>
- <entry>__u16</entry>
- <entry><structfield>service_lines</structfield>[2][24]</entry>
- <entry spanname="hspan"><para>Applications initialize this
-array with sets of data services the driver shall look for or insert
-on the respective scan line. Subject to hardware capabilities drivers
-return the requested set, a subset, which may be just a single
-service, or an empty set. When the hardware cannot handle multiple
-services on the same line the driver shall choose one. No assumptions
-can be made on which service the driver chooses.</para><para>Data
-services are defined in <xref linkend="vbi-services2" />. Array indices
-map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref
- linkend="vbi-625" />) as follows: <!-- No nested
-tables, sigh. --></para></entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry>Element</entry>
- <entry>525 line systems</entry>
- <entry>625 line systems</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][1]</entry>
- <entry align="center">1</entry>
- <entry align="center">1</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[0][23]</entry>
- <entry align="center">23</entry>
- <entry align="center">23</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][1]</entry>
- <entry align="center">264</entry>
- <entry align="center">314</entry>
- </row>
- <row>
- <entry></entry>
- <entry></entry>
- <entry><structfield>service_lines</structfield>[1][23]</entry>
- <entry align="center">286</entry>
- <entry align="center">336</entry>
- </row>
- <!-- End of line numbers table. -->
- <row>
- <entry></entry>
- <entry></entry>
- <entry spanname="hspan">Drivers must set
-<structfield>service_lines</structfield>[0][0] and
-<structfield>service_lines</structfield>[1][0] to zero.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>io_size</structfield></entry>
- <entry spanname="hspan">Maximum number of bytes passed by
-one &func-read; or &func-write; call, and the buffer size in bytes for
-the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
-the size of &v4l2-sliced-vbi-data; times the number of non-zero
-elements in the returned <structfield>service_lines</structfield>
-array (that is the number of lines potentially carrying data).</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield>[2]</entry>
- <entry spanname="hspan">This array is reserved for future
-extensions. Applications and drivers must set it to zero.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <!-- See also vidioc-g-sliced-vbi-cap.sgml -->
- <table frame="none" pgwide="1" id="vbi-services2">
- <title>Sliced VBI services</title>
- <tgroup cols="5">
- <colspec colname="c1" colwidth="2*" />
- <colspec colname="c2" colwidth="1*" />
- <colspec colname="c3" colwidth="1*" />
- <colspec colname="c4" colwidth="2*" />
- <colspec colname="c5" colwidth="2*" />
- <spanspec namest="c3" nameend="c5" spanname="rlp" />
- <thead>
- <row>
- <entry>Symbol</entry>
- <entry>Value</entry>
- <entry>Reference</entry>
- <entry>Lines, usually</entry>
- <entry>Payload</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_SLICED_TELETEXT_B</constant>
-(Teletext System B)</entry>
- <entry>0x0001</entry>
- <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
- <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
- <entry>Last 42 of the 45 byte Teletext packet, that is
-without clock run-in and framing code, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VPS</constant></entry>
- <entry>0x0400</entry>
- <entry><xref linkend="ets300231" /></entry>
- <entry>PAL line 16</entry>
- <entry>Byte number 3 to 15 according to Figure 9 of
-ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
- <entry>0x1000</entry>
- <entry><xref linkend="eia608" /></entry>
- <entry>NTSC line 21, 284 (second field 21)</entry>
- <entry>Two bytes in transmission order, including parity
-bit, lsb first transmitted.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
- <entry>0x4000</entry>
- <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
- <entry>PAL/SECAM line 23</entry>
- <entry><screen>
-Byte 0 1
- msb lsb msb lsb
- Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
-</screen></entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
- <entry>0x1000</entry>
- <entry spanname="rlp">Set of services applicable to 525
-line systems.</entry>
- </row>
- <row>
- <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
- <entry>0x4401</entry>
- <entry spanname="rlp">Set of services applicable to 625
-line systems.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Drivers may return an &EINVAL; when applications attempt to
-read or write data without prior format negotiation, after switching
-the video standard (which may invalidate the negotiated VBI
-parameters) and after switching the video input (which may change the
-video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
-an &EBUSY; when applications attempt to change the format while i/o is
-in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
-and after the first &func-read; or &func-write; call).</para>
- </section>
-
- <section>
- <title>Reading and writing sliced VBI data</title>
-
- <para>A single &func-read; or &func-write; call must pass all data
-belonging to one video frame. That is an array of
-<structname>v4l2_sliced_vbi_data</structname> structures with one or
-more elements and a total size not exceeding
-<structfield>io_size</structfield> bytes. Likewise in streaming I/O
-mode one buffer of <structfield>io_size</structfield> bytes must
-contain data of one video frame. The <structfield>id</structfield> of
-unused <structname>v4l2_sliced_vbi_data</structname> elements must be
-zero.</para>
-
- <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
- <title>struct
-<structname>v4l2_sliced_vbi_data</structname></title>
- <tgroup cols="3">
- &cs-def;
- <tbody valign="top">
- <row>
- <entry>__u32</entry>
- <entry><structfield>id</structfield></entry>
- <entry>A flag from <xref linkend="vbi-services" />
-identifying the type of data in this packet. Only a single bit must be
-set. When the <structfield>id</structfield> of a captured packet is
-zero, the packet is empty and the contents of other fields are
-undefined. Applications shall ignore empty packets. When the
-<structfield>id</structfield> of a packet for output is zero the
-contents of the <structfield>data</structfield> field are undefined
-and the driver must no longer insert data on the requested
-<structfield>field</structfield> and
-<structfield>line</structfield>.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>field</structfield></entry>
- <entry>The video field number this data has been captured
-from, or shall be inserted at. <constant>0</constant> for the first
-field, <constant>1</constant> for the second field.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>line</structfield></entry>
- <entry>The field (as opposed to frame) line number this
-data has been captured from, or shall be inserted at. See <xref
- linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
-values. Sliced VBI capture devices can set the line number of all
-packets to <constant>0</constant> if the hardware cannot reliably
-identify scan lines. The field number must always be valid.</entry>
- </row>
- <row>
- <entry>__u32</entry>
- <entry><structfield>reserved</structfield></entry>
- <entry>This field is reserved for future extensions.
-Applications and drivers must set it to zero.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>data</structfield>[48]</entry>
- <entry>The packet payload. See <xref
- linkend="vbi-services" /> for the contents and number of
-bytes passed for each data type. The contents of padding bytes at the
-end of this array are undefined, drivers and applications shall ignore
-them.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Packets are always passed in ascending line number order,
-without duplicate line numbers. The &func-write; function and the
-&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
-this rule. They must also return an &EINVAL; when applications pass an
-incorrect field or line number, or a combination of
-<structfield>field</structfield>, <structfield>line</structfield> and
-<structfield>id</structfield> which has not been negotiated with the
-&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
-unknown the driver must pass the packets in transmitted order. The
-driver can insert empty packets with <structfield>id</structfield> set
-to zero anywhere in the packet array.</para>
-
- <para>To assure synchronization and to distinguish from frame
-dropping, when a captured frame does not carry any of the requested
-data services drivers must pass one or more empty packets. When an
-application fails to pass VBI data in time for output, the driver
-must output the last VPS and WSS packet again, and disable the output
-of Closed Caption and Teletext data, or output data which is ignored
-by Closed Caption and Teletext decoders.</para>
-
- <para>A sliced VBI device may support <link
-linkend="rw">read/write</link> and/or streaming (<link
-linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
-pointer</link>) I/O. The latter bears the possibility of synchronizing
-video and VBI data by using buffer timestamps.</para>
-
- </section>
-
- <section>
- <title>Sliced VBI Data in MPEG Streams</title>
-
- <para>If a device can produce an MPEG output stream, it may be
-capable of providing <link
-linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
-services</link> as data embedded in the MPEG stream. Users or
-applications control this sliced VBI data insertion with the <link
-linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
-control.</para>
-
- <para>If the driver does not provide the <link
-linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
-control, or only allows that control to be set to <link
-linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
-cannot embed sliced VBI data in the MPEG stream.</para>
-
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
-V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
-the device driver to capture nor cease capturing sliced VBI data. The
-control only indicates to embed sliced VBI data in the MPEG stream, if
-an application has negotiated sliced VBI service be captured.</para>
-
- <para>It may also be the case that a device can embed sliced VBI
-data in only certain types of MPEG streams: for example in an MPEG-2
-PS but not an MPEG-2 TS. In this situation, if sliced VBI data
-insertion is requested, the sliced VBI data will be embedded in MPEG
-stream types when supported, and silently omitted from MPEG stream
-types where sliced VBI data insertion is not supported by the device.
-</para>
-
- <para>The following subsections specify the format of the
-embedded sliced VBI data.</para>
-
- <section>
- <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
-format shall be interpreted by drivers as a control to cease
-embedding sliced VBI data in MPEG streams. Neither the device nor
-driver shall insert "empty" embedded sliced VBI data packets in the
-MPEG stream when this format is set. No MPEG stream data structures
-are specified for this format.</para>
- </section>
-
- <section>
- <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
- <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
-V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
-format, when supported, indicates to the driver to embed up to 36
-lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
-Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
-Program Pack</emphasis> in the MPEG stream.</para>
-
- <para><emphasis>Historical context</emphasis>: This format
-specification originates from a custom, embedded, sliced VBI data
-format used by the <filename>ivtv</filename> driver. This format
-has already been informally specified in the kernel sources in the
-file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
-. The maximum size of the payload and other aspects of this format
-are driven by the CX23415 MPEG decoder's capabilities and limitations
-with respect to extracting, decoding, and displaying sliced VBI data
-embedded within an MPEG stream.</para>
-
- <para>This format's use is <emphasis>not</emphasis> exclusive to
-the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
-exclusive to CX2341x devices, as the sliced VBI data packet insertion
-into the MPEG stream is implemented in driver software. At least the
-<filename>cx18</filename> driver provides sliced VBI data insertion
-into an MPEG-2 PS in this format as well.</para>
-
- <para>The following definitions specify the payload of the
-MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
-sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
-<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
-(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
-and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
-not detailed here. Please refer to the MPEG-2 specifications for
-details on those packet headers.)</para>
-
- <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
-</emphasis> packets that contain sliced VBI data is specified by
-&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
-length, depending on the actual number of lines of sliced VBI data
-present in a video frame. The payload may be padded at the end with
-unspecified fill bytes to align the end of the payload to a 4-byte
-boundary. The payload shall never exceed 1552 bytes (2 fields with
-18 lines/field with 43 bytes of data/line and a 4 byte magic number).
-</para>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
- <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
- </title>
- <tgroup cols="4">
- &cs-ustr;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>magic</structfield>[4]</entry>
- <entry></entry>
- <entry>A "magic" constant from <xref
- linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
-this is a valid sliced VBI data payload and also indicates which
-member of the anonymous union, <structfield>itv0</structfield> or
-<structfield>ITV0</structfield>, to use for the payload data.</entry>
- </row>
- <row>
- <entry>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
- <structname>v4l2_mpeg_vbi_itv0</structname></link>
- </entry>
- <entry><structfield>itv0</structfield></entry>
- <entry>The primary form of the sliced VBI data payload
-that contains anywhere from 1 to 35 lines of sliced VBI data.
-Line masks are provided in this form of the payload indicating
-which VBI lines are provided.</entry>
- </row>
- <row>
- <entry></entry>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
- <structname>v4l2_mpeg_vbi_ITV0</structname></link>
- </entry>
- <entry><structfield>ITV0</structfield></entry>
- <entry>An alternate form of the sliced VBI data payload
-used when 36 lines of sliced VBI data are present. No line masks are
-provided in this form of the payload; all valid line mask bits are
-implcitly set.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
- <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
- <structfield>magic</structfield> field</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry align="left">Defined Symbol</entry>
- <entry align="left">Value</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
- </entry>
- <entry>"itv0"</entry>
- <entry>Indicates the <structfield>itv0</structfield>
-member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
- </entry>
- <entry>"ITV0"</entry>
- <entry>Indicates the <structfield>ITV0</structfield>
-member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
-that 36 lines of sliced VBI data are present.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
- <title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__le32</entry>
- <entry><structfield>linemask</structfield>[2]</entry>
- <entry><para>Bitmasks indicating the VBI service lines
-present. These <structfield>linemask</structfield> values are stored
-in little endian byte order in the MPEG stream. Some reference
-<structfield>linemask</structfield> bit positions with their
-corresponding VBI line number and video field are given below.
-b<subscript>0</subscript> indicates the least significant bit of a
-<structfield>linemask</structfield> value:<screen>
-<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
-<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
-<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
-<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
-<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
-<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
-<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
- </row>
- <row>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
- <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
- </entry>
- <entry><structfield>line</structfield>[35]</entry>
- <entry>This is a variable length array that holds from 1
-to 35 lines of sliced VBI data. The sliced VBI data lines present
-correspond to the bits set in the <structfield>linemask</structfield>
-array, starting from b<subscript>0</subscript> of <structfield>
-linemask</structfield>[0] up through b<subscript>31</subscript> of
-<structfield>linemask</structfield>[0], and from b<subscript>0
-</subscript> of <structfield>linemask</structfield>[1] up through b
-<subscript>3</subscript> of <structfield>linemask</structfield>[1].
-<structfield>line</structfield>[0] corresponds to the first bit
-found set in the <structfield>linemask</structfield> array,
-<structfield>line</structfield>[1] corresponds to the second bit
-found set in the <structfield>linemask</structfield> array, etc.
-If no <structfield>linemask</structfield> array bits are set, then
-<structfield>line</structfield>[0] may contain one line of
-unspecified data that should be ignored by applications.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
- <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
- <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
- </entry>
- <entry><structfield>line</structfield>[36]</entry>
- <entry>A fixed length array of 36 lines of sliced VBI
-data. <structfield>line</structfield>[0] through <structfield>line
-</structfield>[17] correspond to lines 6 through 23 of the
-first field. <structfield>line</structfield>[18] through
-<structfield>line</structfield>[35] corresponds to lines 6
-through 23 of the second field.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
- <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
- </title>
- <tgroup cols="3">
- &cs-str;
- <tbody valign="top">
- <row>
- <entry>__u8</entry>
- <entry><structfield>id</structfield></entry>
- <entry>A line identifier value from
-<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
-the type of sliced VBI data stored on this line.</entry>
- </row>
- <row>
- <entry>__u8</entry>
- <entry><structfield>data</structfield>[42]</entry>
- <entry>The sliced VBI data for the line.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
- <title>Line Identifiers for struct <link
- linkend="v4l2-mpeg-vbi-itv0-line"><structname>
-v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
-</structfield> field</title>
- <tgroup cols="3">
- &cs-def;
- <thead>
- <row>
- <entry align="left">Defined Symbol</entry>
- <entry align="left">Value</entry>
- <entry align="left">Description</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
- </entry>
- <entry>1</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
- </entry>
- <entry>4</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant>
- </entry>
- <entry>5</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- <row>
- <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
- </entry>
- <entry>7</entry>
- <entry>Refer to <link linkend="vbi-services2">
-Sliced VBI services</link> for a description of the line payload.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
- </section>
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
deleted file mode 100644
index 4afcbbec5ed..00000000000
--- a/Documentation/DocBook/media/v4l/dev-subdev.xml
+++ /dev/null
@@ -1,467 +0,0 @@
- <title>Sub-device Interface</title>
-
- <note>
- <title>Experimental</title>
- <para>This is an <link linkend="experimental">experimental</link>
- interface and may change in the future.</para>
- </note>
-
- <para>The complex nature of V4L2 devices, where hardware is often made of
- several integrated circuits that need to interact with each other in a
- controlled way, leads to complex V4L2 drivers. The drivers usually reflect
- the hardware model in software, and model the different hardware components
- as software blocks called sub-devices.</para>
-
- <para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
- implements the media device API, they will automatically inherit from media
- entities. Applications will be able to enumerate the sub-devices and discover
- the hardware topology using the media entities, pads and links enumeration
- API.</para>
-
- <para>In addition to make sub-devices discoverable, drivers can also choose
- to make them directly configurable by applications. When both the sub-device
- driver and the V4L2 device driver support this, sub-devices will feature a
- character device node on which ioctls can be called to
- <itemizedlist>
- <listitem><para>query, read and write sub-devices controls</para></listitem>
- <listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem>
- <listitem><para>negotiate image formats on individual pads</para></listitem>
- </itemizedlist>
- </para>
-
- <para>Sub-device character device nodes, conventionally named
- <filename>/dev/v4l-subdev*</filename>, use major number 81.</para>
-
- <section>
- <title>Controls</title>
- <para>Most V4L2 controls are implemented by sub-device hardware. Drivers
- usually merge all controls and expose them through video device nodes.
- Applications can control all sub-devices through a single interface.</para>
-
- <para>Complex devices sometimes implement the same control in different
- pieces of hardware. This situation is common in embedded platforms, where
- both sensors and image processing hardware implement identical functions,
- such as contrast adjustment, white balance or faulty pixels correction. As
- the V4L2 controls API doesn't support several identical controls in a single
- device, all but one of the identical controls are hidden.</para>
-
- <para>Applications can access those hidden controls through the sub-device
- node with the V4L2 control API described in <xref linkend="control" />. The
- ioctls behave identically as when issued on V4L2 device nodes, with the
- exception that they deal only with controls implemented in the sub-device.
- </para>
-
- <para>Depending on the driver, those controls might also be exposed through
- one (or several) V4L2 device nodes.</para>
- </section>
-
- <section>
- <title>Events</title>
- <para>V4L2 sub-devices can notify applications of events as described in
- <xref linkend="event" />. The API behaves identically as when used on V4L2
- device nodes, with the exception that it only deals with events generated by
- the sub-device. Depending on the driver, those events might also be reported
- on one (or several) V4L2 device nodes.</para>
- </section>
-
- <section id="pad-level-formats">
- <title>Pad-level Formats</title>
-
- <warning><para>Pad-level formats are only applicable to very complex device that
- need to expose low-level format configuration to user space. Generic V4L2
- applications do <emphasis>not</emphasis> need to use the API described in
- this section.</para></warning>
-
- <note><para>For the purpose of this section, the term
- <wordasword>format</wordasword> means the combination of media bus data
- format, frame width and frame height.</para></note>
-
- <para>Image formats are typically negotiated on video capture and
- output devices using the format and <link
- linkend="vidioc-subdev-g-selection">selection</link> ioctls. The
- driver is responsible for configuring every block in the video
- pipeline according to the requested format at the pipeline input
- and/or output.</para>
-
- <para>For complex devices, such as often found in embedded systems,
- identical image sizes at the output of a pipeline can be achieved using
- different hardware configurations. One such example is shown on
- <xref linkend="pipeline-scaling" />, where
- image scaling can be performed on both the video sensor and the host image
- processing hardware.</para>
-
- <figure id="pipeline-scaling">
- <title>Image Format Negotiation on Pipelines</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="pipeline.pdf" format="PS" />
- </imageobject>
- <imageobject>
- <imagedata fileref="pipeline.png" format="PNG" />
- </imageobject>
- <textobject>
- <phrase>High quality and high speed pipeline configuration</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- <para>The sensor scaler is usually of less quality than the host scaler, but
- scaling on the sensor is required to achieve higher frame rates. Depending
- on the use case (quality vs. speed), the pipeline must be configured
- differently. Applications need to configure the formats at every point in
- the pipeline explicitly.</para>
-
- <para>Drivers that implement the <link linkend="media-controller-intro">media
- API</link> can expose pad-level image format configuration to applications.
- When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and
- &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para>
-
- <para>Applications are responsible for configuring coherent parameters on
- the whole pipeline and making sure that connected pads have compatible
- formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON;
- time, and an &EPIPE; is then returned if the configuration is
- invalid.</para>
-
- <para>Pad-level image format configuration support can be tested by calling
- the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL;
- pad-level format configuration is not supported by the sub-device.</para>
-
- <section>
- <title>Format Negotiation</title>
-
- <para>Acceptable formats on pads can (and usually do) depend on a number
- of external parameters, such as formats on other pads, active links, or
- even controls. Finding a combination of formats on all pads in a video
- pipeline, acceptable to both application and driver, can't rely on formats
- enumeration only. A format negotiation mechanism is required.</para>
-
- <para>Central to the format negotiation mechanism are the get/set format
- operations. When called with the <structfield>which</structfield> argument
- set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the
- &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of
- formats parameters that are not connected to the hardware configuration.
- Modifying those 'try' formats leaves the device state untouched (this
- applies to both the software state stored in the driver and the hardware
- state stored in the device itself).</para>
-
- <para>While not kept as part of the device state, try formats are stored
- in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return
- the last try format set <emphasis>on the same sub-device file
- handle</emphasis>. Several applications querying the same sub-device at
- the same time will thus not interact with each other.</para>
-
- <para>To find out whether a particular format is supported by the device,
- applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if
- needed, change the requested <structfield>format</structfield> based on
- device requirements and return the possibly modified value. Applications
- can then choose to try a different format or accept the returned value and
- continue.</para>
-
- <para>Formats returned by the driver during a negotiation iteration are
- guaranteed to be supported by the device. In particular, drivers guarantee
- that a returned format will not be further changed if passed to an
- &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as
- formats on other pads or links' configuration are not changed).</para>
-
- <para>Drivers automatically propagate formats inside sub-devices. When a
- try or active format is set on a pad, corresponding formats on other pads
- of the same sub-device can be modified by the driver. Drivers are free to
- modify formats as required by the device. However, they should comply with
- the following rules when possible:
- <itemizedlist>
- <listitem><para>Formats should be propagated from sink pads to source pads.
- Modifying a format on a source pad should not modify the format on any
- sink pad.</para></listitem>
- <listitem><para>Sub-devices that scale frames using variable scaling factors
- should reset the scale factors to default values when sink pads formats
- are modified. If the 1:1 scaling ratio is supported, this means that
- source pads formats should be reset to the sink pads formats.</para></listitem>
- </itemizedlist>
- </para>
-
- <para>Formats are not propagated across links, as that would involve
- propagating them from one sub-device file handle to another. Applications
- must then take care to configure both ends of every link explicitly with
- compatible formats. Identical formats on the two ends of a link are
- guaranteed to be compatible. Drivers are free to accept different formats
- matching device requirements as being compatible.</para>
-
- <para><xref linkend="sample-pipeline-config" />
- shows a sample configuration sequence for the pipeline described in
- <xref linkend="pipeline-scaling" /> (table
- columns list entity names and pad numbers).</para>
-
- <table pgwide="0" frame="none" id="sample-pipeline-config">
- <title>Sample Pipeline Configuration</title>
- <tgroup cols="3">
- <colspec colname="what"/>
- <colspec colname="sensor-0" />
- <colspec colname="frontend-0" />
- <colspec colname="frontend-1" />
- <colspec colname="scaler-0" />
- <colspec colname="scaler-1" />
- <thead>
- <row>
- <entry></entry>
- <entry>Sensor/0</entry>
- <entry>Frontend/0</entry>
- <entry>Frontend/1</entry>
- <entry>Scaler/0</entry>
- <entry>Scaler/1</entry>
- </row>
- </thead>
- <tbody valign="top">
- <row>
- <entry>Initial state</entry>
- <entry>2048x1536</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>Configure frontend input</entry>
- <entry>2048x1536</entry>
- <entry><emphasis>2048x1536</emphasis></entry>
- <entry><emphasis>2046x1534</emphasis></entry>
- <entry>-</entry>
- <entry>-</entry>
- </row>
- <row>
- <entry>Configure scaler input</entry>
- <entry>2048x1536</entry>
- <entry>2048x1536</entry>
- <entry>2046x1534</entry>
- <entry><emphasis>2046x1534</emphasis></entry>
- <entry><emphasis>2046x1534</emphasis></entry>
- </row>
- <row>
- <entry>Configure scaler output</entry>
- <entry>2048x1536</entry>
- <entry>2048x1536</entry>
- <entry>2046x1534</entry>
- <entry>2046x1534</entry>
- <entry><emphasis>1280x960</emphasis></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- <orderedlist>
- <listitem><para>Initial state. The sensor output is set to its native 3MP
- resolution. Resolutions on the host frontend and scaler input and output
- pads are undefined.</para></listitem>
- <listitem><para>The application configures the frontend input pad resolution to
- 2048x1536. The driver propagates the format to the frontend output pad.
- Note that the propagated output format can be different, as in this case,
- than the input format, as the hardware might need to crop pixels (for
- instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem>
- <listitem><para>The application configures the scaler input pad resolution to
- 2046x1534 to match the frontend output resolution. The driver propagates
- the format to the scaler output pad.</para></listitem>
- <listitem><para>The application configures the scaler output pad resolution to
- 1280x960.</para></listitem>
- </orderedlist>
- </para>
-
- <para>When satisfied with the try results, applications can set the active
- formats by setting the <structfield>which</structfield> argument to
- <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. Active formats are changed
- exactly as try formats by drivers. To avoid modifying the hardware state
- during format negotiation, applications should negotiate try formats first
- and then modify the active settings using the try formats returned during
- the last negotiation iteration. This guarantees that the active format
- will be applied as-is by the driver without being modified.
- </para>
- </section>
-
- <section>
- <title>Selections: cropping, scaling and composition</title>
-
- <para>Many sub-devices support cropping frames on their input or output
- pads (or possible even on both). Cropping is used to select the area of
- interest in an image, typically on an image sensor or a video decoder. It can
- also be used as part of digital zoom implementations to select the area of
- the image that will be scaled up.</para>
-
- <para>Crop settings are defined by a crop rectangle and represented in a
- &v4l2-rect; by the coordinates of the top left corner and the rectangle
- size. Both the coordinates and sizes are expressed in pixels.</para>
-
- <para>As for pad formats, drivers store try and active
- rectangles for the selection targets of ACTUAL type <xref
- linkend="v4l2-subdev-selection-targets">.</xref></para>
-
- <para>On sink pads, cropping is applied relative to the
- current pad format. The pad format represents the image size as
- received by the sub-device from the previous block in the
- pipeline, and the crop rectangle represents the sub-image that
- will be transmitted further inside the sub-device for
- processing.</para>
-
- <para>The scaling operation changes the size of the image by
- scaling it to new dimensions. The scaling ratio isn't specified
- explicitly, but is implied from the original and scaled image
- sizes. Both sizes are represented by &v4l2-rect;.</para>
-
- <para>Scaling support is optional. When supported by a subdev,
- the crop rectangle on the subdev's sink pad is scaled to the
- size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL
- using <constant>V4L2_SUBDEV_SEL_COMPOSE_ACTUAL</constant>
- selection target on the same pad. If the subdev supports scaling
- but not composing, the top and left values are not used and must
- always be set to zero.</para>
-
- <para>On source pads, cropping is similar to sink pads, with the
- exception that the source size from which the cropping is
- performed, is the COMPOSE rectangle on the sink pad. In both
- sink and source pads, the crop rectangle must be entirely
- contained inside the source image size for the crop
- operation.</para>
-
- <para>The drivers should always use the closest possible
- rectangle the user requests on all selection targets, unless
- specifically told otherwise.
- <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_GE</constant> and
- <constant>V4L2_SUBDEV_SEL_FLAG_SIZE_LE</constant> flags may be
- used to round the image size either up or down. <xref
- linkend="v4l2-subdev-selection-flags"></xref></para>
- </section>
-
- <section>
- <title>Types of selection targets</title>
-
- <section>
- <title>ACTUAL targets</title>
-
- <para>ACTUAL targets reflect the actual hardware configuration
- at any point of time. There is a BOUNDS target
- corresponding to every ACTUAL.</para>
- </section>
-
- <section>
- <title>BOUNDS targets</title>
-
- <para>BOUNDS targets is the smallest rectangle that contains
- all valid ACTUAL rectangles. It may not be possible to set the
- ACTUAL rectangle as large as the BOUNDS rectangle, however.
- This may be because e.g. a sensor's pixel array is not
- rectangular but cross-shaped or round. The maximum size may
- also be smaller than the BOUNDS rectangle.</para>
- </section>
-
- </section>
-
- <section>
- <title>Order of configuration and format propagation</title>
-
- <para>Inside subdevs, the order of image processing steps will
- always be from the sink pad towards the source pad. This is also
- reflected in the order in which the configuration must be
- performed by the user: the changes made will be propagated to
- any subsequent stages. If this behaviour is not desired, the
- user must set
- <constant>V4L2_SUBDEV_SEL_FLAG_KEEP_CONFIG</constant> flag. This
- flag causes no propagation of the changes are allowed in any
- circumstances. This may also cause the accessed rectangle to be
- adjusted by the driver, depending on the properties of the
- underlying hardware.</para>
-
- <para>The coordinates to a step always refer to the actual size
- of the previous step. The exception to this rule is the source
- compose rectangle, which refers to the sink compose bounds
- rectangle --- if it is supported by the hardware.</para>
-
- <orderedlist>
- <listitem>Sink pad format. The user configures the sink pad
- format. This format defines the parameters of the image the
- entity receives through the pad for further processing.</listitem>
-
- <listitem>Sink pad actual crop selection. The sink pad crop
- defines the crop performed to the sink pad format.</listitem>
-
- <listitem>Sink pad actual compose selection. The size of the
- sink pad compose rectangle defines the scaling ratio compared
- to the size of the sink pad crop rectangle. The location of
- the compose rectangle specifies the location of the actual
- sink compose rectangle in the sink compose bounds
- rectangle.</listitem>
-
- <listitem>Source pad actual crop selection. Crop on the source
- pad defines crop performed to the image in the sink compose
- bounds rectangle.</listitem>
-
- <listitem>Source pad format. The source pad format defines the
- output pixel format of the subdev, as well as the other
- parameters with the exception of the image width and height.
- Width and height are defined by the size of the source pad
- actual crop selection.</listitem>
- </orderedlist>
-
- <para>Accessing any of the above rectangles not supported by the
- subdev will return <constant>EINVAL</constant>. Any rectangle
- referring to a previous unsupported rectangle coordinates will
- instead refer to the previous supported rectangle. For example,
- if sink crop is not supported, the compose selection will refer
- to the sink pad format dimensions instead.</para>
-
- <figure id="subdev-image-processing-crop">
- <title>Image processing in subdevs: simple crop example</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-crop.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In the above example, the subdev supports cropping on its
- sink pad. To configure it, the user sets the media bus format on
- the subdev's sink pad. Now the actual crop rectangle can be set
- on the sink pad --- the location and size of this rectangle
- reflect the location and size of a rectangle to be cropped from
- the sink format. The size of the sink crop rectangle will also
- be the size of the format of the subdev's source pad.</para>
-
- <figure id="subdev-image-processing-scaling-multi-source">
- <title>Image processing in subdevs: scaling with multiple sources</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-scaling-multi-source.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>In this example, the subdev is capable of first cropping,
- then scaling and finally cropping for two source pads
- individually from the resulting scaled image. The location of
- the scaled image in the cropped image is ignored in sink compose
- target. Both of the locations of the source crop rectangles
- refer to the sink scaling rectangle, independently cropping an
- area at location specified by the source crop rectangle from
- it.</para>
-
- <figure id="subdev-image-processing-full">
- <title>Image processing in subdevs: scaling and composition
- with multiple sinks and sources</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="subdev-image-processing-full.svg"
- format="SVG" scale="200" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The subdev driver supports two sink pads and two source
- pads. The images from both of the sink pads are individually
- cropped, then scaled and further composed on the composition
- bounds rectangle. From that, two independent streams are cropped
- and sent out of the subdev from the source pads.</para>
-
- </section>
-
- </section>
-
- &sub-subdev-formats;
diff --git a/Documentation/DocBook/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml
deleted file mode 100644
index bd21c64d70f..00000000000
--- a/Documentation/DocBook/media/v4l/dev-teletext.xml
+++ /dev/null
@@ -1,29 +0,0 @@
- <title>Teletext Interface</title>
-
- <para>This interface was aimed at devices receiving and demodulating
-Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the
-Teletext packages and storing formatted pages in cache memory. Such
-devices are usually implemented as microcontrollers with serial
-interface (I<superscript>2</superscript>C) and could be found on old
-TV cards, dedicated Teletext decoding cards and home-brew devices
-connected to the PC parallel port.</para>
-
- <para>The Teletext API was designed by Martin Buck. It was defined in
-the kernel header file <filename>linux/videotext.h</filename>, the
-specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/">
-ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of
-the German public television Teletext service.)</para>
-
- <para>Eventually the Teletext API was integrated into the V4L API
-with character device file names <filename>/dev/vtx0</filename> to
-<filename>/dev/vtx31</filename>, device major number 81, minor numbers
-192 to 223.</para>
-
- <para>However, teletext decoders were quickly replaced by more
-generic VBI demodulators and those dedicated teletext decoders no longer exist.
-For many years the vtx devices were still around, even though nobody used
-them. So the decision was made to finally remove support for the Teletext API in
-kernel 2.6.37.</para>
-
- <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or
-<link linkend="sliced">sliced</link> VBI API.</para>
diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml
deleted file mode 100644
index eacafe312cd..00000000000
--- a/Documentation/DocBook/media/v4l/driver.xml
+++ /dev/null
@@ -1,200 +0,0 @@
- <title>V4L2 Driver Programming</title>
-
- <!-- This part defines the interface between the "videodev"
- module and individual drivers. -->
-
- <para>to do</para>
-<!--
- <para>V4L2 is a two-layer driver system. The top layer is the "videodev"
-kernel module. When videodev initializes it registers as character device
-with major number 81, and it registers a set of file operations. All V4L2
-drivers are really clients of videodev, which calls V4L2 drivers through
-driver method functions. V4L2 drivers are also written as kernel modules.
-After probing the hardware they register one or more devices with
-videodev.</para>
-
- <section id="driver-modules">
- <title>Driver Modules</title>
-
- <para>V4L2 driver modules must have an initialization function which is
-called after the module was loaded into kernel, an exit function whis is
-called before the module is removed. When the driver is compiled into the
-kernel these functions called at system boot and shutdown time.</para>
-
- <informalexample>
- <programlisting>
-#include &lt;linux/module.h&gt;
-
-/* Export information about this module. For details and other useful
- macros see <filename>linux/module.h</filename>. */
-MODULE_DESCRIPTION("my - driver for my hardware");
-MODULE_AUTHOR("Your name here");
-MODULE_LICENSE("GPL");
-
-static void
-my_module_exit (void)
-{
- /* Free all resources allocated by my_module_init(). */
-}
-
-static int
-my_module_init (void)
-{
- /* Bind the driver to the supported hardware, see
- <link linkend="driver-pci"> and
- <link linkend="driver-usb"> for examples. */
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-/* Export module functions. */
-module_init (my_module_init);
-module_exit (my_module_exit);
-</programlisting>
- </informalexample>
-
- <para>Users can add parameters when kernel modules are inserted:</para>
-
- <informalexample>
- <programlisting>
-include &lt;linux/moduleparam.h&gt;
-
-static int my_option = 123;
-static int my_option_array[47];
-
-/* Export the symbol, an int, with access permissions 0664.
- See <filename>linux/moduleparam.h</filename> for other types. */
-module_param (my_option, int, 0644);
-module_param_array (my_option_array, int, NULL, 0644);
-
-MODULE_PARM_DESC (my_option, "Does magic things, default 123");
-</programlisting>
- </informalexample>
-
- <para>One parameter should be supported by all V4L2 drivers, the minor
-number of the device it will register. Purpose is to predictably link V4L2
-drivers to device nodes if more than one video device is installed. Use the
-name of the device node followed by a "_nr" suffix, for example "video_nr"
-for <filename>/dev/video</filename>.</para>
-
- <informalexample>
- <programlisting>
-/* Minor number of the device, -1 to allocate the first unused. */
-static int video_nr = -1;
-
-module_param (video_nr, int, 0444);
-</programlisting>
- </informalexample>
- </section>
-
- <section id="driver-pci">
- <title>PCI Devices</title>
-
- <para>PCI devices are initialized like this:</para>
-
- <informalexample>
- <programlisting>
-typedef struct {
- /* State of one physical device. */
-} my_device;
-
-static int
-my_resume (struct pci_dev * pci_dev)
-{
- /* Restore the suspended device to working state. */
-}
-
-static int
-my_suspend (struct pci_dev * pci_dev,
- pm_message_t state)
-{
- /* This function is called before the system goes to sleep.
- Stop all DMAs and disable interrupts, then put the device
- into a low power state. For details see the kernel
- sources under <filename>Documentation/power</filename>. */
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-static void __devexit
-my_remove (struct pci_dev * pci_dev)
-{
- my_device *my = pci_get_drvdata (pci_dev);
-
- /* Describe me. */
-}
-
-static int __devinit
-my_probe (struct pci_dev * pci_dev,
- const struct pci_device_id * pci_id)
-{
- my_device *my;
-
- /* Describe me. */
-
- /* You can allocate per-device data here and store a pointer
- to it in the pci_dev structure. */
- my = ...;
- pci_set_drvdata (pci_dev, my);
-
- return 0; /* a negative value on error, 0 on success. */
-}
-
-/* A list of supported PCI devices. */
-static struct pci_device_id
-my_pci_device_ids [] = {
- { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
- PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 },
- { 0 } /* end of list */
-};
-
-/* Load our module if supported PCI devices are installed. */
-MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
-
-static struct pci_driver
-my_pci_driver = {
- .name = "my",
- .id_table = my_pci_device_ids,
-
- .probe = my_probe,
- .remove = __devexit_p (my_remove),
-
- /* Power management functions. */
- .suspend = my_suspend,
- .resume = my_resume,
-};
-
-static void
-my_module_exit (void)
-{
- pci_unregister_driver (&my_pci_driver);
-}
-
-static int
-my_module_init (void)
-{
- return pci_register_driver (&my_pci_driver);
-}
-</programlisting>
- </informalexample>
- </section>
-
- <section id="driver-usb">
- <title>USB Devices</title>
- <para>to do</para>
- </section>
- <section id="driver-registering">
- <title>Registering V4L2 Drivers</title>
-
- <para>After a V4L2 driver probed the hardware it registers one or more
-devices with the videodev module.</para>
- </section>
- <section id="driver-file-ops">
- <title>File Operations</title>
- <para>to do</para>
- </section>
- <section id="driver-internal-api">
- <title>Internal API</title>
- <para>to do</para>
- </section>
--->
diff --git a/Documentation/DocBook/media/v4l/fdl-appendix.xml b/Documentation/DocBook/media/v4l/fdl-appendix.xml
deleted file mode 100644
index ae22394ba99..00000000000
--- a/Documentation/DocBook/media/v4l/fdl-appendix.xml
+++ /dev/null
@@ -1,671 +0,0 @@
-<!--
- The GNU Free Documentation License 1.1 in DocBook
- Markup by Eric Baudais <baudais@okstate.edu>
- Maintained by the GNOME Documentation Project
- http://live.gnome.org/DocumentationProject
- Version: 1.0.1
- Last Modified: Nov 16, 2000
--->
-
-<appendix id="fdl">
- <appendixinfo>
- <releaseinfo>
- Version 1.1, March 2000
- </releaseinfo>
- <copyright>
- <year>2000</year><holder>Free Software Foundation, Inc.</holder>
- </copyright>
- <legalnotice id="fdl-legalnotice">
- <para>
- <address>Free Software Foundation, Inc. <street>59 Temple Place,
- Suite 330</street>, <city>Boston</city>, <state>MA</state>
- <postcode>02111-1307</postcode> <country>USA</country></address>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </para>
- </legalnotice>
- </appendixinfo>
- <title>GNU Free Documentation License</title>
-
- <sect1 id="fdl-preamble">
- <title>0. PREAMBLE</title>
- <para>
- The purpose of this License is to make a manual, textbook, or
- other written document <quote>free</quote> in the sense of
- freedom: to assure everyone the effective freedom to copy and
- redistribute it, with or without modifying it, either
- commercially or noncommercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for
- their work, while not being considered responsible for
- modifications made by others.
- </para>
-
- <para>
- This License is a kind of <quote>copyleft</quote>, which means
- that derivative works of the document must themselves be free in
- the same sense. It complements the GNU General Public License,
- which is a copyleft license designed for free software.
- </para>
-
- <para>
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same
- freedoms that the software does. But this License is not limited
- to software manuals; it can be used for any textual work,
- regardless of subject matter or whether it is published as a
- printed book. We recommend this License principally for works
- whose purpose is instruction or reference.
- </para>
- </sect1>
- <sect1 id="fdl-section1">
- <title>1. APPLICABILITY AND DEFINITIONS</title>
- <para id="fdl-document">
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The
- <quote>Document</quote>, below, refers to any such manual or
- work. Any member of the public is a licensee, and is addressed
- as <quote>you</quote>.
- </para>
-
- <para id="fdl-modified">
- A <quote>Modified Version</quote> of the Document means any work
- containing the Document or a portion of it, either copied
- verbatim, or with modifications and/or translated into another
- language.
- </para>
-
- <para id="fdl-secondary">
- A <quote>Secondary Section</quote> is a named appendix or a
- front-matter section of the <link
- linkend="fdl-document">Document</link> that deals exclusively
- with the relationship of the publishers or authors of the
- Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within
- that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position
- regarding them.
- </para>
-
- <para id="fdl-invariant">
- The <quote>Invariant Sections</quote> are certain <link
- linkend="fdl-secondary"> Secondary Sections</link> whose titles
- are designated, as being those of Invariant Sections, in the
- notice that says that the <link
- linkend="fdl-document">Document</link> is released under this
- License.
- </para>
-
- <para id="fdl-cover-texts">
- The <quote>Cover Texts</quote> are certain short passages of
- text that are listed, as Front-Cover Texts or Back-Cover Texts,
- in the notice that says that the <link
- linkend="fdl-document">Document</link> is released under this
- License.
- </para>
-
- <para id="fdl-transparent">
- A <quote>Transparent</quote> copy of the <link
- linkend="fdl-document"> Document</link> means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not <quote>Transparent</quote> is called
- <quote>Opaque</quote>.
- </para>
-
- <para>
- Examples of suitable formats for Transparent copies include
- plain ASCII without markup, Texinfo input format, LaTeX input
- format, SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human
- modification. Opaque formats include PostScript, PDF,
- proprietary formats that can be read and edited only by
- proprietary word processors, SGML or XML for which the DTD
- and/or processing tools are not generally available, and the
- machine-generated HTML produced by some word processors for
- output purposes only.
- </para>
-
- <para id="fdl-title-page">
- The <quote>Title Page</quote> means, for a printed book, the
- title page itself, plus such following pages as are needed to
- hold, legibly, the material this License requires to appear in
- the title page. For works in formats which do not have any title
- page as such, <quote>Title Page</quote> means the text near the
- most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
- </para>
- </sect1>
-
- <sect1 id="fdl-section2">
- <title>2. VERBATIM COPYING</title>
- <para>
- You may copy and distribute the <link
- linkend="fdl-document">Document</link> in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this
- License. You may not use technical measures to obstruct or
- control the reading or further copying of the copies you make or
- distribute. However, you may accept compensation in exchange for
- copies. If you distribute a large enough number of copies you
- must also follow the conditions in <link
- linkend="fdl-section3">section 3</link>.
- </para>
-
- <para>
- You may also lend copies, under the same conditions stated
- above, and you may publicly display copies.
- </para>
- </sect1>
-
- <sect1 id="fdl-section3">
- <title>3. COPYING IN QUANTITY</title>
- <para>
- If you publish printed copies of the <link
- linkend="fdl-document">Document</link> numbering more than 100,
- and the Document's license notice requires <link
- linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
- the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these
- copies. The front cover must present the full title with all
- words of the title equally prominent and visible. You may add
- other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the
- <link linkend="fdl-document">Document</link> and satisfy these
- conditions, can be treated as verbatim copying in other
- respects.
- </para>
-
- <para>
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
- </para>
-
- <para>
- If you publish or distribute <link
- linkend="fdl-transparent">Opaque</link> copies of the <link
- linkend="fdl-document">Document</link> numbering more than 100,
- you must either include a machine-readable <link
- linkend="fdl-transparent">Transparent</link> copy along with
- each Opaque copy, or state in or with each Opaque copy a
- publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added
- material, which the general network-using public has access to
- download anonymously at no charge using public-standard network
- protocols. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the
- public.
- </para>
-
- <para>
- It is requested, but not required, that you contact the authors
- of the <link linkend="fdl-document">Document</link> well before
- redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
- </para>
- </sect1>
-
- <sect1 id="fdl-section4">
- <title>4. MODIFICATIONS</title>
- <para>
- You may copy and distribute a <link
- linkend="fdl-modified">Modified Version</link> of the <link
- linkend="fdl-document">Document</link> under the conditions of
- sections <link linkend="fdl-section2">2</link> and <link
- linkend="fdl-section3">3</link> above, provided that you release
- the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
- </para>
-
- <itemizedlist mark="opencircle">
- <listitem>
- <formalpara>
- <title>A</title>
- <para>
- Use in the <link linkend="fdl-title-page">Title
- Page</link> (and on the covers, if any) a title distinct
- from that of the <link
- linkend="fdl-document">Document</link>, and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>B</title>
- <para>
- List on the <link linkend="fdl-title-page">Title
- Page</link>, as authors, one or more persons or entities
- responsible for authorship of the modifications in the
- <link linkend="fdl-modified">Modified Version</link>,
- together with at least five of the principal authors of
- the <link linkend="fdl-document">Document</link> (all of
- its principal authors, if it has less than five).
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>C</title>
- <para>
- State on the <link linkend="fdl-title-page">Title
- Page</link> the name of the publisher of the <link
- linkend="fdl-modified">Modified Version</link>, as the
- publisher.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>D</title>
- <para>
- Preserve all the copyright notices of the <link
- linkend="fdl-document">Document</link>.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>E</title>
- <para>
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>F</title>
- <para>
- Include, immediately after the copyright notices, a
- license notice giving the public permission to use the
- <link linkend="fdl-modified">Modified Version</link> under
- the terms of this License, in the form shown in the
- Addendum below.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>G</title>
- <para>
- Preserve in that license notice the full lists of <link
- linkend="fdl-invariant"> Invariant Sections</link> and
- required <link linkend="fdl-cover-texts">Cover
- Texts</link> given in the <link
- linkend="fdl-document">Document's</link> license notice.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>H</title>
- <para>
- Include an unaltered copy of this License.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>I</title>
- <para>
- Preserve the section entitled <quote>History</quote>, and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <link
- linkend="fdl-modified">Modified Version </link>as given on
- the <link linkend="fdl-title-page">Title Page</link>. If
- there is no section entitled <quote>History</quote> in the
- <link linkend="fdl-document">Document</link>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>J</title>
- <para>
- Preserve the network location, if any, given in the <link
- linkend="fdl-document">Document</link> for public access
- to a <link linkend="fdl-transparent">Transparent</link>
- copy of the Document, and likewise the network locations
- given in the Document for previous versions it was based
- on. These may be placed in the <quote>History</quote>
- section. You may omit a network location for a work that
- was published at least four years before the Document
- itself, or if the original publisher of the version it
- refers to gives permission.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>K</title>
- <para>
- In any section entitled <quote>Acknowledgements</quote> or
- <quote>Dedications</quote>, preserve the section's title,
- and preserve in the section all the substance and tone of
- each of the contributor acknowledgements and/or
- dedications given therein.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>L</title>
- <para>
- Preserve all the <link linkend="fdl-invariant">Invariant
- Sections</link> of the <link
- linkend="fdl-document">Document</link>, unaltered in their
- text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>M</title>
- <para>
- Delete any section entitled
- <quote>Endorsements</quote>. Such a section may not be
- included in the <link linkend="fdl-modified">Modified
- Version</link>.
- </para>
- </formalpara>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>N</title>
- <para>
- Do not retitle any existing section as
- <quote>Endorsements</quote> or to conflict in title with
- any <link linkend="fdl-invariant">Invariant
- Section</link>.
- </para>
- </formalpara>
- </listitem>
- </itemizedlist>
-
- <para>
- If the <link linkend="fdl-modified">Modified Version</link>
- includes new front-matter sections or appendices that qualify as
- <link linkend="fdl-secondary">Secondary Sections</link> and
- contain no material copied from the Document, you may at your
- option designate some or all of these sections as invariant. To
- do this, add their titles to the list of <link
- linkend="fdl-invariant">Invariant Sections</link> in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
- </para>
-
- <para>
- You may add a section entitled <quote>Endorsements</quote>,
- provided it contains nothing but endorsements of your <link
- linkend="fdl-modified">Modified Version</link> by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
- </para>
-
- <para>
- You may add a passage of up to five words as a <link
- linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
- of up to 25 words as a <link
- linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
- the list of <link linkend="fdl-cover-texts">Cover Texts</link>
- in the <link linkend="fdl-modified">Modified Version</link>.
- Only one passage of Front-Cover Text and one of Back-Cover Text
- may be added by (or through arrangements made by) any one
- entity. If the <link linkend="fdl-document">Document</link>
- already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are
- acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
- </para>
-
- <para>
- The author(s) and publisher(s) of the <link
- linkend="fdl-document">Document</link> do not by this License
- give permission to use their names for publicity for or to
- assert or imply endorsement of any <link
- linkend="fdl-modified">Modified Version </link>.
- </para>
- </sect1>
-
- <sect1 id="fdl-section5">
- <title>5. COMBINING DOCUMENTS</title>
- <para>
- You may combine the <link linkend="fdl-document">Document</link>
- with other documents released under this License, under the
- terms defined in <link linkend="fdl-section4">section 4</link>
- above for modified versions, provided that you include in the
- combination all of the <link linkend="fdl-invariant">Invariant
- Sections</link> of all of the original documents, unmodified,
- and list them all as Invariant Sections of your combined work in
- its license notice.
- </para>
-
- <para>
- The combined work need only contain one copy of this License,
- and multiple identical <link linkend="fdl-invariant">Invariant
- Sections</link> may be replaced with a single copy. If there are
- multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding
- at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the
- list of Invariant Sections in the license notice of the combined
- work.
- </para>
-
- <para>
- In the combination, you must combine any sections entitled
- <quote>History</quote> in the various original documents,
- forming one section entitled <quote>History</quote>; likewise
- combine any sections entitled <quote>Acknowledgements</quote>,
- and any sections entitled <quote>Dedications</quote>. You must
- delete all sections entitled <quote>Endorsements.</quote>
- </para>
- </sect1>
-
- <sect1 id="fdl-section6">
- <title>6. COLLECTIONS OF DOCUMENTS</title>
- <para>
- You may make a collection consisting of the <link
- linkend="fdl-document">Document</link> and other documents
- released under this License, and replace the individual copies
- of this License in the various documents with a single copy that
- is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </para>
-
- <para>
- You may extract a single document from such a collection, and
- dispbibute it individually under this License, provided you
- insert a copy of this License into the extracted document, and
- follow this License in all other respects regarding verbatim
- copying of that document.
- </para>
- </sect1>
-
- <sect1 id="fdl-section7">
- <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
- <para>
- A compilation of the <link
- linkend="fdl-document">Document</link> or its derivatives with
- other separate and independent documents or works, in or on a
- volume of a storage or distribution medium, does not as a whole
- count as a <link linkend="fdl-modified">Modified Version</link>
- of the Document, provided no compilation copyright is claimed
- for the compilation. Such a compilation is called an
- <quote>aggregate</quote>, and this License does not apply to the
- other self-contained works thus compiled with the Document , on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document. If the <link
- linkend="fdl-cover-texts">Cover Text</link> requirement of <link
- linkend="fdl-section3">section 3</link> is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
- </para>
- </sect1>
-
- <sect1 id="fdl-section8">
- <title>8. TRANSLATION</title>
- <para>
- Translation is considered a kind of modification, so you may
- distribute translations of the <link
- linkend="fdl-document">Document</link> under the terms of <link
- linkend="fdl-section4">section 4</link>. Replacing <link
- linkend="fdl-invariant"> Invariant Sections</link> with
- translations requires special permission from their copyright
- holders, but you may include translations of some or all
- Invariant Sections in addition to the original versions of these
- Invariant Sections. You may include a translation of this
- License provided that you also include the original English
- version of this License. In case of a disagreement between the
- translation and the original English version of this License,
- the original English version will prevail.
- </para>
- </sect1>
-
- <sect1 id="fdl-section9">
- <title>9. TERMINATION</title>
- <para>
- You may not copy, modify, sublicense, or distribute the <link
- linkend="fdl-document">Document</link> except as expressly
- provided for under this License. Any other attempt to copy,
- modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However,
- parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such
- parties remain in full compliance.
- </para>
- </sect1>
-
- <sect1 id="fdl-section10">
- <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
- <para>
- The <ulink type="http"
- url="http://www.gnu.org/fsf/fsf.html">Free Software
- Foundation</ulink> may publish new, revised versions of the GNU
- Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ
- in detail to address new problems or concerns. See <ulink
- type="http"
- url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
- </para>
-
- <para>
- Each version of the License is given a distinguishing version
- number. If the <link linkend="fdl-document">Document</link>
- specifies that a particular numbered version of this License
- <quote>or any later version</quote> applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
- </para>
- </sect1>
-
- <sect1 id="fdl-using">
- <title>Addendum</title>
- <para>
- To use this License in a document you have written, include a copy of
- the License in the document and put the following copyright and
- license notices just after the title page:
- </para>
-
- <blockquote>
- <para>
- Copyright &copy; YEAR YOUR NAME.
- </para>
- <para>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with the <link
- linkend="fdl-invariant">Invariant Sections</link> being LIST
- THEIR TITLES, with the <link
- linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
- and with the <link linkend="fdl-cover-texts">Back-Cover
- Texts</link> being LIST. A copy of the license is included in
- the section entitled <quote>GNU Free Documentation
- License</quote>.
- </para>
- </blockquote>
-
- <para>
- If you have no <link linkend="fdl-invariant">Invariant
- Sections</link>, write <quote>with no Invariant Sections</quote>
- instead of saying which ones are invariant. If you have no
- <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
- <quote>no Front-Cover Texts</quote> instead of
- <quote>Front-Cover Texts being LIST</quote>; likewise for <link
- linkend="fdl-cover-texts">Back-Cover Texts</link>.
- </para>
-
- <para>
- If your document contains nontrivial examples of program code,
- we recommend releasing these examples in parallel under your
- choice of free software license, such as the <ulink type="http"
- url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
- License</ulink>, to permit their use in free software.
- </para>
- </sect1>
-</appendix>
-
-
-
-
-
-
diff --git a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf b/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
deleted file mode 100644
index 26598b23f80..00000000000
--- a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf b/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
deleted file mode 100644
index 4965b22ddb3..00000000000
--- a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
+++ /dev/null
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml
deleted file mode 100644
index 232920d2f3c..00000000000
--- a/Documentation/DocBook/media/v4l/func-close.xml
+++ /dev/null
@@ -1,62 +0,0 @@
-<refentry id="func-close">
- <refmeta>
- <refentrytitle>V4L2 close()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-close</refname>
- <refpurpose>Close a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>close</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Closes the device. Any I/O in progress is terminated and
-resources associated with the file descriptor are freed. However data
-format parameters, current input or output, control values or other
-properties remain unchanged.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>The function returns <returnvalue>0</returnvalue> on
-success, <returnvalue>-1</returnvalue> on failure and the
-<varname>errno</varname> is set appropriately. Possible error
-codes:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid open file
-descriptor.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml
deleted file mode 100644
index 4394184a1a6..00000000000
--- a/Documentation/DocBook/media/v4l/func-ioctl.xml
+++ /dev/null
@@ -1,71 +0,0 @@
-<refentry id="func-ioctl">
- <refmeta>
- <refentrytitle>V4L2 ioctl()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-ioctl</refname>
- <refpurpose>Program a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>ioctl</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>int <parameter>request</parameter></paramdef>
- <paramdef>void *<parameter>argp</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>request</parameter></term>
- <listitem>
- <para>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example
-VIDIOC_QUERYCAP.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>argp</parameter></term>
- <listitem>
- <para>Pointer to a function parameter, usually a structure.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <function>ioctl()</function> function is used to program
-V4L2 devices. The argument <parameter>fd</parameter> must be an open
-file descriptor. An ioctl <parameter>request</parameter> has encoded
-in it whether the argument is an input, output or read/write
-parameter, and the size of the argument <parameter>argp</parameter> in
-bytes. Macros and defines specifying V4L2 ioctl requests are located
-in the <filename>videodev2.h</filename> header file.
-Applications should use their own copy, not include the version in the
-kernel sources on the system they compile on. All V4L2 ioctl requests,
-their respective function and parameters are specified in <xref
- linkend="user-func" />.</para>
- </refsect1>
-
- <refsect1>
- &return-value;
- <para>When an ioctl that takes an output or read/write parameter fails,
- the parameter remains unmodified.</para>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml
deleted file mode 100644
index f31ad71bf30..00000000000
--- a/Documentation/DocBook/media/v4l/func-mmap.xml
+++ /dev/null
@@ -1,183 +0,0 @@
-<refentry id="func-mmap">
- <refmeta>
- <refentrytitle>V4L2 mmap()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-mmap</refname>
- <refpurpose>Map device memory into application address space</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;unistd.h&gt;
-#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>void *<function>mmap</function></funcdef>
- <paramdef>void *<parameter>start</parameter></paramdef>
- <paramdef>size_t <parameter>length</parameter></paramdef>
- <paramdef>int <parameter>prot</parameter></paramdef>
- <paramdef>int <parameter>flags</parameter></paramdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>off_t <parameter>offset</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
- <variablelist>
- <varlistentry>
- <term><parameter>start</parameter></term>
- <listitem>
- <para>Map the buffer to this address in the
-application's address space. When the <constant>MAP_FIXED</constant>
-flag is specified, <parameter>start</parameter> must be a multiple of the
-pagesize and mmap will fail when the specified address
-cannot be used. Use of this option is discouraged; applications should
-just specify a <constant>NULL</constant> pointer here.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>length</parameter></term>
- <listitem>
- <para>Length of the memory area to map. This must be the
-same value as returned by the driver in the &v4l2-buffer;
-<structfield>length</structfield> field for the
-single-planar API, and the same value as returned by the driver
-in the &v4l2-plane; <structfield>length</structfield> field for the
-multi-planar API.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>prot</parameter></term>
- <listitem>
- <para>The <parameter>prot</parameter> argument describes the
-desired memory protection. Regardless of the device type and the
-direction of data exchange it should be set to
-<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
-permitting read and write access to image buffers. Drivers should
-support at least this combination of flags. Note the Linux
-<filename>video-buf</filename> kernel module, which is used by the
-bttv, saa7134, saa7146, cx88 and vivi driver supports only
-<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
-the driver does not support the desired protection the
-<function>mmap()</function> function fails.</para>
- <para>Note device memory accesses (&eg; the memory on a
-graphics card with video capturing hardware) may incur a performance
-penalty compared to main memory accesses, or reads may be
-significantly slower than writes or vice versa. Other I/O methods may
-be more efficient in this case.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>The <parameter>flags</parameter> parameter
-specifies the type of the mapped object, mapping options and whether
-modifications made to the mapped copy of the page are private to the
-process or are to be shared with other references.</para>
- <para><constant>MAP_FIXED</constant> requests that the
-driver selects no other address than the one specified. If the
-specified address cannot be used, <function>mmap()</function> will fail. If
-<constant>MAP_FIXED</constant> is specified,
-<parameter>start</parameter> must be a multiple of the pagesize. Use
-of this option is discouraged.</para>
- <para>One of the <constant>MAP_SHARED</constant> or
-<constant>MAP_PRIVATE</constant> flags must be set.
-<constant>MAP_SHARED</constant> allows applications to share the
-mapped memory with other (&eg; child-) processes. Note the Linux
-<filename>video-buf</filename> module which is used by the bttv,
-saa7134, saa7146, cx88 and vivi driver supports only
-<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
-requests copy-on-write semantics. V4L2 applications should not set the
-<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
-<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
-flag.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>offset</parameter></term>
- <listitem>
- <para>Offset of the buffer in device memory. This must be the
-same value as returned by the driver in the &v4l2-buffer;
-<structfield>m</structfield> union <structfield>offset</structfield> field for
-the single-planar API, and the same value as returned by the driver
-in the &v4l2-plane; <structfield>m</structfield> union
-<structfield>mem_offset</structfield> field for the multi-planar API.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>The <function>mmap()</function> function asks to map
-<parameter>length</parameter> bytes starting at
-<parameter>offset</parameter> in the memory of the device specified by
-<parameter>fd</parameter> into the application address space,
-preferably at address <parameter>start</parameter>. This latter
-address is a hint only, and is usually specified as 0.</para>
-
- <para>Suitable length and offset parameters are queried with the
-&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
-&VIDIOC-REQBUFS; ioctl before they can be queried.</para>
-
- <para>To unmap buffers the &func-munmap; function is used.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>mmap()</function> returns a pointer to
-the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
-returned, and the <varname>errno</varname> variable is set
-appropriately. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is
-not open for reading and writing.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>start</parameter> or
-<parameter>length</parameter> or <parameter>offset</parameter> are not
-suitable. (E.&nbsp;g. they are too large, or not aligned on a
-<constant>PAGESIZE</constant> boundary.)</para>
- <para>The <parameter>flags</parameter> or
-<parameter>prot</parameter> value is not supported.</para>
- <para>No buffers have been allocated with the
-&VIDIOC-REQBUFS; ioctl.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>Not enough physical or virtual memory was available to
-complete the request.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml
deleted file mode 100644
index 860d49ca54a..00000000000
--- a/Documentation/DocBook/media/v4l/func-munmap.xml
+++ /dev/null
@@ -1,76 +0,0 @@
-<refentry id="func-munmap">
- <refmeta>
- <refentrytitle>V4L2 munmap()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-munmap</refname>
- <refpurpose>Unmap device memory</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;unistd.h&gt;
-#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>munmap</function></funcdef>
- <paramdef>void *<parameter>start</parameter></paramdef>
- <paramdef>size_t <parameter>length</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
- <refsect1>
- <title>Arguments</title>
- <variablelist>
- <varlistentry>
- <term><parameter>start</parameter></term>
- <listitem>
- <para>Address of the mapped buffer as returned by the
-&func-mmap; function.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>length</parameter></term>
- <listitem>
- <para>Length of the mapped buffer. This must be the same
-value as given to <function>mmap()</function> and returned by the
-driver in the &v4l2-buffer; <structfield>length</structfield>
-field for the single-planar API and in the &v4l2-plane;
-<structfield>length</structfield> field for the multi-planar API.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para>Unmaps a previously with the &func-mmap; function mapped
-buffer and frees it, if possible. <!-- ? This function (not freeing)
-has no impact on I/O in progress, specifically it does not imply
-&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
-enqueued, dequeued or queried, they are just not accessible by the
-application.--></para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>munmap()</function> returns 0, on
-failure -1 and the <varname>errno</varname> variable is set
-appropriately:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>start</parameter> or
-<parameter>length</parameter> is incorrect, or no buffers have been
-mapped yet.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml
deleted file mode 100644
index cf64e207c3e..00000000000
--- a/Documentation/DocBook/media/v4l/func-open.xml
+++ /dev/null
@@ -1,113 +0,0 @@
-<refentry id="func-open">
- <refmeta>
- <refentrytitle>V4L2 open()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-open</refname>
- <refpurpose>Open a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>open</function></funcdef>
- <paramdef>const char *<parameter>device_name</parameter></paramdef>
- <paramdef>int <parameter>flags</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>device_name</parameter></term>
- <listitem>
- <para>Device to be opened.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>flags</parameter></term>
- <listitem>
- <para>Open flags. Access mode must be
-<constant>O_RDWR</constant>. This is just a technicality, input devices
-still support only reading and output devices only writing.</para>
- <para>When the <constant>O_NONBLOCK</constant> flag is
-given, the read() function and the &VIDIOC-DQBUF; ioctl will return
-the &EAGAIN; when no data is available or no buffer is in the driver
-outgoing queue, otherwise these functions block until data becomes
-available. All V4L2 drivers exchanging data with applications must
-support the <constant>O_NONBLOCK</constant> flag.</para>
- <para>Other flags have no effect.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
-
- <para>To open a V4L2 device applications call
-<function>open()</function> with the desired device name. This
-function has no side effects; all data format parameters, current
-input or output, control values or other properties remain unchanged.
-At the first <function>open()</function> call after loading the driver
-they will be reset to default values, drivers are never in an
-undefined state.</para>
- </refsect1>
- <refsect1>
- <title>Return Value</title>
-
- <para>On success <function>open</function> returns the new file
-descriptor. On error -1 is returned, and the <varname>errno</varname>
-variable is set appropriately. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EACCES</errorcode></term>
- <listitem>
- <para>The caller has no permission to access the
-device.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple opens and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENXIO</errorcode></term>
- <listitem>
- <para>No device corresponding to this device special file
-exists.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENOMEM</errorcode></term>
- <listitem>
- <para>Not enough kernel memory was available to complete the
-request.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EMFILE</errorcode></term>
- <listitem>
- <para>The process already has the maximum number of
-files open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>ENFILE</errorcode></term>
- <listitem>
- <para>The limit on the total number of files open on the
-system has been reached.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml
deleted file mode 100644
index 85cad8bff5b..00000000000
--- a/Documentation/DocBook/media/v4l/func-poll.xml
+++ /dev/null
@@ -1,119 +0,0 @@
-<refentry id="func-poll">
- <refmeta>
- <refentrytitle>V4L2 poll()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-poll</refname>
- <refpurpose>Wait for some event on a file descriptor</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>poll</function></funcdef>
- <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
- <paramdef>unsigned int <parameter>nfds</parameter></paramdef>
- <paramdef>int <parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>With the <function>poll()</function> function applications
-can suspend execution until the driver has captured data or is ready
-to accept data for output.</para>
-
- <para>When streaming I/O has been negotiated this function waits
-until a buffer has been filled or displayed and can be dequeued with
-the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
-queue of the driver the function returns immediately.</para>
-
- <para>On success <function>poll()</function> returns the number of
-file descriptors that have been selected (that is, file descriptors
-for which the <structfield>revents</structfield> field of the
-respective <structname>pollfd</structname> structure is non-zero).
-Capture devices set the <constant>POLLIN</constant> and
-<constant>POLLRDNORM</constant> flags in the
-<structfield>revents</structfield> field, output devices the
-<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
-flags. When the function timed out it returns a value of zero, on
-failure it returns <returnvalue>-1</returnvalue> and the
-<varname>errno</varname> variable is set appropriately. When the
-application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
-<function>poll()</function> function succeeds, but sets the
-<constant>POLLERR</constant> flag in the
-<structfield>revents</structfield> field.</para>
-
- <para>When use of the <function>read()</function> function has
-been negotiated and the driver does not capture yet, the
-<function>poll</function> function starts capturing. When that fails
-it returns a <constant>POLLERR</constant> as above. Otherwise it waits
-until data has been captured and can be read. When the driver captures
-continuously (as opposed to, for example, still images) the function
-may return immediately.</para>
-
- <para>When use of the <function>write()</function> function has
-been negotiated the <function>poll</function> function just waits
-until the driver is ready for a non-blocking
-<function>write()</function> call.</para>
-
- <para>All drivers implementing the <function>read()</function> or
-<function>write()</function> function or streaming I/O must also
-support the <function>poll()</function> function.</para>
-
- <para>For more details see the
-<function>poll()</function> manual page.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, <function>poll()</function> returns the number
-structures which have non-zero <structfield>revents</structfield>
-fields, or zero if the call timed out. On error
-<returnvalue>-1</returnvalue> is returned, and the
-<varname>errno</varname> variable is set appropriately:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para>One or more of the <parameter>ufds</parameter> members
-specify an invalid file descriptor.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read or write
-streams and the device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>ufds</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>nfds</parameter> argument is greater
-than <constant>OPEN_MAX</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml
deleted file mode 100644
index e218bbfbd36..00000000000
--- a/Documentation/DocBook/media/v4l/func-read.xml
+++ /dev/null
@@ -1,181 +0,0 @@
-<refentry id="func-read">
- <refmeta>
- <refentrytitle>V4L2 read()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-read</refname>
- <refpurpose>Read from a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>ssize_t <function>read</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>void *<parameter>buf</parameter></paramdef>
- <paramdef>size_t <parameter>count</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>buf</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>count</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para><function>read()</function> attempts to read up to
-<parameter>count</parameter> bytes from file descriptor
-<parameter>fd</parameter> into the buffer starting at
-<parameter>buf</parameter>. The layout of the data in the buffer is
-discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero,
-<function>read()</function> returns zero and has no other results. If
-<parameter>count</parameter> is greater than
-<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless
-of the <parameter>count</parameter> value each
-<function>read()</function> call will provide at most one frame (two
-fields) worth of data.</para>
-
- <para>By default <function>read()</function> blocks until data
-becomes available. When the <constant>O_NONBLOCK</constant> flag was
-given to the &func-open; function it
-returns immediately with an &EAGAIN; when no data is available. The
-&func-select; or &func-poll; functions
-can always be used to suspend execution until data becomes available. All
-drivers supporting the <function>read()</function> function must also
-support <function>select()</function> and
-<function>poll()</function>.</para>
-
- <para>Drivers can implement read functionality in different
-ways, using a single or multiple buffers and discarding the oldest or
-newest frames once the internal buffers are filled.</para>
-
- <para><function>read()</function> never returns a "snapshot" of a
-buffer being filled. Using a single buffer the driver will stop
-capturing when the application starts reading the buffer until the
-read is finished. Thus only the period of the vertical blanking
-interval is available for reading, or the capture rate must fall below
-the nominal frame rate of the video standard.</para>
-
-<para>The behavior of
-<function>read()</function> when called during the active picture
-period or the vertical blanking separating the top and bottom field
-depends on the discarding policy. A driver discarding the oldest
-frames keeps capturing into an internal buffer, continuously
-overwriting the previously, not read frame, and returns the frame
-being received at the time of the <function>read()</function> call as
-soon as it is complete.</para>
-
- <para>A driver discarding the newest frames stops capturing until
-the next <function>read()</function> call. The frame being received at
-<function>read()</function> time is discarded, returning the following
-frame instead. Again this implies a reduction of the capture rate to
-one half or less of the nominal frame rate. An example of this model
-is the video read mode of the bttv driver, initiating a DMA to user
-memory when <function>read()</function> is called and returning when
-the DMA finished.</para>
-
- <para>In the multiple buffer model drivers maintain a ring of
-internal buffers, automatically advancing to the next free buffer.
-This allows continuous capturing when the application can empty the
-buffers fast enough. Again, the behavior when the driver runs out of
-free buffers depends on the discarding policy.</para>
-
- <para>Applications can get and set the number of buffers used
-internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
-ioctls. They are optional, however. The discarding policy is not
-reported and cannot be changed. For minimum requirements see <xref
- linkend="devices" />.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, the number of bytes read is returned. It is not
-an error if this number is smaller than the number of bytes requested,
-or the amount of data required for one frame. This may happen for
-example because <function>read()</function> was interrupted by a
-signal. On error, -1 is returned, and the <varname>errno</varname>
-variable is set appropriately. In this case the next read will start
-at the beginning of a new frame. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Non-blocking I/O has been selected using
-O_NONBLOCK and no data was immediately available for reading.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor or is not open for reading, or the process already has the
-maximum number of files open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read streams and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>buf</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal before any
-data was read.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EIO</errorcode></term>
- <listitem>
- <para>I/O error. This indicates some hardware problem or a
-failure to communicate with a remote device (USB camera etc.).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <function>read()</function> function is not
-supported by this driver, not on this device, or generally not on this
-type of device.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml
deleted file mode 100644
index e12a60d9bd8..00000000000
--- a/Documentation/DocBook/media/v4l/func-select.xml
+++ /dev/null
@@ -1,130 +0,0 @@
-<refentry id="func-select">
- <refmeta>
- <refentrytitle>V4L2 select()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-select</refname>
- <refpurpose>Synchronous I/O multiplexing</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>
-#include &lt;sys/time.h&gt;
-#include &lt;sys/types.h&gt;
-#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>select</function></funcdef>
- <paramdef>int <parameter>nfds</parameter></paramdef>
- <paramdef>fd_set *<parameter>readfds</parameter></paramdef>
- <paramdef>fd_set *<parameter>writefds</parameter></paramdef>
- <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
- <paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para>With the <function>select()</function> function applications
-can suspend execution until the driver has captured data or is ready
-to accept data for output.</para>
-
- <para>When streaming I/O has been negotiated this function waits
-until a buffer has been filled or displayed and can be dequeued with
-the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
-queue of the driver the function returns immediately.</para>
-
- <para>On success <function>select()</function> returns the total
-number of bits set in the <structname>fd_set</structname>s. When the
-function timed out it returns a value of zero. On failure it returns
-<returnvalue>-1</returnvalue> and the <varname>errno</varname>
-variable is set appropriately. When the application did not call
-&VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
-<function>select()</function> function succeeds, setting the bit of
-the file descriptor in <parameter>readfds</parameter> or
-<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
-will fail.<footnote><para>The Linux kernel implements
-<function>select()</function> like the &func-poll; function, but
-<function>select()</function> cannot return a
-<constant>POLLERR</constant>.</para>
- </footnote></para>
-
- <para>When use of the <function>read()</function> function has
-been negotiated and the driver does not capture yet, the
-<function>select()</function> function starts capturing. When that
-fails, <function>select()</function> returns successful and a
-subsequent <function>read()</function> call, which also attempts to
-start capturing, will return an appropriate error code. When the
-driver captures continuously (as opposed to, for example, still
-images) and data is already available the
-<function>select()</function> function returns immediately.</para>
-
- <para>When use of the <function>write()</function> function has
-been negotiated the <function>select()</function> function just waits
-until the driver is ready for a non-blocking
-<function>write()</function> call.</para>
-
- <para>All drivers implementing the <function>read()</function> or
-<function>write()</function> function or streaming I/O must also
-support the <function>select()</function> function.</para>
-
- <para>For more details see the <function>select()</function>
-manual page.</para>
-
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, <function>select()</function> returns the number
-of descriptors contained in the three returned descriptor sets, which
-will be zero if the timeout expired. On error
-<returnvalue>-1</returnvalue> is returned, and the
-<varname>errno</varname> variable is set appropriately; the sets and
-<parameter>timeout</parameter> are undefined. Possible error codes
-are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para>One or more of the file descriptor sets specified a
-file descriptor that is not open.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple read or write
-streams and the device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para>The <parameter>readfds</parameter>,
-<parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
-<parameter>timeout</parameter> pointer references an inaccessible memory
-area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <parameter>nfds</parameter> argument is less than
-zero or greater than <constant>FD_SETSIZE</constant>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml
deleted file mode 100644
index 57520788572..00000000000
--- a/Documentation/DocBook/media/v4l/func-write.xml
+++ /dev/null
@@ -1,128 +0,0 @@
-<refentry id="func-write">
- <refmeta>
- <refentrytitle>V4L2 write()</refentrytitle>
- &manvol;
- </refmeta>
-
- <refnamediv>
- <refname>v4l2-write</refname>
- <refpurpose>Write to a V4L2 device</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
- <funcprototype>
- <funcdef>ssize_t <function>write</function></funcdef>
- <paramdef>int <parameter>fd</parameter></paramdef>
- <paramdef>void *<parameter>buf</parameter></paramdef>
- <paramdef>size_t <parameter>count</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Arguments</title>
-
- <variablelist>
- <varlistentry>
- <term><parameter>fd</parameter></term>
- <listitem>
- <para>&fd;</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>buf</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>count</parameter></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
-
- <para><function>write()</function> writes up to
-<parameter>count</parameter> bytes to the device referenced by the
-file descriptor <parameter>fd</parameter> from the buffer starting at
-<parameter>buf</parameter>. When the hardware outputs are not active
-yet, this function enables them. When <parameter>count</parameter> is
-zero, <function>write()</function> returns
-<returnvalue>0</returnvalue> without any other effect.</para>
-
- <para>When the application does not provide more data in time, the
-previous video frame, raw VBI image, sliced VPS or WSS data is
-displayed again. Sliced Teletext or Closed Caption data is not
-repeated, the driver inserts a blank line instead.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para>On success, the number of bytes written are returned. Zero
-indicates nothing was written. On error, <returnvalue>-1</returnvalue>
-is returned, and the <varname>errno</varname> variable is set
-appropriately. In this case the next write will start at the beginning
-of a new frame. Possible error codes are:</para>
-
- <variablelist>
- <varlistentry>
- <term><errorcode>EAGAIN</errorcode></term>
- <listitem>
- <para>Non-blocking I/O has been selected using the <link
-linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no
-buffer space was available to write the data immediately.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBADF</errorcode></term>
- <listitem>
- <para><parameter>fd</parameter> is not a valid file
-descriptor or is not open for writing.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EBUSY</errorcode></term>
- <listitem>
- <para>The driver does not support multiple write streams and the
-device is already in use.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EFAULT</errorcode></term>
- <listitem>
- <para><parameter>buf</parameter> references an inaccessible
-memory area.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINTR</errorcode></term>
- <listitem>
- <para>The call was interrupted by a signal before any
-data was written.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EIO</errorcode></term>
- <listitem>
- <para>I/O error. This indicates some hardware problem.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><errorcode>EINVAL</errorcode></term>
- <listitem>
- <para>The <function>write()</function> function is not
-supported by this driver, not on this device, or generally not on this
-type of device.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-</refentry>
diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml
deleted file mode 100644
index 5bbf3ce1973..00000000000
--- a/Documentation/DocBook/media/v4l/gen-errors.xml
+++ /dev/null
@@ -1,78 +0,0 @@
-<title>Generic Error Codes</title>
-
-<table frame="none" pgwide="1" id="gen-errors">
- <title>Generic error codes</title>
- <tgroup cols="2">
- &cs-str;
- <tbody valign="top">
- <!-- Keep it ordered alphabetically -->
- <row>
- <entry>EBADF</entry>
- <entry>The file descriptor is not a valid.</entry>
- </row>
- <row>
- <entry>EBUSY</entry>
- <entry>The ioctl can't be handled because the device is busy. This is
- typically return while device is streaming, and an ioctl tried to
- change something that would affect the stream, or would require the
- usage of a hardware resource that was already allocated. The ioctl
- must not be retried without performing another action to fix the
- problem first (typically: stop the stream before retrying).</entry>
- </row>
- <row>
- <entry>EFAULT</entry>
- <entry>There was a failure while copying data from/to userspace,
- probably caused by an invalid pointer reference.</entry>
- </row>
- <row>
- <entry>EINVAL</entry>
- <entry>One or more of the ioctl parameters are invalid or out of the
- allowed range. This is a widely used error code. See the individual
- ioctl requests for specific causes.</entry>
- </row>
- <row>
- <entry>ENODEV</entry>
- <entry>Device not found or was removed.</entry>
- </row>
- <row>
- <entry>ENOMEM</entry>
- <entry>There's not enough memory to handle the desired operation.</entry>
- </row>
- <row>
- <entry>ENOTTY</entry>
- <entry>The ioctl is not supported by the driver, actually meaning that
- the required functionality is not available, or the file
- descriptor is not for a media device.</entry>
- </row>
- <row>
- <entry>ENOSPC</entry>
- <entry>On USB devices, the stream ioctl's can return this error, meaning
- that this request would overcommit the usb bandwidth reserved
- for periodic transfers (up to 80% of the USB bandwidth).</entry>
- </row>
- <row>
- <entry>ENOSYS or EOPNOTSUPP</entry>
- <entry>Function not available for this device (dvb API only. Will likely
- be replaced anytime soon by ENOTTY).</entry>
- </row>
- <row>
- <entry>EPERM</entry>
- <entry>Permission denied. Can be returned if the device needs write
- permission, or some special capabilities is needed
- (e. g. root)</entry>
- </row>
- <row>
- <entry>EWOULDBLOCK</entry>
- <entry>Operation would block. Used when the ioctl would need to wait
- for an event, but the device was opened in non-blocking mode.</entry>
- </row>
- </tbody>
- </tgroup>
-</table>
-
-<para>Note 1: ioctls may return other error codes. Since errors may have side
-effects such as a driver reset, applications should abort on unexpected errors.
-</para>
-
-<para>Note 2: Request-specific error codes are listed in the individual
-requests descriptions.</para>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
deleted file mode 100644
index fd6aca2922b..00000000000
--- a/Documentation/DocBook/media/v4l/io.xml
+++ /dev/null
@@ -1,1286 +0,0 @@
- <title>Input/Output</title>
-
- <para>The V4L2 API defines several different methods to read from or
-write to a device. All drivers exchanging data with applications must
-support at least one of them.</para>
-
- <para>The classic I/O method using the <function>read()</function>
-and <function>write()</function> function is automatically selected
-after opening a V4L2 device. When the driver does not support this
-method attempts to read or write will fail at any time.</para>
-
- <para>Other methods must be negotiated. To select the streaming I/O
-method with memory mapped or user buffers applications call the
-&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
-yet.</para>
-
- <para>Video overlay can be considered another I/O method, although
-the application does not directly receive the image data. It is
-selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
-For more information see <xref linkend="overlay" />.</para>
-
- <para>Generally exactly one I/O method, including overlay, is
-associated with each file descriptor. The only exceptions are
-applications not exchanging data with a driver ("panel applications",
-see <xref linkend="open" />) and drivers permitting simultaneous video capturing
-and overlay using the same file descriptor, for compatibility with V4L
-and earlier versions of V4L2.</para>
-
- <para><constant>VIDIOC_S_FMT</constant> and
-<constant>VIDIOC_REQBUFS</constant> would permit this to some degree,
-but for simplicity drivers need not support switching the I/O method
-(after first switching away from read/write) other than by closing
-and reopening the device.</para>
-
- <para>The following sections describe the various I/O methods in
-more detail.</para>
-
- <section id="rw">
- <title>Read/Write</title>
-
- <para>Input and output devices support the
-<function>read()</function> and <function>write()</function> function,
-respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
-the <structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
-
- <para>Drivers may need the CPU to copy the data, but they may also
-support DMA to or from user memory, so this I/O method is not
-necessarily less efficient than other methods merely exchanging buffer
-pointers. It is considered inferior though because no meta-information
-like frame counters or timestamps are passed. This information is
-necessary to recognize frame dropping and to synchronize with other
-data streams. However this is also the simplest I/O method, requiring
-little or no setup to exchange data. It permits command line stunts
-like this (the <application>vidctrl</application> tool is
-fictitious):</para>
-
- <informalexample>
- <screen>
-&gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
-&gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
-</screen>
- </informalexample>
-
- <para>To read from the device applications use the
-&func-read; function, to write the &func-write; function.
-Drivers must implement one I/O method if they
-exchange data with applications, but it need not be this.<footnote>
- <para>It would be desirable if applications could depend on
-drivers supporting all I/O interfaces, but as much as the complex
-memory mapping I/O can be inadequate for some devices we have no
-reason to require this interface, which is most useful for simple
-applications capturing still images.</para>
- </footnote> When reading or writing is supported, the driver
-must also support the &func-select; and &func-poll;
-function.<footnote>
- <para>At the driver level <function>select()</function> and
-<function>poll()</function> are the same, and
-<function>select()</function> is too important to be optional.</para>
- </footnote></para>
- </section>
-
- <section id="mmap">
- <title>Streaming I/O (Memory Mapping)</title>
-
- <para>Input and output devices support this I/O method when the
-<constant>V4L2_CAP_STREAMING</constant> flag in the
-<structfield>capabilities</structfield> field of &v4l2-capability;
-returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
-streaming methods, to determine if the memory mapping flavor is
-supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
-
- <para>Streaming is an I/O method where only pointers to buffers
-are exchanged between application and driver, the data itself is not
-copied. Memory mapping is primarily intended to map buffers in device
-memory into the application's address space. Device memory can be for
-example the video memory on a graphics card with a video capture
-add-on. However, being the most efficient I/O method available for a
-long time, many other drivers support streaming as well, allocating
-buffers in DMA-able main memory.</para>
-
- <para>A driver can support many sets of buffers. Each set is
-identified by a unique buffer type value. The sets are independent and
-each set can hold a different type of data. To access different sets
-at the same time different f