1sane-test(5)             SANE Scanner Access Now Easy             sane-test(5)
2
3
4

NAME

6       sane-test - SANE backend for testing frontends
7

DESCRIPTION

9       The sane-test library implements a SANE (Scanner Access Now Easy) back‐
10       end that allows testing the SANE installation and SANE  frontends.   It
11       provides  access  to  a  (nearly)  unlimited number of virtual devices.
12       There is no support for real scanners or cameras.  However, the backend
13       simulates scanning and setting options.
14
15       The  idea  is  not  only to find bugs in frontends but also to show all
16       capabilities of SANE.  Therefore  sane-test  implements  functions  and
17       options that are not (or seldom) found in other backends.
18
19       The  backend  is  commented  out in /etc/sane.d/dll.conf, so either the
20       comment character must be removed or the backend must be called explic‐
21       itly.  E.g.  `scanimage -d test' or `xscanimage test'.
22
23

SCAN MODE OPTIONS

25       Option mode selects the scan mode (Gray or Color).
26
27       Option  depth  determines  the number of bits per sample (1. 8, or 16).
28       Keep in mind, that this value refers to the sample, not the pixel.   So
29       depth=16  results  in  48  bits per pixel in color mode. The most usual
30       combinations are mode=Gray, depth=1 for lineart, mode=Gray, depth=8 for
31       gray  and mode=Color, depth=8 for color mode.  The combination of color
32       and 1-bit mode is quite obscure (8 colors)  but  allowed  in  the  SANE
33       standard.  However,  the  meaning of bits is not defined. Currently 1 =
34       high intensity and 0 = low intensity is used.
35
36       Setting option hand-scanner results in the test-backend behaving like a
37       hand-scanner.   Hand-scanners  do  not  know the image height a priori.
38       Instead, they return a height of -1.  Setting  this  option  allows  to
39       test  whether  a  frontend can handle this correctly.  This option also
40       enables a fixed width of 11 cm.
41
42       Setting option three-pass simulates a three-pass scanner.  Older  color
43       scanners  needed  to  scan the image once per color (reg/green/blue) to
44       get the full image.  Therefore, in this mode three  single  frames  are
45       transmitted in color mode.
46
47       Option  three-pass-order provides support for changing the order of the
48       three frames (see option three-pass above).  A frontend should  support
49       all orders.
50
51       Option resolution sets the resolution of the image in dots per inch.
52
53       Option  source  can  be  used  to simulate an Automatic Document Feeder
54       (ADF). After 10 scans, the ADF will be "empty".
55

SPECIAL OPTIONS

57       Option test-picture allows to set the  image  that's  returned  to  the
58       frontend.  While "Solid white" and "Solid black" are quite obvious, the
59       other options need some more explanation.  Color patterns are  used  to
60       determine  if  all  modes and their colors are represented correctly by
61       the frontend.  The grid should look like the same  in  every  mode  and
62       resolution.   A  table  of  all  the  test  pictures  can  be found at:
63       http://www.meier-geinitz.de/sane/test-backend/test-pictures.html.
64
65       If option invert-endianess is set, the upper and lower bytes  of  image
66       data  in  16  bit modes are exchanged.  This option can be used to test
67       the 16 bit modes of frontends, e.g. if the frontend  uses  the  correct
68       endianess.
69
70       If  option  read-limit  is  set, the maximum amount of data transferred
71       with each call to sane_read() is limited.
72
73       Option read-limit-size sets the limit for  option  read-limit.   A  low
74       limit slows down scanning.  It can be used to detect errors in frontend
75       that occur because of wrong assumptions on the size of  the  buffer  or
76       timing problems.
77
78       Option read-delay enables delaying data to the frontend.
79
80       Option read-delay-duration selects the number of microseconds the back‐
81       ends waits after each transfer of a buffer.  This option is  useful  to
82       find timing-related bugs, especially if used over the network.
83
84       If  option  read-return-value is different from "Default", the selected
85       status will be returned by every call to sane_read().  This  is  useful
86       to test the frontend's handling of the SANE statuses.
87
88       If  option  ppl-loss  is  different from 0, it determines the number of
89       pixels that are "lost" at the end of each line.  That means, lines  are
90       padded with unused data.
91
92       Option  fuzzy-parameters  selects  that  fuzzy (inexact) parameters are
93       returned as long as the scan hasn't been started.  This option  can  be
94       used  to  test  if  the  frontend uses the parameters it got before the
95       start of the scan (which it shouldn't).
96
97       Option non-blocking  determines  if  non-blocking  IO  for  sane_read()
98       should be used if supported by the frontend.
99
100       If  option select-fd is set, the backend offers a select filedescriptor
101       for detecting if sane_read() will return data.
102
103       If option enable-test-options is set, a fairly big list of options  for
104       testing the various SANE option types is enabled.
105
106       Option  print-options  can  be  used  to print a list of all options to
107       standard error.
108

GEOMETRY OPTIONS

110       Option tl-x determines the top-left x position of the scan area.
111
112       Option tl-y determines the top-left y position of the scan area.
113
114       Option br-x determines the bottom-right x position of the scan area.
115
116       Option br-y determines the bottom-right y position of the scan area.
117

BOOL TEST OPTIONS

119       There are 6 bool test options  in  total.   Each  option  is  numbered.
120       (3/6)  means:  this is option 3 of 6.  The numbering scheme is intended
121       for easier detection of options not displayed by the frontend  (because
122       of missing support or bugs).
123
124       Option  bool-soft-select-soft-detect  (1/6)  is a bool test option that
125       has soft select and soft detect (and  advanced)  capabilities.   That's
126       just a normal bool option.
127
128       Option  bool-hard-select-soft-detect  (2/6)  is a bool test option that
129       has hard select and soft  detect  (and  advanced)  capabilities.   That
130       means  the option can't be set by the frontend but by the user (e.g. by
131       pressing a button at the device).
132
133       Option bool-hard-select (3/6) is a  bool  test  option  that  has  hard
134       select (and advanced) capabilities.  That means the option can't be set
135       by the frontend but by the user (e.g.  by  pressing  a  button  at  the
136       device) and can't be read by the frontend.
137
138       Option  bool-soft-detect  (4/6)  is  a  bool  test option that has soft
139       detect (and advanced) capabilities.  That means  the  option  is  read-
140       only.
141
142       Option  bool-soft-select-soft-detect-emulated  (5/6)  is  a  Bool  test
143       option that has soft select, soft detect, and emulated  (and  advanced)
144       capabilities.
145
146       Option  bool-soft-select-soft-detect-auto  (6/6)  is a Bool test option
147       that has soft select, soft detect, and automatic (and  advanced)  capa‐
148       bilities.  This option can be automatically set by the backend.
149

INT TEST OPTIONS

151       There are 6 int test options in total.
152
153       Option  int  (1/6) is an int test option with no unit and no constraint
154       set.
155
156       Option int-constraint-range (2/6) is an int test option with unit pixel
157       and constraint range set.  Minimum is 4, maximum 192, and quant is 2.
158
159       Option  int-constraint-word-list  (3/6) is an int test option with unit
160       bits and constraint word list set.
161
162       Option int-constraint-array (4/6) is an int test option  with  unit  mm
163       and using an array without constraints.
164
165       Option  int-constraint-array-constraint-range  (5/6)  is  an  int  test
166       option with unit mm and using an array with a range constraint.   Mini‐
167       mum is 4, maximum 192, and quant is 2.
168
169       Option  int-constraint-array-constraint-word-list  (6/6) is an int test
170       option with unit percent and using an array a word list constraint.
171
172

FIXED TEST OPTIONS

174       There are 3 fixed test options in total.
175
176       Option fixed (1/3) is a fixed test option with  no  unit  and  no  con‐
177       straint set.
178
179       Option  fixed-constraint-range  (2/3)  is a fixed test option with unit
180       microsecond and  constraint  range  set.  Minimum  is  -42.17,  maximum
181       32767.9999, and quant is 2.0.
182
183       Option  fixed-constraint-word-list (3/3) is a Fixed test option with no
184       unit and constraint word list set.
185

STRING TEST OPTIONS

187       There are 3 string test options in total.
188
189       Option string (1/3) is a string test option without constraint.
190
191       Option string-constraint-string-list (2/3) is a string test option with
192       string list constraint.
193
194       Option string-constraint-long-string-list (3/3) is a string test option
195       with string list constraint. Contains some more entries...
196

BUTTON TEST OPTION

198       Option button (1/1) is a Button test option. Prints some text...
199

FILES

201       /etc/sane.d/test.conf
202              The  backend  configuration  file  (see  also   description   of
203              SANE_CONFIG_DIR  below). The initial values of most of the basic
204              SANE options can be configured in this file. A template contain‐
205              ing  all the default values is provided together with this back‐
206              end.  One  of  the  more  interesting   values   may   be   num‐
207              ber_of_devices.   It can be used to check the frontend's ability
208              to show a long list of devices.  The  config  values  concerning
209              resolution  and  geometry  can be useful to test the handling of
210              big file sizes.
211
212
213       /usr/lib64/sane/libsane-test.a
214              The static library implementing this backend.
215
216       /usr/lib64/sane/libsane-test.so
217              The shared library implementing this backend (present on systems
218              that support dynamic loading).
219

ENVIRONMENT

221       SANE_CONFIG_DIR
222              This environment variable specifies the list of directories that
223              may contain the configuration file.  Under UNIX, the directories
224              are  separated  by a colon (`:'), under OS/2, they are separated
225              by a semi-colon (`;').  If this variable is not set, the config‐
226              uration  file is searched in two default directories: first, the
227              current working directory (".") and then in /etc/sane.d.  If the
228              value  of the environment variable ends with the directory sepa‐
229              rator character, then the default directories are searched after
230              the  explicitly  specified  directories.   For  example, setting
231              SANE_CONFIG_DIR to "/tmp/config:" would  result  in  directories
232              "tmp/config",  ".",  and  "/etc/sane.d"  being searched (in this
233              order).
234
235       SANE_DEBUG_TEST
236              If the library was compiled with  debug  support  enabled,  this
237              environment  variable controls the debug level for this backend.
238              Higher debug levels increase the verbosity of the output.
239
240              Example: export SANE_DEBUG_TEST=4
241
242

SEE ALSO

244       sane(7), http://www.meier-geinitz.de/sane/test-backend/
245
246
247

AUTHOR

249       Henning Meier-Geinitz <henning@meier-geinitz.de>
250
251

BUGS

253       - config file values aren't tested for correctness
254
255
256
257                                  14 Jul 2008                     sane-test(5)
Impressum