| 1 |
.TH sane\-test 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy" |
| 2 |
.IX sane\-test |
| 3 |
.SH NAME |
| 4 |
sane\-test \- SANE backend for testing frontends |
| 5 |
.SH DESCRIPTION |
| 6 |
The |
| 7 |
.B sane\-test |
| 8 |
library implements a SANE (Scanner Access Now Easy) backend that allows |
| 9 |
testing the SANE installation and SANE frontends. It provides access to a |
| 10 |
(nearly) unlimited number of virtual devices. There is no support for real |
| 11 |
scanners or cameras. However, the backend simulates scanning and setting |
| 12 |
options. |
| 13 |
.PP |
| 14 |
The idea is not only to find bugs in frontends but also to show all |
| 15 |
capabilities of SANE. Therefore |
| 16 |
.B sane\-test |
| 17 |
implements functions and options that are not (or seldom) found in other |
| 18 |
backends. |
| 19 |
.PP |
| 20 |
The backend is commented out in |
| 21 |
.IR /etc/sane.d/dll.conf , |
| 22 |
so either the comment |
| 23 |
character must be removed or the backend must be called explicitly. E.g. |
| 24 |
.I scanimage \-d test |
| 25 |
or |
| 26 |
.IR "xscanimage test" . |
| 27 |
|
| 28 |
|
| 29 |
.SH SCAN MODE OPTIONS |
| 30 |
Option |
| 31 |
.B mode |
| 32 |
selects the scan mode (Gray or Color). |
| 33 |
.PP |
| 34 |
Option |
| 35 |
.B depth |
| 36 |
determines the number of bits per sample (1. 8, or 16). Keep in mind, that |
| 37 |
this value refers to the sample, not the pixel. So depth=16 results in 48 |
| 38 |
bits per pixel in color mode. The most usual combinations are mode=Gray, |
| 39 |
depth=1 for lineart, mode=Gray, depth=8 for gray and mode=Color, depth=8 for |
| 40 |
color mode. The combination of color and 1-bit mode is quite obscure (8 |
| 41 |
colors) but allowed in the SANE standard. However, the meaning of bits is not |
| 42 |
defined. Currently 1 = high intensity and 0 = low intensity is used. |
| 43 |
.PP |
| 44 |
Setting option |
| 45 |
.B hand\-scanner |
| 46 |
results in the test-backend behaving like a hand-scanner. Hand-scanners do |
| 47 |
not know the image height a priori. Instead, they return a height of \-1. |
| 48 |
Setting this option allows one to test whether a frontend can handle this |
| 49 |
correctly. This option also enables a fixed width of 11 cm. |
| 50 |
.PP |
| 51 |
Setting option |
| 52 |
.B three\-pass |
| 53 |
simulates a three-pass scanner. Older color scanners needed to scan the image |
| 54 |
once per color (red/green/blue) to get the full image. Therefore, in this mode |
| 55 |
three single frames are transmitted in color mode. |
| 56 |
.PP |
| 57 |
Option |
| 58 |
.B three\-pass\-order |
| 59 |
provides support for changing the order of the three frames (see option |
| 60 |
three-pass above). A frontend should support all orders. |
| 61 |
.PP |
| 62 |
Option |
| 63 |
.B resolution |
| 64 |
sets the resolution of the image in dots per inch. |
| 65 |
.PP |
| 66 |
.PP |
| 67 |
Option |
| 68 |
.B source |
| 69 |
can be used to simulate an Automatic Document Feeder (ADF). After 10 scans, the |
| 70 |
ADF will be "empty". |
| 71 |
.PP |
| 72 |
|
| 73 |
.SH SPECIAL OPTIONS |
| 74 |
Option |
| 75 |
.B test\-picture |
| 76 |
allows one to set the image that's returned to the frontend. While "Solid white" |
| 77 |
and "Solid black" are quite obvious, the other options need some more |
| 78 |
explanation. Color patterns are used to determine if all modes and their |
| 79 |
colors are represented correctly by the frontend. The grid should look like the |
| 80 |
same in every mode and resolution. A table of all the test pictures can be |
| 81 |
found at: |
| 82 |
.IR http://www.meier\-geinitz.de/sane/test\-backend/test\-pictures.html . |
| 83 |
.PP |
| 84 |
If option |
| 85 |
.B invert\-endianness |
| 86 |
is set, the upper and lower bytes of image data in 16 bit modes are exchanged. |
| 87 |
This option can be used to test the 16 bit modes of frontends, e.g. if the |
| 88 |
frontend uses the correct endianness. |
| 89 |
.PP |
| 90 |
If option |
| 91 |
.B read\-limit |
| 92 |
is set, the maximum amount of data transferred with each call to |
| 93 |
.BR sane_read () |
| 94 |
is limited. |
| 95 |
.PP |
| 96 |
Option |
| 97 |
.B read\-limit\-size |
| 98 |
sets the limit for option read-limit. A low limit slows down scanning. It |
| 99 |
can be used to detect errors in frontend that occur because of wrong |
| 100 |
assumptions on the size of the buffer or timing problems. |
| 101 |
.PP |
| 102 |
Option |
| 103 |
.B read\-delay |
| 104 |
enables delaying data to the frontend. |
| 105 |
.PP |
| 106 |
Option |
| 107 |
.B read\-delay\-duration |
| 108 |
selects the number of microseconds the backends waits after each transfer of a |
| 109 |
buffer. This option is useful to find timing-related bugs, especially if |
| 110 |
used over the network. |
| 111 |
.PP |
| 112 |
If option |
| 113 |
.B read\-return\-value |
| 114 |
is different from "Default", the selected status will be returned by every |
| 115 |
call to |
| 116 |
.BR sane_read (). |
| 117 |
This is useful to test the frontend's handling of the SANE statuses. |
| 118 |
.PP |
| 119 |
If option |
| 120 |
.B ppl\-loss |
| 121 |
is different from 0, it determines the number of pixels that are "lost" at the |
| 122 |
end of each line. That means, lines are padded with unused data. |
| 123 |
.PP |
| 124 |
Option |
| 125 |
.B fuzzy\-parameters |
| 126 |
selects that fuzzy (inexact) parameters are returned as long as the scan |
| 127 |
hasn't been started. This option can be used to test if the frontend uses the |
| 128 |
parameters it got before the start of the scan (which it shouldn't). |
| 129 |
.PP |
| 130 |
Option |
| 131 |
.B non\-blocking |
| 132 |
determines if non-blocking IO for |
| 133 |
.BR sane_read () |
| 134 |
should be used if supported by the frontend. |
| 135 |
.PP |
| 136 |
If option |
| 137 |
.B select\-fd |
| 138 |
is set, the backend offers a select filedescriptor for detecting if |
| 139 |
.BR sane_read() |
| 140 |
will return data. |
| 141 |
.PP |
| 142 |
If option |
| 143 |
.B enable\-test\-options |
| 144 |
is set, a fairly big list of options for testing the various SANE option |
| 145 |
types is enabled. |
| 146 |
.PP |
| 147 |
Option |
| 148 |
.B print\-options |
| 149 |
can be used to print a list of all options to standard error. |
| 150 |
.PP |
| 151 |
|
| 152 |
.SH GEOMETRY OPTIONS |
| 153 |
Option |
| 154 |
.B tl\-x |
| 155 |
determines the top-left x position of the scan area. |
| 156 |
.PP |
| 157 |
Option |
| 158 |
.B tl\-y |
| 159 |
determines the top-left y position of the scan area. |
| 160 |
.PP |
| 161 |
Option |
| 162 |
.B br\-x |
| 163 |
determines the bottom-right x position of the scan area. |
| 164 |
.PP |
| 165 |
Option |
| 166 |
.B br\-y |
| 167 |
determines the bottom-right y position of the scan area. |
| 168 |
.PP |
| 169 |
|
| 170 |
.SH BOOL TEST OPTIONS |
| 171 |
There are 6 bool test options in total. Each option is numbered. (3/6) |
| 172 |
means: this is option 3 of 6. The numbering scheme is intended for easier |
| 173 |
detection of options not displayed by the frontend (because of missing support |
| 174 |
or bugs). |
| 175 |
.PP |
| 176 |
Option |
| 177 |
.B bool\-soft\-select\-soft\-detect |
| 178 |
(1/6) is a bool test option that has soft select and soft detect (and |
| 179 |
advanced) capabilities. That's just a normal bool option. |
| 180 |
.PP |
| 181 |
Option |
| 182 |
.B bool\-hard\-select\-soft\-detect |
| 183 |
(2/6) is a bool test option that has hard select and soft detect (and |
| 184 |
advanced) capabilities. That means the option can't be set by the frontend |
| 185 |
but by the user (e.g. by pressing a button at the device). |
| 186 |
.PP |
| 187 |
Option |
| 188 |
.B bool\-hard\-select |
| 189 |
(3/6) is a bool test option that has hard select (and advanced) capabilities. |
| 190 |
That means the option can't be set by the frontend but by the user (e.g. by |
| 191 |
pressing a button at the device) and can't be read by the frontend. |
| 192 |
.PP |
| 193 |
Option |
| 194 |
.B bool\-soft\-detect |
| 195 |
(4/6) is a bool test option that has soft detect (and advanced) |
| 196 |
capabilities. That means the option is read-only. |
| 197 |
.PP |
| 198 |
Option |
| 199 |
.B bool\-soft\-select\-soft\-detect\-emulated |
| 200 |
(5/6) is a Bool test option that has soft select, soft detect, and emulated |
| 201 |
(and advanced) capabilities. |
| 202 |
.PP |
| 203 |
Option |
| 204 |
.B bool\-soft\-select\-soft\-detect\-auto |
| 205 |
(6/6) is a Bool test option that has soft select, soft detect, and automatic |
| 206 |
(and advanced) capabilities. This option can be automatically set by the |
| 207 |
backend. |
| 208 |
.PP |
| 209 |
|
| 210 |
.SH INT TEST OPTIONS |
| 211 |
There are 7 int test options in total. |
| 212 |
.PP |
| 213 |
Option |
| 214 |
.B int |
| 215 |
(1/7) is an int test option with no unit and no constraint set. |
| 216 |
.PP |
| 217 |
Option |
| 218 |
.B int\-constraint\-range |
| 219 |
(2/7) is an int test option with unit pixel and constraint range set. Minimum |
| 220 |
is 4, maximum 192, and quant is 2. |
| 221 |
.PP |
| 222 |
Option |
| 223 |
.B int\-constraint\-word\-list |
| 224 |
(3/7) is an int test option with unit bits and constraint word list set. |
| 225 |
.PP |
| 226 |
Option |
| 227 |
.B int\-constraint\-array |
| 228 |
(4/7) is an int test option with unit mm and using an array without |
| 229 |
constraints. |
| 230 |
.PP |
| 231 |
Option |
| 232 |
.B int\-constraint\-array\-constraint\-range |
| 233 |
(5/7) is an int test option with unit mm and using an array with a range |
| 234 |
constraint. Minimum is 4, maximum 192, and quant is 2. |
| 235 |
.PP |
| 236 |
Option |
| 237 |
.B int\-constraint\-array\-constraint\-word\-list |
| 238 |
(6/7) is an int test option with unit percent and using an array or word list |
| 239 |
constraint. |
| 240 |
.PP |
| 241 |
Option |
| 242 |
.B int\-inexact |
| 243 |
(7/7) is an int test option that increments the requested value and returns |
| 244 |
flag SANE_INFO_INEXACT. |
| 245 |
|
| 246 |
|
| 247 |
.SH FIXED TEST OPTIONS |
| 248 |
There are 3 fixed test options in total. |
| 249 |
.PP |
| 250 |
Option |
| 251 |
.B fixed |
| 252 |
(1/3) is a fixed test option with no unit and no constraint set. |
| 253 |
.PP |
| 254 |
Option |
| 255 |
.B fixed\-constraint\-range |
| 256 |
(2/3) is a fixed test option with unit microsecond and constraint range |
| 257 |
set. Minimum is \-42.17, maximum 32767.9999, and quant is 2.0. |
| 258 |
.PP |
| 259 |
Option |
| 260 |
.B fixed\-constraint\-word\-list |
| 261 |
(3/3) is a fixed test option with no unit and constraint word list set. |
| 262 |
.PP |
| 263 |
|
| 264 |
.SH STRING TEST OPTIONS |
| 265 |
There are 3 string test options in total. |
| 266 |
.PP |
| 267 |
Option |
| 268 |
.B string |
| 269 |
(1/3) is a string test option without constraint. |
| 270 |
.PP |
| 271 |
Option |
| 272 |
.B string\-constraint\-string\-list |
| 273 |
(2/3) is a string test option with string list constraint. |
| 274 |
.PP |
| 275 |
Option |
| 276 |
.B string\-constraint\-long\-string\-list |
| 277 |
(3/3) is a string test option with string list constraint. Contains some more |
| 278 |
entries... |
| 279 |
.PP |
| 280 |
|
| 281 |
.SH BUTTON TEST OPTION |
| 282 |
Option |
| 283 |
.B button |
| 284 |
(1/1) is a Button test option. Prints some text... |
| 285 |
.PP |
| 286 |
|
| 287 |
.SH FILES |
| 288 |
.TP |
| 289 |
.I /etc/sane.d/test.conf |
| 290 |
The backend configuration file (see also description of |
| 291 |
.B SANE_CONFIG_DIR |
| 292 |
below). The initial values of most of the basic SANE options can be configured |
| 293 |
in this file. A template containing all the default values is provided |
| 294 |
together with this backend. One of the more interesting values may be |
| 295 |
.BR number_of_devices . |
| 296 |
It can be used to check the frontend's ability to show a long list of devices. |
| 297 |
The config values concerning resolution and geometry can be useful to test |
| 298 |
the handling of big file sizes. |
| 299 |
|
| 300 |
.TP |
| 301 |
.I /usr/lib/x86_64-linux-gnu/sane/libsane\-test.a |
| 302 |
The static library implementing this backend. |
| 303 |
.TP |
| 304 |
.I /usr/lib/x86_64-linux-gnu/sane/libsane\-test.so |
| 305 |
The shared library implementing this backend (present on systems that |
| 306 |
support dynamic loading). |
| 307 |
|
| 308 |
.SH ENVIRONMENT |
| 309 |
.TP |
| 310 |
.B SANE_CONFIG_DIR |
| 311 |
This environment variable specifies the list of directories that may |
| 312 |
contain the configuration file. On *NIX systems, the directories are |
| 313 |
separated by a colon (`:'), under OS/2, they are separated by a |
| 314 |
semi-colon (`;'). If this variable is not set, the configuration file |
| 315 |
is searched in two default directories: first, the current working |
| 316 |
directory (".") and then in |
| 317 |
.IR /etc/sane.d . |
| 318 |
If the value of the |
| 319 |
environment variable ends with the directory separator character, then |
| 320 |
the default directories are searched after the explicitly specified |
| 321 |
directories. For example, setting |
| 322 |
.B SANE_CONFIG_DIR |
| 323 |
to "/tmp/config:" would result in directories |
| 324 |
.IR tmp/config , |
| 325 |
.IR . , |
| 326 |
and |
| 327 |
.I "/etc/sane.d" |
| 328 |
being searched (in this order). |
| 329 |
.TP |
| 330 |
.B SANE_DEBUG_TEST |
| 331 |
If the library was compiled with debug support enabled, this |
| 332 |
environment variable controls the debug level for this backend. Higher |
| 333 |
debug levels increase the verbosity of the output. |
| 334 |
|
| 335 |
Example: |
| 336 |
export SANE_DEBUG_TEST=4 |
| 337 |
|
| 338 |
.SH "SEE ALSO" |
| 339 |
.BR sane (7), |
| 340 |
.BR scanimage (1), |
| 341 |
.BR xscanimage (1) |
| 342 |
.br |
| 343 |
.IR http://www.meier\-geinitz.de/sane/test\-backend/ |
| 344 |
|
| 345 |
|
| 346 |
.SH AUTHOR |
| 347 |
Henning Meier-Geinitz |
| 348 |
.RI < henning@meier\-geinitz.de > |
| 349 |
|
| 350 |
.SH BUGS |
| 351 |
\- config file values aren't tested for correctness |