Document libv4l at V4L2 API specs

From: Mauro Carvalho Chehab <mchehab@redhat.com>

Since applications aren't prepared to handle all V4L2 available formats,
an effort is done to have a library capable of understanding especially
the proprietary formats.

This patch documents this library, and adds v4l2grab.c as an example on
how to use it.

Parts of the text are based at the libv4l README file (c) by Hans de
Goede.

Thanks to Hans de Goede <hdegoede@redhat.com> for his good work with
libv4l.

Priority: normal

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

5 files changed, 222 insertions, 4 deletions

diff --git a/.hgignore b/.hgignore
index e09075e29..bc408c495 100644
--- a/.hgignore
+++ b/.hgignore
@@ -66,6 +66,8 @@ v4l2-spec/capture.c.sgml$
 v4l2-spec/entities.sgml$
 v4l2-spec/.*\.stamp$
 v4l2-spec/indices.sgml$
+v4l2-spec/libv4l-fmt.sgml$
+v4l2-spec/v4l2grab.c.sgml$
 v4l2-spec/v4l2-single$
 v4l2-spec/v4l2$
 v4l2-spec/v4l2.pdf$
diff --git a/v4l2-apps/test/v4l2grab.c b/v4l2-apps/test/v4l2grab.c
index 153a0dd30..de921874b 100644
--- a/v4l2-apps/test/v4l2grab.c
+++ b/v4l2-apps/test/v4l2grab.c
@@ -1,5 +1,5 @@
 /* V4L2 video picture grabber
-   Copyright (C) 2006 Mauro Carvalho Chehab <mchehab@infradead.org>
+   Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org>
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile
index 8f40e8614..616445137 100644
--- a/v4l2-spec/Makefile
+++ b/v4l2-spec/Makefile
@@ -5,6 +5,7 @@ SHELL=/bin/bash
 SGMLS = \
 	biblio.sgml \
 	capture.c.sgml \
+	v4l2grab.c.sgml \
 	common.sgml \
 	compat.sgml \
 	controls.sgml \
@@ -20,6 +21,7 @@ SGMLS = \
 	dev-sliced-vbi.sgml \
 	dev-teletext.sgml \
 	driver.sgml \
+	libv4l.sgml \
 	entities.sgml \
 	fdl-appendix.sgml \
 	func-close.sgml \
@@ -323,6 +325,12 @@ DOCUMENTED = \
 	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
 	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta"
 
+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>" > $@
 	expand --tabs=8 < $< | \
@@ -330,6 +338,13 @@ 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>" >> $@
+
 videodev2.h.sgml: ../linux/include/linux/videodev2.h Makefile
 	echo "<programlisting>" > $@
 	expand --tabs=8 < $< | \
@@ -488,6 +503,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/libv4l.sgml b/v4l2-spec/libv4l.sgml
new file mode 100644
index 000000000..ec1f8b6fe
--- /dev/null
+++ b/v4l2-spec/libv4l.sgml
@@ -0,0 +1,168 @@
+<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/v4l2.sgml b/v4l2-spec/v4l2.sgml
index bae7eb441..8e7610685 100644
--- a/v4l2-spec/v4l2.sgml
+++ b/v4l2-spec/v4l2.sgml
@@ -25,7 +25,7 @@
 <book id="v4l2spec">
   <bookinfo>
     <title>Video for Linux Two API Specification</title>
-    <subtitle>Revision 0.26</subtitle>
+    <subtitle>Revision 0.27</subtitle>
 
     <authorgroup>
       <author>
@@ -92,6 +92,18 @@ MPEG stream embedded, sliced VBI data format in this specification.
       </author>
     </authorgroup>
 
+      <author>
+	<firstname>Mauro</firstname>
+	<surname>Carvalho Chehab</surname>
+	<contrib>Documented libv4l, designed and added v4l2grab example
+	</contrib>
+	<affiliation>
+	  <address>
+	    <email>mchehab@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
+
     <copyright>
       <year>1999</year>
       <year>2000</year>
@@ -105,12 +117,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 &copy; 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,6 +144,13 @@ structs, ioctls) must be noted in more detail in the history chapter
 applications. -->
 
       <revision>
+	<revnumber>0.27</revnumber>
+	<date>2009-08-15</date>
+	<authorinitials>mcc</authorinitials>
+	<revremark>Added libv4l documentation and v4l2grab example.</revremark>
+      </revision>
+
+      <revision>
 	<revnumber>0.26</revnumber>
 	<date>2009-06-15</date>
 	<authorinitials>hv</authorinitials>
@@ -471,6 +491,10 @@ available here: <ulink url="http://linuxtv.org/downloads/video4linux/API/V4L2_AP
     &sub-driver;
   </chapter>
 
+  <chapter id="libv4l">
+    &sub-libv4l;
+  </chapter>
+
   <chapter id="compat">
     &sub-compat;
   </chapter>
@@ -485,6 +509,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;