diff options
Diffstat (limited to 'Documentation/usb')
| -rw-r--r-- | Documentation/usb/ibmcam.txt | 134 |
1 files changed, 112 insertions, 22 deletions
diff --git a/Documentation/usb/ibmcam.txt b/Documentation/usb/ibmcam.txt index 6880ed334..5943227a6 100644 --- a/Documentation/usb/ibmcam.txt +++ b/Documentation/usb/ibmcam.txt @@ -10,7 +10,12 @@ which was produced by standard Windows driver (c-it98.sys). 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 @@ or http://www.c-itnow.com/ for details and pictures. 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 @@ XVP610 [KSX-X9902] (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 @@ Module can be inserted with camera connected or disconnected. 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_brightness Integer 0-255 [128] init_brightness=100 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 @@ init_hue controls will be used too. These options allow you to 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: |