From patchwork Sat Aug 15 19:37:26 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 41648 X-Patchwork-Delegate: mchehab@redhat.com Received: from vger.kernel.org (vger.kernel.org [209.132.176.167]) by demeter.kernel.org (8.14.2/8.14.2) with ESMTP id n7FJbcYV018818 for ; Sat, 15 Aug 2009 19:37:39 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751192AbZHOThd (ORCPT ); Sat, 15 Aug 2009 15:37:33 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1751684AbZHOThd (ORCPT ); Sat, 15 Aug 2009 15:37:33 -0400 Received: from bombadil.infradead.org ([18.85.46.34]:51867 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751192AbZHOThc (ORCPT ); Sat, 15 Aug 2009 15:37:32 -0400 Received: from 189-46-174-98.dsl.telesp.net.br ([189.46.174.98] helo=caramujo.chehab.org) by bombadil.infradead.org with esmtpsa (Exim 4.69 #1 (Red Hat Linux)) id 1McP4F-00067J-8N for linux-media@vger.kernel.org; Sat, 15 Aug 2009 19:37:33 +0000 Date: Sat, 15 Aug 2009 16:37:26 -0300 From: Mauro Carvalho Chehab To: linux-media@vger.kernel.org Subject: [PATCH] Document libv4l at V4L2 API specs Message-ID: <20090815163726.5f4bae41@caramujo.chehab.org> X-Mailer: Claws Mail 3.3.1 (GTK+ 2.10.4; x86_64-redhat-linux-gnu) Mime-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org See http://www.infradead.org/rpr.html Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org 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 for his good work with libv4l. Signed-off-by: Hans de Goede Signed-off-by: Mauro Carvalho Chehab --- 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 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 + Copyright (C) 2009 Mauro Carvalho Chehab 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_]\+\) /\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 "$$1,\n"; };' \ + |sort|uniq| \ + sed -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" > $@ + capture.c.sgml: ../v4l2-apps/test/capture-example.c Makefile echo "" > $@ expand --tabs=8 < $< | \ @@ -330,6 +338,13 @@ sed 's/i\.e\./&ie;/' >> $@ echo "" >> $@ +v4l2grab.c.sgml: ../v4l2-apps/test/v4l2grab.c Makefile + echo "" > $@ + expand --tabs=8 < $< | \ + sed $(ESCAPE) $(DOCUMENTED) | \ + sed 's/i\.e\./&ie;/' >> $@ + echo "" >> $@ + videodev2.h.sgml: ../linux/include/linux/videodev2.h Makefile echo "" > $@ 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 @@ +Libv4l Userspace Library +
+ Introduction + + 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. +An example of using libv4l is provided by +v4l2grab. + + + libv4l consists of 3 different libraries: +
+ libv4lconvert + + libv4lconvert is a library that converts different +several different pixelformats found at V4L2 drivers into a few common RGB and +YUY formats. + It currently accepts the following V4L2 driver formats: +V4L2_PIX_FMT_BGR24, +V4L2_PIX_FMT_HM12, +V4L2_PIX_FMT_JPEG, +V4L2_PIX_FMT_MJPEG, +V4L2_PIX_FMT_MR97310A, +V4L2_PIX_FMT_OV511, +V4L2_PIX_FMT_OV518, +V4L2_PIX_FMT_PAC207, +V4L2_PIX_FMT_PJPG, +V4L2_PIX_FMT_RGB24, +V4L2_PIX_FMT_SBGGR8, +V4L2_PIX_FMT_SGBRG8, +V4L2_PIX_FMT_SGRBG8, +V4L2_PIX_FMT_SN9C10X, +V4L2_PIX_FMT_SN9C20X_I420, +V4L2_PIX_FMT_SPCA501, +V4L2_PIX_FMT_SPCA505, +V4L2_PIX_FMT_SPCA508, +V4L2_PIX_FMT_SPCA561, +V4L2_PIX_FMT_SQ905C, +V4L2_PIX_FMT_SRGGB8, +V4L2_PIX_FMT_UYVY, +V4L2_PIX_FMT_YUV420, +V4L2_PIX_FMT_YUYV, +V4L2_PIX_FMT_YVU420, +and V4L2_PIX_FMT_YVYU. + + 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. + + 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. + + libv4lconvert/processing offers the actual video +processing functionality. +
+
+ libv4l1 + 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. + Since those functions are emulations of the old V4L1 API, +it shouldn't be used on new applications. +
+
+ libv4l2 + This library should be used on all modern V4L2 application + + 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. + On most cases, libv4l2 just passes the calls directly +through to the v4l2 driver, intercepting the calls to +VIDIOC_TRY_FMT, +VIDIOC_G_FMT and +VIDIOC_S_FMT in order +to emulate the formats V4L2_PIX_FMT_BGR24, +V4L2_PIX_FMT_RGB24, +V4L2_PIX_FMT_YUV420, +and V4L2_PIX_FMT_YVU420, +if they aren't available at the driver. +VIDIOC_ENUM_FMT keep +enumerating the hardware supported formats. + +
+ Libv4l device control functions + The common file operation methods are provided by +libv4l. They work like the non-v4l2 ones: + v4l2_open(const char *file, int oflag, ...) - +operates like the standard open() function. + + + int v4l2_close(int fd) - +operates like the standard close() function. + + + int v4l2_dup(int fd) - +operates like the standard dup() function, duplicating a file handler. + + + int v4l2_ioctl (int fd, unsigned long int request, ...) - +operates like the standard ioctl() function. + + + int v4l2_read (int fd, void* buffer, size_t n) - +operates like the standard read() function. + + + void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); - +operates like the standard mmap() function. + + + int v4l2_munmap(void *_start, size_t length); - +operates like the standard munmap() function. + +
+
+
+ + v4l1compat.so wrapper library + + 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. + It allows usage of binary legacy applications that +still don't use libv4l. +
+ +
+ 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 @@ Video for Linux Two API Specification - Revision 0.26 + Revision 0.27 @@ -92,6 +92,18 @@ + + Mauro + Carvalho Chehab + Documented libv4l, designed and added v4l2grab example + + +
+ mchehab@redhat.com +
+ + + 1999 2000 @@ -105,12 +117,13 @@ 2008 2009 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls +Rubli, Andy Walls, Mauro Carvalho Chehab This document is copyrighted © 1999-2009 by Bill -Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, and Andy Walls. +Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls and +Mauro Carvalho Chehab. 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. --> + 0.27 + 2009-08-15 + mcc + Added libv4l documentation and v4l2grab example. + + + 0.26 2009-06-15 hv @@ -471,6 +491,10 @@ &sub-driver; + + &sub-libv4l; + + &sub-compat; @@ -485,6 +509,14 @@ &sub-capture-c; + + Video Grabber example using libv4l + 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. + &sub-v4l2grab-c; + + &sub-fdl-appendix; &sub-indices;