All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] Document libv4l at V4L2 API specs
@ 2009-08-15 19:37 Mauro Carvalho Chehab
  2009-08-16  7:42 ` Hans Verkuil
  0 siblings, 1 reply; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2009-08-15 19:37 UTC (permalink / raw)
  To: linux-media

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.

Signed-off-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

diff -r ee300d3178c4 .hgignore
--- a/.hgignore	Fri Aug 14 01:48:42 2009 -0300
+++ b/.hgignore	Sat Aug 15 16:32:08 2009 -0300
@@ -66,6 +66,8 @@
 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 -r ee300d3178c4 v4l2-apps/test/v4l2grab.c
--- a/v4l2-apps/test/v4l2grab.c	Fri Aug 14 01:48:42 2009 -0300
+++ b/v4l2-apps/test/v4l2grab.c	Sat Aug 15 16:32:08 2009 -0300
@@ -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 -r ee300d3178c4 v4l2-spec/Makefile
--- a/v4l2-spec/Makefile	Fri Aug 14 01:48:42 2009 -0300
+++ b/v4l2-spec/Makefile	Sat Aug 15 16:32:08 2009 -0300
@@ -5,6 +5,7 @@
 SGMLS = \
 	biblio.sgml \
 	capture.c.sgml \
+	v4l2grab.c.sgml \
 	common.sgml \
 	compat.sgml \
 	controls.sgml \
@@ -20,6 +21,7 @@
 	dev-sliced-vbi.sgml \
 	dev-teletext.sgml \
 	driver.sgml \
+	libv4l.sgml \
 	entities.sgml \
 	fdl-appendix.sgml \
 	func-close.sgml \
@@ -323,6 +325,12 @@
 	-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 @@
 	  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 @@
 	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 -r ee300d3178c4 v4l2-spec/libv4l.sgml
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/v4l2-spec/libv4l.sgml	Sat Aug 15 16:32:08 2009 -0300
@@ -0,0 +1,143 @@
+<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 op 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 seperate 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 different
+several different pixelformats found at 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 improve webcam video quality on a software
+basis. The video processing is plit 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 he video processing functions made available by
+	libv4lconvert/processing. These controls are stored application wide
+(untill	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 by 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 on new applications.</para>
+	</section>
+	<section>
+		<title>libv4l2</title>
+		<para>This library should be used on all modern V4L2 application
+		</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>On 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> and
+<link linkend='VIDIOC-G-FMT'><constant>VIDIOC_S_FMT</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 at the driver.
+<link linkend='VIDIOC-ENUM-FMT'><constant>VIDIOC_ENUM_FMT</constant></link> keep
+enumerating the hardware supported formats.
+</para>
+		<section id="libv4l-ops">
+			<title>Libv4l device control functions</title>
+			<para>The common file operation methods are provided by
+libv4l. They work like the non-v4l2 ones:</para>
+			<para>v4l2_open(const char *file, int oflag, ...) -
+operates like the standard <link linkend='func-open'>open()</link> function.
+</para>
+
+			<para>int v4l2_close(int fd) -
+operates like the standard <link linkend='func-close'>close()</link> function.
+</para>
+
+			<para>int v4l2_dup(int fd) -
+operates like the standard dup() function, duplicating a file handler.
+</para>
+
+			<para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
+operates like the standard <link linkend='func-ioctl'>ioctl()</link> function.
+</para>
+
+			<para>int v4l2_read (int fd, void* buffer, size_t n) -
+operates like the standard <link linkend='func-read'>read()</link> function.
+</para>
+
+			<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>
+
+			<para>int v4l2_munmap(void *_start, size_t length); -
+operates like the standard <link linkend='func-munmap'>munmap()</link> function.
+</para>
+		</section>
+	</section>
+	<section>
+
+		<title>v4l1compat.so wrapper library</title>
+
+		<para>This library intercept calls to V4L2
+open/close/ioctl/mmap/mmunmap operations and redirects to the libv4lX
+counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so.</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 -r ee300d3178c4 v4l2-spec/v4l2.sgml
--- a/v4l2-spec/v4l2.sgml	Fri Aug 14 01:48:42 2009 -0300
+++ b/v4l2-spec/v4l2.sgml	Sat Aug 15 16:32:08 2009 -0300
@@ -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 @@
       </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 @@
       <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 @@
 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 @@
     &sub-driver;
   </chapter>
 
+  <chapter id="libv4l">
+    &sub-libv4l;
+  </chapter>
+
   <chapter id="compat">
     &sub-compat;
   </chapter>
@@ -485,6 +509,14 @@
     &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;

^ permalink raw reply	[flat|nested] 3+ messages in thread
* Re: [PATCH] Document libv4l at V4L2 API specs
  2009-08-15 19:37 [PATCH] Document libv4l at V4L2 API specs Mauro Carvalho Chehab
@ 2009-08-16  7:42 ` Hans Verkuil
  2009-08-16 23:29   ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 3+ messages in thread
From: Hans Verkuil @ 2009-08-16  7:42 UTC (permalink / raw)
  To: Mauro Carvalho Chehab; +Cc: linux-media

Hi Mauro,

I've done a quick review of the text. See comments below.

On Saturday 15 August 2009 21:37:26 Mauro Carvalho Chehab wrote:
> 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.
> 
> Signed-off-by: Hans de Goede <hdegoede@redhat.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
> 
> diff -r ee300d3178c4 .hgignore
> --- a/.hgignore	Fri Aug 14 01:48:42 2009 -0300
> +++ b/.hgignore	Sat Aug 15 16:32:08 2009 -0300
> @@ -66,6 +66,8 @@
>  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 -r ee300d3178c4 v4l2-apps/test/v4l2grab.c
> --- a/v4l2-apps/test/v4l2grab.c	Fri Aug 14 01:48:42 2009 -0300
> +++ b/v4l2-apps/test/v4l2grab.c	Sat Aug 15 16:32:08 2009 -0300
> @@ -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 -r ee300d3178c4 v4l2-spec/Makefile
> --- a/v4l2-spec/Makefile	Fri Aug 14 01:48:42 2009 -0300
> +++ b/v4l2-spec/Makefile	Sat Aug 15 16:32:08 2009 -0300
> @@ -5,6 +5,7 @@
>  SGMLS = \
>  	biblio.sgml \
>  	capture.c.sgml \
> +	v4l2grab.c.sgml \
>  	common.sgml \
>  	compat.sgml \
>  	controls.sgml \
> @@ -20,6 +21,7 @@
>  	dev-sliced-vbi.sgml \
>  	dev-teletext.sgml \
>  	driver.sgml \
> +	libv4l.sgml \
>  	entities.sgml \
>  	fdl-appendix.sgml \
>  	func-close.sgml \
> @@ -323,6 +325,12 @@
>  	-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 @@
>  	  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 @@
>  	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 -r ee300d3178c4 v4l2-spec/libv4l.sgml
> --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
> +++ b/v4l2-spec/libv4l.sgml	Sat Aug 15 16:32:08 2009 -0300
> @@ -0,0 +1,143 @@
> +<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 op of video4linux2 devices. The purpose of this (thin) layer is to make

"on top"

> +it easy for application writers to support a wide variety of devices without
> +having to write seperate code for different devices in the same class.</para>

"separate"

> +<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 different

remove "different",

> +several different pixelformats found at V4L2 drivers into a few common RGB and

because it's here already ("several different").

"found at" -> "found in"

> +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 improve webcam video quality on a software

"to improve"

Remove "on a software basis"

> +basis. The video processing is plit in to 2 parts: libv4lconvert/control and

"split in two parts"

> +libv4lconvert/processing.</para>
> +
> +		<para>The control part is used to offer video controls which can
> +be used	to control he video processing functions made available by

"control the video"

> +	libv4lconvert/processing. These controls are stored application wide
> +(untill	reboot) by using a persistent shared memory object.</para>

"until reboot"

> +
> +		<para>libv4lconvert/processing offers the actual video
> +processing functionality.</para>

I hope that Hans or someone else can document the v4lconvert functions in
detail in the future.

> +	</section>
> +	<section>
> +		<title>libv4l1</title>
> +		<para>This library offers functions that can by used to quickly

"be used"

> +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 on new applications.</para>

"used for"

> +	</section>
> +	<section>
> +		<title>libv4l2</title>
> +		<para>This library should be used on all modern V4L2 application

"used for"

> +		</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>On most cases, libv4l2 just passes the calls directly

"In most cases"

> +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> and
> +<link linkend='VIDIOC-G-FMT'><constant>VIDIOC_S_FMT</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 at the driver.

"in the driver"

> +<link linkend='VIDIOC-ENUM-FMT'><constant>VIDIOC_ENUM_FMT</constant></link> keep
> +enumerating the hardware supported formats.

"keeps".

Actually, you might want to rewrite this ENUM_FMT description, since I'm not
quite sure what you want to say here. I think what you mean is something like
this:

"VIDIOC_ENUM_FMT still enumerates the hardware supported formats, but the
emulated formats are added at the end."

We should mention that ENUM_FRAMESIZES and ENUM_FRAMEINTERVALS are also
intercepted.

> +</para>
> +		<section id="libv4l-ops">
> +			<title>Libv4l device control functions</title>
> +			<para>The common file operation methods are provided by
> +libv4l. They work like the non-v4l2 ones:</para>

"They work like the non-v4l2 ones:": That makes no sense to me, what does
"non-v4l2" mean in this context?

