kopia lustrzana https://gitlab.com/sane-project/website
146 wiersze
6.3 KiB
HTML
146 wiersze
6.3 KiB
HTML
<html><body>
|
|
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
|
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
|
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
|
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
|
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
|
<hr>
|
|
|
|
<title>Well-Known Options</title>
|
|
<h2><a name="s4.5">4.5 Well-Known Options</a></h2><a name="i107">
|
|
|
|
<p>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.
|
|
|
|
<p><h3><a name="s4.5.1">4.5.1 Option Number Count</a></h3><a name="i108">
|
|
|
|
<p>Option number 0 has an empty string as its name. The value of this
|
|
option is of type <tt>SANE_TYPE_INT</tt> 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
|
|
<tt>sane_get_option_descriptor()</tt> returns <tt>NULL</tt>, or a
|
|
frontend can directly read out the value of option number 0.
|
|
|
|
<p><h3><a name="s4.5.2">4.5.2 Scan Resolution Option</a></h3><a name="i109"><a name="i110">
|
|
|
|
<p>Option <tt>resolution</tt> is used to select the resolution at which an
|
|
image should be acquired. The type of this option is either
|
|
<tt>SANE_TYPE_INT</tt> or <tt>SANE_TYPE_FIXED</tt>. The unit is
|
|
<tt>SANE_UNIT_DPI</tt> (dots/inch).
|
|
|
|
<p>This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
|
|
<p><h3><a name="s4.5.3">4.5.3 Preview Mode Option</a></h3><a name="i111">
|
|
|
|
<p>The boolean option <tt>preview</tt> 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 <tt>SANE_TRUE</tt>,
|
|
preview mode is in effect, when set to <tt>SANE_FALSE</tt> image
|
|
acquisition should proceed in normal quality mode. The setting of
|
|
this option <em>must not</em> 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 <tt>resolution</tt>). A backend is free to override the
|
|
<tt>resolution</tt> value with its own choice for preview mode, but it
|
|
is advised to leave this choice to the frontend wherever possible.
|
|
|
|
<p>This option is not mandatory, but if a backend does support it, it
|
|
must implement it in a manner consistent with the above definition.
|
|
|
|
<p><h3><a name="s4.5.4">4.5.4 Scan Area Options</a></h3><a name="i112">
|
|
|
|
<p>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 <a href="doc014.html#f5">5</a>. 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 <em>smallest</em> and the bottom-right corner is the
|
|
corner for which the abscissa and ordinate values are simulatenously
|
|
the <em>largest</em>. If this coordinate system is not natural for a
|
|
given device, it is the job of the backend to perform the necessary
|
|
conversions.
|
|
<p><a name="f5"></a>
|
|
<center>
|
|
|
|
<img width=330 height=306 src="img004.gif">
|
|
<p><center>Figure 5: Scan area options</center>
|
|
|
|
</center>
|
|
<p>
|
|
|
|
<p>The names of the four options that define the scan area are given in
|
|
the table below:
|
|
<center>
|
|
<table cellpadding=0 cellspacing=0>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<b>Name</b> </td>
|
|
<td colspan=1 align=left nowrap> <b>Description</b> </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>tl-x<a name="i113"></tt> </td>
|
|
<td colspan=1 align=left nowrap> Top-left x coordinate value </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>tl-y<a name="i114"></tt> </td>
|
|
<td colspan=1 align=left nowrap> Top-left y coordinate value </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>br-x<a name="i115"></tt> </td>
|
|
<td colspan=1 align=left nowrap> Bottom-right x coordinate value </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
<tt>br-y<a name="i116"></tt> </td>
|
|
<td colspan=1 align=left nowrap> Bottom-right y coordinate value </td></tr>
|
|
<tr valign=top>
|
|
<td colspan=1 align=left nowrap>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
There are several rules that should be followed by front and backends
|
|
regarding these options:
|
|
<ul>
|
|
|
|
<p><li>Backends must attach a unit of either pixels
|
|
(<tt>SANE_UNIT_PIXEL</tt>) or millimeters (<tt>SANE_UNIT_MM</tt>) to
|
|
these options. The unit of all four options must be identical.
|
|
|
|
<p><li>Whenever meaningful, a backend should attach a range or a
|
|
word-list constraint to these options.
|
|
|
|
<p><li>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.
|
|
|
|
<p><li>A frontend must work properly with any or all of these options
|
|
missing.
|
|
|
|
</ul>
|
|
|
|
<p><p><hr>
|
|
<a href="doc015.html"><img src=../icons/next.gif alt="Next"></a>
|
|
<a href="doc000.html"><img src=../icons/up.gif alt="Up"></a>
|
|
<a href="doc013.html"><img src=../icons/previous.gif alt="Previous"></a>
|
|
<a href="doc000.html"><img src=../icons/contents.gif alt="Contents"></a>
|
|
<a href="doc019.html"><img src=../icons/index.gif alt="Index"></a>
|
|
<hr>
|
|
</body></html>
|