home *** CD-ROM | disk | FTP | other *** search
/ MACD 9 / MACD9.iso / Skanery / BetaScan / ScannerDev / ScannerDev.doc < prev    next >
Encoding:
Text File  |  1998-06-06  |  7.4 KB  |  246 lines
  1. Making a Scanner Driver
  2. =======================
  3.  
  4. A scanner driver is made as an Amiga Device.
  5.  
  6.  
  7. The Device I/O request
  8. ----------------------
  9.  
  10. The scanner device uses a special I/O request:
  11.  
  12.   struct ScannerIO
  13.   {
  14.     struct IOStdReq       IOScan;
  15.     struct ScannerOptions option;
  16.   }
  17.  
  18. where struct IOStdReq is a standard IO request as defined in exec/io.h and
  19. struct ScannerOptions is defined in the include file scanner.h
  20.  
  21. Before opening the device BetaScan places a pointer to a string containing
  22. the name of the IO unit where the scanner is connected (for instance
  23. scsi.device) in the IOScan.io_Data field. Then the open device is called:
  24.  
  25.   OpenDevice(scannerName,unit,(struct IORequest *)ScannerIO,0)
  26.  
  27. where unit is the unit number of the IO unit.
  28.  
  29. The open routine must do the necessary initializations and then set the fields
  30. in the structure option. This is to tell BetaScan what the scanner is able to
  31. do. You must set the  following fields:
  32.  
  33.   so_vendor;
  34.   so_model;
  35.   so_version;
  36.   so_revision;
  37.  
  38.   so_colorMode;
  39.  
  40.   so_opticResolution;
  41.   so_opticResStep;
  42.   so_interResolution;
  43.   so_interResStep;
  44.  
  45.   double so_docWidth;  /* Paper size in mm */
  46.   double so_docLength;
  47.  
  48. All other fields are optional. Do not touch if the facility is not supported
  49. by your scanner. The structure is filled with zero before the device is opened.
  50.  
  51.  
  52. IO Commands
  53. -----------
  54.  
  55. The device must respond to the following commands:
  56.  
  57.  CMD_START   - Start scanning
  58.  
  59.    The scanning parameters must have been set before (SCANCMD_SET). The
  60.    IOScan.io_Data field contains a pointer to a structure
  61.  
  62.    struct ScanInformation
  63.    {
  64.      UWORD sv_imageWidth;           /* image width in pixels               */
  65.      UWORD sv_imageHeight;          /* image height in pixels              */
  66.      UWORD sv_bytesPerLine;         /* bytes per line read (excl. color)   */
  67.      UWORD sv_Flags;                /* data information flags (set to 0)   */
  68.      UWORD sv_xResolution;          /* actual horizontal resolution        */
  69.      UWORD sv_yResolution;          /* actual vertical resolution          */
  70.    }
  71.  
  72.    Most scanners must do some roundings so that your scanner parameters are
  73.    not exactly the actual ones. Fill in the actual parameter values in this
  74.    structure.
  75.  
  76.    The field sv_bytesPerLine is normally the same as sv_imageWidth (except for
  77.    B/W scanning).
  78.  
  79.  CMD_STOP    - Stop scanning
  80.  
  81.    This command is always send (even if the driver has send all scan lines or
  82.    has reported an error).
  83.  
  84.  CMD_READ    - Read one or more scan lines
  85.  
  86.     The IOScan.io_Data field contains a pointer to a data buffer and the
  87.     IOScan.io_Length the buffer length.
  88.  
  89.     Copy scan line data to this buffer. The first byte of of a scan line must
  90.     be the color: 0 = red, 1 = green and 2 = blue (0 if grey scale or B/W).
  91.     The bytes 1,2,...,sv_bytesPerLine+1 are the actual scanned data.
  92.  
  93.     Note that you have to separate the colors (if this is not already done by
  94.     the scanner). In this way it is possible to handle 3-pass scanning.
  95.  
  96.     Return the actual number of bytes returned (an integral multiple of
  97.     sv_bytesPerLine+1).
  98.  
  99.  SCANCMD_SET - Set scanning parameters (command value defined in scanner.h)
  100.  
  101.     The field IOScan.io_Data contains a pointer to the structure (found in
  102.     scanner.h):
  103.  
  104.     struct ScanParameters
  105.     {
  106.       ULONG  sp_ColorNum;            /* 0: halftone, >0: number of colors  */
  107.       double sp_x0;                  /* Scanning frame in mm               */
  108.       double sp_y0;
  109.       double sp_x1;
  110.       double sp_y1;
  111.       UWORD  sp_xResolution;         /* Horizontal resolution              */
  112.       UWORD  sp_yResolution;         /* Vertical resolution                */
  113.       WORD   sp_brightness[3];       /* Brightness for red, green and blue */
  114.       WORD   sp_contrast;            /* Contrast                           */
  115.       WORD   sp_shadow;              /* shadow adjust                      */
  116.       WORD   sp_highlight;           /* highlight adjust                   */
  117.       WORD   sp_midtone;             /* midtone adjust                     */
  118.       WORD   sp_halftonePattern;     /* halftomePattern                    */
  119.       WORD   sp_exposureTime;        /* Exposure time                      */
  120.       double sp_gamma;               /* gamma value                        */
  121.  
  122.       ULONG  sp_flags;
  123.     }
  124.  
  125.     It is up to you if you want to send the values directly to the scanner or
  126.     store them until the CMD_READ is send.
  127.  
  128.  
  129. Actual development
  130. ------------------
  131.  
  132. To avoid making all the nasty device stuff and to facilitate the testing you
  133. can use the files in the ScannerDev directory (SAS/C 6.57).
  134.  
  135. By using these files you only have to make a single file with the following
  136. routines:
  137.  
  138.   void openScanner(char* name,int unit,struct ScannerOptions* option,BYTE* status)
  139.  
  140.     This is called when the scanner device is opened.
  141.  
  142.     input:
  143.       name:   name of the IO unit
  144.       unit:   number of the IO unit
  145.       option: pointer to the option structure
  146.       status: the return value (io_Error)
  147.  
  148.  
  149.   void closeScanner(void)
  150.  
  151.     Close the scanner
  152.  
  153.  
  154.   void setParameter(struct ScanParameters* param,BYTE* status)
  155.  
  156.     Set scanning parameters
  157.  
  158.     input:
  159.       param:  pointer to a parameter structure
  160.       status: the return value
  161.  
  162.  
  163.   void startScanning(struct ScanInformation* inform,BYTE* status)
  164.  
  165.     Start the scanning
  166.  
  167.     input:
  168.       inform: a pointer to a ScanInformation structure to be filled by you.
  169.       status: the return value
  170.  
  171.  
  172.   void stopScanning(void)
  173.  
  174.     Stop the scanning
  175.  
  176.  
  177.   void readScanLine(UBYTE* data,ULONG* length,BYTE* status)
  178.  
  179.     Read one ore more scan line(s)
  180.  
  181.     input:
  182.       data:   pointer to the data buffer
  183.       length: pointer to an ULONG containing the buffer length
  184.               fill with actual number at return
  185.       status: the return value
  186.  
  187.  
  188. An example file is in ScanDev directory (in fact divided into two: ScanmakerE3.c
  189. and Scsi.c). To make a test version execute the command:
  190.  
  191.    smake -f smakeTest
  192.  
  193.  
  194. The resulting executable is called scanner. The command template for this is:
  195.  
  196.    scanner [options]
  197.  
  198. where options are one or more of these:
  199.  
  200.    color=bw|grey|rgb24                 default is: color=rgb24
  201.  
  202.    frame=x0,y0,x1,y1                   upper left and lower right corner in mm
  203.                                        default is: frame=25,50,75,100
  204.  
  205.    resolution=r                        resolution in dpi
  206.                                        default is: resolution=300
  207.  
  208.    brightness=b                        brightness in %
  209.                                        default is scanner-default
  210.  
  211.    contrast=c                          contrast in %
  212.                                        default is scanner-default
  213.  
  214.    shadow=s                            default is scanner-default
  215.  
  216.    highlight=h                         default is scanner-default
  217.  
  218.    midtone=m                           default is scanner-default
  219.  
  220.    pattern=p                           default is scanner-default
  221.  
  222.    time=t                              exposure time
  223.                                        default is scanner-default
  224.  
  225.    gamma=g                             default is: gamma=1.0
  226.  
  227.    compress=on|off                     default is: compress=on
  228.  
  229.    file=<name>                         default is: file=ram:scanner.ilbm
  230.  
  231.  
  232. Example commands:
  233.  
  234.    scanner
  235.  
  236.    scanner color=grey frame=0,0,10,10 compress=off file=dh0:test.ilbm
  237.  
  238.  
  239.  
  240. To make a device execute
  241.  
  242.    smake -f smakeDevice
  243.  
  244. The linker will make 4 warnings about absolute addressing. Don't care.
  245.  
  246.