Next Up Previous Contents Index

4.5 Well-Known Options

Well-Known Options

While most backend options are completely self-describing, there are a few cases where a user interface might want to special-case 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 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 Area Options

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. 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:

4.5.3 Resolution Option

Resolution Option

Frontends that implement graphical user interfaces may want to support a preview window. To support this properly, a frontend must know how to set the resolution of the acquired image (if this is at all possible). The well-known option name resolution identifies the option that controls scanning resolution. Its unit must be in dots/inch (SANE_UNIT_DPI). A frontend must work properly in the absence of this option, but it may not be able to support a preview window in such a case.


Next Up Previous Contents Index