Debian Codegraph @

upstream/debian-unstable/man5/sane-test.5

raw
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