> +			<para>v4l2_open(const char *file, int oflag, ...) -
> +operates like the standard <link linkend='func-open'>open()</link> function.
> +</para>
> +
> +			<para>int v4l2_close(int fd) -
> +operates like the standard <link linkend='func-close'>close()</link> function.
> +</para>
> +
> +			<para>int v4l2_dup(int fd) -
> +operates like the standard dup() function, duplicating a file handler.
> +</para>
> +
> +			<para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
> +operates like the standard <link linkend='func-ioctl'>ioctl()</link> function.
> +</para>
> +
> +			<para>int v4l2_read (int fd, void* buffer, size_t n) -
> +operates like the standard <link linkend='func-read'>read()</link> function.
> +</para>
> +
> +			<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>
> +
> +			<para>int v4l2_munmap(void *_start, size_t length); -
> +operates like the standard <link linkend='func-munmap'>munmap()</link> function.
> +</para>
> +		</section>

The description of v4l2_fd_open is missing.

> +	</section>
> +	<section>
> +
> +		<title>v4l1compat.so wrapper library</title>
> +
> +		<para>This library intercept calls to V4L2

"intercepts"

> +open/close/ioctl/mmap/mmunmap operations and redirects to the libv4lX

"redirects them"

> +counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so.</para>
> +		<para>It allows usage of binary legacy applications that
> +still don't use libv4l.</para>

Is this description really correct? Based on the name of the wrapper I would
say that this is a library has something to do with V4L1 compatibility, yet
the description makes no mention of that.

> +	</section>
> +
> +</section>
> +<!--
> +Local Variables:
> +mode: sgml
> +sgml-parent-document: "v4l2.sgml"
> +indent-tabs-mode: nil
> +End:
> +-->
> diff -r ee300d3178c4 v4l2-spec/v4l2.sgml
> --- a/v4l2-spec/v4l2.sgml	Fri Aug 14 01:48:42 2009 -0300
> +++ b/v4l2-spec/v4l2.sgml	Sat Aug 15 16:32:08 2009 -0300
> @@ -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 @@
>        </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 @@
>        <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 @@
>  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 @@
>      &sub-driver;
>    </chapter>
>  
> +  <chapter id="libv4l">
> +    &sub-libv4l;
> +  </chapter>
> +
>    <chapter id="compat">
>      &sub-compat;
>    </chapter>
> @@ -485,6 +509,14 @@
>      &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;
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 

Very good to see this documented in the spec! Thanks for this work!

Regards,

	Hans

-- 
Hans Verkuil - video4linux developer - sponsored by TANDBERG Telecom

^ permalink raw reply	[flat|nested] 3+ messages in thread
* Re: [PATCH] Document libv4l at V4L2 API specs
  2009-08-16  7:42 ` Hans Verkuil
@ 2009-08-16 23:29   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2009-08-16 23:29 UTC (permalink / raw)
  To: Hans Verkuil; +Cc: linux-media

Hi Hans,

Em Sun, 16 Aug 2009 09:42:20 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> Hi Mauro,
> 
> I've done a quick review of the text. See comments below.

Thank you for the review! I've addressed your points. I'll commit it. Later, it
can improved as needed.

> > +		<para>libv4lconvert/processing offers the actual video
> > +processing functionality.</para>
> 
> I hope that Hans or someone else can document the v4lconvert functions in
> detail in the future.

Yes, that would be great.

> > +<link linkend='VIDIOC-ENUM-FMT'><constant>VIDIOC_ENUM_FMT</constant></link> keep
> > +enumerating the hardware supported formats.
> 
> "keeps".
> 
> Actually, you might want to rewrite this ENUM_FMT description, since I'm not
> quite sure what you want to say here. I think what you mean is something like
> this:
>
> "VIDIOC_ENUM_FMT still enumerates the hardware supported formats, but the
> emulated formats are added at the end."

Ok, I changed it to:

VIDIOC_ENUM_FMT keeps enumerating the hardware supported formats, plus the
emulated formats offered by libv4l at the end.

> The description of v4l2_fd_open is missing.

Added, together with the get/set control functions.

> > +counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so.</para>
> > +		<para>It allows usage of binary legacy applications that
> > +still don't use libv4l.</para>
> 
> Is this description really correct? Based on the name of the wrapper I would
> say that this is a library has something to do with V4L1 compatibility, yet
> the description makes no mention of that.

It also emulates V4L1 calls. Changed it to:

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.



Cheers,
Mauro

^ permalink raw reply	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2009-08-16 23:29 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-08-15 19:37 [PATCH] Document libv4l at V4L2 API specs Mauro Carvalho Chehab
2009-08-16  7:42 ` Hans Verkuil
2009-08-16 23:29   ` Mauro Carvalho Chehab

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.