patch-2.3.49 linux/Documentation/usb/ibmcam.txt

• Lines: 213
• Date: Mon Feb 28 14:21:15 2000
• Orig file: v2.3.48/linux/Documentation/usb/ibmcam.txt
• Orig date: Thu Feb 10 17:11:02 2000

diff -u --recursive --new-file v2.3.48/linux/Documentation/usb/ibmcam.txt linux/Documentation/usb/ibmcam.txt
@@ -10,7 +10,12 @@
 I did not have any input from Xirlink. Some people asked about
 data sheets, but nothing came out of that. I didn't try.
 
-Video formats: 128x96, 176x144, 352x288
+Video formats:
+      128x96  [model 1]
+      176x144
+      320x240 [model 2]
+      352x240 [model 2]
+      352x288
 Frame rate: 3 - 30 frames per second (FPS)
 External interface: USB
 Internal interface: Video For Linux (V4L)
@@ -28,11 +33,11 @@
 
 The Linux driver was developed with camera with following
 model number (or FCC ID): KSX-XVP510. This camera has three
-interfaces, each with one endpoint (control, iso, iso).
+interfaces, each with one endpoint (control, iso, iso). This
+type of cameras is referred to as "model 1".
 
 It appears that Xirlink made some changes in their cameras recently.
-In particular, following models [FCC ID] are suspect; one with
-with FCC ID KSX-X9903 is known to be one of them:
+In particular, following models [FCC ID] belong to that category:
 
 XVP300 [KSX-X9903]
 XVP600 [KSX-X9902]
