While most backend options are completely self-describing, there are a
cases where a user interface might want to special-case the handling
of certain options. For example, the scan area is typically defined
by four options that specify the top-left and bottom-right corners of
the area. With a graphical user interface, it would be tedious to
force the user to type in these four numbers. Instead, most such
interfaces will want to present to the user a preview (low-resolution
scan) of the scanner surface and let the user pick the scan area by
dragging a rectangle into the desired position. For this reason, the
SANE API specifies a small number of option names that have
well-defined meanings.
Option number 0 has an empty string as its name. The value of this
option is of type SANE_TYPE_INT and it specifies the total
number of options available for a given device (the count includes
option number 0). This means that there are two ways of counting the
number of options available: a frontend can either cycle through all
option numbers starting at one until
sane_get_option_descriptor() returns NULL, or a
frontend can directly read out the value of option number 0.
Option resolution is used to select the resolution at which an
image should be acquired. The type of this option is either
SANE_TYPE_INT or SANE_TYPE_FIXED. The unit is
SANE_UNIT_DPI (dots/inch).
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
The boolean option preview is used by a frontend to inform the
backend when image acquisition should be optimized for speed, rather
than quality (``preview mode''). When set to SANE_TRUE,
preview mode is in effect, when set to SANE_FALSE image
acquisition should proceed in normal quality mode. The setting of
this option must not affect any other option. That is, as
far as the other options are concerned, the preview mode is completely
side effect free. A backend can assume that the frontend will take
care of appropriately setting the scan resolution for preview mode
(through option resolution). A backend is free to override the
resolution value with its own choice for preview mode, but it
is advised to leave this choice to the frontend wherever possible.
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
The four most important well-known options are the ones that define
the scan area. The scan area is defined by two points (x/y coordinate
pairs) that specify the top-left and the bottom-right corners. This
is illustrated in Figure 5. Note that the origin of the
coordinate system is at the top-left corner of the scan surface as
seen by the sensor (which typically is a mirror image of the scan
surface seen by the user). For this reason, the top-left corner is
the corner for which the abscissa and ordinate values are
simultaneously the smallest and the bottom-right corner is the
corner for which the abscissa and ordinate values are simulatenously
the largest. If this coordinate system is not natural for a
given device, it is the job of the backend to perform the necessary
conversions.
Figure 5:Scan area options
The names of the four options that define the scan area are given in
the table below:
Name |
Description |
tl-x |
Top-left x coordinate value |
tl-y |
Top-left y coordinate value |
br-x |
Bottom-right x coordinate value |
br-y |
Bottom-right y coordinate value |
|
There are several rules that should be followed by front and backends
regarding these options:
- Backends must attach a unit of either pixels
(SANE_UNIT_PIXEL) or millimeters (SANE_UNIT_MM) to
these options. The unit of all four options must be identical.
- Whenever meaningful, a backend should attach a range or a
word-list constraint to these options.
- A frontend can determine the size of the scan surface by first
checking that the options have range constraints associated. If a
range or word-list constraints exist, the frontend can take the
minimum and maximum values of one of the x and y option
range-constraints to determine the scan surface size.
- A frontend must work properly with any or all of these options
missing.