Documentation/admin-guide/media/cpia2.rst

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