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