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 <hdego...@redhat.com> for his good work with libv4l.
> 
> Signed-off-by: Hans de Goede <hdego...@redhat.com>
> Signed-off-by: Mauro Carvalho Chehab <mche...@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 <mche...@infradead.org>
> +   Copyright (C) 2009 Mauro Carvalho Chehab <mche...@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>mche...@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 majord...@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
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to