readme

Webcam Linux driver for Quickcam

		  pale walls are not good, try a bookshelf or something.
		- Run GIMP, select "File/Acquire/Screen Shot".
		  Enable "Single Window", disable "Decorations", click OK.
		- Click on the Xawtv window. If you get completely blue
		  image instead of what xawtv displays, then you didn't
		  disable Xvideo.
		- Click on the GIMP image window with right mouse button,
		  select "File/Save As...", enter filename.pnm, select
		  raw PNM file.
		- qcset quality=best -e filename.pnm
		The equalization image is sensor and lighting-specific, so if
		you change the camera or go indoors/outdoors, redo the
		procedure above.
		There may be some pre-made equalization files in
		http://www.ee.oulu.fi/~tuukkat/quickcam/eq-*.pmn.
		This option can not be use simultaneously with the "-g" option.
		You can disable static equalization with "-g -".
		Software lookup table will have no effect when compression is
		enabled (compress=y).
-g + / -e +	Enable software-based lookup-table for correcting colors
-g - / -e -	Disable lookup-table
-g '?' / -e '?'	Display whether lookup-table is enabled and the table contents
qcdebug		Enable selected debug messages. You can write symbolic list
		of error message types or bitmask, for example
		"qcdebug=errors,common" displays debug messages related to
		various errors and some common messages as "frame lost".
		The kernel messages are logged typically into file
		/var/log/kern.log.
		Note that if the driver was not compiled with debugging
		enabled ("USER_OPT=-DDEBUG") this option will not do much.
debug		Same as 'qcdebug', for compatibility with older versions.
keepsettings	Keep image settings over camera uses. When this option
		is disabled, the image settings (brightness etc.)
		are reset to the default values each time when a program
		opens the camera.
settle		Specify the maximum number of frames to wait for image
		brightness to settle before starting capturing. Has
		effect only when adaptation is enabled. For example,
		if settle=30, the camera driver waits maximum of 30
		frames until automatic adaptation (brightness control)
		has stabilized the image brightness and only then gives
		the first image. Some programs, e.g. xawtv, don't like
		if the driver pauses for a long time.
		This option is particularly useful if you take single
		image snapshots but the images are too dark or bright.
subsample	Increases framerate but decreases image resolution.
		May work or not to work depending on camera sensor type.
		Works on HDCS-1000. To get high frame rate, you must use
		short exposure time. Either disable adaptation and set
		contrast into small value or use enough light so that the
		adaptation routine uses short exposure time.
compress	Enable MJPEG compression with QuickCam Web and LEGO cameras.
		On other cameras, compression is automatically disabled.
		When using compression, image size is fixed to 320*240
		and frame rate is about doubled to 15 frames per second.
frameskip	Lower frame rate by skipping frames. Decreases CPU
		power requirement. For slow computers.
quality		Select image conversion routine which is used for
		converting Bayer CFA image into RGB image. Has no
		effect when compression is enabled.
adaptive	Enable or disable automatic brightness control.
		Use -b to set the target brightness.
equalize	Equalizes the image. May improve colors hugely sometimes.
userlut		Enables or disables the default whether to use software
		lookup-table color correction in the driver. Affects only
		cameras which are plugged in after setting this setting.
		For already plugged-in cameras, use -g and -e options.
retryerrors	If there are problems with communicating with the camera,
		and retryerrors is enabled, the driver tries to retry
		a few times instead of immediately failing and returning
		error to application.
compatible	Enable various compatibility levels:
		16x: force image width and height be multiple of sixteen.
		dblbuf: lie applications about the number of frame buffers.
		torgb: convert BGR values into RGB.
video_nr	Select the video device number to use. Can not be set
		with qcset.
You can query the named parameters by adding a question mark, for example
	qcset 'qcdebug?'
displays the current debugging selection.
With kernel 2.6.x you can run qcset simultaneously while running other
applications which use the camera. With older kernels, you must close
other applications before qcset can be used.

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 
32768, 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 [e-mail]. 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.
If you have any problems, try running the script "quickcam.sh". It
will determine automatically system configuration and check many
possible problems.
	You can enable debugging mode in the driver by compiling
it with
	make clean; make all USER_OPT="-DDEBUG"
After this you can set a suitable debug level with qcset, for example
	qcset qcdebug=errors,common
and the driver will print lots of debugging messages to the kernel
log files.

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 <[e-mail]>