diff options
Diffstat (limited to 'v4l2-apps')
| -rw-r--r-- | v4l2-apps/lib/libv4l/ChangeLog | 107 | ||||
| -rw-r--r-- | v4l2-apps/lib/libv4l/INSTALL | 4 | ||||
| -rw-r--r-- | v4l2-apps/lib/libv4l/Makefile | 16 | ||||
| -rw-r--r-- | v4l2-apps/lib/libv4l/README | 129 | ||||
| -rw-r--r-- | v4l2-apps/lib/libv4l/README.multi-threading | 12 | ||||
| -rw-r--r-- | v4l2-apps/lib/libv4l/TODO | 26 |
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) |