
                            CX100 Frame Grabber
                      Device Driver for Linux  v0.1(beta)
                      ===================================
                       README Updated: 09/07/1995  01:50



This is version 0.1 (beta) of the CX100 device driver for Linux.  The
CX100 is a frame grabber is made by ImageNation Corporation.  I don't
work for them, I just made this driver because we needed it.

I've currently only tested this on my computer, and have not had any
reports of it working on other computers, which is why it is still
considered beta.

The CX100 is a B&W frame grabber with an 8-bit depth, which provides
256 shades of grey.  It is capable of two modes of operation: low
resolution (243x256) and high resolution (486x512).

The CX100 also as an input and output LUT and has the option of having
overlay RAM.  The LUTs allow one to perform various grey level pixel
translations, while the overlay RAM allows for 4 extra bits of RAM for
every pixel to display overlayed images.  Neither of these two
features are currently supported by the device driver as I personally
find them rather useless.  If needed, they can be easily done through
software, which I think is the better, more flexible approach.


New in this release
-------------------

	o  a nice X11 "application"
	o  an X11 demo program
	o  an SVGA demo program
	o  a C library to interface the device driver

Ok, the X demo ("xcxdemo") uses some bits of Xt, but it's mainly
straight X calls.  It's got command line help, and again, it
should be fairly simple to use.  It doesn't have much in it, but
it's a nice example of how to use the frame grabber library.  This
version has the added benefit that the program does not have to be
run as root.

The SVGA demo ("scxdemo") is noticably faster than the X version (at
least on my system -- a 486-66 and a really old non-accelerated tseng
4k based card).  I haven't timed it, but it looks like real-time
quality to me (at least maybe 12-15 fps.  I personally don't think the
CX100 is capable of more than 20 to 25 fps.  But again, I haven't done
any timing checks).  The speed with SVGALIB also seems to be
faster than the DOS demo program that came with it running on the
Pentiums in the lab.  The down side to this version is that, like all
SVGALIB based programs, this program MUST be run either as root or
setuid root.

As for the X app ("xcxapp" -- I know, not very creative, but hey...),
it behaves more like an X program should.  This one uses Xt Intrinsics
and makes use of the Athena Widget set.  It also makes use of the LUG
library (and along with it, libgif, etc.) for saving grabbed frames.
Several command line parameters are available.  However the documentation
as well as the default resource file have not yet been completed.
This program is not considered finished, but it is useable in its
current state.


Making the Device File
----------------------

The device driver should be in /dev/cx100.  It can be made by doing
"mknod /dev/cx100 c 42 0" as root.  Yes, I'm using 42 has the major
code for now, and this number is not registered.  So, for the time
being, you'll have to either use it or change it manually.  Sorry.


Installing the Device Driver
----------------------------

For convenience, I have included the kernel module compiled on Linux
kernel version 1.2.9 with ELF patch (although ELF-ness shouldn't make
a difference).  If this doesn't work, just recompile the module.

Remember, loadable modules are loaded with "insmod filename" and
removed with "rmmod filename".  The module should probably be placed
in "/lib/modules/misc/cx100.o" or "/lib/modules/1.2.9/misc/cx100.o".
In this case, do "insmod /lib/modules/misc/cx100.o" or
"rmmod /lib/modules/misc/cx100.o" (with the appropriate paths) when you
no longer need to use the frame grabber.


Installing the Library
----------------------

After doing a make on the library, you'll get a libcx100.a file.  For
ELF systems, you will also get a nice shared library libcx100.so.0.1.0.
If you wish to do any development with this library, I recommend placing
this in /usr/local/lib/libcx100.a.  The header files ("cx100.h" and
"cxlib.h") should be placed in /usr/local/include/{cx100.h,cxlib.h}.
Only "cxlib.h" need be included in your functions, as "cxlib.h"
includes "cx100.h" automatically.  Make sure these are in your search
path when compiling your programs.

Although there are provisions for interfacing with much of the
features the CX100 has to offer through ioctl() calls, I strongly
recommend using the library instead.  For one, it makes code much
easier to read.  Secondly, I just think it's a bad idea to muck around
these ioctl()'s manually.


Notes about this release
------------------------

This is the first driver I've written for Linux, so it's probably not
the best driver around.  But, it works and I haven't had any problems
with it yet.  If you have any tips on how I can make this a better
driver, I'm open to suggestions.

I've included source for the library and both the SVGA and X11 demos
for this driver.  So, it should be fairly easy to figure out what you
need pick out your images.  There really isn't that much.  But, for
those who want to do lower-level stuff with the driver, most of the
functions are available through ioctl() calls.  You can check out
cx100.h if you really need to access these ioctl()'s.  However, in
most implementations, I think the cxlib.c library should be sufficient.
If you have any troubles, read the cxlib.h header file as it is well
documented, and has all the basic functions (grab a frame, and read in
the data).

If there are any requests to add more functionality into the
library/driver, don't hesitate to make them.  If you make any
significant changes to the library or driver, I'd like to know so that
it might be incorporated.


Known Bugs/Quirks
-----------------

	-  There appears to be a bit of noise and the picture sometimes
		jittering up and down when grabbing in continuous mode (as "scxdemo"
		and "xcxdemo" do).  I'm not sure exactly, but I think this might
		have to do with the timings in the device driver being a little off.
		Please let me know if you're experiencing these problems or know of
		a way to fix it.

	-  There was a problem with the older version of the driver running on
		the lab's computers.  I'd get noise around the screen for no apparent
		reason.  I never found the problem, and I don't see it here.
		However, it might be related to other "visual effects" I mentioned
		above.
		I'm not entirely certain, but I believe this might be because
		the lab's computers are PCI.  I've been informed that PCI's
		reserve the address range from C000 to F000.  So, if you've got
		this problem, check your CMOS and see if you can disable this
		feature.


TODO List (in order of precendence)
---------

	- Overlay and LUT support is currently in the works.  When this is
		known to work, I'll consider it a full 1.0 release.

	- A simply paint program-like interface for modifying the overlay
		buffer.  As well as a way to load/save overlays to/from disk.

	- Support for multiple frame grabbers
		I'll get to this as soon as I get my hands on a machine with two
		of these things on them.

	- More functionality in the X App.  In particular:
		A nice dialog box for asking what you want the filename to be
			when you save a frame.
		a way to save motion video
		on-the-fly user gamma correction and contrast/brightness adjustment
		auto gamma correction and brightness control

Note:
	Both the device driver and the xcxapp should be considered "work in
	progress."  As for the SVGA and X11 demo programs, I don't plan on
	working on them anymore.


Author
------

The current maintainer of this device driver is Danny Sung of
UCLinux (UCLA's Linux User's Group).

Please mail questions/comments related to this driver to:
			dannys@seas.ucla.edu.

Other general Linux questions or questions about UCLinux should be
directed to:
			linux@seas.ucla.edu



Happy Linuxing,
Danny Sung
dannys@seas.ucla.edu


