Re: [PATCH] Document libv4l at V4L2 API specs

2009-08-16 Thread Hans Verkuil 
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 +
 +++ b/v4l2-spec/libv4l.sgml   Sat Aug 15 16:32:08 2009 -0300
 @@ -0,0 +1,143 @@
 +titleLibv4l Userspace Library/title
 +section id=libv4l-introduction
 + titleIntroduction/title
 +
 + paralibv4l 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

 +paraAn example of using libv4l is provided by
 +link linkend='v4l2grab-example'v4l2grab/link.
 +/para
 +
 + paralibv4l consists of 3 different libraries:/para
 + section
 + titlelibv4lconvert/title
 +
 + paralibv4lconvert 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
 + paraIt currently accepts the following V4L2 driver formats:
 +link 
 linkend=V4L2-PIX-FMT-BGR24constantV4L2_PIX_FMT_BGR24/constant/link,
 +link 
 linkend=V4L2-PIX-FMT-HM12constantV4L2_PIX_FMT_HM12/constant/link,
 +link 
 linkend=V4L2-PIX-FMT-JPEGconstantV4L2_PIX_FMT_JPEG/constant/link,
 +link 
 linkend=V4L2-PIX-FMT-MJPEGconstantV4L2_PIX_FMT_MJPEG/constant/link,
 +link 
 linkend=V4L2-PIX-FMT-MR97310AconstantV4L2_PIX_FMT_MR97310A/constant/link,
 +link 
 linkend=V4L2-PIX-FMT-OV511constantV4L2_PIX_FMT_OV511/constant/link,
 +link

Re: [PATCH] Document libv4l at V4L2 API specs

2009-08-16 Thread Mauro Carvalho Chehab 
Hi Hans,

Em Sun, 16 Aug 2009 09:42:20 +0200
Hans Verkuil hverk...@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.

  +   paralibv4lconvert/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'constantVIDIOC_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
  +   paraIt 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
--
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

[PATCH] Document libv4l at V4L2 API specs

2009-08-15 Thread Mauro Carvalho Chehab 
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/MakefileFri Aug 14 01:48:42 2009 -0300
+++ b/v4l2-spec/MakefileSat 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 +
+++ b/v4l2-spec/libv4l.sgml Sat Aug 15 16:32:08 2009 -0300
@@ -0,0 +1,143 @@
+titleLibv4l Userspace Library/title
+section id=libv4l-introduction
+   titleIntroduction/title
+
+   paralibv4l 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
+paraAn example of using libv4l is provided by
+link linkend='v4l2grab-example'v4l2grab/link.
+/para
+
+   paralibv4l consists of 3 different libraries:/para
+   section
+   titlelibv4lconvert/title
+
+   paralibv4lconvert is a library that converts different
+several different pixelformats found at V4L2 drivers into a few common RGB and
+YUY formats./para
+   paraIt currently accepts the following V4L2 driver formats:
+link 
linkend=V4L2-PIX-FMT-BGR24constantV4L2_PIX_FMT_BGR24/constant/link,
+link 
linkend=V4L2-PIX-FMT-HM12constantV4L2_PIX_FMT_HM12/constant/link,
+link 
linkend=V4L2-PIX-FMT-JPEGconstantV4L2_PIX_FMT_JPEG/constant/link,
+link 
linkend=V4L2-PIX-FMT-MJPEGconstantV4L2_PIX_FMT_MJPEG/constant/link,
+link 
linkend=V4L2-PIX-FMT-MR97310AconstantV4L2_PIX_FMT_MR97310A/constant/link,
+link 
linkend=V4L2-PIX-FMT-OV511constantV4L2_PIX_FMT_OV511/constant/link,
+link 
linkend=V4L2-PIX-FMT-OV518constantV4L2_PIX_FMT_OV518/constant/link,
+link 
linkend=V4L2-PIX-FMT-PAC207constantV4L2_PIX_FMT_PAC207/constant/link,
+link 
linkend=V4L2-PIX-FMT-PJPGconstantV4L2_PIX_FMT_PJPG/constant/link,
+link 
linkend=V4L2-PIX-FMT-RGB24constantV4L2_PIX_FMT_RGB24/constant/link,
+link