While most backend options are completely self-describing, there are 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 full scanner surface or a high(er) resolution scan of a subpart 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. When the backend wants to allow different
values for x- and y-resolution it has to define the options
x_resolution and y_resolution. Note that only
the option resolution or the options
x_resolution and y_resolution may be active.
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. When the preview option is set the backend should transfer the image in frame type SANE_FRAME_RAW if 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.
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 |
red_value = gamma-table(red-gamma-table(value)) green_value = gamma-table(green-gamma-table(value)) blue_value = gamma-table(blue-gamma-table(value))
The backend should not use the gamma tables to emulate other functions or options
like highlight, shadow, contrast, brightness, threshold, analog_gamma.
These functions are common for all backends and should be added to the frontend
or a meta-backend.
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
When analog gamma, highlight and shadow functions are available at the same time then the backend author has to care about the order in which the functions are implemented in the scanner hardware. The SANE standard expects that changing the analog gamma value has no effect on the shadow and highlight function. When the analog gamma function is executed in the scanner hardware before the shadow and highlight functions then the backend should do a compensation. For this the shadow and highlight values have to be gamma corrected with the relevant analog gamma value.
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
This option is not mandatory, but if a backend does support it, it
must implement it in a manner consistent with the above definition.
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 option lamp-off is used to turn the lamp of the scanner off. The type of this option is SANE_TYPE_BUTTON. The unit is SANE_UNIT_NONE. When the option is set then the lamp of the scanner is turned off.
These options are not mandatory, but if a backend does support them, it
must implement them in a manner consistent with the above definition.
A backend that does make available the scanner-buttons has to
implement the following options:
scanner-buttons-lock is of type SANE_TYPE_BOOL, default = SANE_FALSE
scanner-buttons-status is of type SANE_TYPE_INT, default = 0
scanner-buttons-status-update is of type SANE_TYPE_BUTTON
When setting these options the backend does not set SANE_INFO_RELOAD_OPTIONS
or SANE_INFO_RELOAD_PARAMS if not explictly defined.
A frontend has to disable the usage of the scanner-buttons by default. This is important because other frontends will not be able to use the buttons when the button-functions are locked. Another important thing is that some scanners do not turn off their lamp when the driver does frequently talk to the scanner (what is done when reading the button status from the scanner).
sane_close() should do the same as setting option scanner-buttons-lock to SANE_FALSE.