About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / README.cpia2


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.

1	$Id: README,v 1.7 2005/08/29 23:39:57 sbertin Exp $
2	
3	1. Introduction
4	
5		This is a driver for STMicroelectronics's CPiA2 (second generation
6	Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
7	stream at up to vga size. It implements the Video4Linux interface as much as
8	possible.  Since the V4L interface does not support compressed formats, only
9	an mjpeg enabled application can be used with the camera. We have modified the
10	gqcam application to view this stream.
11	
12		The driver is implemented as two kernel modules. The cpia2 module
13	contains the camera functions and the V4L interface.  The cpia2_usb module
14	contains usb specific functions.  The main reason for this was the size of the
15	module was getting out of hand, so I separated them.  It is not likely that
16	there will be a parallel port version.
17	
18	FEATURES:
19	   - Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos
20	     sensors. I only have the vga sensor, so can't test the other.
21	   - Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between.
22	     VGA and QVGA are the native image sizes for the VGA camera. CIF is done
23	     in the coprocessor by scaling QVGA.  All other sizes are done by clipping.
24	   - Palette: YCrCb, compressed with MJPEG.
25	   - Some compression parameters are settable.
26	   - Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
27	   - Adjust brightness, color, contrast while streaming.
28	   - Flicker control settable for 50 or 60 Hz mains frequency.
29	
30	2. Making and installing the stv672 driver modules:
31	
32		Requirements:
33		-------------
34		This should work with 2.4 (2.4.23 and later) and 2.6 kernels, but has
35	only been tested on 2.6.  Video4Linux must be either compiled into the kernel or
36	available as a module.  Video4Linux2 is automatically detected and made
37	available at compile time.
38	
39		Compiling:
40		----------
41		As root, do a make install.  This will compile and install the modules
42	into the media/video directory in the module tree. For 2.4 kernels, use
43	Makefile_2.4 (aka do make -f Makefile_2.4 install).
44	
45		Setup:
46		------
47		Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This
48	may be done automatically by your distribution.
49	
50	3. Driver options
51	
52		Option		Description
53		------		-----------
54		video_nr	video device to register (0=/dev/video0, etc)
55				range -1 to 64.  default is -1 (first available)
56				If you have more than 1 camera, this MUST be -1.
57		buffer_size	Size for each frame buffer in bytes (default 68k)
58		num_buffers	Number of frame buffers (1-32, default 3)
59		alternate	USB Alternate (2-7, default 7)
60		flicker_freq	Frequency for flicker reduction(50 or 60, default 60)
61		flicker_mode	0 to disable, or 1 to enable flicker reduction.
62				(default 0). This is only effective if the camera
63				uses a stv0672 coprocessor.
64	
65		Setting the options:
66		--------------------
67		If you are using modules, edit /etc/modules.conf and add an options
68	line like this:
69		options cpia2 num_buffers=3 buffer_size=65535
70	
71		If the driver is compiled into the kernel, at boot time specify them
72	like this:
73		cpia2.num_buffers=3 cpia2.buffer_size=65535
74	
75		What buffer size should I use?
76		------------------------------
77		The maximum image size depends on the alternate you choose, and the
78	frame rate achieved by the camera.  If the compression engine is able to
79	keep up with the frame rate, the maximum image size is given by the table
80	below.
81		The compression engine starts out at maximum compression, and will
82	increase image quality until it is close to the size in the table.  As long
83	as the compression engine can keep up with the frame rate, after a short time
84	the images will all be about the size in the table, regardless of resolution.
85		At low alternate settings, the compression engine may not be able to
86	compress the image enough and will reduce the frame rate by producing larger
87	images.
88		The default of 68k should be good for most users.  This will handle
89	any alternate at frame rates down to 15fps.  For lower frame rates, it may
90	be necessary to increase the buffer size to avoid having frames dropped due
91	to insufficient space.
92	
93				     Image size(bytes)
94		Alternate  bytes/ms   15fps    30fps
95		    2         128      8533     4267
96		    3         384     25600    12800
97		    4         640     42667    21333
98		    5         768     51200    25600
99		    6         896     59733    29867
100		    7        1023     68200    34100
101	
102		How many buffers should I use?
103		------------------------------
104		For normal streaming, 3 should give the best results.  With only 2,
105	it is possible for the camera to finish sending one image just after a
106	program has started reading the other.  If this happens, the driver must drop
107	a frame.  The exception to this is if you have a heavily loaded machine.  In
108	this case use 2 buffers.  You are probably not reading at the full frame rate.
109	If the camera can send multiple images before a read finishes, it could
110	overwrite the third buffer before the read finishes, leading to a corrupt
111	image.  Single and double buffering have extra checks to avoid overwriting.
112	
113	4. Using the camera
114	
115		We are providing a modified gqcam application to view the output. In
116	order to avoid confusion, here it is called mview.  There is also the qx5view
117	program which can also control the lights on the qx5 microscope. MJPEG Tools
118	(http://mjpeg.sourceforge.net) can also be used to record from the camera.
119	
120	5. Notes to developers:
121	
122	   - This is a driver version stripped of the 2.4 back compatibility
123	     and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.
124	
125	6. Thanks:
126	
127	   - Peter Pregler <Peter_Pregler@email.com>,
128	     Scott J. Bertin <scottbertin@yahoo.com>, and
129	     Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
130	     this one was modelled from.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog