	=================================================
	qc-usb: Logitech QuickCam USB Video Camera driver
	=================================================

QUICKSTART
----------
Type "./quickcam.sh" in the current directory and follow the instructions.

Requirements
------------
An USB camera with ST Microelectronics bridge chip and either VV6410,
HDCS-1000, HDCS-1020 or Photobit sensor. Usually Logitech QuickCams qualify,
but check if your camera is supported from http://qce-ga.sourceforge.net.
	Linux 2.2.x (x >= 18), 2.4.x, or 2.6.x (2.6.x is not yet well tested).
x86 is best tested, but the driver might also work on other architectures
(I got a success report on Alpha, but you need to edit the Makefile,
read comments in it). SMP appears to work too.

Where to get it?
----------------
Well, you're already reading this so you obviously should already have 
the driver too. But just in case, here's the important links:
	http://qce-ga.sourceforge.net
	http://sourceforge.net/projects/qce-ga
	http://sourceforge.net/project/showfiles.php?group_id=12924
To get the latest version under development, use anonymous CVS
at http://qce-ga.sourceforge.net.
Here may be also some interesting links and information:
	http://www.ee.oulu.fi/~tuukkat/quickcam/quickcam.html

How to install?
---------------
Just type "make clean && make all" to compile the driver. The resulting
driver file is "quickcam.o". Type "make" to get some installation options.
Especially you should consider disabling debugging, it will make the driver
about 30% smaller and faster. And if compressed mode is not supported with
your camera, you might want to compile the driver with
"USER_OPT=-DCOMPRESS=0 make all", which will save some more bytes.
	Note: /lib/modules/x.y.zz/build should be a symbolic link to your
kernel source. It is created automatically by "make modules_install" in
kernel source directory, but some distributions (such as Debian) might not
have it pre-installed correctly. You can make the link manually or by 
specifying alternate kernel source directory with LINUX_DIR=/usr/src/x.y.zz.
You can see the kernel version that you are running with "uname -r".
	The kernel source must be configured (with "make menuconfig", for
example) to have the same options as the kernel you will be running with the
camera. Also "make dep" must be performed in the kernel source directory
before the camera can be compiled against it. One way is to download fresh
kernel source into /usr/src/linux-x.y.zz, copy .config into the directory,
and then enter "make oldconfig && make dep". Then you can compile the
camera driver against the kernel source using the LINUX_DIR option, and
compile the kernel with "make bzImage && make modules", install the
kernel with "make modules_install" and running lilo, and install the camera
driver with "MODULE_DIR=/lib/modules/x.y.zz make install", and reboot.
You should also compile the kernel and the camera driver with same versions
of gcc. Check gcc version with "gcc -v" and the version which was used
for compiling the kernel with "cat /proc/version".
	Easier is just to install the kernel source package from your Linux
distribution and compile then the camera driver.
	The driver is accessed using either /dev/video or /dev/videoX
device file. If you are using devfs, it should appear automatically when
the driver is loaded. If not, you can create the file manually with
	mknod /dev/video0 c 81 0
	mknod /dev/video1 c 81 1
	chmod a+rw /dev/video0
	ln -s /dev/video0 /dev/video
as root.
If you still don't have a clue, ask from 
qce-ga-discussion@lists.sourceforge.net.

How to load?
------------
You need USB and Video4Linux support in your kernel. Check that they
are compiled, if not, reconfigure kernel, compile and install. It took
a long time to find the Video4Linux checkbox in 2.2, it is in 
	Character Devices / Video4Linux
When you have a supported kernel, just load the necessary drivers with
	modprobe videodev
	modprobe usb-uhci	# Either UHCI or OHCI,
	modprobe usb-ohci	# loading the another will fail
	insmod ./quickcam.o compatible=3
(or "modprobe quickcam" if you have already installed it).
If it works, you can install these lines into some startup script
in /etc to load the driver every time you boot up your computer.

How to run?
-----------
Check out the possible module parameters with "modinfo -p ./quickcam.o".
After the driver has been loaded, you can run your favorite camera software 
such as Xawtv, Motv, or Mplayer/Mencoder.
If some piece of program doesn't work, try enabling more compatibility levels:
	./qcset compatible=3
