Webcam Library and Tools ======================== Introduction ------------ The webcam-tools package contains the following two components: - libwebcam Webcam Library - uvcdynctrl Manage dynamic controls in uvcvideo This README file contains information that is common to all of the above components. For component specific information please refer to the README files in the libwebcam/ and uvcdynctrl/ subdirectories. Versions -------- Note that the latest versions of the Webcam Library, its API documentation, and the tools can always be found at the following address: QuickCam Team http://www.quickcamteam.net/ Dependencies ------------ The Webcam Tools have the following external dependencies: - Linux UVC driver (uvcvideo) interface header file or source files - LibXML 2 development files (usually from the libxml2-dev package) - gengetopt (optional) - V4L2 2.6.32 (optional) Linux UVC driver (uvcvideo) interface header file or source files: Unless the USE_UVCVIDEO constant is disabled (it is enabled by default), libwebcam needs the uvcvideo.h header file from the Linux UVC driver (uvcvideo). If the build system cannot find the required header file the following error is shown at build time: "Linux UVC Driver include file (linux/uvcvideo.h or uvcvideo.h) not found. Try adding -DUVCVIDEO_INCLUDE_PATH=... to specify its path." Starting with kernel 2.6.26 the uvcvideo driver is part of the kernel. You can find it in the directory drivers/media/video/uvc. If your kernel is older than that you may download a historic stand-alone version from the uvcvideo project's home page at http://linux-uvc.berlios.de/ or directly from the Subversion repository at: http://svn.berlios.de/svnroot/repos/linux-uvc/linux-uvc/trunk/ Starting with kernel 2.6.38 or 2.6.39 (at the time of writing this isn't clear yet) the uvcvideo.h header file has been made public and moved to the standard include/linux/ directory. Therefore it is no longer necessary to obtain the kernel sources. Installing the kernel headers is enough. Either way, you need to add the path where uvcvideo.h is located to the CMake UVCVIDEO_INCLUDE_PATH variable before calling cmake unless it is already located in one of your default include directories: # For pre-2.6.38/39 kernels cmake -DUVCVIDEO_INCLUDE_PATH=.../linux/drivers/media/video/uvc .. # For 2.6.38/39 kernels and newer without the kernel headers installed cmake -DUVCVIDEO_INCLUDE_PATH=.../linux/include .. The older methods using environment variables and CMAKE_INCLUDE_PATH are no longer supported. gengetopt (optional): The uvcdynctrl directory ships with the two files cmdline.[ch]. As long as those are present, gnugetopt is not required. If they are missing, the build process will try to create them with the help of gnugetopt. V4L2 2.6.32 (optional): (Note that this is an advanced feature that most users won't need and doesn't work without a modified uvcvideo driver.) To take advantage of the raw/string control support version 2.6.32 of V4L2 is required. To be more specific: V4L2_CTRL_TYPE_STRING needs to be supported. Whether this is the case is determined at build time and if string control support is not present in your version of V4L2 the corresponding feature in libwebcam is disabled. During the build process one of the following messages is displayed indicating the result of the test: ** Your V4L2 has V4L2_CTRL_TYPE_STRING support. Enabling raw control support. ** Your V4L2 does NOT have V4L2_CTRL_TYPE_STRING support. Compiling WITHOUT raw control support. Note that the uvcvideo version that comes with 2.6.32 does not yet support string controls. At the time of this writing support for it is being added to the UVC driver, so future versions should support it, therefore allowing V4L2 control values to be more than 4 bytes long. If you need to specify the location of the V4L2 header files (videodev2.h) explicitly you can use the V4L2_INCLUDE_PATH CMake variable like this: cmake -DUVCVIDEO_INCLUDE_PATH=.../linux/include \ -DV4L2_INCLUDE_PATH=.../linux/include .. Building -------- The build system is based on CMake. Because of the way CMake works, Makefiles do not ship with libwebcam, so you have to have CMake installed. Don't worry, though, you are likely to have much fewer illegible error messages than with the previous GNU Automake. Once you have CMake installed you can build and install it by running the following commands in the webcam-tools top level source directory: mkdir build cd build cmake .. make make install (as root) You need at least CMake 2.6, so if you are running Ubuntu 8.04 you need to enable the hardy-backports repository in /etc/apt/sources.list and update the 'cmake' package. CMake defaults to installing binaries and libraries to /usr/local. To use a different install prefix, you can add a command line parameter to 'cmake' like this: cmake .. -DCMAKE_INSTALL_PREFIX=/usr If you prefer to leave the prefix alone, you should make sure that /usr/local/bin is in your path and LD_LIBRARY_PATH contains the /usr/local/lib directory. Packaging --------- Packaging the binaries is a little unusual and doesn't use the normal 'make package' way that CMake suggests. The reason for this is that we want libwebcam and uvcdynctrl in one build, but the CMake packager can only ever create one package per build. Because we want separate packages for the different components packing has to be launched separately for each component. There are two methods to accomplish this: Method A: Run CPack manually The necessary configuration files for running CPack are generated during the normal build from the CPackConfig.cmake.conf template in the common/build/ directory. You can run cpack by specifying these as follows: 1. Build the package as described above and make sure that the current directory is still ./build (from where cmake was run). 2. cpack --config libwebcam/CPackConfig.cmake This creates a .tar.bz2 archive and a .deb package for libwebcam. 3. cpack --config uvcdynctrl/CPackConfig.cmake This creates a .tar.bz2 archive and a .deb package for uvcdynctrl. Method B: Run CMake for each component Instead of creating a 'build' directory at the top level and then running 'cmake ..' you can do the same thing once under the libwebcam/ and once under the uvcdynctrl/ directory and then launch the packaging process: mkdir libwebcam/build cd libwebcam/build cmake .. make package cd ../.. mkdir uvcdynctrl/build cd uvcdynctrl/build cmake .. make package Questions and feedback ---------------------- There is a forum for developers and users of the Webcam Library. Please feel free to post your questions and comments: QuickCam Team discussion forums http://forums.quickcamteam.net/