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

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