diff options
| author | Mauro Carvalho Chehab <mchehab@redhat.com> | 2009-09-06 23:42:19 -0300 |
|---|---|---|
| committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2009-09-06 23:42:19 -0300 |
| commit | 5700f50011f5c8ad20cfc1377cc830ed4eee9d06 (patch) | |
| tree | 2c82f7573c54bdce520b1a4748deb0fe4126d2a6 /v4l2-spec | |
| parent | 4b70cc85ac708fdb3107b4d17851e70e6bf9ecc6 (diff) | |
| parent | 00c1eda676d0707af2602f156278772fe3c30cb8 (diff) | |
| download | mediapointer-dvb-s2-5700f50011f5c8ad20cfc1377cc830ed4eee9d06.tar.gz mediapointer-dvb-s2-5700f50011f5c8ad20cfc1377cc830ed4eee9d06.tar.bz2 | |
merge: http://linuxtv.org/hg/~hgoede/gspca/
From: Mauro Carvalho Chehab <mchehab@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'v4l2-spec')
69 files changed, 1390 insertions, 591 deletions
diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 8f40e8614..f593faccd 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -5,6 +5,8 @@ SHELL=/bin/bash SGMLS = \ biblio.sgml \ capture.c.sgml \ + keytable.c.sgml \ + v4l2grab.c.sgml \ common.sgml \ compat.sgml \ controls.sgml \ @@ -20,6 +22,8 @@ SGMLS = \ dev-sliced-vbi.sgml \ dev-teletext.sgml \ driver.sgml \ + libv4l.sgml \ + remote_controllers.sgml \ entities.sgml \ fdl-appendix.sgml \ func-close.sgml \ @@ -117,8 +121,12 @@ WARN = #WARN = -w all -w duplicate -w net # Stylesheet customization. + # docbook/db2 syntax CUSTOM_HTML = --dsl custom.dsl\#html CUSTOM_PRINT = --dsl custom.dsl\#print + # xmlto syntax +CUSTOM_HTML_XMLTO = -m custom.xsl +CUSTOM_PRINT_XMLTO = -m custom.xsl all: capture html-single @@ -128,6 +136,12 @@ html-single: html-single-build.stamp pdf: pdf-build.stamp +man: man-build.stamp + +man_install: man-build.stamp + install -d /usr/local/man/man2 + install -b man/* /usr/local/man/man2 + coffeebreak: all html pdf FUNCS = \ @@ -243,6 +257,7 @@ ENUMS = \ v4l2_power_line_frequency \ v4l2_priority \ v4l2_tuner_type \ + v4l2_preemphasis \ STRUCTS = \ v4l2_audio \ @@ -305,6 +320,7 @@ ERRORS = \ EINVAL \ ENFILE \ ENOMEM \ + ENOSPC \ ENOTTY \ ENXIO \ EMFILE \ @@ -321,7 +337,14 @@ DOCUMENTED = \ -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \ -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \ -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \ - -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" + -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \ + -e "s/(linkend=\")v4l2-mpeg-vbi-ITV0/\1)v4l2_mpeg_vbi_itv0-1/g" + +libv4l-fmt.sgml: + cat ../v4l2-apps/libv4l/libv4lconvert/*.c| \ + perl -ne 'if (m/(V4L2_PIX_FMT_[^\s\;\\)\,:]+)/) { printf "<link linkend=\"$$1\"><constant>$$1</constant></link>,\n"; };' \ + |sort|uniq| \ + sed -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" > $@ capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile echo "<programlisting>" > $@ @@ -330,6 +353,20 @@ capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile sed 's/i\.e\./&ie;/' >> $@ echo "</programlisting>" >> $@ +v4l2grab.c.sgml: ../v4l2-apps/test/v4l2grab.c Makefile + echo "<programlisting>" > $@ + expand --tabs=8 < $< | \ + sed $(ESCAPE) $(DOCUMENTED) | \ + sed 's/i\.e\./&ie;/' >> $@ + echo "</programlisting>" >> $@ + +keytable.c.sgml: ../v4l2-apps/util/keytable.c Makefile + echo "<programlisting>" > $@ + expand --tabs=8 < $< | \ + sed $(ESCAPE) $(DOCUMENTED) | \ + sed 's/i\.e\./&ie;/' >> $@ + echo "</programlisting>" >> $@ + videodev2.h.sgml: ../linux/include/linux/videodev2.h Makefile echo "<programlisting>" > $@ expand --tabs=8 < $< | \ @@ -443,10 +480,14 @@ indices.sgml: Makefile # HTML version. html-build.stamp: Makefile checks $(SGMLS) $(GIFPICS) rm -rf v4l2 - if which docbook2html >/dev/null ; then \ - docbook2html $(WARN) $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \ + if which xmlto >/dev/null ; then \ + xmlto xhtml $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2 v4l2.sgml ; \ + elif which docbook2html >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2html $(WARN) $$DCL $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \ else \ - db2html $(WARN) $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + db2html $(WARN) $$DCL $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \ fi cp $(GIFPICS) v4l2/ cd v4l2 ; \ @@ -460,11 +501,15 @@ html-build.stamp: Makefile checks $(SGMLS) $(GIFPICS) # is more convenient than clicking through dozens of pages. html-single-build.stamp: Makefile checks $(SGMLS) $(GIFPICS) rm -rf v4l2-single - if which docbook2html >/dev/null; then \ - docbook2html $(WARN) $(CUSTOM_HTML) --nochunks \ + if which xmlto >/dev/null ; then \ + xmlto html-nochunks $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2-single v4l2.sgml ; \ + elif which docbook2html >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \ --output v4l2-single v4l2.sgml ; \ else \ - db2html $(WARN) $(CUSTOM_HTML) --nochunks \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + db2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \ --output v4l2-single v4l2.sgml ; \ fi cp $(GIFPICS) v4l2-single/ @@ -473,13 +518,22 @@ html-single-build.stamp: Makefile checks $(SGMLS) $(GIFPICS) # For printing. pdf-build.stamp: Makefile checks $(SGMLS) $(PDFPICS) - if which docbook2pdf >/dev/null; then \ - docbook2pdf $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \ + if which db2pdf >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl|head -1`"; \ + db2pdf $$DCL $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \ + elif which xmlto >/dev/null ; then \ + xmlto pdf $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2-single v4l2.sgml ; \ else \ - db2pdf $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2pdf $$DCL $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \ fi touch pdf-build.stamp + +# For man +man-build.stamp: Makefile checks $(SGMLS) $(PDFPICS) + xmlto man $(WARN) $(CUSTOM_HTML_XMLTO) -o man v4l2.sgml + # Example. capture: ../v4l2-apps/test/capture-example.c gcc $^ -o $@ @@ -488,6 +542,7 @@ distclean clean: rm -f *.stamp rm -f videodev2.h.sgml rm -f capture.c.sgml + rm -f v4l2grab.c.sgml rm -f capture rm -f indices.sgml entities.sgml rm -rf v4l2 v4l2-single v4l2.pdf diff --git a/v4l2-spec/common.sgml b/v4l2-spec/common.sgml index 75c7141e3..dd598ac9a 100644 --- a/v4l2-spec/common.sgml +++ b/v4l2-spec/common.sgml @@ -27,7 +27,7 @@ input, video standard, picture brightness a. o.</para> <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 +details in <xref linkend="devices" />. In this chapter we will discuss the basic concepts applicable to all devices.</para> <section id="open"> @@ -75,8 +75,8 @@ 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"> +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"> @@ -91,7 +91,7 @@ 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"> +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 @@ -101,7 +101,7 @@ 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 recomended for the -different V4L2 device types are listed in <xref linkend="devices">. +different V4L2 device types are listed in <xref linkend="devices" />. </para> <para>The creation of character special files (with @@ -143,7 +143,7 @@ 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> +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 @@ -197,7 +197,7 @@ so applications cannot know if it really works.</para> 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> +<xref linkend="app-pri" />.</para> </section> <section> @@ -303,10 +303,10 @@ device has one or more outputs.</para> <title>Input and output enumeration is the root of most device properties.</title> <mediaobject> <imageobject> - <imagedata fileref="links.pdf" format="ps"> + <imagedata fileref="links.pdf" format="ps" /> </imageobject> <imageobject> - <imagedata fileref="links.gif" format="gif"> + <imagedata fileref="links.gif" format="gif" /> </imageobject> <textobject> <phrase>Links between various device property structures.</phrase> @@ -604,7 +604,7 @@ to zero, the <constant>VIDIOC_G_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 + <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> @@ -752,8 +752,8 @@ using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and 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> +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 @@ -863,10 +863,10 @@ determine if scaling takes place.</emphasis></para> <title>Image Cropping, Insertion and Scaling</title> <mediaobject> <imageobject> - <imagedata fileref="crop.pdf" format="PS"> + <imagedata fileref="crop.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="crop.gif" format="GIF"> + <imagedata fileref="crop.gif" format="GIF" /> </imageobject> <textobject> <phrase>The cropping, insertion and scaling process</phrase> @@ -881,10 +881,10 @@ the <structfield>bounds</structfield> substructure of the 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">). +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 +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 @@ -1036,13 +1036,13 @@ if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &format)) { <title>Selecting an output area</title> <programlisting> -&v4l2-cropcap cropcap; -&v4l2-crop crop; +&v4l2-cropcap; cropcap; +&v4l2-crop; crop; memset (&cropcap, 0, sizeof (cropcap)); cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; -if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { +if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { perror ("VIDIOC_CROPCAP"); exit (EXIT_FAILURE); } @@ -1063,7 +1063,7 @@ crop.c.top += crop.c.height / 2; /* Ignore if cropping is not supported (EINVAL). */ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { + && errno != EINVAL) { perror ("VIDIOC_S_CROP"); exit (EXIT_FAILURE); } diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index bcc372c18..4d1902a54 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -23,8 +23,8 @@ API.</para> <para>For compatibility reasons the character device file names recommended for V4L2 video capture, overlay, radio, teletext 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> +listed in <xref linkend="devices" /> and below in <xref + linkend="v4l-dev" />.</para> <para>The V4L <filename>videodev</filename> module automatically assigns minor numbers to drivers in load order, depending on the @@ -85,14 +85,14 @@ not compatible with V4L or V4L2.</para> </footnote>, <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> +opens, see <xref linkend="open" /> for details and consequences.</para> <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The compatibility layer in the V4L2 <filename>videodev</filename> module can translate V4L ioctl requests to their V4L2 counterpart, however a V4L2 driver usually needs more preparation to become fully V4L compatible. This is covered in more detail in <xref - linkend="driver">.</para> + linkend="driver" />.</para> </section> <section> @@ -109,7 +109,7 @@ equivalent to V4L2's &VIDIOC-QUERYCAP;.</para> 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 +capturing. See <xref linkend="open" /> for an introduction.<informaltable> <tgroup cols="3"> <thead> @@ -154,7 +154,7 @@ field <structfield>capability</structfield> of &v4l2-framebuffer;</entry> <entry>Whether chromakey overlay is supported. For more information on overlay see -<xref linkend="overlay">.</entry> +<xref linkend="overlay" />.</entry> </row> <row> <entry><constant>VID_TYPE_CLIPPING</constant></entry> @@ -162,7 +162,7 @@ more information on overlay see 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> +supported, see <xref linkend="overlay" />.</entry> </row> <row> <entry><constant>VID_TYPE_FRAMERAM</constant></entry> @@ -170,7 +170,7 @@ supported, see <xref linkend="overlay">.</entry> <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> +see <xref linkend="overlay" />.</entry> </row> <row> <entry><constant>VID_TYPE_SCALES</constant></entry> @@ -180,7 +180,7 @@ 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> + linkend="crop" />.</entry> </row> <row> <entry><constant>VID_TYPE_MONOCHROME</constant></entry> @@ -188,7 +188,7 @@ For more information on cropping and scaling see <xref <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> +formats see <xref linkend="pixfmt" />.</entry> </row> <row> <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry> @@ -197,7 +197,7 @@ formats see <xref linkend="pixfmt">.</entry> 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> + linkend="crop" />.</entry> </row> <row> <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry> @@ -231,7 +231,7 @@ by <structfield>capabilities</structfield> flag <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> + linkend="audio" />.</para> <para>The <structfield>maxwidth</structfield>, <structfield>maxheight</structfield>, @@ -250,7 +250,7 @@ video standard, cropping and scaling limitations.</para> <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> +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 @@ -284,7 +284,7 @@ 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> + linkend="tuner" />.</para> <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was dropped. Video inputs associated with a tuner are of type @@ -294,7 +294,7 @@ dropped. Video inputs associated with a tuner are of type 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> +how to switch between them see <xref linkend="audio" />.</para> <para>The <structfield>norm</structfield> field describing the supported video standards was replaced by @@ -303,7 +303,7 @@ supported video standards was replaced by 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 +to video standards, see <xref linkend="standard" /> for more information.</para> </section> @@ -315,7 +315,7 @@ information.</para> <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> +covered in <xref linkend="tuner" />.</para> <para>The <structfield>tuner</structfield> field counting tuners was renamed to <structfield>index</structfield>. The fields @@ -330,7 +330,7 @@ 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">. +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), @@ -403,7 +403,7 @@ fields where replaced by V4L2 controls accessible with the 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> +linkend="control" />.</para> <para>The <structfield>depth</structfield> (average number of bits per pixel) of a video image is implied by the selected image @@ -455,7 +455,7 @@ linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entr 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 endianess. V4L2 defines little-endian, big-endian and red/blue -swapped variants. For details see <xref linkend="pixfmt-rgb">.</para> +swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para> </footnote></para></entry> </row> <row> @@ -522,7 +522,7 @@ linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></p </informaltable></para> <para>V4L2 image formats are defined in <xref -linkend="pixfmt">. The image format can be selected with the +linkend="pixfmt" />. The image format can be selected with the &VIDIOC-S-FMT; ioctl.</para> </section> @@ -534,7 +534,7 @@ linkend="pixfmt">. The image format can be selected with the <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> +discussed in <xref linkend="audio" />.</para> <para>The <structfield>audio</structfield> "channel number" field counting audio inputs was renamed to @@ -555,7 +555,7 @@ 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 +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> @@ -608,7 +608,7 @@ attribute replacing the struct <structname>video_audio</structname> 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> +controls see <xref linkend="control" />.</para> </section> <section> @@ -624,7 +624,7 @@ defines a flag to indicate non-destructive overlays instead of a &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 + linkend="pixfmt-rgb" /> for a list of RGB formats and their respective color depths.</para> <para>Instead of the special ioctls @@ -680,7 +680,7 @@ defines the <constant>VIDIOCGCAPTURE</constant> and <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> +<xref linkend="crop" /> for details.</para> <para>The <structfield>x</structfield>, <structfield>y</structfield>, <structfield>width</structfield> and @@ -723,7 +723,7 @@ ioctls. V4L2 uses the general-purpose data format negotiation ioctls union is used.</para> <para>For more information about the V4L2 read interface see -<xref linkend="rw">.</para> +<xref linkend="rw" />.</para> </section> <section> <title>Capturing using memory mapping</title> @@ -796,7 +796,7 @@ queues. Applications can query the signal status, if known, with the </informaltable> <para>For a more in-depth discussion of memory mapping and -examples, see <xref linkend="mmap">.</para> +examples, see <xref linkend="mmap" />.</para> </section> </section> @@ -859,7 +859,7 @@ correct values.</para></footnote></para></entry> <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> +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 @@ -881,12 +881,12 @@ parameters are invalid.</para> <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> +<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> + linkend="extended-controls" />.</para> </section> </section> @@ -1250,7 +1250,7 @@ into Linux 2.5.46.</para> <orderedlist> <listitem> - <para>As specified in <xref linkend="related">, drivers + <para>As specified in <xref linkend="related" />, drivers must make related device functions available under all minor device numbers.</para> </listitem> @@ -1264,7 +1264,7 @@ 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> +<xref linkend="open" />.</para> </listitem> <listitem> @@ -1294,8 +1294,8 @@ set and was merged into the <structfield>flags</structfield> field. <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> +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>, @@ -1303,15 +1303,15 @@ fields <structfield>maxwidth</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> +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> + linkend="format" />.</para> </listitem> <listitem> @@ -1383,7 +1383,7 @@ 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 + 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 @@ -1577,7 +1577,7 @@ field.<informaltable> &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 +by the driver or the application. See <xref linkend="io" /> for details.</para> </listitem> @@ -1595,7 +1595,7 @@ 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"> +added to distinguish between I/O methods. See <xref linkend="io" /> for details.</para> <para>The <constant>V4L2_BUF_REQ_CONTIG</constant> @@ -1649,7 +1649,7 @@ to distinguish between field and frame (interlaced) overlay.</para> 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> +See <xref linkend="crop" /> for details.</para> </listitem> <listitem> @@ -1683,7 +1683,7 @@ applications.</para> <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 +corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be 0.587, and 127/112 != 255/224 --></para> </listitem> </orderedlist> @@ -1702,7 +1702,7 @@ tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para> <listitem> <para>An optional driver access priority mechanism was -added, see <xref linkend="app-pri"> for details.</para> +added, see <xref linkend="app-pri" /> for details.</para> </listitem> <listitem> @@ -1734,7 +1734,7 @@ must be recompiled, but not applications.</para> </listitem> <listitem> - <para><xref linkend="overlay"> incorrectly stated that + <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 @@ -1756,7 +1756,7 @@ applications assuming a constant parameter need an update.</para> <title>V4L2 2003-11-05</title> <orderedlist> <listitem> - <para>In <xref linkend="pixfmt-rgb"> the following pixel + <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> @@ -1795,7 +1795,7 @@ ascending address order.<informaltable> </informaltable> The <constant>V4L2_PIX_FMT_BGR24</constant> example was always correct.</para> - <para>In <xref linkend="v4l-image-properties"> the mapping + <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> @@ -1805,7 +1805,7 @@ was accordingly corrected.</para> <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> + linkend="pixfmt-rgb" />.</para> </listitem> </orderedlist> </section> @@ -1844,7 +1844,7 @@ read-only.</para> <orderedlist> <listitem> <para>The return value of the -<xref linkend="func-open"> function was incorrectly documented.</para> +<xref linkend="func-open" /> function was incorrectly documented.</para> </listitem> <listitem> @@ -1872,7 +1872,7 @@ was not documented.</para> <orderedlist> <listitem> <para>A new sliced VBI interface was added. It is documented -in <xref linkend="sliced"> and replaces the interface first +in <xref linkend="sliced" /> and replaces the interface first proposed in V4L2 specification 0.8.</para> </listitem> </orderedlist> @@ -1895,7 +1895,7 @@ and <constant>V4L2_STD_ATSC</constant> (a set of <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> + linkend="v4l2-std-id" />.</para> </listitem> <listitem> @@ -1914,10 +1914,10 @@ was replaced by a struct <section> <title>V4L2 spec erratum 2005-11-27</title> - <para>The capture example in <xref linkend="capture-example"> + <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 +<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong argument type.</para> </section> @@ -1999,18 +1999,18 @@ interface were not mentioned along with other buffer types.</para> </listitem> <listitem> - <para>In <xref linkend="vidioc-g-audio"> it was clarified + <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 + <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 + <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> @@ -2022,8 +2022,8 @@ 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 + <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> @@ -2046,13 +2046,13 @@ 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 + 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> + linkend="control-flags" />). See <xref + linkend="extended-controls" /> for details.</para> </listitem> </orderedlist> </section> @@ -2077,7 +2077,7 @@ compatibility</emphasis> with older drivers and applications.</para> <listitem> <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref -linkend="rgb-formats">) was added.</para> +linkend="rgb-formats" />) was added.</para> </listitem> </orderedlist> </section> @@ -2087,7 +2087,7 @@ linkend="rgb-formats">) was added.</para> <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> +linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para> </listitem> </orderedlist> </section> @@ -2110,7 +2110,7 @@ later, and under a 3-clause BSD-style license.</para> <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> + added. See <xref linkend="v4l2-field" /> for details.</para> </listitem> <listitem> @@ -2265,7 +2265,7 @@ video encoding.</para> <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> +was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para> </listitem> <listitem> <para>The pixel formats @@ -2297,12 +2297,31 @@ was renamed to <structname id=v4l2-chip-ident-old>v4l2_chip_ident_old</structnam <title>V4L2 in Linux 2.6.32</title> <orderedlist> <listitem> - <para>Finalized the RDS capture API. See <xref linkend="rds"> for + <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> @@ -2348,7 +2367,7 @@ 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> + 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 @@ -2383,15 +2402,15 @@ and may change in the future.</para> <itemizedlist> <listitem> <para>Video Output Overlay (OSD) Interface, <xref - linkend="osd">.</para> + linkend="osd" />.</para> </listitem> <listitem> <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, - &v4l2-buf-type;, <xref linkend="v4l2-buf-type">.</para> + &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> +&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> </listitem> <listitem> <para>&VIDIOC-ENUM-FRAMESIZES; and @@ -2424,7 +2443,7 @@ interfaces and should not be implemented in new drivers.</para> <listitem> <para><constant>VIDIOC_G_MPEGCOMP</constant> and <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, -<xref linkend="extended-controls">.</para> +<xref linkend="extended-controls" />.</para> </listitem> </itemizedlist> </section> diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index 477a97077..f492accb6 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -15,7 +15,7 @@ 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 +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 @@ -215,7 +215,7 @@ linkend="camera-controls">Camera class controls</link> <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 +<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>, @@ -291,7 +291,7 @@ minimum value disables backlight compensation.</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> +driver name and version, see <xref linkend="querycap" />.</entry> </row> </tbody> </tgroup> @@ -458,6 +458,12 @@ 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> @@ -492,8 +498,7 @@ 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 (although the latter is not yet used -anywhere).</para> +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 @@ -541,7 +546,7 @@ control class is found:</para> <informalexample> <programlisting> qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL; -while (0 == ioctl (fd, &VIDIOC-QUERYCTRL, &qctrl)) { +while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) { if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG) break; /* ... */ @@ -600,12 +605,12 @@ certain hardware.</para> <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"> + <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> @@ -1381,12 +1386,12 @@ 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"> + <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> @@ -1600,12 +1605,12 @@ 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"> + <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> @@ -1811,11 +1816,228 @@ 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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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> </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 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> </entry> + <entry>No pre-emphasis is applied.</entry> + </row> + <row> + <entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry> + <entry>A pre-emphasis of 50 uS is used.</entry> + </row> + <row> + <entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </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> </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> </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> <!-- diff --git a/v4l2-spec/custom.xsl b/v4l2-spec/custom.xsl new file mode 100644 index 000000000..e1556c37c --- /dev/null +++ b/v4l2-spec/custom.xsl @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8"?> +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Extension for HTML files --> +<param name="html.ext" select="'.html'"/> + +<!-- Generate TOCs for book, article, part --> +<param name="generate.book.toc">1</param> +<param name="generate.article.toc">0</param> +<param name="generate.part.toc">0</param> +<param name="toc.chapter.depth">0</param> + +<param name="refentry.separator">1</param> + +<param name="chunk.first.sections">1</param> +<param name="chunk.id.as.filename">1</param> +<param name="chunk.separate.lots">1</param> + +<param name="funcsynopsis.style">ansi</param> +<param name="funcsynopsis.tabular.threshold">80</param> +<param name="funcsynopsis.decoration">1</param> + +<param name="chapter.autolabel">1</param> +<param name="section.autolabel">1</param> +<param name="section.label.includes.component.label">1</param> +<param name="toc.section.depth">3</param> + +<param name="paper.type">A4</param> +</stylesheet> diff --git a/v4l2-spec/dev-capture.sgml b/v4l2-spec/dev-capture.sgml index d2885988b..32807e43f 100644 --- a/v4l2-spec/dev-capture.sgml +++ b/v4l2-spec/dev-capture.sgml @@ -60,7 +60,7 @@ and scaling.</para> <para>Cropping initialization at minimum requires to reset the parameters to defaults. An example is given in <xref -linkend="crop">.</para> +linkend="crop" />.</para> <para>To query the current image format applications set the <structfield>type</structfield> field of a &v4l2-format; to @@ -85,7 +85,7 @@ without disabling I/O or possibly time consuming hardware preparations.</para> <para>The contents of &v4l2-pix-format; are discussed in <xref -linkend="pixfmt">. See also the specification of the +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 @@ -103,7 +103,7 @@ returns default parameters as <constant>VIDIOC_G_FMT</constant> does. 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> +linkend="io" /> for details.</para> </section> <!-- diff --git a/v4l2-spec/dev-osd.sgml b/v4l2-spec/dev-osd.sgml index 7210292fa..c9a68a2cc 100644 --- a/v4l2-spec/dev-osd.sgml +++ b/v4l2-spec/dev-osd.sgml @@ -59,7 +59,7 @@ framebuffer device.</para> <programlisting> #include <linux/fb.h> -&v4l2-framebuffer fbuf; +&v4l2-framebuffer; fbuf; unsigned int i; int fb_fd; @@ -68,7 +68,7 @@ if (-1 == ioctl (fd, VIDIOC_G_FBUF, &fbuf)) { exit (EXIT_FAILURE); } -for (i = 0; i < 30; ++i) { +for (i = 0; i > 30; ++i) { char dev_name[16]; struct fb_fix_screeninfo si; @@ -144,7 +144,7 @@ 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> +data flow. For more information see <xref linkend="crop" />.</para> </section> <section> diff --git a/v4l2-spec/dev-output.sgml b/v4l2-spec/dev-output.sgml index 4cbc08b10..63c3c20e5 100644 --- a/v4l2-spec/dev-output.sgml +++ b/v4l2-spec/dev-output.sgml @@ -56,7 +56,7 @@ and scaling.</para> <para>Cropping initialization at minimum requires to reset the parameters to defaults. An example is given in <xref -linkend="crop">.</para> +linkend="crop" />.</para> <para>To query the current image format applications set the <structfield>type</structfield> field of a &v4l2-format; to @@ -81,7 +81,7 @@ without disabling I/O or possibly time consuming hardware preparations.</para> <para>The contents of &v4l2-pix-format; are discussed in <xref -linkend="pixfmt">. See also the specification of the +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 @@ -99,7 +99,7 @@ returns default parameters as <constant>VIDIOC_G_FMT</constant> does. 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> +linkend="io" /> for details.</para> </section> <!-- diff --git a/v4l2-spec/dev-overlay.sgml b/v4l2-spec/dev-overlay.sgml index be56fc594..92513cf79 100644 --- a/v4l2-spec/dev-overlay.sgml +++ b/v4l2-spec/dev-overlay.sgml @@ -131,7 +131,7 @@ format requested first takes precedence. The attempt to capture 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> +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 @@ -157,7 +157,7 @@ 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> +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 @@ -281,7 +281,7 @@ more pixels or not write the image at all.</para> <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> +&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry> </row> <row> <entry></entry> diff --git a/v4l2-spec/dev-radio.sgml b/v4l2-spec/dev-radio.sgml index 4d521d2a8..73aa90b45 100644 --- a/v4l2-spec/dev-radio.sgml +++ b/v4l2-spec/dev-radio.sgml @@ -38,9 +38,9 @@ methods are reserved for future extensions.</para> <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 +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 +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 diff --git a/v4l2-spec/dev-raw-vbi.sgml b/v4l2-spec/dev-raw-vbi.sgml index 39d814c44..c5a70bdfa 100644 --- a/v4l2-spec/dev-raw-vbi.sgml +++ b/v4l2-spec/dev-raw-vbi.sgml @@ -121,7 +121,7 @@ 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> +edge. See also <xref linkend="vbi-hsync" />.</para></entry> </row> <row> <entry>__u32</entry> @@ -132,7 +132,7 @@ edge. See also <xref linkend="vbi-hsync">.</para></entry> <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> +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> @@ -149,8 +149,8 @@ signal. Drivers shall not convert the sample format by software.</para></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 +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> @@ -174,8 +174,8 @@ 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 +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 @@ -186,7 +186,7 @@ be evaluated for this purpose.</para></entry> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>See <xref linkend="vbifmt-flags"> below. Currently + <entry>See <xref linkend="vbifmt-flags" /> below. Currently only drivers set flags, applications must set this field to zero.</entry> </row> @@ -226,7 +226,7 @@ cannot be reliable decoded or encoded when <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"> +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 @@ -247,10 +247,10 @@ the same time. For simplicity setting this flag implies that both <title>Line synchronization</title> <mediaobject> <imageobject> - <imagedata fileref="vbi_hsync.pdf" format="PS"> + <imagedata fileref="vbi_hsync.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="vbi_hsync.gif" format="GIF"> + <imagedata fileref="vbi_hsync.gif" format="GIF" /> </imageobject> <textobject> <phrase>Line synchronization diagram</phrase> @@ -262,10 +262,10 @@ the same time. For simplicity setting this flag implies that both <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title> <mediaobject> <imageobject> - <imagedata fileref="vbi_525.pdf" format="PS"> + <imagedata fileref="vbi_525.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="vbi_525.gif" format="GIF"> + <imagedata fileref="vbi_525.gif" format="GIF" /> </imageobject> <textobject> <phrase>NTSC field synchronization diagram</phrase> @@ -282,10 +282,10 @@ supported.</para> <title>ITU-R 625 line numbering</title> <mediaobject> <imageobject> - <imagedata fileref="vbi_625.pdf" format="PS"> + <imagedata fileref="vbi_625.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="vbi_625.gif" format="GIF"> + <imagedata fileref="vbi_625.gif" format="GIF" /> </imageobject> <textobject> <phrase>PAL/SECAM field synchronization diagram</phrase> diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml index 9d59d0cb0..0869d701b 100644 --- a/v4l2-spec/dev-rds.sgml +++ b/v4l2-spec/dev-rds.sgml @@ -6,8 +6,8 @@ information, on an inaudible audio subcarrier of a radio program. This interface is aimed at devices capable of receiving and decoding RDS information.</para> - <para>For more information see the core RDS standard <xref linkend="en50067"> -and the RBDS standard <xref linkend="nrsc4">.</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 can also handle RBDS. Only some of the fields @@ -54,9 +54,9 @@ as follows:</para> <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*"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="1*" /> + <colspec colname="c3" colwidth="5*" /> <tbody valign="top"> <row> <entry>__u8</entry> @@ -79,8 +79,8 @@ as follows:</para> <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*"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="5*" /> <tbody valign="top"> <row> <entry>Bits 0-2</entry> @@ -105,9 +105,9 @@ as follows:</para> <table frame="none" pgwide="1" id="v4l2-rds-block-codes"> <title>Block defines</title> <tgroup cols="3"> - <colspec colname="c1" colwidth="1*"> - <colspec colname="c2" colwidth="1*"> - <colspec colname="c3" colwidth="5*"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="1*" /> + <colspec colname="c3" colwidth="5*" /> <tbody valign="top"> <row> <entry>V4L2_RDS_BLOCK_MSK</entry> diff --git a/v4l2-spec/dev-sliced-vbi.sgml b/v4l2-spec/dev-sliced-vbi.sgml index 3c260e3e3..a2cfc45ef 100644 --- a/v4l2-spec/dev-sliced-vbi.sgml +++ b/v4l2-spec/dev-sliced-vbi.sgml @@ -96,12 +96,12 @@ points which may return <errorcode>EBUSY</errorcode> can be the <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"> + <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> @@ -139,9 +139,9 @@ 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 +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> @@ -211,12 +211,12 @@ extensions. Applications and drivers must set it to zero.</entry> <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"> + <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> @@ -231,7 +231,7 @@ extensions. Applications and drivers must set it to zero.</entry> <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext System B)</entry> <entry>0x0001</entry> - <entry><xref linkend="ets300706">, <xref linkend="itu653"></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> @@ -239,7 +239,7 @@ without clock run-in and framing code, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_VPS</constant></entry> <entry>0x0400</entry> - <entry><xref linkend="ets300231"></entry> + <entry><xref linkend="ets300231" /></entry> <entry>PAL line 16</entry> <entry>Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb first transmitted.</entry> @@ -247,7 +247,7 @@ ETS 300 231, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> <entry>0x1000</entry> - <entry><xref linkend="eia608"></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> @@ -255,7 +255,7 @@ bit, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_WSS_625</constant></entry> <entry>0x4000</entry> - <entry><xref linkend="itu1119">, <xref linkend="en300294"></entry> + <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> <entry>PAL/SECAM line 23</entry> <entry><screen> Byte 0 1 @@ -311,7 +311,7 @@ zero.</para> <row> <entry>__u32</entry> <entry><structfield>id</structfield></entry> - <entry>A flag from <xref linkend="vbi-services"> + <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 @@ -334,7 +334,7 @@ field, <constant>1</constant> for the second field.</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 + 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> @@ -349,7 +349,7 @@ Applications and drivers must set it to zero.</entry> <entry>__u8</entry> <entry><structfield>data</structfield>[48]</entry> <entry>The packet payload. See <xref - linkend="vbi-services"> for the contents and number of + 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> @@ -488,7 +488,7 @@ boundary. The payload shall never exceed 1552 bytes (2 fields with <entry><structfield>magic</structfield>[4]</entry> <entry></entry> <entry>A "magic" constant from <xref - linkend="v4l2-mpeg-vbi-fmt-ivtv-magic"> that indicates + 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> @@ -636,7 +636,7 @@ through 23 of the second field.</entry> <entry>__u8</entry> <entry><structfield>id</structfield></entry> <entry>A line identifier value from -<xref linkend="ITV0-Line-Identifier-Constants"> that indicates +<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates the type of sliced VBI data stored on this line.</entry> </row> <row> diff --git a/v4l2-spec/dev-teletext.sgml b/v4l2-spec/dev-teletext.sgml index 26e125c16..59f9993e1 100644 --- a/v4l2-spec/dev-teletext.sgml +++ b/v4l2-spec/dev-teletext.sgml @@ -1,7 +1,7 @@ <title>Teletext Interface</title> <para>This interface aims at devices receiving and demodulating -Teletext data [<xref linkend="ets300706">, <xref linkend="itu653">], evaluating the +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 can be found on older diff --git a/v4l2-spec/fdl-appendix.sgml b/v4l2-spec/fdl-appendix.sgml index f21019ae4..b6ce50dbe 100644 --- a/v4l2-spec/fdl-appendix.sgml +++ b/v4l2-spec/fdl-appendix.sgml @@ -8,7 +8,7 @@ --> <appendix id="fdl"> - <docinfo> + <appendixinfo> <releaseinfo> Version 1.1, March 2000 </releaseinfo> @@ -24,7 +24,7 @@ license document, but changing it is not allowed. </para> </legalnotice> - </docinfo> + </appendixinfo> <title>GNU Free Documentation License</title> <sect1 id="fdl-preamble"> diff --git a/v4l2-spec/func-ioctl.sgml b/v4l2-spec/func-ioctl.sgml index 96dead0ec..00f9690e1 100644 --- a/v4l2-spec/func-ioctl.sgml +++ b/v4l2-spec/func-ioctl.sgml @@ -61,7 +61,7 @@ in the <link linkend="videodev">videodev.h</link> 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> + linkend="user-func" />.</para> </refsect1> <refsect1> @@ -116,7 +116,7 @@ character special device.</para> <para>The <parameter>request</parameter> or the data pointed to by <parameter>argp</parameter> is not valid. This is a very common error code, see the individual ioctl requests listed in <xref - linkend="user-func"> for actual causes.</para> + linkend="user-func" /> for actual causes.</para> </listitem> </varlistentry> <varlistentry> diff --git a/v4l2-spec/func-read.sgml b/v4l2-spec/func-read.sgml index a67a5f507..a5089bf88 100644 --- a/v4l2-spec/func-read.sgml +++ b/v4l2-spec/func-read.sgml @@ -110,7 +110,7 @@ free buffers depends on the discarding policy.</para> 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> + linkend="devices" />.</para> </refsect1> <refsect1> diff --git a/v4l2-spec/io.sgml b/v4l2-spec/io.sgml index 957ffa0bc..f92f24323 100644 --- a/v4l2-spec/io.sgml +++ b/v4l2-spec/io.sgml @@ -17,12 +17,12 @@ 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> +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 +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> @@ -414,7 +414,7 @@ the frames are not properly stamped by the sender. This is frequently the case with USB cameras. Here timestamps refer to the instant the field or frame was received by the driver, not the capture time. These devices identify by not enumerating any video standards, see <xref -linkend="standard">.</para> +linkend="standard" />.</para> <para>Similar limitations apply to output timestamps. Typically the video hardware locks to a clock controlling the video timing, the @@ -472,14 +472,14 @@ refers to an input stream, applications when an output stream.</entry> <entry><structfield>flags</structfield></entry> <entry></entry> <entry>Flags set by the application or driver, see <xref -linkend="buffer-flags">.</entry> +linkend="buffer-flags" />.</entry> </row> <row> <entry>&v4l2-field;</entry> <entry><structfield>field</structfield></entry> <entry></entry> <entry>Indicates the field order of the image in the -buffer, see <xref linkend="v4l2-field">. This field is not used when +buffer, see <xref linkend="v4l2-field" />. This field is not used when the buffer contains VBI data. Drivers must set it when <structfield>type</structfield> refers to an input stream, applications when an output stream.</entry> @@ -534,7 +534,7 @@ time.</para><para>Note this may count the frames received e.g. over USB, without taking into account the frames dropped by the remote hardware due to limited compression throughput or bus bandwidth. These devices identify by not enumerating any video -standards, see <xref linkend="standard">.</para></entry> +standards, see <xref linkend="standard" />.</para></entry> </row> <row> <entry>&v4l2-memory;</entry> @@ -555,7 +555,7 @@ in accordance with the selected I/O method.</entry> <constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer from the start of the device memory. The value is returned by the driver and apart of serving as parameter to the &func-mmap; function -not useful for applications. See <xref linkend="mmap"> for details.</entry> +not useful for applications. See <xref linkend="mmap" /> for details.</entry> </row> <row> <entry></entry> @@ -564,7 +564,7 @@ not useful for applications. See <xref linkend="mmap"> for details.</entry> <entry>When <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the buffer (casted to unsigned long type) in virtual memory, set by the -application. See <xref linkend="userp"> for details.</entry> +application. See <xref linkend="userp" /> for details.</entry> </row> <row> <entry>__u32</entry> @@ -604,48 +604,48 @@ number of a video input as in &v4l2-input; field <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> <entry>1</entry> <entry>Buffer of a video capture stream, see <xref - linkend="capture">.</entry> + linkend="capture" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> <entry>2</entry> <entry>Buffer of a video output stream, see <xref - linkend="output">.</entry> + linkend="output" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> <entry>3</entry> - <entry>Buffer for video overlay, see <xref linkend="overlay">.</entry> + <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> <entry>4</entry> <entry>Buffer of a raw VBI capture stream, see <xref - linkend="raw-vbi">.</entry> + linkend="raw-vbi" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> <entry>5</entry> <entry>Buffer of a raw VBI output stream, see <xref - linkend="raw-vbi">.</entry> + linkend="raw-vbi" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> <entry>6</entry> <entry>Buffer of a sliced VBI capture stream, see <xref - linkend="sliced">.</entry> + linkend="sliced" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> <entry>7</entry> <entry>Buffer of a sliced VBI output stream, see <xref - linkend="sliced">.</entry> + linkend="sliced" />.</entry> </row> <row> <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> <entry>8</entry> <entry>Buffer for video output overlay (OSD), see <xref - linkend="osd">. Status: <link + linkend="osd" />. Status: <link linkend="experimental">Experimental</link>.</entry> </row> <row> @@ -667,7 +667,7 @@ linkend="experimental">Experimental</link>.</entry> <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> <entry>0x0001</entry> <entry>The buffer resides in device memory and has been mapped -into the application's address space, see <xref linkend="mmap"> for details. +into the application's address space, see <xref linkend="mmap" /> for details. Drivers set or clear this flag when the <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link @@ -769,7 +769,7 @@ pointer</link> I/O.</entry> <title>Timecodes</title> <para>The <structname>v4l2_timecode</structname> structure is -designed to hold a <xref linkend="smpte12m"> or similar timecode. +designed to hold a <xref linkend="smpte12m" /> or similar timecode. (struct <structname>timeval</structname> timestamps are stored in &v4l2-buffer; field <structfield>timestamp</structfield>.)</para> @@ -782,12 +782,12 @@ designed to hold a <xref linkend="smpte12m"> or similar timecode. <entry>__u32</entry> <entry><structfield>type</structfield></entry> <entry>Frame rate the timecodes are based on, see <xref - linkend="timecode-type">.</entry> + linkend="timecode-type" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>Timecode flags, see <xref linkend="timecode-flags">.</entry> + <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> </row> <row> <entry>__u8</entry> @@ -1043,10 +1043,10 @@ line, top field first. The bottom field is transmitted first.</entry> <title>Field Order, Top Field First Transmitted</title> <mediaobject> <imageobject> - <imagedata fileref="fieldseq_tb.pdf" format="PS"> + <imagedata fileref="fieldseq_tb.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="fieldseq_tb.gif" format="GIF"> + <imagedata fileref="fieldseq_tb.gif" format="GIF" /> </imageobject> </mediaobject> </figure> @@ -1055,10 +1055,10 @@ line, top field first. The bottom field is transmitted first.</entry> <title>Field Order, Bottom Field First Transmitted</title> <mediaobject> <imageobject> - <imagedata fileref="fieldseq_bt.pdf" format="PS"> + <imagedata fileref="fieldseq_bt.pdf" format="PS" /> </imageobject> <imageobject> - <imagedata fileref="fieldseq_bt.gif" format="GIF"> + <imagedata fileref="fieldseq_bt.gif" format="GIF" /> </imageobject> </mediaobject> </figure> diff --git a/v4l2-spec/libv4l.sgml b/v4l2-spec/libv4l.sgml new file mode 100644 index 000000000..c14fc3db2 --- /dev/null +++ b/v4l2-spec/libv4l.sgml @@ -0,0 +1,167 @@ +<title>Libv4l Userspace Library</title> +<section id="libv4l-introduction"> + <title>Introduction</title> + + <para>libv4l is a collection of libraries which adds a thin abstraction +layer on top of video4linux2 devices. The purpose of this (thin) layer +is to make it easy for application writers to support a wide variety of +devices without having to write separate code for different devices in the +same class.</para> +<para>An example of using libv4l is provided by +<link linkend='v4l2grab-example'>v4l2grab</link>. +</para> + + <para>libv4l consists of 3 different libraries:</para> + <section> + <title>libv4lconvert</title> + + <para>libv4lconvert is a library that converts several +different pixelformats found in V4L2 drivers into a few common RGB and +YUY formats.</para> + <para>It currently accepts the following V4L2 driver formats: +<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, +<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>, +<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>, +<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>, +<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>, +<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>, +<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>, +<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>, +<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>, +<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, +<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>, +<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>, +<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>, +<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>, +<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>, +<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>, +<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>, +<constant>V4L2_PIX_FMT_SRGGB8</constant>, +<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>, +<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, +<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>, +<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, +and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>. +</para> + <para>Later on libv4lconvert was expanded to also be able to do +various video processing functions to improve webcam video quality. +The video processing is split in to 2 parts: libv4lconvert/control and +libv4lconvert/processing.</para> + + <para>The control part is used to offer video controls which can +be used to control the video processing functions made available by + libv4lconvert/processing. These controls are stored application wide +(until reboot) by using a persistent shared memory object.</para> + + <para>libv4lconvert/processing offers the actual video +processing functionality.</para> + </section> + <section> + <title>libv4l1</title> + <para>This library offers functions that can be used to quickly +make v4l1 applications work with v4l2 devices. These functions work exactly +like the normal open/close/etc, except that libv4l1 does full emulation of +the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it +will just pass calls through.</para> + <para>Since those functions are emulations of the old V4L1 API, +it shouldn't be used for new applications.</para> + </section> + <section> + <title>libv4l2</title> + <para>This library should be used for all modern V4L2 +applications.</para> + <para>It provides handles to call V4L2 open/ioctl/close/poll +methods. Instead of just providing the raw output of the device, it enhances +the calls in the sense that it will use libv4lconvert to provide more video +formats and to enhance the image quality.</para> + <para>In most cases, libv4l2 just passes the calls directly +through to the v4l2 driver, intercepting the calls to +<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>, +<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link> +<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link> +<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link> +and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link> +in order to emulate the formats +<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>, +<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>, +<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>, +and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>, +if they aren't available in the driver. +<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link> +keeps enumerating the hardware supported formats, plus the emulated formats +offered by libv4l at the end. +</para> + <section id="libv4l-ops"> + <title>Libv4l device control functions</title> + <para>The common file operation methods are provided by +libv4l.</para> + <para>Those functions operate just like glibc +open/close/dup/ioctl/read/mmap/munmap:</para> +<itemizedlist><listitem> + <para>int v4l2_open(const char *file, int oflag, +...) - +operates like the standard <link linkend='func-open'>open()</link> function. +</para></listitem><listitem> + <para>int v4l2_close(int fd) - +operates like the standard <link linkend='func-close'>close()</link> function. +</para></listitem><listitem> + <para>int v4l2_dup(int fd) - +operates like the standard dup() function, duplicating a file handler. +</para></listitem><listitem> + <para>int v4l2_ioctl (int fd, unsigned long int request, ...) - +operates like the standard <link linkend='func-ioctl'>ioctl()</link> function. +</para></listitem><listitem> + <para>int v4l2_read (int fd, void* buffer, size_t n) - +operates like the standard <link linkend='func-read'>read()</link> function. +</para></listitem><listitem> + <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - +operates like the standard <link linkend='func-mmap'>mmap()</link> function. +</para></listitem><listitem> + <para>int v4l2_munmap(void *_start, size_t length); - +operates like the standard <link linkend='func-munmap'>munmap()</link> function. +</para></listitem> +</itemizedlist> + <para>Those functions provide additional control:</para> +<itemizedlist><listitem> + <para>int v4l2_fd_open(int fd, int v4l2_flags) - +opens an already opened fd for further use through v4l2lib and possibly +modify libv4l2's default behavior through the v4l2_flags argument. +Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>, +to disable format conversion. +</para></listitem><listitem> + <para>int v4l2_set_control(int fd, int cid, int value) - +This function takes a value of 0 - 65535, and then scales that range to +the actual range of the given v4l control id, and then if the cid exists +and is not locked sets the cid to the scaled value. +</para></listitem><listitem> + <para>int v4l2_get_control(int fd, int cid) - +This function returns a value of 0 - 65535, scaled to from the actual range +of the given v4l control id. when the cid does not exist, could not be +accessed for some reason, or some error occured 0 is returned. +</para></listitem> +</itemizedlist> + </section> + </section> + <section> + + <title>v4l1compat.so wrapper library</title> + + <para>This library intercepts calls to +open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l +counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also +emulates V4L1 calls via V4L2 API.</para> + <para>It allows usage of binary legacy applications that +still don't use libv4l.</para> + </section> + +</section> +<!-- +Local Variables: +mode: sgml +sgml-parent-document: "v4l2.sgml" +indent-tabs-mode: nil +End: +--> diff --git a/v4l2-spec/pixfmt-grey.sgml b/v4l2-spec/pixfmt-grey.sgml index 271814c53..3b72bc6b2 100644 --- a/v4l2-spec/pixfmt-grey.sgml +++ b/v4l2-spec/pixfmt-grey.sgml @@ -22,7 +22,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-nv12.sgml b/v4l2-spec/pixfmt-nv12.sgml index ec3aec6a0..873f67035 100644 --- a/v4l2-spec/pixfmt-nv12.sgml +++ b/v4l2-spec/pixfmt-nv12.sgml @@ -39,7 +39,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-nv16.sgml b/v4l2-spec/pixfmt-nv16.sgml index c67ba2ebe..26094035f 100644 --- a/v4l2-spec/pixfmt-nv16.sgml +++ b/v4l2-spec/pixfmt-nv16.sgml @@ -38,7 +38,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-packed-rgb.sgml b/v4l2-spec/pixfmt-packed-rgb.sgml index 8c32db3c2..d2dd697a8 100644 --- a/v4l2-spec/pixfmt-packed-rgb.sgml +++ b/v4l2-spec/pixfmt-packed-rgb.sgml @@ -21,50 +21,50 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <table pgwide="1" frame="none" id="rgb-formats"> <title>Packed RGB Image Formats</title> <tgroup cols="37" align="center"> - <colspec colname="id" align="left"> - <colspec colname="fourcc"> - <colspec colname="bit"> + <colspec colname="id" align="left" /> + <colspec colname="fourcc" /> + <colspec colname="bit" /> - <colspec colnum="4" colname="b07" align="center"> - <colspec colnum="5" colname="b06" align="center"> - <colspec colnum="6" colname="b05" align="center"> - <colspec colnum="7" colname="b04" align="center"> - <colspec colnum="8" colname="b03" align="center"> - <colspec colnum="9" colname="b02" align="center"> - <colspec colnum="10" colname="b01" align="center"> - <colspec colnum="11" colname="b00" align="center"> + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> - <colspec colnum="13" colname="b17" align="center"> - <colspec colnum="14" colname="b16" align="center"> - <colspec colnum="15" colname="b15" align="center"> - <colspec colnum="16" colname="b14" align="center"> - <colspec colnum="17" colname="b13" align="center"> - <colspec colnum="18" colname="b12" align="center"> - <colspec colnum="19" colname="b11" align="center"> - <colspec colnum="20" colname="b10" align="center"> + <colspec colnum="13" colname="b17" align="center" /> + <colspec colnum="14" colname="b16" align="center" /> + <colspec colnum="15" colname="b15" align="center" /> + <colspec colnum="16" colname="b14" align="center" /> + <colspec colnum="17" colname="b13" align="center" /> + <colspec colnum="18" colname="b12" align="center" /> + <colspec colnum="19" colname="b11" align="center" /> + <colspec colnum="20" colname="b10" align="center" /> - <colspec colnum="22" colname="b27" align="center"> - <colspec colnum="23" colname="b26" align="center"> - <colspec colnum="24" colname="b25" align="center"> - <colspec colnum="25" colname="b24" align="center"> - <colspec colnum="26" colname="b23" align="center"> - <colspec colnum="27" colname="b22" align="center"> - <colspec colnum="28" colname="b21" align="center"> - <colspec colnum="29" colname="b20" align="center"> + <colspec colnum="22" colname="b27" align="center" /> + <colspec colnum="23" colname="b26" align="center" /> + <colspec colnum="24" colname="b25" align="center" /> + <colspec colnum="25" colname="b24" align="center" /> + <colspec colnum="26" colname="b23" align="center" /> + <colspec colnum="27" colname="b22" align="center" /> + <colspec colnum="28" colname="b21" align="center" /> + <colspec colnum="29" colname="b20" align="center" /> - <colspec colnum="31" colname="b37" align="center"> - <colspec colnum="32" colname="b36" align="center"> - <colspec colnum="33" colname="b35" align="center"> - <colspec colnum="34" colname="b34" align="center"> - <colspec colnum="35" colname="b33" align="center"> - <colspec colnum="36" colname="b32" align="center"> - <colspec colnum="37" colname="b31" align="center"> - <colspec colnum="38" colname="b30" align="center"> + <colspec colnum="31" colname="b37" align="center" /> + <colspec colnum="32" colname="b36" align="center" /> + <colspec colnum="33" colname="b35" align="center" /> + <colspec colnum="34" colname="b34" align="center" /> + <colspec colnum="35" colname="b33" align="center" /> + <colspec colnum="36" colname="b32" align="center" /> + <colspec colnum="37" colname="b31" align="center" /> + <colspec colnum="38" colname="b30" align="center" /> - <spanspec namest="b07" nameend="b00" spanname="b0"> - <spanspec namest="b17" nameend="b10" spanname="b1"> - <spanspec namest="b27" nameend="b20" spanname="b2"> - <spanspec namest="b37" nameend="b30" spanname="b3"> + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <spanspec namest="b17" nameend="b10" spanname="b1" /> + <spanspec namest="b27" nameend="b20" spanname="b2" /> + <spanspec namest="b37" nameend="b30" spanname="b3" /> <thead> <row> <entry>Identifier</entry> @@ -401,7 +401,7 @@ image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="13" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> @@ -476,55 +476,55 @@ image</title> <para>Some RGB formats above are uncommon and were probably defined in error. Drivers may interpret them as in <xref - linkend="rgb-formats-corrected">.</para> + linkend="rgb-formats-corrected" />.</para> <table pgwide="1" frame="none" id="rgb-formats-corrected"> <title>Packed RGB Image Formats (corrected)</title> <tgroup cols="37" align="center"> - <colspec colname="id" align="left"> - <colspec colname="fourcc"> - <colspec colname="bit"> + <colspec colname="id" align="left" /> + <colspec colname="fourcc" /> + <colspec colname="bit" /> - <colspec colnum="4" colname="b07" align="center"> - <colspec colnum="5" colname="b06" align="center"> - <colspec colnum="6" colname="b05" align="center"> - <colspec colnum="7" colname="b04" align="center"> - <colspec colnum="8" colname="b03" align="center"> - <colspec colnum="9" colname="b02" align="center"> - <colspec colnum="10" colname="b01" align="center"> - <colspec colnum="11" colname="b00" align="center"> + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> - <colspec colnum="13" colname="b17" align="center"> - <colspec colnum="14" colname="b16" align="center"> - <colspec colnum="15" colname="b15" align="center"> - <colspec colnum="16" colname="b14" align="center"> - <colspec colnum="17" colname="b13" align="center"> - <colspec colnum="18" colname="b12" align="center"> - <colspec colnum="19" colname="b11" align="center"> - <colspec colnum="20" colname="b10" align="center"> + <colspec colnum="13" colname="b17" align="center" /> + <colspec colnum="14" colname="b16" align="center" /> + <colspec colnum="15" colname="b15" align="center" /> + <colspec colnum="16" colname="b14" align="center" /> + <colspec colnum="17" colname="b13" align="center" /> + <colspec colnum="18" colname="b12" align="center" /> + <colspec colnum="19" colname="b11" align="center" /> + <colspec colnum="20" colname="b10" align="center" /> - <colspec colnum="22" colname="b27" align="center"> - <colspec colnum="23" colname="b26" align="center"> - <colspec colnum="24" colname="b25" align="center"> - <colspec colnum="25" colname="b24" align="center"> - <colspec colnum="26" colname="b23" align="center"> - <colspec colnum="27" colname="b22" align="center"> - <colspec colnum="28" colname="b21" align="center"> - <colspec colnum="29" colname="b20" align="center"> + <colspec colnum="22" colname="b27" align="center" /> + <colspec colnum="23" colname="b26" align="center" /> + <colspec colnum="24" colname="b25" align="center" /> + <colspec colnum="25" colname="b24" align="center" /> + <colspec colnum="26" colname="b23" align="center" /> + <colspec colnum="27" colname="b22" align="center" /> + <colspec colnum="28" colname="b21" align="center" /> + <colspec colnum="29" colname="b20" align="center" /> - <colspec colnum="31" colname="b37" align="center"> - <colspec colnum="32" colname="b36" align="center"> - <colspec colnum="33" colname="b35" align="center"> - <colspec colnum="34" colname="b34" align="center"> - <colspec colnum="35" colname="b33" align="center"> - <colspec colnum="36" colname="b32" align="center"> - <colspec colnum="37" colname="b31" align="center"> - <colspec colnum="38" colname="b30" align="center"> + <colspec colnum="31" colname="b37" align="center" /> + <colspec colnum="32" colname="b36" align="center" /> + <colspec colnum="33" colname="b35" align="center" /> + <colspec colnum="34" colname="b34" align="center" /> + <colspec colnum="35" colname="b33" align="center" /> + <colspec colnum="36" colname="b32" align="center" /> + <colspec colnum="37" colname="b31" align="center" /> + <colspec colnum="38" colname="b30" align="center" /> - <spanspec namest="b07" nameend="b00" spanname="b0"> - <spanspec namest="b17" nameend="b10" spanname="b1"> - <spanspec namest="b27" nameend="b20" spanname="b2"> - <spanspec namest="b37" nameend="b30" spanname="b3"> + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <spanspec namest="b17" nameend="b10" spanname="b1" /> + <spanspec namest="b27" nameend="b20" spanname="b2" /> + <spanspec namest="b37" nameend="b30" spanname="b3" /> <thead> <row> <entry>Identifier</entry> diff --git a/v4l2-spec/pixfmt-packed-yuv.sgml b/v4l2-spec/pixfmt-packed-yuv.sgml index 7ad8d924a..3cab5d0ca 100644 --- a/v4l2-spec/pixfmt-packed-yuv.sgml +++ b/v4l2-spec/pixfmt-packed-yuv.sgml @@ -17,50 +17,50 @@ word.</para> <table pgwide="1" frame="none"> <title>Packed YUV Image Formats</title> <tgroup cols="37" align="center"> - <colspec colname="id" align="left"> - <colspec colname="fourcc"> - <colspec colname="bit"> + <colspec colname="id" align="left" /> + <colspec colname="fourcc" /> + <colspec colname="bit" /> - <colspec colnum="4" colname="b07" align="center"> - <colspec colnum="5" colname="b06" align="center"> - <colspec colnum="6" colname="b05" align="center"> - <colspec colnum="7" colname="b04" align="center"> - <colspec colnum="8" colname="b03" align="center"> - <colspec colnum="9" colname="b02" align="center"> - <colspec colnum="10" colname="b01" align="center"> - <colspec colnum="11" colname="b00" align="center"> + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> - <colspec colnum="13" colname="b17" align="center"> - <colspec colnum="14" colname="b16" align="center"> - <colspec colnum="15" colname="b15" align="center"> - <colspec colnum="16" colname="b14" align="center"> - <colspec colnum="17" colname="b13" align="center"> - <colspec colnum="18" colname="b12" align="center"> - <colspec colnum="19" colname="b11" align="center"> - <colspec colnum="20" colname="b10" align="center"> + <colspec colnum="13" colname="b17" align="center" /> + <colspec colnum="14" colname="b16" align="center" /> + <colspec colnum="15" colname="b15" align="center" /> + <colspec colnum="16" colname="b14" align="center" /> + <colspec colnum="17" colname="b13" align="center" /> + <colspec colnum="18" colname="b12" align="center" /> + <colspec colnum="19" colname="b11" align="center" /> + <colspec colnum="20" colname="b10" align="center" /> - <colspec colnum="22" colname="b27" align="center"> - <colspec colnum="23" colname="b26" align="center"> - <colspec colnum="24" colname="b25" align="center"> - <colspec colnum="25" colname="b24" align="center"> - <colspec colnum="26" colname="b23" align="center"> - <colspec colnum="27" colname="b22" align="center"> - <colspec colnum="28" colname="b21" align="center"> - <colspec colnum="29" colname="b20" align="center"> + <colspec colnum="22" colname="b27" align="center" /> + <colspec colnum="23" colname="b26" align="center" /> + <colspec colnum="24" colname="b25" align="center" /> + <colspec colnum="25" colname="b24" align="center" /> + <colspec colnum="26" colname="b23" align="center" /> + <colspec colnum="27" colname="b22" align="center" /> + <colspec colnum="28" colname="b21" align="center" /> + <colspec colnum="29" colname="b20" align="center" /> - <colspec colnum="31" colname="b37" align="center"> - <colspec colnum="32" colname="b36" align="center"> - <colspec colnum="33" colname="b35" align="center"> - <colspec colnum="34" colname="b34" align="center"> - <colspec colnum="35" colname="b33" align="center"> - <colspec colnum="36" colname="b32" align="center"> - <colspec colnum="37" colname="b31" align="center"> - <colspec colnum="38" colname="b30" align="center"> + <colspec colnum="31" colname="b37" align="center" /> + <colspec colnum="32" colname="b36" align="center" /> + <colspec colnum="33" colname="b35" align="center" /> + <colspec colnum="34" colname="b34" align="center" /> + <colspec colnum="35" colname="b33" align="center" /> + <colspec colnum="36" colname="b32" align="center" /> + <colspec colnum="37" colname="b31" align="center" /> + <colspec colnum="38" colname="b30" align="center" /> - <spanspec namest="b07" nameend="b00" spanname="b0"> - <spanspec namest="b17" nameend="b10" spanname="b1"> - <spanspec namest="b27" nameend="b20" spanname="b2"> - <spanspec namest="b37" nameend="b30" spanname="b3"> + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <spanspec namest="b17" nameend="b10" spanname="b1" /> + <spanspec namest="b27" nameend="b20" spanname="b2" /> + <spanspec namest="b37" nameend="b30" spanname="b3" /> <thead> <row> <entry>Identifier</entry> diff --git a/v4l2-spec/pixfmt-sbggr16.sgml b/v4l2-spec/pixfmt-sbggr16.sgml index 275489596..519a9efba 100644 --- a/v4l2-spec/pixfmt-sbggr16.sgml +++ b/v4l2-spec/pixfmt-sbggr16.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-sbggr8.sgml b/v4l2-spec/pixfmt-sbggr8.sgml index 37805fe11..5fe84ecc2 100644 --- a/v4l2-spec/pixfmt-sbggr8.sgml +++ b/v4l2-spec/pixfmt-sbggr8.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-sgbrg8.sgml b/v4l2-spec/pixfmt-sgbrg8.sgml index 7b148b636..d67a472b0 100644 --- a/v4l2-spec/pixfmt-sgbrg8.sgml +++ b/v4l2-spec/pixfmt-sgbrg8.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-sgrbg8.sgml b/v4l2-spec/pixfmt-sgrbg8.sgml index 553c5264a..0cdf13b8a 100644 --- a/v4l2-spec/pixfmt-sgrbg8.sgml +++ b/v4l2-spec/pixfmt-sgrbg8.sgml @@ -27,7 +27,7 @@ columns and rows.</para> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-uyvy.sgml b/v4l2-spec/pixfmt-uyvy.sgml index 4c33e06cc..816c8d467 100644 --- a/v4l2-spec/pixfmt-uyvy.sgml +++ b/v4l2-spec/pixfmt-uyvy.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-vyuy.sgml b/v4l2-spec/pixfmt-vyuy.sgml index 61a789fcf..61f12a5e6 100644 --- a/v4l2-spec/pixfmt-vyuy.sgml +++ b/v4l2-spec/pixfmt-vyuy.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-y16.sgml b/v4l2-spec/pixfmt-y16.sgml index 98a550b19..d58404015 100644 --- a/v4l2-spec/pixfmt-y16.sgml +++ b/v4l2-spec/pixfmt-y16.sgml @@ -25,7 +25,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-y41p.sgml b/v4l2-spec/pixfmt-y41p.sgml index c18aae440..73c8536ef 100644 --- a/v4l2-spec/pixfmt-y41p.sgml +++ b/v4l2-spec/pixfmt-y41p.sgml @@ -31,7 +31,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="13" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yuv410.sgml b/v4l2-spec/pixfmt-yuv410.sgml index fb989204c..8eb4a193d 100644 --- a/v4l2-spec/pixfmt-yuv410.sgml +++ b/v4l2-spec/pixfmt-yuv410.sgml @@ -37,7 +37,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yuv411p.sgml b/v4l2-spec/pixfmt-yuv411p.sgml index 8de4e8c94..00e0960a9 100644 --- a/v4l2-spec/pixfmt-yuv411p.sgml +++ b/v4l2-spec/pixfmt-yuv411p.sgml @@ -38,7 +38,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yuv420.sgml b/v4l2-spec/pixfmt-yuv420.sgml index 0b0b57cd5..42d7de5e4 100644 --- a/v4l2-spec/pixfmt-yuv420.sgml +++ b/v4l2-spec/pixfmt-yuv420.sgml @@ -39,7 +39,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yuv422p.sgml b/v4l2-spec/pixfmt-yuv422p.sgml index 5a295eb0d..4348bd9f0 100644 --- a/v4l2-spec/pixfmt-yuv422p.sgml +++ b/v4l2-spec/pixfmt-yuv422p.sgml @@ -36,7 +36,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="5" align="center"> - <colspec align="left" colwidth="2*"> + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yuyv.sgml b/v4l2-spec/pixfmt-yuyv.sgml index 4f083b3be..bdb2ffacb 100644 --- a/v4l2-spec/pixfmt-yuyv.sgml +++ b/v4l2-spec/pixfmt-yuyv.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt-yvyu.sgml b/v4l2-spec/pixfmt-yvyu.sgml index 734688fef..40d17ae39 100644 --- a/v4l2-spec/pixfmt-yvyu.sgml +++ b/v4l2-spec/pixfmt-yvyu.sgml @@ -27,7 +27,7 @@ pixel image</title> <para>Each cell is one byte. <informaltable frame="none"> <tgroup cols="9" align="center"> - <colspec align="left" colwidth="2*" + <colspec align="left" colwidth="2*" /> <tbody valign="top"> <row> <entry>start + 0:</entry> diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml index 9e6bebeb4..aaea55d44 100644 --- a/v4l2-spec/pixfmt.sgml +++ b/v4l2-spec/pixfmt.sgml @@ -39,9 +39,9 @@ format is YUV 4:2:0, <structfield>width</structfield> and <entry>The pixel format or type of compression, set by the application. This is a little endian <link linkend="v4l2-fourcc">four character code</link>. V4L2 defines -standard RGB formats in <xref linkend="rgb-formats">, YUV formats in <xref -linkend="yuv-formats">, and reserved codes in <xref -linkend="reserved-formats"></entry> +standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref +linkend="yuv-formats" />, and reserved codes in <xref +linkend="reserved-formats" /></entry> </row> <row> <entry>&v4l2-field;</entry> @@ -50,7 +50,7 @@ linkend="reserved-formats"></entry> can request to capture or output only the top or bottom field, or both fields interlaced or sequentially stored in one buffer or alternating in separate buffers. Drivers return the actual field order selected. -For details see <xref linkend="field-order">.</entry> +For details see <xref linkend="field-order" />.</entry> </row> <row> <entry>__u32</entry> @@ -94,7 +94,7 @@ hold an image.</entry> <entry><structfield>colorspace</structfield></entry> <entry>This information supplements the <structfield>pixelformat</structfield> and must be set by the driver, -see <xref linkend="colorspaces">.</entry> +see <xref linkend="colorspaces" />.</entry> </row> <row> <entry>__u32</entry> @@ -304,20 +304,20 @@ EB = clamp (b * 255); <table pgwide="1" id="v4l2-colorspace" orient="land"> <title>enum v4l2_colorspace</title> <tgroup cols="11" align="center"> - <colspec align="left"> - <colspec align="center"> - <colspec align="left"> - <colspec colname="cr"> - <colspec colname="cg"> - <colspec colname="cb"> - <colspec colname="wp"> - <colspec colname="gc"> - <colspec colname="lum"> - <colspec colname="qy"> - <colspec colname="qc"> - <spanspec namest="cr" nameend="cb" spanname="chrom"> - <spanspec namest="qy" nameend="qc" spanname="quant"> - <spanspec namest="lum" nameend="qc" spanname="spam"> + <colspec align="left" /> + <colspec align="center" /> + <colspec align="left" /> + <colspec colname="cr" /> + <colspec colname="cg" /> + <colspec colname="cb" /> + <colspec colname="wp" /> + <colspec colname="gc" /> + <colspec colname="lum" /> + <colspec colname="qy" /> + <colspec colname="qc" /> + <spanspec namest="cr" nameend="cb" spanname="chrom" /> + <spanspec namest="qy" nameend="qc" spanname="quant" /> + <spanspec namest="lum" nameend="qc" spanname="spam" /> <thead> <row> <entry morerows="1">Identifier</entry> @@ -344,8 +344,8 @@ given in the CIE system (1931)</para> <row> <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> <entry>1</entry> - <entry>NTSC/PAL according to <xref linkend="smpte170m">, -<xref linkend="itu601"></entry> + <entry>NTSC/PAL according to <xref linkend="smpte170m" />, +<xref linkend="itu601" /></entry> <entry>x = 0.630, y = 0.340</entry> <entry>x = 0.310, y = 0.595</entry> <entry>x = 0.155, y = 0.070</entry> @@ -363,7 +363,7 @@ given in the CIE system (1931)</para> <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> <entry>2</entry> <entry>1125-Line (US) HDTV, see <xref -linkend="smpte240m"></entry> +linkend="smpte240m" /></entry> <entry>x = 0.630, y = 0.340</entry> <entry>x = 0.310, y = 0.595</entry> <entry>x = 0.155, y = 0.070</entry> @@ -381,7 +381,7 @@ linkend="smpte240m"></entry> <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> <entry>3</entry> <entry>HDTV and modern devices, see <xref -linkend="itu709"></entry> +linkend="itu709" /></entry> <entry>x = 0.640, y = 0.330</entry> <entry>x = 0.300, y = 0.600</entry> <entry>x = 0.150, y = 0.060</entry> @@ -404,7 +404,7 @@ quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … 235. This is not a typo in the Bt878 documentation, it has been implemented in silicon. The chroma extents are unclear.</para> - </footnote>, <xref linkend="itu601"></entry> + </footnote>, <xref linkend="itu601" /></entry> <entry>?</entry> <entry>?</entry> <entry>?</entry> @@ -423,8 +423,8 @@ implemented in silicon. The chroma extents are unclear.</para> <para>No identifier exists for M/PAL which uses the chromaticities of M/NTSC, the remaining parameters are equal to B and G/PAL.</para> - </footnote> according to <xref linkend="itu470">, <xref - linkend="itu601"></entry> + </footnote> according to <xref linkend="itu470" />, <xref + linkend="itu601" /></entry> <entry>x = 0.67, y = 0.33</entry> <entry>x = 0.21, y = 0.71</entry> <entry>x = 0.14, y = 0.08</entry> @@ -440,7 +440,7 @@ G/PAL.</para> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> <entry>6</entry> <entry>625-line PAL and SECAM systems according to <xref -linkend="itu470">, <xref linkend="itu601"></entry> +linkend="itu470" />, <xref linkend="itu601" /></entry> <entry>x = 0.64, y = 0.33</entry> <entry>x = 0.29, y = 0.60</entry> <entry>x = 0.15, y = 0.06</entry> @@ -456,7 +456,7 @@ Illuminant D<subscript>65</subscript></entry> <row> <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> <entry>7</entry> - <entry>JPEG Y'CbCr, see <xref linkend="jfif">, <xref linkend="itu601"></entry> + <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> <entry>?</entry> <entry>?</entry> <entry>?</entry> @@ -502,23 +502,23 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< <table pgwide="0" frame="none"> <title>Indexed Image Format</title> <tgroup cols="37" align="center"> - <colspec colname="id" align="left"> - <colspec colname="fourcc"> - <colspec colname="bit"> - - <colspec colnum="4" colname="b07" align="center"> - <colspec colnum="5" colname="b06" align="center"> - <colspec colnum="6" colname="b05" align="center"> - <colspec colnum="7" colname="b04" align="center"> - <colspec colnum="8" colname="b03" align="center"> - <colspec colnum="9" colname="b02" align="center"> - <colspec colnum="10" colname="b01" align="center"> - <colspec colnum="11" colname="b00" align="center"> - - <spanspec namest="b07" nameend="b00" spanname="b0"> - <spanspec namest="b17" nameend="b10" spanname="b1"> - <spanspec namest="b27" nameend="b20" spanname="b2"> - <spanspec namest="b37" nameend="b30" spanname="b3"> + <colspec colname="id" align="left" /> + <colspec colname="fourcc" /> + <colspec colname="bit" /> + + <colspec colnum="4" colname="b07" align="center" /> + <colspec colnum="5" colname="b06" align="center" /> + <colspec colnum="6" colname="b05" align="center" /> + <colspec colnum="7" colname="b04" align="center" /> + <colspec colnum="8" colname="b03" align="center" /> + <colspec colnum="9" colname="b02" align="center" /> + <colspec colnum="10" colname="b01" align="center" /> + <colspec colnum="11" colname="b00" align="center" /> + + <spanspec namest="b07" nameend="b00" spanname="b0" /> + <spanspec namest="b17" nameend="b10" spanname="b1" /> + <spanspec namest="b27" nameend="b20" spanname="b2" /> + <spanspec namest="b37" nameend="b30" spanname="b3" /> <thead> <row> <entry>Identifier</entry> @@ -565,7 +565,7 @@ access the palette, this must be done with ioctls of the Linux framebuffer API.< &sub-packed-rgb; &sub-sbggr8; &sub-sgbrg8; - &sub-sgrbg8 + &sub-sgrbg8; &sub-sbggr16; </section> @@ -577,7 +577,7 @@ signals. It separates the brightness information (Y) from the color information (U and V or Cb and Cr). The color information consists of red and blue <emphasis>color difference</emphasis> signals, this way the green component can be reconstructed by subtracting from the -brightness component. See <xref linkend="colorspaces"> for conversion +brightness component. See <xref linkend="colorspaces" /> for conversion examples. YUV was chosen because early television would only transmit brightness information. To add color in a way compatible with existing receivers a new signal carrier was added to transmit the color @@ -629,7 +629,7 @@ information.</para> <entry>'MPEG'</entry> <entry>MPEG stream. The actual format is determined by extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see -<xref linkend="mpeg-control-id">.</entry> +<xref linkend="mpeg-control-id" />.</entry> </row> </tbody> </tgroup> diff --git a/v4l2-spec/remote_controllers.sgml b/v4l2-spec/remote_controllers.sgml new file mode 100644 index 000000000..eb669537a --- /dev/null +++ b/v4l2-spec/remote_controllers.sgml @@ -0,0 +1,170 @@ +<title>Remote Controllers</title> +<section id="Remote_controllers_Intro"> +<title>Introduction</title> + +<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each manufacturer has their own type of control. It is not rare that the same manufacturer to ship different types of controls, depending on the device.</para> +<para>Unfortunately, during several years, there weren't any effort to uniform the IR keycodes under different boards. This resulted that the same IR keyname to be mapped completely different on different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para> +<para>This standard should be used by both V4L/DVB drivers and userspace applications</para> +<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para> + +<table pgwide="1" frame="none" id="rc_standard_keymap"> +<title>IR default keymapping</title> +<tgroup cols="3"> +&cs-str; +<tbody valign="top"> +<row> +<entry>Key code</entry> +<entry>Meaning</entry> +<entry>Key examples on IR</entry> +</row> + +<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row> + +<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row> +<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row> +<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row> +<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row> +<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row> +<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row> +<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row> +<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row> +<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row> +<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row> + +<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row> + +<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>>> / FORWARD</entry></row> +<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry><<< / BACK</entry></row> +<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>>>> / FORWARD</entry></row> +<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row> +<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row> +<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry><< / PREV / PREVIOUS</entry></row> +<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row> +<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row> +<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / ></entry></row> +<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row> +<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row> +<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row> +<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row> +<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row> +<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row> +<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row> +<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row> + +<row><entry><emphasis role="bold">Image control</emphasis></entry></row> + +<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row> +<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row> + +<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row> +<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row> +<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row> + +<row><entry><emphasis role="bold">Audio control</emphasis></entry></row> + +<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row> +<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row> +<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row> +<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row> +<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row> +<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row> + +<row><entry><emphasis role="bold">Channel control</emphasis></entry></row> + +<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row> +<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row> +<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row> +<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row> +<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row> + +<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row> + +<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row> +<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row> +<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row> +<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row> + +<row><entry><emphasis role="bold">Media selection</emphasis></entry></row> + +<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row> +<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row> +<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-> ) / CLOSE / OPEN</entry></row> + +<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row> +<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row> +<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row> +<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row> +<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row> +<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row> +<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row> + +<row><entry><emphasis role="bold">Power control</emphasis></entry></row> + +<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row> +<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row> +<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row> +<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row> + +<row><entry><emphasis role="bold">Window control</emphasis></entry></row> + +<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row> +<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row> +<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row> +<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row> +<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row> +<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row> +<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row> +<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row> + +<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row> + +<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row> +<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row> +<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row> +<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row> +<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row> +<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row> +<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row> +<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row> +<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row> + +<row><entry><emphasis role="bold">Miscelaneous keys</emphasis></entry></row> + +<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row> +<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row> + +</tbody> +</tgroup> +</table> + +<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para> + +<table pgwide="1" frame="none" id="rc_keymap_notes"> +<title>Notes</title> +<tgroup cols="1"> +&cs-str; +<tbody valign="top"> +<row> +<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry> +</row><row> +<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry> +</row><row> +<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry> +</row><row> +<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry> +</row> +</tbody> +</tgroup> +</table> + +</section> + +<section id="Remote_controllers_table_change"> +<title>Changing default Remote Controller mappings</title> +<para>The event interface provides two ioctls to be used against +the /dev/input/event device, to allow changing the default +keymapping.</para> + +<para>This program demonstrates how to replace the keymap tables.</para> +&sub-keytable-c; +</section> diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index bae7eb441..d4c13e51f 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -1,6 +1,7 @@ -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ -<!ENTITY % entities SYSTEM "entities.sgml"> %entities; -<!ENTITY indices SYSTEM "indices.sgml"> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "./entities.sgml"> %entities; +<!ENTITY indices SYSTEM "./indices.sgml"> <!ENTITY eg "e. g."> <!ENTITY ie "i. e."> @@ -10,9 +11,9 @@ <!ENTITY manvol "<manvolnum>2</manvolnum>"> <!-- Table templates: structs, structs w/union, defines. --> -<!ENTITY cs-str "<colspec colname='c1' colwidth='1*'><colspec colname='c2' colwidth='1*'><colspec colname='c3' colwidth='2*'><spanspec spanname='hspan' namest='c1' nameend='c3'>"> -<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*'><colspec colname='c2' colwidth='1*'><colspec colname='c3' colwidth='1*'><colspec colname='c4' colwidth='2*'><spanspec spanname='hspan' namest='c1' nameend='c4'>"> -<!ENTITY cs-def "<colspec colname='c1' colwidth='3*'><colspec colname='c2' colwidth='1*'><colspec colname='c3' colwidth='4*'><spanspec spanname='hspan' namest='c1' nameend='c3'>"> +<!ENTITY cs-str "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> +<!ENTITY cs-ustr "<colspec colname='c1' colwidth='1*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='1*' /><colspec colname='c4' colwidth='2*' /><spanspec spanname='hspan' namest='c1' nameend='c4' />"> +<!ENTITY cs-def "<colspec colname='c1' colwidth='3*' /><colspec colname='c2' colwidth='1*' /><colspec colname='c3' colwidth='4*' /><spanspec spanname='hspan' namest='c1' nameend='c3' />"> <!-- Video for Linux mailing list address. --> <!ENTITY v4l-ml "<ulink url='http://www.linuxtv.org/lists.php'>http://www.linuxtv.org/lists.php</ulink>"> @@ -25,7 +26,7 @@ <book id="v4l2spec"> <bookinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 0.26</subtitle> + <subtitle>Revision 2.6.32</subtitle> <authorgroup> <author> @@ -90,6 +91,19 @@ MPEG stream embedded, sliced VBI data format in this specification. </address> </affiliation> </author> + + <author> + <firstname>Mauro</firstname> + <surname>Carvalho Chehab</surname> + <contrib>Documented libv4l, designed and added v4l2grab example, +Remote Controller chapter + </contrib> + <affiliation> + <address> + <email>mchehab@redhat.com</email> + </address> + </affiliation> + </author> </authorgroup> <copyright> @@ -105,12 +119,13 @@ MPEG stream embedded, sliced VBI data format in this specification. <year>2008</year> <year>2009</year> <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls</holder> +Rubli, Andy Walls, Mauro Carvalho Chehab</holder> </copyright> <legalnotice> <para>This document is copyrighted © 1999-2009 by Bill -Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, and Andy Walls.</para> +Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls and +Mauro Carvalho Chehab.</para> <para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, @@ -131,11 +146,42 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>2.6.32</revnumber> + <date>2009-08-31</date> + <authorinitials>mcc</authorinitials> + <revremark>Now, revisions will match the kernel version where +the V4L2 API changes will be used by the Linux Kernel. +Also added Remote Controller chapter.</revremark> + </revision> + + <revision> + <revnumber>0.29</revnumber> + <date>2009-08-26</date> + <authorinitials>ev</authorinitials> + <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark> + </revision> + + <revision> + <revnumber>0.28</revnumber> + <date>2009-08-26</date> + <authorinitials>gl</authorinitials> + <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark> + </revision> + + <revision> + <revnumber>0.27</revnumber> + <date>2009-08-15</date> + <authorinitials>mcc</authorinitials> + <revremark>Added libv4l and Remote Controller documentation; +added v4l2grab and keytable application examples.</revremark> + </revision> + + <revision> <revnumber>0.26</revnumber> - <date>2009-06-15</date> + <date>2009-07-23</date> <authorinitials>hv</authorinitials> <revremark>Finalized the RDS capture API. Added modulator and RDS encoder -capabilities.</revremark> +capabilities. Added support for string controls.</revremark> </revision> <revision> @@ -471,6 +517,14 @@ available here: <ulink url="http://linuxtv.org/downloads/video4linux/API/V4L2_AP &sub-driver; </chapter> + <chapter id="libv4l"> + &sub-libv4l; + </chapter> + + <chapter id="remote_controllers"> + &sub-remote_controllers; + </chapter> + <chapter id="compat"> &sub-compat; </chapter> @@ -485,6 +539,14 @@ available here: <ulink url="http://linuxtv.org/downloads/video4linux/API/V4L2_AP &sub-capture-c; </appendix> + <appendix id="v4l2grab-example"> + <title>Video Grabber example using libv4l</title> + <para>This program demonstrates how to grab V4L2 images in ppm format by +using libv4l handlers. The advantage is that this grabber can potentially work +with any V4L2 driver.</para> + &sub-v4l2grab-c; + </appendix> + &sub-fdl-appendix; &sub-indices; diff --git a/v4l2-spec/vidioc-cropcap.sgml b/v4l2-spec/vidioc-cropcap.sgml index 49bb9855b..816e90e28 100644 --- a/v4l2-spec/vidioc-cropcap.sgml +++ b/v4l2-spec/vidioc-cropcap.sgml @@ -104,7 +104,7 @@ frequency and the frequency required to get square pixels.</para><para>When cropping coordinates refer to square pixels, the driver sets <structfield>pixelaspect</structfield> to 1/1. Other common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled -according to [<xref linkend="itu601">].</para></entry> +according to [<xref linkend="itu601" />].</para></entry> </row> </tbody> </tgroup> diff --git a/v4l2-spec/vidioc-dbg-g-chip-ident.sgml b/v4l2-spec/vidioc-dbg-g-chip-ident.sgml index 84c704e61..4a09e203a 100644 --- a/v4l2-spec/vidioc-dbg-g-chip-ident.sgml +++ b/v4l2-spec/vidioc-dbg-g-chip-ident.sgml @@ -141,7 +141,7 @@ access instructions.</para> <row> <entry>__u32</entry> <entry><structfield>type</structfield></entry> - <entry>See <xref linkend="ident-chip-match-types"> for a list of + <entry>See <xref linkend="ident-chip-match-types" /> for a list of possible types.</entry> </row> <row> @@ -174,14 +174,14 @@ to the <structfield>type</structfield> field.</entry> <row> <entry>struct v4l2_dbg_match</entry> <entry><structfield>match</structfield></entry> - <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match">.</entry> + <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>ident</structfield></entry> <entry>A chip identifier as defined in the Linux <filename>media/v4l2-chip-ident.h</filename> header file, or one of -the values from <xref linkend="chip-ids">.</entry> +the values from <xref linkend="chip-ids" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-dbg-g-register.sgml b/v4l2-spec/vidioc-dbg-g-register.sgml index de8aacc3f..980c7f3e2 100644 --- a/v4l2-spec/vidioc-dbg-g-register.sgml +++ b/v4l2-spec/vidioc-dbg-g-register.sgml @@ -156,7 +156,7 @@ access instructions.</para> <row> <entry>__u32</entry> <entry><structfield>type</structfield></entry> - <entry>See <xref linkend="ident-chip-match-types"> for a list of + <entry>See <xref linkend="ident-chip-match-types" /> for a list of possible types.</entry> </row> <row> @@ -185,14 +185,14 @@ to the <structfield>type</structfield> field.</entry> <table pgwide="1" frame="none" id="v4l2-dbg-register"> <title>struct <structname>v4l2_dbg_register</structname></title> <tgroup cols="4"> - <colspec colname="c1"> - <colspec colname="c2"> - <colspec colname="c4"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c4" /> <tbody valign="top"> <row> <entry>struct v4l2_dbg_match</entry> <entry><structfield>match</structfield></entry> - <entry>How to match the chip, see <xref linkend="v4l2-dbg-match">.</entry> + <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry> </row> <row> <entry>__u64</entry> diff --git a/v4l2-spec/vidioc-encoder-cmd.sgml b/v4l2-spec/vidioc-encoder-cmd.sgml index 144b61c66..b0dde9438 100644 --- a/v4l2-spec/vidioc-encoder-cmd.sgml +++ b/v4l2-spec/vidioc-encoder-cmd.sgml @@ -95,13 +95,13 @@ them. They were introduced in Linux 2.6.21.</para> <row> <entry>__u32</entry> <entry><structfield>cmd</structfield></entry> - <entry>The encoder command, see <xref linkend="encoder-cmds">.</entry> + <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Flags to go with the command, see <xref - linkend="encoder-flags">. If no flags are defined for + linkend="encoder-flags" />. If no flags are defined for this command, drivers and applications must set this field to zero.</entry> </row> diff --git a/v4l2-spec/vidioc-enum-fmt.sgml b/v4l2-spec/vidioc-enum-fmt.sgml index 73af15640..960d44615 100644 --- a/v4l2-spec/vidioc-enum-fmt.sgml +++ b/v4l2-spec/vidioc-enum-fmt.sgml @@ -84,7 +84,7 @@ and higher.</entry> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>See <xref linkend="fmtdesc-flags"></entry> + <entry>See <xref linkend="fmtdesc-flags" /></entry> </row> <row> <entry>__u8</entry> @@ -104,7 +104,7 @@ macro:</entry> <entry spanname="hspan"><para><programlisting id="v4l2-fourcc"> #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24)) </programlisting></para><para>Several image formats are already -defined by this specification in <xref linkend="pixfmt">. Note these +defined by this specification in <xref linkend="pixfmt" />. Note these codes are not the same as those used in the Windows world.</para></entry> </row> <row> diff --git a/v4l2-spec/vidioc-enum-frameintervals.sgml b/v4l2-spec/vidioc-enum-frameintervals.sgml index fa0ac3616..3c216e113 100644 --- a/v4l2-spec/vidioc-enum-frameintervals.sgml +++ b/v4l2-spec/vidioc-enum-frameintervals.sgml @@ -62,7 +62,7 @@ type of frame intervals the device supports. Here are the semantics of the function for the different cases:</para> <itemizedlist> <listitem> - <para><emphasis Role="bold">Discrete:</emphasis> The function + <para><emphasis role="bold">Discrete:</emphasis> The function returns success if the given index value (zero-based) is valid. The application should increase the index by one for each call until <constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type` @@ -70,7 +70,7 @@ field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only the `discrete` member is valid.</para> </listitem> <listitem> - <para><emphasis Role="bold">Step-wise:</emphasis> The function + <para><emphasis role="bold">Step-wise:</emphasis> The function returns success if the given index value is zero and <constant>EINVAL</constant> for any other index value. The <structfield>v4l2_frmivalenum.type</structfield> field is set to @@ -79,7 +79,7 @@ union only the <structfield>stepwise</structfield> member is valid.</para> </listitem> <listitem> - <para><emphasis Role="bold">Continuous:</emphasis> This is a + <para><emphasis role="bold">Continuous:</emphasis> This is a special case of the step-wise type above. The function returns success if the given index value is zero and <constant>EINVAL</constant> for any other index value. The @@ -111,7 +111,7 @@ enumeration.</para> <itemizedlist> <listitem> - <para><emphasis Role="bold">Frame intervals and frame + <para><emphasis role="bold">Frame intervals and frame rates:</emphasis> The V4L2 API uses frame intervals instead of frame rates. Given the frame interval the frame rate can be computed as follows:<screen>frame_rate = 1 / frame_interval</screen></para> @@ -156,10 +156,10 @@ application should zero out all members except for the <table pgwide="1" frame="none" id="v4l2-frmivalenum"> <title>struct <structname>v4l2_frmivalenum</structname></title> <tgroup cols="4"> - <colspec colname="c1"> - <colspec colname="c2"> - <colspec colname="c3"> - <colspec colname="c4"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> <tbody valign="top"> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-enum-framesizes.sgml b/v4l2-spec/vidioc-enum-framesizes.sgml index 909cda68b..6afa4542c 100644 --- a/v4l2-spec/vidioc-enum-framesizes.sgml +++ b/v4l2-spec/vidioc-enum-framesizes.sgml @@ -69,7 +69,7 @@ function for the different cases:</para> <itemizedlist> <listitem> - <para><emphasis Role="bold">Discrete:</emphasis> The function + <para><emphasis role="bold">Discrete:</emphasis> The function returns success if the given index value (zero-based) is valid. The application should increase the index by one for each call until <constant>EINVAL</constant> is returned. The @@ -79,7 +79,7 @@ union only the <structfield>discrete</structfield> member is valid.</para> </listitem> <listitem> - <para><emphasis Role="bold">Step-wise:</emphasis> The function + <para><emphasis role="bold">Step-wise:</emphasis> The function returns success if the given index value is zero and <constant>EINVAL</constant> for any other index value. The <structfield>v4l2_frmsizeenum.type</structfield> field is set to @@ -88,7 +88,7 @@ union only the <structfield>stepwise</structfield> member is valid.</para> </listitem> <listitem> - <para><emphasis Role="bold">Continuous:</emphasis> This is a + <para><emphasis role="bold">Continuous:</emphasis> This is a special case of the step-wise type above. The function returns success if the given index value is zero and <constant>EINVAL</constant> for any other index value. The @@ -185,10 +185,10 @@ application should zero out all members except for the <table pgwide="1" frame="none" id="v4l2-frmsizeenum"> <title>struct <structname>v4l2_frmsizeenum</structname></title> <tgroup cols="4"> - <colspec colname="c1"> - <colspec colname="c2"> - <colspec colname="c3"> - <colspec colname="c4"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> <tbody valign="top"> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-enumaudio.sgml b/v4l2-spec/vidioc-enumaudio.sgml index 2cd9e020d..9ae8f2d3a 100644 --- a/v4l2-spec/vidioc-enumaudio.sgml +++ b/v4l2-spec/vidioc-enumaudio.sgml @@ -57,7 +57,7 @@ to this structure. Drivers fill the rest of the structure or return an inputs applications shall begin at index zero, incrementing by one until the driver returns <errorcode>EINVAL</errorcode>.</para> - <para>See <xref linkend="vidioc-g-audio"> for a description of + <para>See <xref linkend="vidioc-g-audio" /> for a description of &v4l2-audio;.</para> </refsect1> diff --git a/v4l2-spec/vidioc-enumaudioout.sgml b/v4l2-spec/vidioc-enumaudioout.sgml index 5c51e3bfe..d3d7c0ab1 100644 --- a/v4l2-spec/vidioc-enumaudioout.sgml +++ b/v4l2-spec/vidioc-enumaudioout.sgml @@ -60,7 +60,7 @@ until the driver returns <errorcode>EINVAL</errorcode>.</para> <para>Note connectors on a TV card to loop back the received audio signal to a sound card are not audio outputs in this sense.</para> - <para>See <xref linkend="vidioc-g-audioout"> for a description of + <para>See <xref linkend="vidioc-g-audioout" /> for a description of &v4l2-audioout;.</para> </refsect1> diff --git a/v4l2-spec/vidioc-enuminput.sgml b/v4l2-spec/vidioc-enuminput.sgml index 824b47e5f..414856b82 100644 --- a/v4l2-spec/vidioc-enuminput.sgml +++ b/v4l2-spec/vidioc-enuminput.sgml @@ -79,7 +79,7 @@ for the user, preferably the connector label on the device itself.</entry> <entry>__u32</entry> <entry><structfield>type</structfield></entry> <entry>Type of the input, see <xref - linkend="input-type">.</entry> + linkend="input-type" />.</entry> </row> <row> <entry>__u32</entry> @@ -94,7 +94,7 @@ shall not interpret this as lack of audio support. Some drivers automatically select audio sources and do not enumerate them since there is no choice anyway.</para><para>For details on audio inputs and how to select the current input see <xref - linkend="audio">.</para></entry> + linkend="audio" />.</para></entry> </row> <row> <entry>__u32</entry> @@ -104,7 +104,7 @@ demodulators). When the <structfield>type</structfield> is set to <constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and this field identifies the tuner. It corresponds to &v4l2-tuner; field <structfield>index</structfield>. For details on -tuners see <xref linkend="tuner">.</entry> +tuners see <xref linkend="tuner" />.</entry> </row> <row> <entry>&v4l2-std-id;</entry> @@ -112,13 +112,13 @@ tuners see <xref linkend="tuner">.</entry> <entry>Every video input supports one or more different video standards. This field is a set of all supported standards. For details on video standards and how to switch see <xref -linkend="standard">.</entry> +linkend="standard" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>status</structfield></entry> <entry>This field provides status information about the -input. See <xref linkend="input-status"> for flags. +input. See <xref linkend="input-status" /> for flags. With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the current input.</entry> </row> @@ -162,11 +162,11 @@ is OK." --> <table frame="none" pgwide="1" id="input-status"> <title>Input Status Flags</title> <tgroup cols="3"> - <colspec colname="c1"> - <colspec colname="c2" align="center"> - <colspec colname="c3"> + <colspec colname="c1" /> + <colspec colname="c2" align="center" /> + <colspec colname="c3" /> <spanspec namest="c1" nameend="c3" spanname="hspan" - align="left"> + align="left" /> <tbody valign="top"> <row> <entry spanname="hspan">General</entry> diff --git a/v4l2-spec/vidioc-enumoutput.sgml b/v4l2-spec/vidioc-enumoutput.sgml index 7e3481203..e8d16dcd5 100644 --- a/v4l2-spec/vidioc-enumoutput.sgml +++ b/v4l2-spec/vidioc-enumoutput.sgml @@ -78,7 +78,7 @@ user, preferably the connector label on the device itself.</entry> <entry>__u32</entry> <entry><structfield>type</structfield></entry> <entry>Type of the output, see <xref - linkend="output-type">.</entry> + linkend="output-type" />.</entry> </row> <row> <entry>__u32</entry> @@ -92,7 +92,7 @@ none.</para><para>When the driver does not enumerate audio outputs no bits must be set. Applications shall not interpret this as lack of audio support. Drivers may automatically select audio outputs without enumerating them.</para><para>For details on audio outputs and how to -select the current output see <xref linkend="audio">.</para></entry> +select the current output see <xref linkend="audio" />.</para></entry> </row> <row> <entry>__u32</entry> @@ -102,7 +102,7 @@ When the <structfield>type</structfield> is <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF connector and this field identifies the modulator. It corresponds to &v4l2-modulator; field <structfield>index</structfield>. For details -on modulators see <xref linkend="tuner">.</entry> +on modulators see <xref linkend="tuner" />.</entry> </row> <row> <entry>&v4l2-std-id;</entry> @@ -110,7 +110,7 @@ on modulators see <xref linkend="tuner">.</entry> <entry>Every video output supports one or more different video standards. This field is a set of all supported standards. For details on video standards and how to switch see <xref - linkend="standard">.</entry> + linkend="standard" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-enumstd.sgml b/v4l2-spec/vidioc-enumstd.sgml index c775671bd..95803fe2c 100644 --- a/v4l2-spec/vidioc-enumstd.sgml +++ b/v4l2-spec/vidioc-enumstd.sgml @@ -78,7 +78,7 @@ application.</entry> <entry>&v4l2-std-id;</entry> <entry><structfield>id</structfield></entry> <entry>The bits in this field identify the standard as -one of the common standards listed in <xref linkend="v4l2-std-id">, +one of the common standards listed in <xref linkend="v4l2-std-id" />, or if bits 32 to 63 are set as custom standards. Multiple bits can be set if the hardware does not distinguish between these standards, however separate indices do not indicate the opposite. The @@ -145,7 +145,7 @@ the array to zero.</entry> <entry><structfield>v4l2_std_id</structfield></entry> <entry>This type is a set, each bit representing another video standard as listed below and in <xref -linkend="video-standards">. The 32 most significant bits are reserved +linkend="video-standards" />. The 32 most significant bits are reserved for custom (driver defined) video standards.</entry> </row> </tbody> @@ -252,20 +252,20 @@ url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> </programlisting></para> <table pgwide="1" id="video-standards" orient="land"> - <title>Video Standards (based on [<xref linkend="itu470">])</title> + <title>Video Standards (based on [<xref linkend="itu470" />])</title> <tgroup cols="12" colsep="1" rowsep="1" align="center"> - <colspec colname="c1" align="left"> - <colspec colname="c2"> - <colspec colname="c3"> - <colspec colname="c4"> - <colspec colname="c5"> - <colspec colnum="7" colname="c7"> - <colspec colnum="9" colname="c9"> - <colspec colnum="12" colname="c12"> - <spanspec namest="c2" nameend="c3" spanname="m" align="center"> - <spanspec namest="c4" nameend="c12" spanname="x" align="center"> - <spanspec namest="c5" nameend="c7" spanname="b" align="center"> - <spanspec namest="c9" nameend="c12" spanname="s" align="center"> + <colspec colname="c1" align="left" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> + <colspec colname="c5" /> + <colspec colnum="7" colname="c7" /> + <colspec colnum="9" colname="c9" /> + <colspec colnum="12" colname="c12" /> + <spanspec namest="c2" nameend="c3" spanname="m" align="center" /> + <spanspec namest="c4" nameend="c12" spanname="x" align="center" /> + <spanspec namest="c5" nameend="c7" spanname="b" align="center" /> + <spanspec namest="c9" nameend="c12" spanname="s" align="center" /> <thead> <row> <entry>Characteristics</entry> diff --git a/v4l2-spec/vidioc-g-audio.sgml b/v4l2-spec/vidioc-g-audio.sgml index 8b929158e..65361a8c2 100644 --- a/v4l2-spec/vidioc-g-audio.sgml +++ b/v4l2-spec/vidioc-g-audio.sgml @@ -99,13 +99,13 @@ user, preferably the connector label on the device itself.</entry> <entry>__u32</entry> <entry><structfield>capability</structfield></entry> <entry>Audio capability flags, see <xref - linkend="audio-capability">.</entry> + linkend="audio-capability" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>mode</structfield></entry> <entry>Audio mode flags set by drivers and applications (on - <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode">.</entry> + <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-g-enc-index.sgml b/v4l2-spec/vidioc-g-enc-index.sgml index bc4153647..9f242e4b2 100644 --- a/v4l2-spec/vidioc-g-enc-index.sgml +++ b/v4l2-spec/vidioc-g-enc-index.sgml @@ -126,8 +126,8 @@ order by their <structfield>offset</structfield>.</entry> <entry>The offset in bytes from the beginning of the compressed video stream to the beginning of this picture, that is a <wordasword>PES packet header</wordasword> as defined in <xref - linkend="mpeg2part1"> or a <wordasword>picture -header</wordasword> as defined in <xref linkend="mpeg2part2">. When + linkend="mpeg2part1" /> or a <wordasword>picture +header</wordasword> as defined in <xref linkend="mpeg2part2" />. When the encoder is stopped, the driver resets the offset to zero.</entry> </row> <row> @@ -135,7 +135,7 @@ the encoder is stopped, the driver resets the offset to zero.</entry> <entry><structfield>pts</structfield></entry> <entry>The 33 bit <wordasword>Presentation Time Stamp</wordasword> of this picture as defined in <xref - linkend="mpeg2part1">.</entry> + linkend="mpeg2part1" />.</entry> </row> <row> <entry>__u32</entry> @@ -146,7 +146,7 @@ Stamp</wordasword> of this picture as defined in <xref <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Flags containing the coding type of this picture, see <xref - linkend="enc-idx-flags">.</entry> + linkend="enc-idx-flags" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-g-ext-ctrls.sgml b/v4l2-spec/vidioc-g-ext-ctrls.sgml index 510520254..3aa7f8f9f 100644 --- a/v4l2-spec/vidioc-g-ext-ctrls.sgml +++ b/v4l2-spec/vidioc-g-ext-ctrls.sgml @@ -56,7 +56,7 @@ VIDIOC_TRY_EXT_CTRLS</para> <para>These ioctls allow the caller to get or set multiple controls atomically. Control IDs are grouped into control classes (see -<xref linkend="ctrl-class">) and all controls in the control array +<xref linkend="ctrl-class" />) and all controls in the control array must belong to the same control class.</para> <para>Applications must always fill in the @@ -68,20 +68,35 @@ initialize the &v4l2-ext-control; array pointed to by the <structfield>controls</structfield> fields.</para> <para>To get the current value of a set of controls applications -initialize the <structfield>id</structfield> field of each -&v4l2-ext-control; and call the -<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl.</para> +initialize the <structfield>id</structfield>, +<structfield>size</structfield> and <structfield>reserved2</structfield> fields +of each &v4l2-ext-control; and call the +<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls +must also set the <structfield>string</structfield> field.</para> + + <para>If the <structfield>size</structfield> is too small to +receive the control result (only relevant for pointer-type controls +like strings), then the driver will set <structfield>size</structfield> +to a valid value and return an &ENOSPC;. You should re-allocate the +string memory to this new size and try again. It is possible that the +same issue occurs again if the string has grown in the meantime. It is +recommended to call &VIDIOC-QUERYCTRL; first and use +<structfield>maximum</structfield>+1 as the new <structfield>size</structfield> +value. It is guaranteed that that is sufficient memory. +</para> <para>To change the value of a set of controls applications -initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls will only be set if <emphasis>all</emphasis> control values are valid.</para> - <para>To check if the a set of controls have correct values -applications initialize the <structfield>id</structfield> and -<structfield>value</structfield> fields of a &v4l2-ext-control; and + <para>To check if a set of controls have correct values applications +initialize the <structfield>id</structfield>, <structfield>size</structfield>, +<structfield>reserved2</structfield> and +<structfield>value/string</structfield> fields of each &v4l2-ext-control; and call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned.</para> @@ -112,7 +127,23 @@ application.</entry> </row> <row> <entry>__u32</entry> - <entry><structfield>reserved2</structfield>[2]</entry> + <entry><structfield>size</structfield></entry> + <entry></entry> + <entry>The total size in bytes of the payload of this +control. This is normally 0, but for pointer controls this should be +set to the size of the memory containing the payload, or that will +receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds +that this value is less than is required to store +the payload result, then it is set to a value large enough to store the +payload result and ENOSPC is returned. Note that for string controls +this <structfield>size</structfield> field should not be confused with the length of the string. +This field refers to the size of the memory that contains the string. +The actual <emphasis>length</emphasis> of the string may well be much smaller. +</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved2</structfield>[1]</entry> <entry></entry> <entry>Reserved for future extensions. Drivers and applications must set the array to zero.</entry> @@ -135,9 +166,9 @@ applications must set the array to zero.</entry> </row> <row> <entry></entry> - <entry>void *</entry> - <entry><structfield>reserved</structfield></entry> - <entry>Reserved for future pointer-type controls. Currently unused.</entry> + <entry>char *</entry> + <entry><structfield>string</structfield></entry> + <entry>A pointer to a string.</entry> </row> </tbody> </tgroup> @@ -152,7 +183,7 @@ applications must set the array to zero.</entry> <entry>__u32</entry> <entry><structfield>ctrl_class</structfield></entry> <entry>The control class to which all controls belong, see -<xref linkend="ctrl-class">.</entry> +<xref linkend="ctrl-class" />.</entry> </row> <row> <entry>__u32</entry> @@ -194,7 +225,7 @@ if <structfield>count</structfield> equals zero.</entry> <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry> <entry>0x980000</entry> <entry>The class containing user controls. These controls -are described in <xref linkend="control">. All controls that can be set +are described in <xref linkend="control" />. All controls that can be set using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this class.</entry> </row> @@ -202,8 +233,22 @@ class.</entry> <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry> <entry>0x990000</entry> <entry>The class containing MPEG compression controls. -These controls are described in section <xref - linkend="mpeg-controls">.</entry> +These controls are described in <xref + linkend="mpeg-controls" />.</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry> + <entry>0x9a0000</entry> + <entry>The class containing camera controls. +These controls are described in <xref + linkend="camera-controls" />.</entry> + </row> + <row> + <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry> + <entry>0x9b0000</entry> + <entry>The class containing FM Transmitter (FM TX) controls. +These controls are described in <xref + linkend="fm-tx-controls" />.</entry> </row> </tbody> </tgroup> @@ -241,6 +286,14 @@ because another applications took over control of the device function this control belongs to.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENOSPC</errorcode></term> + <listitem> + <para>The space reserved for the control's payload is insufficient. +The field <structfield>size</structfield> is set to a value that is enough +to store the payload and this error code is returned.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/v4l2-spec/vidioc-g-fbuf.sgml b/v4l2-spec/vidioc-g-fbuf.sgml index 6781b5334..f70170626 100644 --- a/v4l2-spec/vidioc-g-fbuf.sgml +++ b/v4l2-spec/vidioc-g-fbuf.sgml @@ -118,14 +118,14 @@ can set the parameters for a destructive video overlay.</para> <entry><structfield>capability</structfield></entry> <entry></entry> <entry>Overlay capability flags set by the driver, see -<xref linkend="framebuffer-cap">.</entry> +<xref linkend="framebuffer-cap" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry></entry> <entry>Overlay control flags set by application and -driver, see <xref linkend="framebuffer-flags"></entry> +driver, see <xref linkend="framebuffer-flags" /></entry> </row> <row> <entry>void *</entry> @@ -149,7 +149,7 @@ provide a base address. The driver may accept only base addresses which are a multiple of two, four or eight bytes. For <wordasword>Video Output Overlays</wordasword> the driver must return a valid base address, so applications can find the corresponding Linux -framebuffer device (see <xref linkend="osd">).</entry> +framebuffer device (see <xref linkend="osd" />).</entry> </row> <row> <entry>&v4l2-pix-format;</entry> @@ -157,7 +157,7 @@ framebuffer device (see <xref linkend="osd">).</entry> <entry></entry> <entry>Layout of the frame buffer. The <structname>v4l2_pix_format</structname> structure is defined in <xref -linkend="pixfmt">, for clarification the fields and acceptable values +linkend="pixfmt" />, for clarification the fields and acceptable values are listed below:</entry> </row> <row> @@ -207,7 +207,7 @@ not including <constant>V4L2_PIX_FMT_YUYV</constant> and <constant>V4L2_PIX_FMT_UYVY</constant>) and the <constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The behavior of the driver when an application requests a compressed -format is undefined. See <xref linkend="pixfmt"> for information on +format is undefined. See <xref linkend="pixfmt" /> for information on pixel formats.</entry> </row> <row> @@ -270,7 +270,7 @@ driver.</para></entry> <entry><structfield>colorspace</structfield></entry> <entry>This information supplements the <structfield>pixelformat</structfield> and must be set by the driver, -see <xref linkend="colorspaces">.</entry> +see <xref linkend="colorspaces" />.</entry> </row> <row> <entry></entry> @@ -371,15 +371,15 @@ Most drivers seem to ignore these flags. For compatibility with the <entry>Use chroma-keying. The chroma-key color is determined by the <structfield>chromakey</structfield> field of &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay"> + linkend="overlay" /> and - <xref linkend="osd">.</entry> + <xref linkend="osd" />.</entry> </row> <row> <entry spanname="hspan">There are no flags to enable clipping using a list of clip rectangles or a bitmap. These methods are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay"> and <xref linkend="osd">.</entry> + linkend="overlay" /> and <xref linkend="osd" />.</entry> </row> <row> <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry> @@ -398,8 +398,8 @@ with video images. The blend function is: output = (framebuffer pixel * alpha + video pixel * (255 - alpha)) / 255. The alpha value is determined by the <structfield>global_alpha</structfield> field of &v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref - linkend="overlay"> -and <xref linkend="osd">.</entry> + linkend="overlay" /> +and <xref linkend="osd" />.</entry> </row> <row> <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry> diff --git a/v4l2-spec/vidioc-g-fmt.sgml b/v4l2-spec/vidioc-g-fmt.sgml index 0a466b2c7..7c7d1b72c 100644 --- a/v4l2-spec/vidioc-g-fmt.sgml +++ b/v4l2-spec/vidioc-g-fmt.sgml @@ -72,7 +72,7 @@ When the requested buffer type is not supported drivers return an initialize the <structfield>type</structfield> field and all fields of the respective <structfield>fmt</structfield> union member. For details see the documentation of the various devices -types in <xref linkend="devices">. Good practice is to query the +types in <xref linkend="devices" />. Good practice is to query the current parameters first, and to modify only those parameters not suitable for the application. When the application calls the <constant>VIDIOC_S_FMT</constant> ioctl @@ -108,17 +108,17 @@ this ioctl.</para> <table pgwide="1" frame="none" id="v4l2-format"> <title>struct <structname>v4l2_format</structname></title> <tgroup cols="4"> - <colspec colname="c1"> - <colspec colname="c2"> - <colspec colname="c3"> - <colspec colname="c4"> + <colspec colname="c1" /> + <colspec colname="c2" /> + <colspec colname="c3" /> + <colspec colname="c4" /> <tbody valign="top"> <row> <entry>&v4l2-buf-type;</entry> <entry><structfield>type</structfield></entry> <entry></entry> <entry>Type of the data stream, see <xref - linkend="v4l2-buf-type">.</entry> + linkend="v4l2-buf-type" />.</entry> </row> <row> <entry>union</entry> @@ -129,7 +129,7 @@ this ioctl.</para> <entry>&v4l2-pix-format;</entry> <entry><structfield>pix</structfield></entry> <entry>Definition of an image format, see <xref - linkend="pixfmt">, used by video capture and output + linkend="pixfmt" />, used by video capture and output devices.</entry> </row> <row> @@ -137,14 +137,14 @@ devices.</entry> <entry>&v4l2-window;</entry> <entry><structfield>win</structfield></entry> <entry>Definition of an overlaid image, see <xref - linkend="overlay">, used by video overlay devices.</entry> + linkend="overlay" />, used by video overlay devices.</entry> </row> <row> <entry></entry> <entry>&v4l2-vbi-format;</entry> <entry><structfield>vbi</structfield></entry> <entry>Raw VBI capture or output parameters. This is -discussed in more detail in <xref linkend="raw-vbi">. Used by raw VBI +discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI capture and output devices.</entry> </row> <row> @@ -152,7 +152,7 @@ capture and output devices.</entry> <entry>&v4l2-sliced-vbi-format;</entry> <entry><structfield>sliced</structfield></entry> <entry>Sliced VBI capture or output parameters. See -<xref linkend="sliced"> for details. Used by sliced VBI +<xref linkend="sliced" /> for details. Used by sliced VBI capture and output devices.</entry> </row> <row> diff --git a/v4l2-spec/vidioc-g-jpegcomp.sgml b/v4l2-spec/vidioc-g-jpegcomp.sgml index 0755b834b..77394b287 100644 --- a/v4l2-spec/vidioc-g-jpegcomp.sgml +++ b/v4l2-spec/vidioc-g-jpegcomp.sgml @@ -116,7 +116,7 @@ to add them.</para> <row> <entry>__u32</entry> <entry><structfield>jpeg_markers</structfield></entry> - <entry>See <xref linkend="jpeg-markers">.</entry> + <entry>See <xref linkend="jpeg-markers" />.</entry> </row> </tbody> </tgroup> diff --git a/v4l2-spec/vidioc-g-modulator.sgml b/v4l2-spec/vidioc-g-modulator.sgml index 945147f90..15ce660f0 100644 --- a/v4l2-spec/vidioc-g-modulator.sgml +++ b/v4l2-spec/vidioc-g-modulator.sgml @@ -128,7 +128,7 @@ Hz.</entry> <entry><structfield>txsubchans</structfield></entry> <entry>With this field applications can determine how audio sub-carriers shall be modulated. It contains a set of flags as -defined in <xref linkend="modulator-txsubchans">. Note the tuner +defined in <xref linkend="modulator-txsubchans" />. Note the tuner <structfield>rxsubchans</structfield> flags are reused, but the semantics are different. Video output devices are assumed to have an analog or PCM audio input with 1-3 channels. The diff --git a/v4l2-spec/vidioc-g-parm.sgml b/v4l2-spec/vidioc-g-parm.sgml index 6ad43823e..78332d365 100644 --- a/v4l2-spec/vidioc-g-parm.sgml +++ b/v4l2-spec/vidioc-g-parm.sgml @@ -123,12 +123,12 @@ higher.</entry> <row> <entry>__u32</entry> <entry><structfield>capability</structfield></entry> - <entry>See <xref linkend="parm-caps">.</entry> + <entry>See <xref linkend="parm-caps" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>capturemode</structfield></entry> - <entry>Set by drivers and applications, see <xref linkend="parm-flags">.</entry> + <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry> </row> <row> <entry>&v4l2-fract;</entry> @@ -153,7 +153,7 @@ zero.</para><para>Drivers support this function only when they set the <entry>Custom (driver specific) streaming parameters. When unused, applications and drivers must set this field to zero. Applications using this field should check the driver name and -version, see <xref linkend="querycap">.</entry> +version, see <xref linkend="querycap" />.</entry> </row> <row> <entry>__u32</entry> @@ -163,7 +163,7 @@ of buffers used internally by the driver in &func-read; mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error code. For details see <xref - linkend="rw">.</entry> + linkend="rw" />.</entry> </row> <row> <entry>__u32</entry> @@ -183,13 +183,13 @@ applications must set the array to zero.</entry> <row> <entry>__u32</entry> <entry><structfield>capability</structfield></entry> - <entry>See <xref linkend="parm-caps">.</entry> + <entry>See <xref linkend="parm-caps" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>outputmode</structfield></entry> <entry>Set by drivers and applications, see <xref - linkend="parm-flags">.</entry> + linkend="parm-flags" />.</entry> </row> <row> <entry>&v4l2-fract;</entry> @@ -218,7 +218,7 @@ zero.</para><para>Drivers support this function only when they set the <entry>Custom (driver specific) streaming parameters. When unused, applications and drivers must set this field to zero. Applications using this field should check the driver name and -version, see <xref linkend="querycap">.</entry> +version, see <xref linkend="querycap" />.</entry> </row> <row> <entry>__u32</entry> @@ -228,7 +228,7 @@ of buffers used internally by the driver in <function>write()</function> mode. Drivers return the actual number of buffers. When an application requests zero buffers, drivers should just return the current setting rather than the minimum or an error -code. For details see <xref linkend="rw">.</entry> +code. For details see <xref linkend="rw" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/v4l2-spec/vidioc-g-sliced-vbi-cap.sgml b/v4l2-spec/vidioc-g-sliced-vbi-cap.sgml index 3568bacf1..10e721b17 100644 --- a/v4l2-spec/vidioc-g-sliced-vbi-cap.sgml +++ b/v4l2-spec/vidioc-g-sliced-vbi-cap.sgml @@ -63,12 +63,12 @@ and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para> <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap"> <title>struct <structname>v4l2_sliced_vbi_cap</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 spanname="hspan" namest="c3" nameend="c5"> + <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 spanname="hspan" namest="c3" nameend="c5" /> <tbody valign="top"> <row> <entry>__u16</entry> @@ -83,10 +83,10 @@ supported by the driver. Equal to the union of all elements of the <entry spanname="hspan">Each element of this array contains a set of data services the hardware can look for or insert into a particular scan line. Data services are defined in <xref - linkend="vbi-services">. Array indices map to ITU-R + linkend="vbi-services" />. Array indices map to ITU-R line numbers (see also <xref - linkend="vbi-525"> and <xref -linkend="vbi-625">) as follows:</entry> + linkend="vbi-525" /> and <xref +linkend="vbi-625" />) as follows:</entry> </row> <row> <entry></entry> @@ -135,7 +135,7 @@ can identify on a given line may be 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. Applications can learn about these limits using the &VIDIOC-S-FMT; ioctl as described in <xref - linkend="sliced">.</entry> + linkend="sliced" />.</entry> </row> <row> <entry></entry> @@ -151,7 +151,7 @@ using the &VIDIOC-S-FMT; ioctl as described in <xref <entry>&v4l2-buf-type;</entry> <entry><structfield>type</structfield></entry> <entry>Type of the data stream, see <xref - linkend="v4l2-buf-type">. Should be + linkend="v4l2-buf-type" />. Should be <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry> </row> @@ -169,12 +169,12 @@ extensions. Applications and drivers must set it to zero.</entry> <table pgwide="1" frame="none" id="vbi-services"> <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 spanname='rlp' namest='c3' nameend='c5'> + <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 spanname='rlp' namest='c3' nameend='c5' /> <thead> <row> <entry>Symbol</entry> @@ -189,7 +189,7 @@ extensions. Applications and drivers must set it to zero.</entry> <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext System B)</entry> <entry>0x0001</entry> - <entry><xref linkend="ets300706">, <xref linkend="itu653"></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> @@ -197,7 +197,7 @@ without clock run-in and framing code, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_VPS</constant></entry> <entry>0x0400</entry> - <entry><xref linkend="ets300231"></entry> + <entry><xref linkend="ets300231" /></entry> <entry>PAL line 16</entry> <entry>Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb first transmitted.</entry> @@ -205,7 +205,7 @@ ETS 300 231, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> <entry>0x1000</entry> - <entry><xref linkend="eia608"></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> @@ -213,7 +213,7 @@ bit, lsb first transmitted.</entry> <row> <entry><constant>V4L2_SLICED_WSS_625</constant></entry> <entry>0x4000</entry> - <entry><xref linkend="en300294">, <xref linkend="itu1119"></entry> + <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry> <entry>PAL/SECAM line 23</entry> <entry><screen> Byte 0 1 diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml index eb0b89e9a..bd98c734c 100644 --- a/v4l2-spec/vidioc-g-tuner.sgml +++ b/v4l2-spec/vidioc-g-tuner.sgml @@ -86,11 +86,11 @@ is available.</para> <table pgwide="1" frame="none" id="v4l2-tuner"> <title>struct <structname>v4l2_tuner</structname></title> <tgroup cols="3"> - <colspec colname="c1" colwidth="1*"> - <colspec colname="c2" colwidth="1*"> - <colspec colname="c3" colwidth="1*"> - <colspec colname="c4" colwidth="1*"> - <spanspec spanname="hspan" namest="c3" nameend="c4"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="1*" /> + <colspec colname="c3" colwidth="1*" /> + <colspec colname="c4" colwidth="1*" /> + <spanspec spanname="hspan" namest="c3" nameend="c4" /> <tbody valign="top"> <row> <entry>__u32</entry> @@ -110,13 +110,13 @@ field is not quite clear.--></para></entry> <entry>&v4l2-tuner-type;</entry> <entry><structfield>type</structfield></entry> <entry spanname="hspan">Type of the tuner, see <xref - linkend="v4l2-tuner-type">.</entry> + linkend="v4l2-tuner-type" />.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>capability</structfield></entry> <entry spanname="hspan"><para>Tuner capability flags, see -<xref linkend="tuner-capability">. Audio flags indicate the ability +<xref linkend="tuner-capability" />. Audio flags indicate the ability to decode audio subprograms. They will <emphasis>not</emphasis> change, for example with the current video standard.</para><para>When the structure refers to a radio tuner only the @@ -147,7 +147,7 @@ Hz.</entry> decoders can determine the received audio subprograms by analyzing audio carriers, pilot tones or other indicators. To pass this information drivers set flags defined in <xref - linkend="tuner-rxsubchans"> in this field. For + linkend="tuner-rxsubchans" /> in this field. For example:</para></entry> </row> <row> @@ -200,11 +200,11 @@ tuner.</para></entry> <entry>__u32</entry> <entry><structfield>audmode</structfield></entry> <entry spanname="hspan"><para>The selected audio mode, see -<xref linkend="tuner-audmode"> for valid values. The audio mode does +<xref linkend="tuner-audmode" /> for valid values. The audio mode does not affect audio subprogram detection, and like a <link linkend="control">control</link> it does not automatically change unless the requested mode is invalid or unsupported. See <xref - linkend="tuner-matrix"> for possible results when + linkend="tuner-matrix" /> for possible results when the selected and received audio programs do not match.</para><para>Currently this is the only field of struct <structname>v4l2_tuner</structname> applications can @@ -436,12 +436,12 @@ mode.</entry> <table pgwide="1" frame="all" id="tuner-matrix"> <title>Tuner Audio Matrix</title> <tgroup cols="6" align="center"> - <colspec align="left"> - <colspec colname="c2" colwidth="1*"> - <colspec colwidth="1*"> - <colspec colwidth="1*"> - <colspec colnum="6" colname="c6" colwidth="1*"> - <spanspec namest="c2" nameend="c6" spanname="hspan" align="center"> + <colspec align="left" /> + <colspec colname="c2" colwidth="1*" /> + <colspec colwidth="1*" /> + <colspec colwidth="1*" /> + <colspec colnum="6" colname="c6" colwidth="1*" /> + <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" /> <thead> <row> <entry></entry> diff --git a/v4l2-spec/vidioc-overlay.sgml b/v4l2-spec/vidioc-overlay.sgml index d16709fd1..1036c582c 100644 --- a/v4l2-spec/vidioc-overlay.sgml +++ b/v4l2-spec/vidioc-overlay.sgml @@ -67,7 +67,7 @@ <listitem> <para>Video overlay is not supported, or the parameters have not been set up. See <xref -linkend="overlay"> for the necessary steps.</para> +linkend="overlay" /> for the necessary steps.</para> </listitem> </varlistentry> </variablelist> diff --git a/v4l2-spec/vidioc-qbuf.sgml b/v4l2-spec/vidioc-qbuf.sgml index f02debb8c..187081778 100644 --- a/v4l2-spec/vidioc-qbuf.sgml +++ b/v4l2-spec/vidioc-qbuf.sgml @@ -71,7 +71,7 @@ intended for output (<structfield>type</structfield> is initialize the <structfield>bytesused</structfield>, <structfield>field</structfield> and <structfield>timestamp</structfield> fields. See <xref - linkend="buffer"> for details. When + linkend="buffer" /> for details. When <constant>VIDIOC_QBUF</constant> is called with a pointer to this structure the driver sets the <constant>V4L2_BUF_FLAG_MAPPED</constant> and @@ -114,7 +114,7 @@ function, <constant>VIDIOC_DQBUF</constant> returns immediately with an &EAGAIN; when no buffer is available.</para> <para>The <structname>v4l2_buffer</structname> structure is -specified in <xref linkend="buffer">.</para> +specified in <xref linkend="buffer" />.</para> </refsect1> <refsect1> diff --git a/v4l2-spec/vidioc-querybuf.sgml b/v4l2-spec/vidioc-querybuf.sgml index e5fb5ac7a..d834993e6 100644 --- a/v4l2-spec/vidioc-querybuf.sgml +++ b/v4l2-spec/vidioc-querybuf.sgml @@ -76,7 +76,7 @@ or may not set the remaining fields and flags, they are meaningless in this context.</para> <para>The <structname>v4l2_buffer</structname> structure is - specified in <xref linkend="buffer">.</para> + specified in <xref linkend="buffer" />.</para> </refsect1> <refsect1> diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml index fa12ae738..6ab7e25b3 100644 --- a/v4l2-spec/vidioc-querycap.sgml +++ b/v4l2-spec/vidioc-querycap.sgml @@ -122,7 +122,7 @@ printf ("Version: %u.%u.%u\n", <entry>__u32</entry> <entry><structfield>capabilities</structfield></entry> <entry>Device capabilities, see <xref - linkend="device-capabilities">.</entry> + linkend="device-capabilities" />.</entry> </row> <row> <entry>__u32</entry> @@ -211,7 +211,7 @@ hardware frequency seeking.</entry> <entry>The device has some sort of tuner to receive RF-modulated video signals. For more information about tuner programming see -<xref linkend="tuner">.</entry> +<xref linkend="tuner" />.</entry> </row> <row> <entry><constant>V4L2_CAP_AUDIO</constant></entry> @@ -220,7 +220,7 @@ tuner programming see may not support audio recording or playback, in PCM or compressed formats. PCM audio support must be implemented as ALSA or OSS interface. For more information on audio inputs and outputs see <xref - linkend="audio">.</entry> + linkend="audio" />.</entry> </row> <row> <entry><constant>V4L2_CAP_RADIO</constant></entry> @@ -233,7 +233,7 @@ interface. For more information on audio inputs and outputs see <xref <entry>The device has some sort of modulator to emit RF-modulated video/audio signals. For more information about modulator programming see -<xref linkend="tuner">.</entry> +<xref linkend="tuner" />.</entry> </row> <row> <entry><constant>V4L2_CAP_READWRITE</constant></entry> diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..4876ff1a1 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -93,8 +93,8 @@ next supported control, or <errorcode>EINVAL</errorcode> if there is none. Drivers which do not support this flag yet always return <errorcode>EINVAL</errorcode>.</para> - <para>Additional information is required for menu controls, the -name of menu items. To query them applications set the + <para>Additional information is required for menu controls: the +names of the menu items. To query them applications set the <structfield>id</structfield> and <structfield>index</structfield> fields of &v4l2-querymenu; and call the <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this @@ -106,7 +106,7 @@ by calling <constant>VIDIOC_QUERYMENU</constant> with successive <structfield>minimum</structfield> (0) to <structfield>maximum</structfield>, inclusive.</para> - <para>See also the examples in <xref linkend="control">.</para> + <para>See also the examples in <xref linkend="control" />.</para> <table pgwide="1" frame="none" id="v4l2-queryctrl"> <title>struct <structname>v4l2_queryctrl</structname></title> @@ -117,7 +117,7 @@ by calling <constant>VIDIOC_QUERYMENU</constant> with successive <entry>__u32</entry> <entry><structfield>id</structfield></entry> <entry>Identifies the control, set by the application. See -<xref linkend="control-id"> for predefined IDs. When the ID is ORed +<xref linkend="control-id" /> for predefined IDs. When the ID is ORed with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns the first control with a higher ID. Drivers which do not support this flag yet always return an &EINVAL;.</entry> @@ -126,7 +126,7 @@ flag yet always return an &EINVAL;.</entry> <entry>&v4l2-ctrl-type;</entry> <entry><structfield>type</structfield></entry> <entry>Type of control, see <xref - linkend="v4l2-ctrl-type">.</entry> + linkend="v4l2-ctrl-type" />.</entry> </row> <row> <entry>__u8</entry> @@ -138,9 +138,12 @@ string. This information is intended for the user.</entry> <entry>__s32</entry> <entry><structfield>minimum</structfield></entry> <entry>Minimum value, inclusive. This field gives a lower -bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may -not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the +lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls. +For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value +gives the minimum length of the string. This length <emphasis>does not include the terminating +zero</emphasis>. It may not be valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a signed value.</entry> </row> <row> @@ -149,16 +152,21 @@ signed value.</entry> <entry>Maximum value, inclusive. This field gives an upper bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> -controls. It may not be valid for any other type of control, including -<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a +controls. +For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value +gives the maximum length of the string. This length <emphasis>does not include the terminating +zero</emphasis>. It may not be valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a signed value.</entry> </row> <row> <entry>__s32</entry> <entry><structfield>step</structfield></entry> <entry><para>This field gives a step size for -<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may not be -valid for any other type of control, including +<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For +<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to +the string length that has to be a multiple of this step size. +It may not be valid for any other type of control, including <constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls.</para><para>Generally drivers should not scale hardware control values. It may be necessary for example when the @@ -171,7 +179,7 @@ an integer control actually affecting hardware. Often the information is needed when the user can change controls by keyboard or GUI buttons, rather than a slider. When for example a hardware register accepts values 0-511 and the driver reports 0-65535, step should be -128.</para><para>Note although signed, the step value is supposed to +128.</para><para>Note that although signed, the step value is supposed to be always positive.</para></entry> </row> <row> @@ -188,7 +196,7 @@ func-open; is called.</entry> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> <entry>Control flags, see <xref - linkend="control-flags">.</entry> + linkend="control-flags" />.</entry> </row> <row> <entry>__u32</entry> @@ -237,11 +245,11 @@ the array to zero.</entry> <table pgwide="1" frame="none" id="v4l2-ctrl-type"> <title>enum v4l2_ctrl_type</title> <tgroup cols="5" align="left"> - <colspec colwidth="30*"> - <colspec colwidth="5*" align="center"> - <colspec colwidth="5*" align="center"> - <colspec colwidth="5*" align="center"> - <colspec colwidth="55*"> + <colspec colwidth="30*" /> + <colspec colwidth="5*" align="center" /> + <colspec colwidth="5*" align="center" /> + <colspec colwidth="5*" align="center" /> + <colspec colwidth="55*" /> <thead> <row> <entry>Type</entry> @@ -297,13 +305,27 @@ Drivers must ignore the value passed with and step size cannot be queried.</entry> </row> <row> + <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry> + <entry>≥ 0</entry> + <entry>≥ 1</entry> + <entry>≥ 0</entry> + <entry>The minimum and maximum string lengths. The step size +means that the string must be (minimum + N * step) characters long for +N ≥ 0. These lengths do not include the terminating zero, so in order to +pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the +<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can +set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1. +Which character encoding is used will depend on the string control itself and +should be part of the control documentation.</entry> + </row> + <row> <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry> <entry>n/a</entry> <entry>n/a</entry> <entry>n/a</entry> <entry>This is not a control. When <constant>VIDIOC_QUERYCTRL</constant> is called with a control ID -equal to a control class code (see <xref linkend="ctrl-class">), the +equal to a control class code (see <xref linkend="ctrl-class" />), the ioctl returns the name of the control class and this control type. Older drivers which do not support this feature return an &EINVAL;.</entry> diff --git a/v4l2-spec/vidioc-reqbufs.sgml b/v4l2-spec/vidioc-reqbufs.sgml index fe3f63019..bab380844 100644 --- a/v4l2-spec/vidioc-reqbufs.sgml +++ b/v4l2-spec/vidioc-reqbufs.sgml @@ -106,7 +106,7 @@ field is only used when <structfield>memory</structfield> is set to <entry><structfield>type</structfield></entry> <entry>Type of the stream or buffers, this is the same as the &v4l2-format; <structfield>type</structfield> field. See <xref - linkend="v4l2-buf-type"> for valid values.</entry> + linkend="v4l2-buf-type" /> for valid values.</entry> </row> <row> <entry>&v4l2-memory;</entry> |