v4l2-library: global files

From: Hans de Goede <j.w.r.degoede at hhs.nl>

Global files to make the libv4l compile, install and exported into a tar.gz file

Signed-off-by: Hans de Goede <j.w.r.degoede at hhs.nl>
Signed-off-by: Thierry MERLE <thierry.merle@free.fr>

6 files changed, 294 insertions, 0 deletions

diff --git a/v4l2-apps/lib/libv4l/ChangeLog b/v4l2-apps/lib/libv4l/ChangeLog
new file mode 100644
index 000000000..e7b899085
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/ChangeLog
@@ -0,0 +1,107 @@
+libv4l-0.3
+----------
+* add extern "C" magic to public header files for c++ usage (Gregor Jasny)
+* Make libv4l1 and libv4l2 multithread use safe, see README.multi-threading
+* Add v4lx_dup() calls (and intercept dup() from the wrappers) this fixes
+  use with gstreamer's v4l2 plugin (tested with cheese)
+* Hopefully definitely fix compile errors on systems with a broken videodev2.h
+
+libv4l-0.2
+----------
+*** API change ***
+* Change v4lconvert api so that the v4lconvert struct always gets allocated
+  by the library, this to make it opaque, so that we can avoid future API
+  and ABI changes
+* Add support for yuv420 -> bgr24 conversion
+* When converting from v4l2 pixelformat to v4l12 palette return
+  VIDEO_PALETTE_YUV420P instead of VIDEO_PALETTE_YUV420 for
+  V4L2_PIX_FMT_YUV420 as that is what most apps seem to expect
+* override kernel v4l1 compat min / max size with our own more accurate values
+* fix v4l1 munmap bug where it didn't recognise the buffer being unmapped was
+  our fake buffer (fixes gstreamer v4l1 support, checked with cheese)
+* add support for reporting the emulated pixelformats with ENUM_FMT, this
+  defaults to off, and can be activated by passing a flag to enable it to
+  v4l2_fd_open. This gets enabled by default the wrappers.
+* v4l2: mmap the real device buffers before doing conversion when DQBUF gets
+  called before the application has called mmap (avoid crash).
+
+
+libv4l-0.1
+----------
+* major shuffle / rewrite now split into libv4l1, libv4l2, libv4lconvert
+  and 2 wrappers for binary compatibility
+* rewritten LGPL bayer decoding
+* many many other changes and fixes
+
+
+v4l1-compat-0.6 (V4L2 apps stay working)
+----------------------------------------
+* Do not go into emulation mode of rgb24 immediately, but only after a
+  GPICT ioctl which has not been preceded by a SPICT ioctl, AKA do not get
+  in the way of V4L2 read calls by doing conversion on them
+* Do not get in the way of mmap calls made by V4L2 applications
+* Fix swapping of red and blue in bayer -> bgr24 decode routine
+* Remember the v4l1 palette asked for with SPICT and return that, as
+  otherwise we loose information when going v4l1 -> v4l2 -> v4l1, for example
+  YUV420P becomes YUV420, which are separate in v4l1.
+
+
+v4l1-compat-0.5 (perfect camorama)
+----------------------------------
+* Allow changing of format after the buffers have been mapped, by tearing
+  down the entire house, changing the fundament and then rebuilding it.
+  Now changing the capture resolution in camorama works!
+* Fix jpeg decoding error reporting
+* Allow jpeg's with a height which is a multiple of 8 (was 16)
+* Remove a number of pretty new VIDIOCXXX -> string mappings from log.c,
+  fixing compiling with somewhat older kernels
+
+
+v4l1-compat 0.4
+---------------
+* Do not even try to change the format in v4l1_compat_set_format(), unless
+  _really_ necessary.
+* Cleanup ambigious use of src_format (no functional changes)
+* Drop the mmap hack for zerocopy access under certain conditions, one of them
+  that the cam can deliver the requested format. Although avoiding the
+  memcpy in this scenarios is a good thing todo, there were several issues
+  with the 0.3 implementation of this, fixing all these means adding lots of
+  special cases all over the code. So instead we just drop support and
+  always do atleast a memcpy (or a conversion). If an application cannot
+  live with the speed penalty this imposes it should be ported to v4l2.
+* Now that we've gotten rid of the zerocopy mmap hack, we can safely allow
+  mixing read and mmap based IO.
+* Explictly include linux/ioctl.h, to fix compile with kernel headers where
+  linux/videodev.h doesn't.
+
+
+v4l1-compat 0.3
+---------------
+* Don't allow multiple opens, in theory our code can handle it, but not all
+  v4l2 devices like it (ekiga does it and uvc doesn't like it).
+
+
+v4l1-compat 0.2
+---------------
+* When mmap gets passed an fd of -1 (anonymous map) don't look for it in our
+  list of managed fds, as we use -1 to mark unused entries (fixes ekiga
+  crashing). Also check for an fd of -1 in the other calls we intercept.
+* In close() start with removing the fd from our list of managed fds, this must
+  be done first, because as soon as we've done the actual close syscall, the
+  fd maybe returned by an open in another thread and we don't want to intercept
+  calls to this new fd.
+* Make unknown v4l1 palette types a normal level log messages instead of an
+  error.
+* When an applicaiton changes the width / height through the CMCAPTURE ioctl
+  remember the new width and height.
+* If the devices initial v4l2 pixformat has no corresponding v4l1 palette, try
+  setting a format which does (and which we emulate when necessary) so that
+  applicactions which just query the current format (GPICT) and then take
+  whatever they get will work (partially fixes camorama)
+* Implement our own SWIN instead of using kernel compat layer, for more
+  flexibility and better error checking
+
+
+v4l1-compat 0.1
+---------------
+* Initial public release.
diff --git a/v4l2-apps/lib/libv4l/INSTALL b/v4l2-apps/lib/libv4l/INSTALL
new file mode 100644
index 000000000..b8eb042ee
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/INSTALL
@@ -0,0 +1,4 @@
+To compile simply type "make" after that you can find the compiled libraries
+and wrappers under the lib dir, public headers are under the include dir.
+
+Sorry no make install target for now.
diff --git a/v4l2-apps/lib/libv4l/Makefile b/v4l2-apps/lib/libv4l/Makefile
new file mode 100644
index 000000000..78c6893a3
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/Makefile
@@ -0,0 +1,16 @@
+LIB_RELEASE=0
+V4L2_LIB_VERSION=$(LIB_RELEASE).3
+
+all clean install:
+	$(MAKE) -C libv4lconvert $@
+	$(MAKE) -C libv4l2 $@
+	$(MAKE) -C libv4l1 $@
+
+export: clean
+	mkdir /tmp/libv4l-$(V4L2_LIB_VERSION)
+	cp -a . /tmp/libv4l-$(V4L2_LIB_VERSION)/
+	cd /tmp/ && \
+		tar cvf /tmp/libv4l-$(V4L2_LIB_VERSION).tar\
+		libv4l-$(V4L2_LIB_VERSION)
+	gzip /tmp/libv4l-$(V4L2_LIB_VERSION).tar
+	rm -rf /tmp/libv4l-$(V4L2_LIB_VERSION)
diff --git a/v4l2-apps/lib/libv4l/README b/v4l2-apps/lib/libv4l/README
new file mode 100644
index 000000000..c588947b5
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/README
@@ -0,0 +1,129 @@
+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 Library General Publishing
+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 libv4l1 wrapper which
+adds v4l2 device compatibility to v4l1 applications is called v4l2convert.so
+
+Example usage:
+$ export LD_LIBRARY_PATH=`pwd`/lib
+$ export LD_PRELOAD=`pwd`/lib/v4l1compat.so
+$ camorama
+
+
+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.
diff --git a/v4l2-apps/lib/libv4l/README.multi-threading b/v4l2-apps/lib/libv4l/README.multi-threading
new file mode 100644
index 000000000..93b393c8c
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/README.multi-threading
@@ -0,0 +1,12 @@
+libv4lconvert is not safe for using one convert instance as returned by
+v4lconvert_create from multiple threads, if you want to use one v4lconvert
+instance from multiple threads you must provide your own locking and make
+sure no simultanious calls are made.
+
+libv4l1 and libv4l2 are safe for multithread use *under* *the* *following*
+*conditions* :
+
+* when using v4lx_fd_open, do not make any v4lx_ calls to the passed fd until
+  v4lx_fd_open has completed
+
+* all v4lx_ calls must be completed before calling v4lx_close
diff --git a/v4l2-apps/lib/libv4l/TODO b/v4l2-apps/lib/libv4l/TODO
new file mode 100644
index 000000000..0170e6b14
--- /dev/null
+++ b/v4l2-apps/lib/libv4l/TODO
@@ -0,0 +1,26 @@
+-protect open() against being called from different threads simultaniously,
+ we are then thread safe except for the jpeg decompression under the following
+ assumption:
+ * We assume all device setup (for a single device) is done from a single
+   thread
+ * We assume that at the time an videodev fd gets closed all other threads
+   which may have been using it have stopped using it.
+
+-add support for setting / getting the number of read buffers
+
+-add code to v4l2_read to not return frames more then say 5 seconds old
+
+-add support for libv4l1 for non pure capture (combined capture and overlay)
+ devices so that atleast CGMBUF emulation (but no conversion, as thats
+ impossible for overlays) can be done, so that it will no longer be
+ necessary to implement CGMBUF in the kernel for each driver.
+
+-add (configurable) support for alsa faking enum_fmt to libv4l2 ?
+
+-check v4l2_field during conversion
+
+-add make install target
+
+-add conversion from bgr24 to yuv420
+
+-add v4l2_dup, make re-entrant safe (for gstreamer v4l2 support)