home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: OtherApp / OtherApp.zip / wincam.zip / winc_src.zip / wincam.h < prev    next >
C/C++ Source or Header  |  1997-02-28  |  12KB  |  320 lines
  1. /*
  2.  *
  3.  * Public header describing interfaces to the wincam lib
  4.  *
  5.  * Copyright (C) 1996, Paul G. Fox
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify it
  8.  * under the terms of the GNU General Public License as published by the
  9.  * Free Software Foundation; either version 2 of the License, or (at your
  10.  * option) any later version.
  11.  * 
  12.  * This program is distributed in the hope that it will be useful, but
  13.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  14.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.  * General Public License for more details.
  16.  * 
  17.  * You should have received a copy of the GNU General Public License along
  18.  * with this program; if not, write to the Free Software Foundation, Inc.,
  19.  * 675 Mass Ave, Cambridge, MA 02139, USA.
  20.  *
  21.  * This software was created with the help of proprietary information
  22.  * belonging to StarDot Technologies.
  23.  *
  24.  * $Header: E:/winc/RCS/wincam.h 1.1 1997/03/01 03:44:14 Derek Exp Derek $
  25.  */
  26.  
  27. /* opaque handle with which to reference the camera */
  28. typedef struct camera_s *cam_t;
  29.  
  30. /* really just a boolean:  okay/not okay */
  31. typedef enum {
  32.     NotOK    = 0,
  33.     OK         = 1
  34. } result;
  35.  
  36.  
  37. #if LATER /* multi-camera per serial port support */
  38. /* the camera has the ability to disable and enable itself, using its
  39.  * id value as an address.  supposedly this lets you put more than one
  40.  * camera on a single serial port.  i only have one camera.
  41.  */
  42. result    winc_disable_all( cam_t cam );
  43. result    winc_enable( cam_t cam );
  44. #endif
  45.  
  46. /*
  47.  * cam_configvar() will look for the specified variable:
  48.  *  - in the caller's environment
  49.  *  - in /usr/local/etc/winc.rc
  50.  *  - failing those, will return the default passed in as the second arg.
  51.  */
  52. char *winc_configvar(char *variable, char *defaultval);
  53.  
  54. /*
  55.  * winc_find() looks for a camera, currently on the configured device;
  56.  * the default is "/dev/ttyCamera".  (i set that up as a symlink to the real
  57.  * special device.)  the "cam_t" handle which is returned will be used
  58.  * in all subsequent communications with the camera.
  59.  */
  60. cam_t    winc_find( int which );
  61.  
  62. /*
  63.  * winc_close() closes the camera, and releases the handle.
  64.  */
  65. void winc_close(cam_t cam);
  66.  
  67. /*
  68.  * sets camera to given baud rate 
  69.  */
  70. int winc_set_baud(cam_t cam, int rate);
  71.  
  72. /*
  73.  * gets camera's current baud rate 
  74.  */
  75. int winc_get_baud(cam_t cam);
  76.  
  77. /*
  78.  * winc_getstatus() isn't normally needed, since it's called internally
  79.  * by winc_find(), but it can be used as a "ping" of sorts.  it fills
  80.  * in version and id information in the cam_t handle.
  81.  */
  82. result    winc_getstatus( cam_t cam );
  83.  
  84. /*
  85.  * the camera can respond to several diagnostic commands, and this does
  86.  * all three of them.  there's a) an echo check, where the camera echoes
  87.  * back a short set of bytes sent to it, b) a transmit check, where it
  88.  * transmits all 256 possible unsigned char values, and c) an internal
  89.  * RAM diagnostic, which does some sort of check on its internals.
  90.  */
  91. result    winc_diagnose( cam_t cam );
  92.  
  93.  
  94. /* 
  95.  * these three are not not normally needed -- they're called internally with,
  96.  * defaults, but are available if needed.
  97.  */
  98.  
  99. /*
  100.  * set no. of extra stop bits that the camera should send when
  101.  * transmitting to us.
  102.  */
  103. result    winc_extrastop( cam_t cam, int extra_stop);
  104.  
  105. /*
  106.  * set true for flourescent flicker control -- synchronizes camera with
  107.  * the flicker or typical indoor flourescent lighting.
  108.  */
  109. result    winc_linesync( cam_t cam, int sync_60hz);    
  110.  
  111. /*
  112.  * set light sensitivity (0-15)
  113.  */
  114. result    winc_sensitivity( cam_t cam, int sensitivity);
  115.  
  116. /*
  117.  * the viewfinder grab can be used to align and focus the camera, as well
  118.  * as to determine an appropriate exposure interval.  if called with
  119.  * "autoexpose" set, it will seek (doing multiple grabs) to a useful
  120.  * exposure value, using average pixel intensity as a guide.
  121.  */
  122. #define DEFAULT_EXPOSURE 33333        /* 1/30th of a second, in microseconds */
  123.  
  124. result winc_viewfinder_snap( cam_t cam,
  125.     int zoom,        /* 1, 2, 4, or 8 */
  126.     int row,        /* when zoomed: starting row: 0 to 197 */
  127.     int col,        /* when zoomed: starting col: 0 to 448 */
  128.     unsigned char *image, /* room for 1536 bytes, 0 to suppress */
  129.     int exposeiters, /* iterations to find correct exposure */
  130.     int *exposurep, /* pointer to exposure guess (or null) 
  131.         (in microseconds -- real granularity is 50,000ths) */
  132.     int *avgp,        /* place to put average pixel value */
  133.     int goal,        /* desired brightness, 1 to 100 */
  134.     int *ok_p);        /* boolean: did we achieve that brightness? */
  135.  
  136. /*
  137.  * "expose" a picture, in one of several modes.
  138.  */
  139. result winc_image_expose( cam_t cam,
  140.     int scantype,   /* single(1), double(2), or noninterlaced(0) */
  141.     int fraction,   /* 1, 2, 4, or 8 for full, half, 1/4 and 8th size */
  142.     int u_exp,         /* exposure (in microseconds), 0 to download only */
  143.     unsigned char *image);    /* room for expected no. bytes */
  144.  
  145. /*
  146.  * fetch a previously exposed picture from the camera
  147.  */
  148. result winc_image_fetch( cam_t cam,
  149.     int scantype,   /* single(1), double(2), or noninterlaced(0) */
  150.     int fraction,   /* 1, 2, 4, or 8 for full, half, 1/4 and 8th size */
  151.     int color,        /* image destined for color processing */
  152.     unsigned char *image,   /* room for expected no. bytes */
  153.     int *rows_p,    /* no. of rows in resulting image */
  154.     int *cols_p);    /* no. of cols in resulting image */
  155.  
  156. /*
  157.  * winc_image_snap() takes a "full-size" picture, in one of several modes.
  158.  * this is a simple combination of winc_image_expose() and winc_image_fetch().
  159.  */
  160. result winc_image_snap( cam_t cam,
  161.     int u_exp,         /* exposure (in microseconds), -1 to autoexpose,
  162.             and 0 to suppress exposure, just download */
  163.     int scantype,   /* single(1), double(2), or noninterlaced(0) */
  164.     int fraction,   /* 1, 2, 4, or 8 for full, half, 1/4 and 8th size */
  165.     int color,        /* image destined for color processing */
  166.     unsigned char *image,   /* room for expected no. bytes */
  167.     int *rows_p,    /* no. of rows in resulting image */
  168.     int *cols_p);   /* no. of cols in resulting image */
  169.  
  170. /*
  171.  * register a routine with the library which will be called when
  172.  * a snapshot is actually being done.  can be used as an audible alert,
  173.  * for instance.  the function is eventually called with the supplied
  174.  * argument.
  175.  */
  176. void winc_register_alerter(
  177.     void (*alert_func)(void *), /* function called when an image is "snapped" */
  178.     void *cookie);        /* single argument passed to that function */
  179.  
  180. /*
  181.  * the camera will report some residual light level even for purely dark
  182.  * scenes.  this level can be detected via some dark "sidebands" that the
  183.  * camera makes available, and then factored out (subtracted) from an entire
  184.  * image to reduce "haziness".
  185.  */
  186. result    winc_black_offset(cam_t id, int *blackadj, unsigned char *blackp);
  187.  
  188. /*
  189.  * structure to hold color balance information.
  190.  * the values are the percent of "standard" that that color
  191.  * should be adjusted to, i.e. 100, 100, 100 means no changes.
  192.  * default standard values for a structure like this are returned by
  193.  * winc_lighting_adjustments()
  194.  */
  195. struct winc_image_adjust {
  196.     int red;            /* percent of "standard" red */
  197.     int green;            /* percent of "standard" green */
  198.     int blue;            /* percent of "standard" green */
  199.     int widen;            /* should image be stretched? */
  200.     int vignette_correction;    /* should edges be brightened? */
  201. };
  202.  
  203. /*
  204.  * take a values, presumably supplied by the user, and turn it into
  205.  * a set of appropriate color adjustment values in the supplied structure.
  206.  * given a null string, will provide defaults for color balance.
  207.  */
  208. void winc_image_adjustments(
  209.     struct winc_image_adjust *ca,
  210.     char *cs,        /* string describing color balance */
  211.     int widen,        /* boolean: should image be stretched? */
  212.     int vignette    /* boolean: shoudl corners be brightened? */
  213. );
  214.  
  215. /*
  216.  * to get proper greyscale, we average every pair of pixes from the
  217.  * camera.  "convimage" should be at least as big as "image".
  218.  */
  219. void winc_grey_convert(
  220.     unsigned char *image,    /* raw data from camera */
  221.     unsigned char *convimage,    /* data with adjacent pixels averaged */
  222.     int *rows_p,        /* no. of rows in image */
  223.     int *cols_p,        /* no. of cols in image */
  224.     int offs,        /* amount (black value) to subtract from every pixel */
  225.     int scantype,    /* double or single scan */
  226.     int fraction,    /* fraction of orig dimension */
  227.     struct winc_image_adjust *ia);    /* image adjustment info */
  228.  
  229. /*
  230.  * color is a more complicated.
  231.  * "convimage" should be 3 times the size of "image", to contain R,G,B
  232.  * values.
  233.  */
  234. void winc_color_convert(
  235.     unsigned char *image,    /* raw data from camera */
  236.     unsigned char *convimage,    /* data with adjacent pixels averaged */
  237.     int *rows_p,        /* no. of rows in image */
  238.     int *cols_p,        /* no. of cols in image */
  239.     int offs,        /* amount (black value) to subtract from every pixel */
  240.     int color,        /* do we want 24 bit color or 8 bit grey ? */
  241.     int scantype,    /* double or single scan */
  242.     int fraction,    /* fraction of orig dimension */
  243.     struct winc_image_adjust *ia);    /* image adjustment info */
  244.  
  245.  
  246. /*
  247.  * winc_snap_and_process combines the actions of winc_image_snap() and
  248.  *  winc_color_convert().  it overlaps the serial i/o with the color
  249.  *  processing, so it's quite a bit faster than doing the two steps
  250.  *  separately
  251.  */
  252. result winc_snap_and_process(
  253.     cam_t cam,
  254.     int u_exp,         /* exposure (in microseconds) */
  255.     unsigned char *image, /* image from winc_image_snap()/winc_image_fetch() */
  256.     unsigned char *convimage,    /* where to put the rgb result */
  257.     int *rows_p,        /* no. of rows in image */
  258.     int *cols_p,        /* no. of cols in image */
  259.     int color,        /* do we want 24 bit color or 8 bit grey ? */
  260.     int scantype,    /* double or single scan */
  261.     int fraction,    /* fraction of orig dimension */
  262.     struct winc_image_adjust *ia);    /* image adjustment info */
  263.  
  264. /*
  265.  * stretch an image horizontally, by 25%, to fix the WinCam's inherent
  266.  * aspect ratio problem.  this takes a 512 column image to 640.
  267.  * returns the new width.
  268.  */
  269. int winc_aspect_fix(
  270.     unsigned char *image,    /* the old narrow image */
  271.     int rows,        /* no. of rows.  remains unchanged */
  272.     int origcols,    /* no. of cols in original image */
  273.     int rgb);        /* is this a color image? */
  274.  
  275. /*
  276.  * the corners of a raw image are darker than the middle, by quite
  277.  * a bit.  this routine tries to correct for this. 
  278.  */
  279. void winc_vignette_fix(
  280.     unsigned char *image,    /* the image */
  281.     int rows,        /* no. of rows */
  282.     int cols,        /* no. of cols */
  283.     int rgb);        /* is this a color image? */
  284.  
  285. /*
  286.  * performa a gamma function on the image.  gamma of 1.0 leaves the
  287.  * image unchanges -- less dims, greater brightens.  the first arg.
  288.  * is the gamma times 1000.
  289.  */
  290. void
  291. winc_gamma(
  292.     int gam,        /* gamma value, times 1000 */
  293.     unsigned char * image,
  294.     int rows,
  295.     int cols,
  296.     int rgb);
  297.  
  298. /*
  299.  * compare two images, returning a simple boolean:  true if they "match",
  300.  * false if they don't.
  301.  */
  302. int winc_compare_image(
  303.     unsigned char *image1,  /* the two images being */
  304.     unsigned char *image2,  /*    compared */
  305.     int rows,            /* rows of pixels */
  306.     int cols,            /* columns of pixels */
  307.     int maxdiff,        /* percent pixels changed for image to be diff */
  308.     int thresh,         /* amount pixel val must, as percentage of max */
  309.     int maxval,            /* maximum pixel value */
  310.     int rgb);            /* boolean -- three bits per pixel, or one */
  311.  
  312.  
  313. /*
  314.  * get and release locks on the camera, to allow multiple programs
  315.  * to attempt to use it at once.
  316.  */
  317. void winc_lock(cam_t cam);
  318. void winc_unlock(cam_t cam);
  319.  
  320.