[sane-devel] Proposal: SANE standard additions/fixes

[Henning Meier-Geinitz]

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}