By default all compatibility is disabled, because it is the user applications
not the driver which should be fixed. Meanwhile, use either compatible=1
or 3.
Some programs that require compatible=1: anything using the Xvideo driver.
Some programs that require compatible=3: motion, vic.
	There's an utility called "qcset" that you can use to change
driver options on-the-fly. Run "./qcset -h" for more info. It is recommended
that you use qcset to change driver options instead of using module parameters
when loading the module with insmod. The module options might go away in
future, and you can set different options for each plugged camera only with
qcset.

Controls
--------
There are two ways to control the camera brightness, hue, etc.: either
using the automatic brightness control that changes the camera exposure time
and gain constantly, trying to match the values which is set into the
"brightness" setting. In this mode the "contrast" setting has no effect.
Another option is to disable automatic brightness control, and set it
manually instead. In this case "brightness" controls the exposure time
and "contrast" controls the global gain with VV6410 and Photobit sensors,
with HDCS-1000/1020 the controls are swapped. If "saturation" is more than 
32767, the "hue" setting will balance gains between red, green, and blue 
gains. Note that with VV6410 it is not possible to set different gains to
different primary colors, so with it the "hue" and "saturation" have no
effect.
	Photobit and HDCS sensor give the faster framerate, the smaller window
you use. VV6410 has constant framerate, independent of window size.
Reducing the window size will make field of view smaller.
With all cameras you can enable subsampling mode, which will give higher
framerate at full view of width (but gives no more resolution than simply
using smaller window size).
	Too big exposure time may slow down the frame rate. So you might
actually get better framerate at bright light, when the exposure time is kept 
short.

Reporting bugs
--------------
Please report about bugs to qce-ga-devel@lists.sourceforge.net. The
SourceForge has a bug tracking system, but unfortunately I don't follow
it much. The bug report should include:
- Camera name (e.g. QuickCam Express)
- Sensor type (load the driver and type "dmesg" right after or look
  from kernel log files, typically at /var/log/kern.log)
  (e.g. HDCS-1020)
- Camera ProductId and VendorId, or just run "lsusb" and copy all what
  it shows to the report. (lsusb is in package "usbutils" in Debian).
- Exact error messages and what applications you tried to use.
  If you get compile errors, compile e.g. with
	make all 2>&1 | tee errors.log
  This will save the errors in file errors.log.
- Kernel version and gcc version (use "cat /proc/version" and "gcc -v").
- cat /proc/video/quickcam/*
- Anything else you think could be useful.

The Story so Far
----------------
"Georg Acher had pulled the first picture out of the QuickCam Express. He 
posted a note on the qvix site with a link to his work saying that he didn't 
have time to do a V4L driver. I posted a note on a few LUGs and started a
project being far outclassed by Jean-Frederic Clere, who within 48 hours had 
made the first V4L driver and has been the rock that supported QuickCam 
Express. ... qce-ga was a project code, not actually a name: quickcam.sf.net 
had been taken by the QuickCam Pro. " (edited from Peter McConnell's mail)
(See README.qce about the qce-ga driver)
	Cristiano De Michele modified the qce-ga driver to support Logitech 
QuickCam Web. Unfortunately, his drivers had some problems: the drivers didn't
support compressed mode, without which the frame rate would be only 7.5 frames 
per second. 
	But then Jochen Hoenicke did something extraordinary: he reverse
engineered the compressed image format. Unfortunately, his hacked drivers were 
not Video4Linux compatible, so they couldn't be used by any standard Linux
video application.
	I (Tuukka Toivonen) took the qce-ga driver code and modified it a LOT.
There's still much original code left, but also many routines have been
completely rewritten or added. Thanks to Jochen Hoenicke, there's now
support for compressed mode with (only) VV6410 sensor. Unfortunately,
it didn't work very well for a long time.
	But then Cristiano stroke again: he supplied a patch that showed
where the problem was. And now this driver, finally, has very usable support
for the compressed mode with the QuickCam Web. Hopefully other cameras
will follow, althought this is yet uncertain.
	I want to give special thanks to Peter McConnell, who started the
project originally and did excellent work maintaining mailing lists and
project web pages, until he disappeared.
				Tuukka Toivonen <tuukkat@ee.oulu.fi>