@@ -41,12 +46,57 @@
 (see http://www.xirlink.com/ibmpccamera/ for updates, they refer
 to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
 These cameras have two interfaces, one endpoint in each (iso, bulk).
-Attempts to remotely debug one of these cameras weren't successful.
-I'd need to have a camera to figure out how to use it.
+Such type of cameras is referred to as "model 2". They are supported.
+
+Quirks of Model 2 cameras:
+-------------------------
+
+These cameras apparently produce only 176x144 native video stream;
+the 352x288 formats are produced from 176x144 RGB stream. In fact,
+Xirlink broke perfectly good Model 1 (which used I420 on all sizes)
+and instead switched to color-separated RGB which is a terrible waste
+of bandwidth and resolution. However it probably allowed to simplify
+the camera and use less RAM. Model 2 camera works visibly worse than
+model 1 even using Xirlink's own driver on Windows. The image quality
+is better on Linux than on Windows, partly thanks to _absence_ of
+annoying automatic color corrections which Windows driver feeds into
+the camera several times per second.
+
+Model 2 does not have hardware contrast control. Corresponding V4L
+control is not used at the moment. It may be possible to implement
+contrast control in software, at cost of extra processor cycles.
+
+The bandwidth demand imposed by RGB quasi-352x288 mode (800 Kbits per
+frame) essentially limits this mode to 10 frames per second or less, in
+ideal conditions on the bus (USB is shared, after all). The frame rate
+has to be programmed very conservatively. Additional concern is that
+frame rate depends on brightness setting; therefore the picture can
+be good at one brightness and broken at another! I did not want to fix
+the frame rate at slowest setting, but I had to move it pretty much down
+the scale (so that framerate option barely matters). I also noticed that
+camera after first powering up produces frames slightly faster than during
+consecutive uses. All this means that if you use videosize=2 (which is
+default), be warned - you may encounter broken picture on first connect;
+try to adjust brightness - brighter image is slower, so USB will be able
+to send all data. However if you regularly use Model 2 cameras you may
+prefer videosize=1 which makes perfectly good I420, with no scaling and
+lesser demands on USB (300 Kbits per second, or 26 frames per second).
+Remember that model 2 cameras never produce images with resolution
+better than "true" 176x144 - or so it seems.
+
+The camera that I had also has a hardware quirk: if disconnected,
+it needs few minutes to "relax" before it can be plugged in again
+(poorly designed USB processor reset circuit?)
+
+Finally, to say something good about Model 2: it is much simpler to program
+than Model 1. Commands are few, and they all are straightforward. This camera
+can be programmed for very high sensitivity (starlight may be enough), this
+makes it convenient for tinkering with. The driver code has enough comments
+to help a programmer to tweak the camera as s/he feels necessary.
 
 WHAT YOU NEED:
 
-- A supported IBM PC (C-it) camera (see above)
+- A supported IBM PC (C-it) camera (model 1 or 2)
 
 - A Linux box with USB support (2.3/2.4 or 2.2 w/backport)
 
@@ -85,7 +135,7 @@
 
 The driver can have options, though some defaults are provided.
 
-Driver options:
+Driver options: (* indicates that option is model-dependent)
 
 Name            Type            Range [default] Example
 --------------  --------------  --------------  ------------------
@@ -97,9 +147,18 @@
 init_contrast   Integer         0-255 [192]     init_contrast=200
 init_color      Integer         0-255 [128]     init_color=130
 init_hue        Integer         0-255 [128]     init_hue=115
-lighting        Integer         0-2 [1]         lighting=2
-sharpness       Integer         0-6 [4]         sharpness=3
-videosize       Integer         0-2 [2]         videosize=1
+lighting        Integer         0-2* [1]        lighting=2
+sharpness       Integer         0-6* [4]        sharpness=3
+videosize       Integer         0-2* [2]        videosize=1
+
+Options for Model 2 only:
+
+Name            Type            Range [default] Example
+--------------  --------------  --------------  ------------------
+init_model2_rg  Integer         0..255 [0x70]   init_model2_rg=128
+init_model2_rg2 Integer         0..255 [0x2f]   init_model2_rg2=50
+init_model2_sat Integer         0..255 [0x34]   init_model2_sat=65
+init_model2_yb  Integer         0..255 [0xa0]   init_model2_yb=200
 
 debug           You don't need this option unless you are a developer.
                 If you are a developer then you will see in the code
@@ -145,49 +204,80 @@
                 preconfigure the camera when it gets connected, before
                 any V4L application connects to it. Good for webcams.
 
+init_model2_rg  These initial settings alter color balance of the
+init_model2_rg2 camera on hardware level. All four settings may be used
+init_model2_sat to tune the camera to specific lighting conditions. These
+init_model2_yb  settings only apply to Model 2 cameras.
+
 lighting        This option selects one of three hardware-defined
                 photosensitivity settings of the camera. 0=bright light,
                 1=Medium (default), 2=Low light. This setting affects
                 frame rate: the dimmer the lighting the lower the frame
-                rate (because longer exposition time is needed).
+                rate (because longer exposition time is needed). The
+                Model 2 cameras allow values more than 2 for this option,
+                thus enabling extremely high sensitivity at cost of frame
+                rate, color saturation and imaging sensor noise.
 
 sharpness       This option controls smoothing (noise reduction)
                 made by camera. Setting 0 is most smooth, setting 6
                 is most sharp. Be aware that CMOS sensor used in the
                 camera is pretty noisy, so if you choose 6 you will
-                be greeted with "snowy" image. Default is 4.
+                be greeted with "snowy" image. Default is 4. Model 2
+                cameras do not support this feature.
 
 videosize       This setting chooses one if three image sizes that are
                 supported by this driver. Camera supports more, but
                 it's difficult to reverse-engineer all formats.
                 Following video sizes are supported:
 
-                videosize=0     128x96
+                videosize=0     128x96  (Model 1 only)
                 videosize=1     176x144
                 videosize=2     352x288
+                videosize=3     320x240 (Model 2 only)
+                videosize=4     352x240 (Model 2 only)
 
                 The last one (352x288) is the native size of the sensor
-                array, so it's the best resolution camera can yield.
+                array, so it's the best resolution camera (Model 1) can
+                yield. The best resolution of Model 2 is 176x144, and
+                larger images are produced by stretching the bitmap.
                 Choose the image size you need. The smaller image can
                 support faster frame rate. Default is 352x288.
 
 WHAT NEEDS TO BE DONE:
 
 - The box freezes if camera is unplugged after being used (OHCI).
-  Workaround: don't do that :)
-- Some USB frames are lost on high frame rates, though they shouldn't
-- ViCE compression (Xirlink proprietary) may improve frame rate
-- On occasion camera does not start properly; xawtv reports errors.
-  Workaround: reload the driver module. Reason: [1].
-- On occasion camera produces negative image (funny colors.)
+  Workaround: remove usb-ohci module first.
+- On occasion camera (model 1) does not start properly (xawtv reports
+  errors), or camera produces negative image (funny colors.)
   Workaround: reload the driver module. Reason: [1].
 - The button on the camera is not used. I don't know how to get to it.
+  I know now how to read button on Model 2, but what to do with it?
 
 [1]
 - Camera reports its status back to the driver; however I don't know
   what returned data means. If camera fails at some initialization
   stage then something should be done, and I don't do that because
-  I don't even know that some command failed.
+  I don't even know that some command failed. This is mostly Model 1
+  concern because Model 2 uses different commands which do not return
+  status (and seem to complete successfully every time).
+
+VIDEO SIZE AND IMAGE SIZE
+
+Camera produces picture X by Y pixels. This is camera-specific and can be
+altered by programming the camera accordingly. This image is placed onto
+larger (or equal) area W by H, this is V4L image. At this time the driver
+uses V4L image size (W by H) 352x288 pixels because many programs (such
+as xawtv) expect quite specific sizes and don't want to deal with arbitrary,
+camera-specific sizes. However this approach "hides" real image size, and
+application always sees the camera as producing only 352x288 image. It is
+possible to change the V4L image size to 128x96, and then if camera is
+switched to 128x96 mode then xawtv will correctly accept this image size. But
+many other popular sizes (such as 176x144) will not be welcomed. This is the
+reason why all camera images are at this time placed onto 352x288 "canvas",
+and size of that canvas (V4L) is reported to applications. It will be easy
+to add options to control the canvas size, but it will be application-
+specific because not all applications are ready to work with variety of
+camera-specific sizes.
 
 CREDITS: