Next Up Previous Contents Index
Well-Known Options

4.5 Well-Known Options

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.

4.5.1 Option Number Count

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.

4.5.2 Scan Resolution Option

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.

4.5.3 Preview Mode Option

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.

4.5.4 Scan Area Options

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:


Next Up Previous Contents Index