1 files changed, 141 insertions, 0 deletions
diff --git a/v4l2-apps/libv4l/README b/v4l2-apps/libv4l/README
new file mode 100644
index 000000000..3a2059224
--- /dev/null
+++ b/v4l2-apps/libv4l/README
@@ -0,0 +1,141 @@
+Introduction
+------------
+
+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 seperate code for different devices in the same class.
+
+All libv4l components are licensed under the GNU Lesser General Public
+License version 2 or (at your option) any later version.
+
+libv4l consists of 3 different libraries:
+
+
+libv4lconvert
+-------------
+
+libv4lconvert offers functions to convert from any (known) pixelformat
+to V4l2_PIX_FMT_BGR24 or V4l2_PIX_FMT_YUV420.
+
+Currently the following source formats are supported:
+jpeg, mjpeg, bayer (all 4 variants: bggr, rggb, gbrg, grbg),
+spca501 (chip specific yuv 420 with interlaced components),
+spca561 (chip specific compressed gbrg bayer)
+For more details on the v4lconvert_ functions see libv4lconvert.h .
+
+
+libv4l1
+-------
+
+This offers functions like v4l1_open, v4l1_ioctl, etc. which 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. For more details on the v4l1_ functions see libv4l1.h .
+
+
+libv4l2
+-------
+
+This offers functions like v4l2_open, v4l2_ioctl, etc. which can by used to
+quickly make v4l2 applications work with v4l2 devices with weird formats.
+libv4l2 mostly passes calls directly through to the v4l2 driver. When the
+app does a TRY_FMT / S_FMT with a not supported format libv4l2 will get in
+the middle and emulate the format (if an app wants to know which formats the
+hardware can _really_ do it should use ENUM_FMT, not randomly try a bunch of
+S_FMT's). For more details on the v4l2_ functions see libv4l2.h .
+
+
+wrappers
+--------
+
+The functionality provided by libv4l1 for v4l1 apps and libv4l2 for v4l2 apps
+can also be used by existing apps without modifying them. For this purpose
+2 wrapper libraries are provided which can be preloaded before starting the
+application using the LD_PRELOAD environment variable. These wrappers will
+then intercept calls to open/close/ioctl/etc. and if these calls directed
+towards a video device the wrapper will redirect the call to the libv4lX
+counterparts.
+
+The preloadable libv4l1 wrapper which adds v4l2 device compatibility to v4l1
+applications is called v4l1compat.so. The preloadable libv4l2 wrapper which
+adds support for various pixelformats to v4l2 applications is called
+v4l2convert.so.
+
+Example usage (after install in default location):
+$ export LD_PRELOAD=/usr/local/lib/libv4l/v4l1compat.so
+$ camorama
+
+
+Installation Instructions
+-------------------------
+
+Simple type the following commands from the libv4l-x.y.z directory
+(adjusting PREFIX as desired):
+make
+make install PREFIX=/usr/local
+
+Note: make install also supports the DESTDIR=... paramter for installation
+into chroots.
+
+
+FAQ
+---
+
+Q: Why libv4l, whats wrong with directly accessing v4l2 devices ?
+Q: Do we really need yet another library ?
+A: Current webcam using applications like ekiga contain code to handle many
+different specific pixelformats webcam's use, but that code only supports a
+small subset of all native webcam (compressed) pixelformats. Other current
+v4l2 applications do not support anything but rgb pixelformats (xawtv for
+example) and this will not work with most webcams at all.
+
+With gspca being ported to v4l2 and thus decoding to normal formats being
+removed from the device driver as this really belongs in userspace, ekiga
+would need to be extended with many more often chip dependent formats, like
+the bayer compression used by the spca561 and the (different) compression used
+by the pac207 and the (again different) compression used by the sn9c102. Adding
+support for all these formats should not be done at the application level, as
+then it needs to be written for each application seperately. Licensing issues
+with the decompressors will then also become a problem as just cut and pasting
+from one application to another is bound to hit license incompatibilities.
+
+So clearly this belongs in a library, and in a library with a license which
+allows this code to be used from as many different applications as possible.
+Hence libv4l was born.
+
+Q: Under which license may I use and distribute libv4l?
+A: All libv4l components are licensed under the GNU Library General Publishing
+License version 2 or (at your option) any later version. See the included
+COPYING.LIB file.
+
+Q: Okay so I get the use of having a libv4lconvert, but why libv4l1 ?
+A: Many v4l2 drivers do not offer full v4l1 compatibility. They often do not
+implemented the CGMBUF ioctl and v4l1 style mmap call. Adding support to all
+these drivers for this is a lot of work and more importantly unnecessary
+adds code to kernel space.
+
+Also even if the CGMBUF ioctl and v4l1 style mmap are supported, then most
+cams still deliver pixelformats which v4l1 applications do not understand.
+
+This libv4l1 was born as an easy way to get v4l1 applications to work with
+v4l2 devices without requiring full v4l1 emulation (including format
+conversion) in the kernel, and without requiring major changes to the
+applications.
+
+
+Q: Why should I use libv4l2 in my app instead of direct device access
+combined with libv4lconvert?
+
+libv4l2 is mainly meant for quickly and easily adding support for more
+pixelformats to existing v4l2 applications. So if you feel better directly
+accessing the device in combination with libv4lconvert thats fine too.
+
+Notice that libv4l2 also does emulation of the read() call on devices which
+do not support it in the driver. In the background this uses mmap buffers
+(even on devices which do support the read call). This mmap gives libv4lconvert
+zero-copy access to the captured frame, and then it can write the converted
+data directly to the buffer the application provided to v4l2_read(). Thus
+another reason to use liv4l2 is to get the no memcpy advantage of the mmap
+capture method combined with the simplicity of making a simple read() call.