[sane-devel] Proposal: SANE standard additions/fixes
Henning Meier-Geinitz
henning@meier-geinitz.de
Thu, 10 Oct 2002 17:44:03 +0200
Hi,
On Thu, Sep 26, 2002 at 10:38:33PM +0200, Henning Meier-Geinitz wrote:
> While I'm working on this topic some more small issues that got lost
> somehow after older discussions. These are proposals for SANE 1. From
> TODO:
Thanks everyone for responding. If nobody opposes, I will change "the
easy topics" in the standard and keep the more complicated ones for
later. Maybe even a comment in doc/backend-writing is enough.
I will change:
> 1) What happens when sane_init returns a status other than
> SANE_STATUS_GOOD?
"This function must be called before any other SANE function can be
called. The behavior of a SANE backend is undefined if this function
is not called first or if the status code returned by sane_init is
different from SANE_STATUS_GOOD."
The slight change in wording is because otherwise I would get an
overfull hbox.
> 4) Return status of sane_start:
Adding another return status:
"SANE_STATUS_INVAL
The scan cannot be started with the current set of options.
The frontend should reload the option descriptors, as if
SANE_INFO_RELOAD_OPTIONS had been returned from a call to
sane_control_option(), since the device's capabilities may have
changed."
> 5) sane_set_io_mode
Adding the last sentence in paragraph and changing the description of
SANE_STATUS_UNSUPPORTED.
> "This function is used to set the I/O mode of handle h. The I/O mode
> can be either blocking or non-blocking. If argument m is SANE_TRUE,
> the mode is set to non-blocking mode, otherwise it's set to blocking
> mode. This function can be called only after a call to sane_start()
> has been performed."
[...]
> SANE_STATUS_UNSUPPORTED:
> The backend does not support the requested I/O mode."
I will attach a patch for sane.tex. This patch includes the earlier
changes for the 1 bit modes that are already applied. The reason is
that I can't access the CVS server currently.
Bye,
Henning
--- ../../sane-bpf/sane-backends/doc/sane.tex 2002-03-08 23:39:59.000000000 +0100
+++ doc/sane.tex 2002-10-10 17:25:45.000000000 +0200
@@ -12,9 +12,9 @@
\setlength{\marginparsep}{0pt}
\addtolength{\topmargin}{-0.75in}
-\title{\huge SANE Standard Version 1.02}
+\title{\huge SANE Standard Version 1.03}
\author{}
-\date{March 8, 2002}
+\date{2002-10-10}
\makeindex
@@ -259,7 +259,8 @@
sample value (for an image bit depth of 8), or a partial sample value
(for an image bit depth of 16 or bigger). In the latter case, the
bytes of each sample value are transmitted in the machine's native
-byte order.
+byte order. For depth 1, the leftmost pixel is stored in the most
+significant bit, and the rightmost pixel in the least significant bit.
\begin{quote}
\begin{center}
{\bf Backend Implementation Note}
@@ -347,12 +348,15 @@
\end{description}
\end{quote}
-In frames of type SANE\_FRAME\_GRAY, when the bit depth is 1 there are
+In frames of type \code{SANE\_FRAME\_GRAY}, when the bit depth is 1 there are
only two sample values possible, 1 represents minimum intensity
(black) and 0 represents maximum intensity (white). For all other bit
depth and frame type combinations, a sample value of 0 represents
minimum intensity and larger values represent increasing intensity.
+The combination of bit depth 1 and \code{SANE\_FRAME\_RGB} (or
+\code{SANE\_FRAME\_RED}, \code{SANE\_FRAME\_GREEN}, \code{SANE\_FRAME\_BLUE})
+is rarely used and may not be supported by every frontend.
\chapter{The SANE Application Programmer Interface (API)}\label{chap:api}
@@ -1066,15 +1070,15 @@
\subsection{\code{sane\_init}}
-This function must be called before any other SANE function can be
-called. The behavior of a SANE backend is undefined if this function
-is not called first. The version code of the backend is returned in
-the value pointed to by \code{version\_code}. If that pointer is
-\code{NULL}, no version code is returned.
- Argument \code{authorize} is either a pointer to a function that is
- invoked when the backend requires authentication for a specific
- resource or \code{NULL} if the frontend does not support
- authentication.
+This function must be called before any other SANE function can be called.
+The behavior of a SANE backend is undefined if this function is not called
+first or if the status code returned by \code{sane\_init} is different from
+\code{\defn{SANE\_STATUS\_GOOD}}. The version code of the backend is returned
+in the value pointed to by \code{version\_code}. If that pointer is
+\code{NULL}, no version code is returned. Argument \code{authorize} is either
+a pointer to a function that is invoked when the backend requires
+authentication for a specific resource or \code{NULL} if the frontend does not
+support authentication.
\begin{quote}\index{sane\_init}
\begin{verbatim}
SANE_Status sane_init (SANE_Int * version_code,
@@ -1488,6 +1492,11 @@
with the device.
\item[\code{SANE\_STATUS\_NO\_MEM}:] An insufficent amount of memory
is available.
+\item[\code{SANE\_STATUS\_INVAL}:] The scan cannot be started with the current
+ set of options. The frontend should reload the option descriptors, as if
+ \code{\defn{SANE\_INFO\_RELOAD\_OPTIONS}} had been returned from a call to
+ \code{sane\_control\_option()}, since the device's capabilities may have
+ changed.
\end{description}
\end{quote}
@@ -1569,10 +1578,11 @@
\subsection{\code{sane\_set\_io\_mode}}
-This function is used to set the I/O mode of handle \code{h}. The I/O
-mode can be either blocking or non-blocking. If argument \code{m} is
-\code{SANE\_TRUE}, the mode is set to non-blocking mode, otherwise
-it's set to blocking mode.
+This function is used to set the I/O mode of handle \code{h}. The I/O mode
+can be either blocking or non-blocking. If argument \code{m} is
+\code{SANE\_TRUE}, the mode is set to non-blocking mode, otherwise it's set to
+blocking mode. This function can be called only after a call to
+\code{sane\_start()} has been performed.
\begin{quote}\index{sane\_set\_io\_mode}
\begin{verbatim}
SANE_Status sane_set_io_mode (SANE_Handle h, SANE_Bool m);
@@ -1590,7 +1600,7 @@
\begin{description}
\item[\code{SANE\_STATUS\_INVAL}:] No image acquisition is pending.
\item[\code{SANE\_STATUS\_UNSUPPORTED}:] The backend does not support
- this operation.
+ the requested I/O mode.
\end{description}
\end{quote}