| 1 |
.TH sane\-apple 5 "11 Jul 2008" "" "SANE Scanner Access Now Easy" |
| 2 |
.IX sane\-apple |
| 3 |
.SH NAME |
| 4 |
sane\-apple \- SANE backend for Apple flatbed scanners |
| 5 |
.SH DESCRIPTION |
| 6 |
The |
| 7 |
.B sane\-apple |
| 8 |
library implements a SANE (Scanner Access Now Easy) backend that |
| 9 |
provides access to Apple flatbed scanners. At present, the following |
| 10 |
scanners are supported from this backend: |
| 11 |
.PP |
| 12 |
.br |
| 13 |
.ft CR |
| 14 |
.nf |
| 15 |
--------------- ----- ------------------ ------ |
| 16 |
AppleScanner 4bit 16 Shades of Gray |
| 17 |
OneScanner 8bit 256 Shades of Gray |
| 18 |
ColorOneScanner 24bit RGB color 3-pass |
| 19 |
.fi |
| 20 |
.ft R |
| 21 |
|
| 22 |
.PP |
| 23 |
If you own a Apple scanner other than the ones listed above that |
| 24 |
works with this backend, please let us know by sending the scanner's |
| 25 |
model name, SCSI id, and firmware revision to |
| 26 |
.IR sane\[email protected] . |
| 27 |
See |
| 28 |
.I http://www.sane\-project.org/mailing\-lists.html |
| 29 |
for details on how to subscribe to sane\-devel. |
| 30 |
|
| 31 |
.SH "DEVICE NAMES" |
| 32 |
This backend expects device names of the form: |
| 33 |
.PP |
| 34 |
.RS |
| 35 |
.I special |
| 36 |
.RE |
| 37 |
.PP |
| 38 |
where |
| 39 |
.I special |
| 40 |
is the path-name for the special device that corresponds to a |
| 41 |
SCSI scanner. For SCSI |
| 42 |
scanners, the special device name must be a generic SCSI device or a |
| 43 |
symlink to such a device. Under Linux, such a device name could be |
| 44 |
.I /dev/sga |
| 45 |
or |
| 46 |
.IR /dev/sge , |
| 47 |
for example. See |
| 48 |
.BR sane\-scsi (5) |
| 49 |
for details. |
| 50 |
|
| 51 |
.SH CONFIGURATION |
| 52 |
The |
| 53 |
.I apple.conf |
| 54 |
file is a list of options and device names that correspond to Apple |
| 55 |
scanners. Empty lines and lines starting with a hash mark (#) are |
| 56 |
ignored. See |
| 57 |
.BR sane\-scsi (5) |
| 58 |
on details of what constitutes a valid device name. |
| 59 |
.PP |
| 60 |
Options come in two flavors: global and positional ones. Global |
| 61 |
options apply to all devices managed by the backend, whereas positional |
| 62 |
options apply just to the most recently mentioned device. Note that |
| 63 |
this means that the order in which the options appear matters! |
| 64 |
|
| 65 |
.SH SCSI ADAPTER TIPS |
| 66 |
SCSI scanners are typically delivered with an ISA SCSI adapter. |
| 67 |
Unfortunately, that adapter is not worth much since it is not |
| 68 |
interrupt driven. It is sometimes possible to get the supplied card |
| 69 |
to work, but without an interrupt line, scanning will put so much load on |
| 70 |
the system that it becomes almost unusable for other tasks. |
| 71 |
.SH FILES |
| 72 |
.TP |
| 73 |
.I /etc/sane.d/apple.conf |
| 74 |
The backend configuration file (see also description of |
| 75 |
.B SANE_CONFIG_DIR |
| 76 |
below). |
| 77 |
.TP |
| 78 |
.I /usr/lib/x86_64-linux-gnu/sane/libsane\-apple.a |
| 79 |
The static library implementing this backend. |
| 80 |
.TP |
| 81 |
.I /usr/lib/x86_64-linux-gnu/sane/libsane\-apple.so |
| 82 |
The shared library implementing this backend (present on systems that |
| 83 |
support dynamic loading). |
| 84 |
.SH ENVIRONMENT |
| 85 |
.TP |
| 86 |
.B SANE_CONFIG_DIR |
| 87 |
This environment variable is a list of directories where SANE looks |
| 88 |
for the configuration file. On *NIX systems, directory names are |
| 89 |
separated by a colon (`:'), under OS/2 by a semi-colon (`;'). |
| 90 |
If SANE_CONFIG_DIR is not set, SANE defaults to |
| 91 |
searching the current working directory (".") and then |
| 92 |
.IR /etc/sane.d . |
| 93 |
If the value of $SANE_CONFIG_DIR ends with the separator |
| 94 |
character, the default directories are searched after the directory list. |
| 95 |
For example, setting |
| 96 |
.B SANE_CONFIG_DIR |
| 97 |
to "/tmp/config:" would result in directories |
| 98 |
.IR tmp/config , |
| 99 |
.IR . , |
| 100 |
and |
| 101 |
.I "/etc/sane.d" |
| 102 |
being searched (in that order). |
| 103 |
.TP |
| 104 |
.B SANE_DEBUG_APPLE |
| 105 |
Controls the debug level. A value of 255 prints |
| 106 |
all debug output. Smaller values reduce verbosity. Requires a |
| 107 |
library compiled with debug support. |
| 108 |
|
| 109 |
.SH CURRENT STATUS |
| 110 |
The apple backend is now in version 0.3 (Tue Jul 21 1998). Since |
| 111 |
I only have the AppleScanner and not the other models (OneScanner, |
| 112 |
ColorOneScanner) I can only develop/test for the AppleScanner effectively. |
| 113 |
However with this release I almost completed the GUI part of all scanners. |
| 114 |
Most of the functionality is there. At least OneScanner should scan |
| 115 |
at the AppleScanner's compatible modes (LineArt, HalfTone, Gray16). My |
| 116 |
personal belief is that with a slight touch of debugging the OneScanner |
| 117 |
could be actually usable. The ColorOneScanner needs more work. AppleScanner |
| 118 |
is of course almost fully supported. |
| 119 |
|
| 120 |
.SH MISSING FUNCTIONALITY |
| 121 |
Currently all three models lack upload/download support. |
| 122 |
.TP |
| 123 |
.B AppleScanner |
| 124 |
Cannot up/download a halftone pattern. |
| 125 |
.TP |
| 126 |
.B OneScanner |
| 127 |
Cannot up/download halftone patterns or calibration vectors. |
| 128 |
.TP |
| 129 |
.B ColorOneScanner |
| 130 |
Cannot up/download halftone patterns, calibration vectors, |
| 131 |
custom Color Correction Tables (CCT) and of course custom gamma tables. |
| 132 |
.TP |
| 133 |
.B Park/UnPark (OneScanner, ColorOneScanner) |
| 134 |
Some capabilities are missing. |
| 135 |
.PP |
| 136 |
The above functionalities are missing because I don't |
| 137 |
have the hardware to experiment on. Another reason is my lack |
| 138 |
of understanding as to how or if the SANE API provide means |
| 139 |
to describe any array type besides gamma. |
| 140 |
|
| 141 |
|
| 142 |
.SH UNSUPPORTED FEATURES |
| 143 |
The following "features" will never be supported, at least while I maintain |
| 144 |
the sane\-apple backend. |
| 145 |
.TP |
| 146 |
.B NoHome (AppleScanner) |
| 147 |
The scanner lamp stays on and the carriage assembly remains where it stops |
| 148 |
at the end of the scan. After two minutes, if the scanner does not receive |
| 149 |
another SCAN command, the lamp goes off and the carriage returns to the home |
| 150 |
position. |
| 151 |
.TP |
| 152 |
.B Compression (AppleScanner) |
| 153 |
The Scanner can compress data with CCITT Group III one dimensional algorithm |
| 154 |
(fax) and the Skip White Line algorithm. |
| 155 |
.TP |
| 156 |
.B Multiple Windows (AppleScanner) |
| 157 |
AppleScanner may support multiple windows. It would be a cool feature |
| 158 |
and a challenge for me to code if it could intermix different options |
| 159 |
for different windows (scan areas). This way it could scan a document |
| 160 |
in LineArt mode but the figures in it in Gray and at a different resolution. |
| 161 |
Unfortunately this is impossible. |
| 162 |
.TP |
| 163 |
.B Scan Direction (OneScanner) |
| 164 |
It controls the scan direction. (?) |
| 165 |
.TP |
| 166 |
.B Status/Reset Button (OneScanner) |
| 167 |
This option controls the status of the button on the OneScanner model. You can |
| 168 |
also reset the button status by software. |
| 169 |
|
| 170 |
.SH BUGS |
| 171 |
SANE backend bugs are divided in two classes. We have |
| 172 |
.B GUI |
| 173 |
bugs and |
| 174 |
.B scanner specific |
| 175 |
bugs. |
| 176 |
.PP |
| 177 |
We know we have a GUI bug when a parameter is not showing up when it |
| 178 |
should (active) or vice versa. Finding out which parameters are active |
| 179 |
across various Apple modes and models from the documentation |
| 180 |
is an interesting exercise. I may have missed some dependencies. For example |
| 181 |
of the threshold parameter the Apple Scanners Programming Guide says |
| 182 |
nothing. I had to assume it is valid only in LineArt mode. |
| 183 |
.PP |
| 184 |
Scanner specific bugs are mostly due to mandatory round-offs in order to |
| 185 |
scan. In the documentation in one place states that the width of the |
| 186 |
scan area should be a byte multiple. In another place it says that the |
| 187 |
width of the scan area should be an even byte multiple. Go figure... |
| 188 |
.PP |
| 189 |
Other sources of bugs are due to scsi communication, scsi connects and |
| 190 |
disconnects. However the classical bugs are still there. So you may |
| 191 |
encounter buffer overruns, null pointers, memory corruption and |
| 192 |
.B SANE |
| 193 |
API violations. |
| 194 |
.TP |
| 195 |
.B SIGSEGV on SliceBars |
| 196 |
When you try to modify the scan area from the slice bar you have a nice |
| 197 |
little cute core dump. I don't know why. If you select the scan area from |
| 198 |
the preview window or by hand typing the numbers everything is fine. The |
| 199 |
SIGSEGV happens deep in gtk library (gdk). I really cannot debug it. |
| 200 |
.TP |
| 201 |
.B Options too much |
| 202 |
It is possible, especially for the ColorOneScanner, for the backend's |
| 203 |
options panel to extend beyond your screen. It happens with mine |
| 204 |
and I am running my X Server at 1024x768. What can I say? Try smaller |
| 205 |
fonts in the X server, or virtual screens. |
| 206 |
.TP |
| 207 |
.B Weird SCSI behaviour |
| 208 |
I am quoting David Myers Here... |
| 209 |
|
| 210 |
>> OS: FreeBSD 2.2.6 |
| 211 |
.br |
| 212 |
>> CC: egcs-1.02 |
| 213 |
.br |
| 214 |
Just wanted to follow up on this... I recently changed my SCSI card from |
| 215 |
the Adaptec 2940UW to a dual-channel Symbios 786 chipset. When I started up |
| 216 |
SANE with your driver, I managed to scan line art drawings okay, but Gray16 |
| 217 |
scans led to a stream of SCSI error messages on the console, ultimately |
| 218 |
hanging with a message saying the scanner wasn't releasing the SCSI bus. |
| 219 |
This may be that the Symbios is simply less tolerant of ancient |
| 220 |
hardware, or may be bugs in your driver or in SANE itself... |
| 221 |
|
| 222 |
.SH DEBUG |
| 223 |
If you encounter a GUI bug please set the environmental variable |
| 224 |
.B SANE_DEBUG_APPLE |
| 225 |
to 255 and rerun the exact sequence of keystrokes |
| 226 |
and menu selections to reproduce it. Then send me a report with the |
| 227 |
log attached. |
| 228 |
.PP |
| 229 |
If you have an Apple Macintosh with the AppleScanners driver installed, |
| 230 |
reporting to me which options are grayed out (inactive) in what modes |
| 231 |
would be very helpful. |
| 232 |
.PP |
| 233 |
If you want to offer some help but you don't have a scanner, or you |
| 234 |
don't have the model you would like to help with, or you are |
| 235 |
a SANE developer and you just want to take a look at how the apple backend |
| 236 |
looks like, goto to |
| 237 |
.I apple.h |
| 238 |
and #define the |
| 239 |
.B NEUTRALIZE_BACKEND |
| 240 |
macro. You can select the scanner model through the |
| 241 |
.B APPLE_MODEL_SELECT |
| 242 |
macro. Available options are |
| 243 |
.BR APPLESCANNER , |
| 244 |
.BR ONESCANNER , |
| 245 |
and |
| 246 |
.BR COLORONESCANNER . |
| 247 |
.PP |
| 248 |
If you encounter a SCSI bus error or trimmed and/or displaced images please |
| 249 |
set the environment variable |
| 250 |
.B SANE_DEBUG_SANEI_SCSI |
| 251 |
to 255 before sending me |
| 252 |
the report. |
| 253 |
|
| 254 |
.SH TODO |
| 255 |
.TP |
| 256 |
.B Non Blocking Support |
| 257 |
Make |
| 258 |
.B sane\-apple |
| 259 |
a non blocking backend. Properly support |
| 260 |
.BR sane_set_io_mode () |
| 261 |
and |
| 262 |
.BR sane_get_select_fd (). |
| 263 |
.TP |
| 264 |
.B Scan |
| 265 |
Make scanning possible for all models in all supported modes. |
| 266 |
.PP |
| 267 |
Add other missing functionality. |
| 268 |
|
| 269 |
.SH "SEE ALSO" |
| 270 |
.BR sane (7), |
| 271 |
.BR sane\-scsi (5) |
| 272 |
|
| 273 |
.SH AUTHOR |
| 274 |
The |
| 275 |
.B sane\-apple |
| 276 |
backend was written not entirely from scratch by |
| 277 |
Milon Firikis. It is mostly based on the |
| 278 |
.BR sane\-mustek (5) |
| 279 |
backend from David Mosberger and Andreas Czechanowski. |