README for qcam 0.3

This is the fourth alpha-test release of my control program for the
Connectix QuickCam parallel port video camera.  It enables you to take
pictures with the camera at 320x240, 160x120, or 80x60 using 4 or 6
bits per pixel.  This program may not work with your camera, and could
possibly damage your system if used improperly.  Use at your own risk.
This version is intended primarily for testing, and has many small
changes.  It may not work on your hardware.


New Features since 0.2:
-----------------------

I've made autoprobing for the QuickCam the default if a port isn't
specified by the user.  This should be safe, but it may not always
find the camera.  Once you locate the camera, you should edit the
qcam.conf file and set it to the correct port.

This release include two versions of the xqcam program.  The first is
the original (from Paul Chinn) that's only slightly different than the
previous version.  I've tried to add some additional debugging, but
it's mostly the same.

The second is his new version with on-screen controls for pretty much
everything.  Unfortunately, it requires the Xforms library, which I
don't have.  I wanted to release what I have, so I disabled it in the
Makefile.  If you want to use it with this release, you'll probably
have to make a few changes to get it to work.  Hopefully someone will
fix it and contribute the patches back to me for version 0.4.

There aren't many other visible changes in this release, but I've made
a lot of small changes to the library.

I've temporarily disabled locking because it doesn't actually work
right more than half the time.  Any volunteers?

I've started on bi-directional support.  It doesn't actually work yet,
but there's a stub for it, and it should be automatically detected.  I
suspect this can be finished in about 5 lines of code, but I don't
have the hardware to test it.

I've added Paul Chinn's changes to make 4-bit mode work correctly.

I've combined qc_scan and qc_scanconvert.  This gives a whopping 1%
speed boost on my machine (Pentium 90), plus it's a bit cleaner.  This
changes makes qc_scan return the same output that qc_scancovert used
to return.

I've added a bunch of get/set functions for manipulating the qcam
structure from client programs.  They aren't needed yet, but they give
a cleaner interface and should make it easier to update the library
without breaking programs.

I've cleaned up the comments in most of the code.


Hopefully the few small changes to xqcam will help.  I haven't had
time to make any major changes, but I have fixed a few small things,
and I've tried to check the return values for most of the X calls that
seem likely to fail.


Future Changes:
---------------

Documentation needs to be written, for the programs, the library, and
the protocol.

I'm planning on adding support for "zoom mode," where the resolutions
on the scan command and the resolution command don't match.

I'd like to get support for bi-directional ports working.

Some people are working on ports to DOS, Windows, OS/2, and possibly
an embedded system.  I don't want to kill any of them, if it can be
avoided.

I think I'm almost done making large changes to the library, so 



Usage:
------

  qcam [options] [filename]
    Options:
      -x width   Set width
      -y height  Set height
      -p port    Set port
      -B bpp     Set bits per pixel
      -c val     Set contrast
      -w val     Set white balance
      -b val     Set brightness
      -V         Print version

The program returns one image from the camera on standard output in
PGM format.  The default resolution is 160x120, and the default port
is 0x378 (LPT1).  There are command-line arguments to change these as
well as a configuration file.  If your camera is on your first
parallel port (0x378 or /dev/lp1), then your should be able to run the
program with no options and get a picture.  If you are unsure which
port your QuickCam is on, run probeqcam as root, and it should tell
you.

There's also a xqcam program that takes the same options, plus two
more:

      -v         Verbose:  print frames-per-second.
      -C         Use private colormap.


Since these programs need access to the parallel port control
registers, they must be run with root privileges.  By default they are
installed SUID root.  They should be safe and should not pose a
security threat, but you should be careful.


Credits:
--------

Several people have contributed to this, including Paul Chinn, Thomas
Davis, Simon Janes, and Russell Nelson.


Copyright:
----------

I've placed this program under the same copyright the X Consortium
uses.  Basically, it's free for any use whatsoever.  If this manages
to cause great problems for anyone (?) let me know and I suspect we
can arrange something.

Here's the notice:


Copyright (C) 1996 by Scott Laird

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL SCOTT LAIRD BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.


Bugs:
-----

This program has bugs.  The known ones should be listed in the BUGS
file that comes with this program.  Please send bug reports/fixes to
me at scott@laird.com, and I'll try to get the bug fixed for the next
version.


FTP Site:
---------

The latest version of this program can be found in
ftp://ftp.nas.com/laird


Mailing List:
-------------

There is a mailing list for discussing the QuickCam and Linux at
linux-connectix@crynwr.com.  Send mail to
linux-connect-request@crynwr.com to be added to the list.



Scott Laird
scott@laird.com
January 6, 1996.
