kopia lustrzana https://gitlab.com/sane-project/standard
Split document on chapter level
rodzic
59078c8b28
commit
daf9e7f469
|
@ -1,310 +1,3 @@
|
||||||
Preface
|
|
||||||
=======
|
|
||||||
|
|
||||||
The SANE standard is being developed by a group of free-software
|
|
||||||
developers. The process is open to the public and comments as well as
|
|
||||||
suggestions for improvements are welcome. Information on how to join the
|
|
||||||
SANE development process can be found in Chapter
|
|
||||||
:numref:`chap:contact`.
|
|
||||||
|
|
||||||
The SANE standard is intended to streamline software development by
|
|
||||||
providing a standard application programming interface to access raster
|
|
||||||
scanner hardware. This should reduce the number of different driver
|
|
||||||
implementations, thereby reducing the need for reimplementing similar
|
|
||||||
code.
|
|
||||||
|
|
||||||
About This Document
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
This document is intended for developers who are creating either an
|
|
||||||
application that requires access to raster scanner hardware and for
|
|
||||||
developers who are implementing a SANE driver. It does not cover
|
|
||||||
specific implementations of SANE components. Its sole purpose is to
|
|
||||||
describe and define the SANE application interface that will enable any
|
|
||||||
application on any platform to interoperate with any SANE backend for
|
|
||||||
that platform.
|
|
||||||
|
|
||||||
The remainder of this document is organized as follows.
|
|
||||||
Chapter :numref:`chap:intro` provides introductional material.
|
|
||||||
Chapter :numref:`chap:environ` presents the environment SANE is
|
|
||||||
designed for. Chapter :numref:`chap:api` details the SANE
|
|
||||||
Application Programmer Interface. Chapter :numref:`chap:net`
|
|
||||||
specifies the network protocol that can be used to implement the SANE
|
|
||||||
API in a network transparent fashion. Finally,
|
|
||||||
Chapter :numref:`chap:contact` gives information on how to join
|
|
||||||
the SANE development process.
|
|
||||||
|
|
||||||
Typographic Conventions
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Changes since the last revision of this document are highlighted like
|
|
||||||
this:
|
|
||||||
|
|
||||||
.. _chap:intro:
|
|
||||||
|
|
||||||
Introduction
|
|
||||||
============
|
|
||||||
|
|
||||||
SANE is an application programming interface (API) that provides
|
|
||||||
standardized access to any raster image scanner hardware. The
|
|
||||||
standardized interface allows to write just one driver for each scanner
|
|
||||||
device instead of one driver for each scanner and application. The
|
|
||||||
reduction in the number of required drivers provides significant savings
|
|
||||||
in development time. More importantly, SANE raises the level at which
|
|
||||||
applications can work. As such, it will enable applications that were
|
|
||||||
previously unheard of in the UNIX world. While SANE is primarily
|
|
||||||
targeted at a UNIX environment, the standard has been carefully designed
|
|
||||||
to make it possible to implement the API on virtually any hardware or
|
|
||||||
operating system.
|
|
||||||
|
|
||||||
SANE is an acronym for “Scanner Access Now Easy.” Also, the hope is that
|
|
||||||
SANE is sane in the sense that it will allow easy implementation of the
|
|
||||||
API while accommodating all features required by today’s scanner
|
|
||||||
hardware and applications. Specifically, SANE should be broad enough to
|
|
||||||
accommodate devices such as scanners, digital still and video cameras,
|
|
||||||
as well as virtual devices like image file filters.
|
|
||||||
|
|
||||||
Terminology
|
|
||||||
-----------
|
|
||||||
|
|
||||||
An application that uses the SANE interface is called a SANE *frontend*.
|
|
||||||
A driver that implements the SANE interface is called a SANE *backend*.
|
|
||||||
A *meta backend* provides some means to manage one or more other
|
|
||||||
backends.
|
|
||||||
|
|
||||||
.. _chap:environ:
|
|
||||||
|
|
||||||
The SANE Environment
|
|
||||||
====================
|
|
||||||
|
|
||||||
SANE is defined as a C-callable library interface. Accessing a raster
|
|
||||||
scanner device typically consists of two phases: first, various controls
|
|
||||||
of the scanner need to be setup or queried. In the second phase, one or
|
|
||||||
more images are acquired.
|
|
||||||
|
|
||||||
Since the device controls are widely different from device to device,
|
|
||||||
SANE provides a generic interface that makes it easy for a frontend to
|
|
||||||
give a user access to all controls without having to understand each and
|
|
||||||
every device control. The design principle used here is to abstract each
|
|
||||||
device control into a SANE *option*. An option is a self-describing
|
|
||||||
name/value pair. For example, the brightness control of a camera might
|
|
||||||
be represented by an option called ``brightness`` whose
|
|
||||||
value is an integer in the range from 0 to 255.
|
|
||||||
|
|
||||||
With self-describing options, a backend need not be concerned with
|
|
||||||
*presentation* issues: the backend simply provides a list of options
|
|
||||||
that describe all the controls available in the device. Similarly, there
|
|
||||||
are benefits to the frontend: it need not be concerned with the
|
|
||||||
*meaning* of each option. It simply provides means to present and alter
|
|
||||||
the options defined by the backend.
|
|
||||||
|
|
||||||
Attaching to a SANE backend
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
The process through which a SANE frontend connects to a backend is
|
|
||||||
platform dependent. Several possibilities exist:
|
|
||||||
|
|
||||||
- **Static linking:** A SANE backend may be linked directly into a
|
|
||||||
frontend. While the simplest method of attaching to a backend, it is
|
|
||||||
somewhat limited in functionality since the available devices is
|
|
||||||
limited to the ones for which support has been linked in when the
|
|
||||||
frontend was built. But even so static linking can be quite useful,
|
|
||||||
particularly when combined with a backend that can access scanners
|
|
||||||
via a network. Also, it is possible to support multiple backends
|
|
||||||
simultaneously by implementing a meta backend that manages several
|
|
||||||
backends that have been compiled in such a manner that they export
|
|
||||||
unique function names. For example, a backend called
|
|
||||||
``be`` would normally export a function called
|
|
||||||
:func:`sane_read()`. If each backend would provide such a
|
|
||||||
function, static linking would fail due to multiple conflicting
|
|
||||||
definitions of the same symbol. This can be resolved by having
|
|
||||||
backend ``be`` include a header file that has lines
|
|
||||||
of the form:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
#define sane_read be_sane_read
|
|
||||||
|
|
||||||
With definitions of this kind, backend ``be`` will
|
|
||||||
export function name ``be_sane_read()``. Thus, all
|
|
||||||
backends will export unique names. As long as a meta backend knows
|
|
||||||
about these names, it is possible to combine several backends at link
|
|
||||||
time and select and use them dynamically at runtime.
|
|
||||||
|
|
||||||
- **Dynamic linking:** A simpler yet more powerful way to support
|
|
||||||
multiple backends is to exploit dynamic linking on platforms that
|
|
||||||
support it. In this case, a frontend is linked against a shared
|
|
||||||
library that implements any SANE backend. Since each dynamically
|
|
||||||
linked backend exports the same set of global symbols (all starting
|
|
||||||
with the prefix ``sane_``), the dynamic library that
|
|
||||||
gets loaded at runtime does not necessarily have to be the same one
|
|
||||||
as one the frontend got linked against. In other words, it is
|
|
||||||
possible to switch the backend by installing the appropriate backend
|
|
||||||
dynamic library.
|
|
||||||
|
|
||||||
More importantly, dynamic linking makes it easy to implement a meta
|
|
||||||
backend that loads other backends *on demand*. This is a powerful
|
|
||||||
mechanism since it allows adding new backends merely by installing a
|
|
||||||
shared library and updating a configuration file.
|
|
||||||
|
|
||||||
- **Network connection:** Arguably the ultimate way to attach to a
|
|
||||||
scanner is by using the network to connect to a backend on a remote
|
|
||||||
machine. This makes it possible to scan images from any host in the
|
|
||||||
universe, as long as there is a network connection to that host and
|
|
||||||
provided the user is permitted to access that scanner.
|
|
||||||
|
|
||||||
.. figure:: figs/hierarchy.*
|
|
||||||
:name: fig:hierarchy
|
|
||||||
:scale: 100%
|
|
||||||
:align: center
|
|
||||||
|
|
||||||
Example SANE Hiearchy
|
|
||||||
|
|
||||||
The above discussion lists just a few ways for frontends to attach to a
|
|
||||||
backend. It is of course possible to combine these solutions to provide
|
|
||||||
an entire hierarchy of SANE backends. Such a hierarchy is depicted in
|
|
||||||
:numref:`fig:hierarchy`. The figure shows that machine A
|
|
||||||
uses a dynamic-linking based meta backend called ``dll``
|
|
||||||
to access the backends called ``pnm``,
|
|
||||||
``mustek``, and ``net``. The first two
|
|
||||||
are real backends, whereas the last one is a meta backend that provides
|
|
||||||
network transparent access to remote scanners. In the figure, machine B
|
|
||||||
provides non-local access to its scanners through the SANE frontend
|
|
||||||
called ``saned``. The ``saned`` in turn
|
|
||||||
has access to the ``hp`` and ``autolum``
|
|
||||||
backends through another instance of the ``dll``
|
|
||||||
backend. The ``autolum`` meta backend is used to
|
|
||||||
automatically adjust the luminance (brightness) of the image data
|
|
||||||
acquired by the camera backend called ``qcam``.
|
|
||||||
|
|
||||||
Note that a meta backend really is both a frontend and a backend at the
|
|
||||||
same time. It is a frontend from the viewpoint of the backends that it
|
|
||||||
manages and a backend from the viewpoint of the frontends that access
|
|
||||||
it. The name “meta backend” was chosen primarily because the SANE
|
|
||||||
standard describes the interface from the viewpoint of a (real)
|
|
||||||
frontend.
|
|
||||||
|
|
||||||
.. index:: image data format
|
|
||||||
.. _sec:imageformat:
|
|
||||||
|
|
||||||
Image Data Format
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
Arguably the most important aspect of an image acquisition system is how
|
|
||||||
images are represented. The SANE approach is to define a simple yet
|
|
||||||
powerful representation that is sufficient for vast majority of
|
|
||||||
applications and devices. While the representation is simple, the
|
|
||||||
interface has been defined carefully to allow extending it in the future
|
|
||||||
without breaking backwards compatibility. Thus, it will be possible to
|
|
||||||
accommodate future applications or devices that were not anticipated at
|
|
||||||
the time this standard was created.
|
|
||||||
|
|
||||||
A SANE image is a rectangular area. The rectangular area is subdivided
|
|
||||||
into a number of rows and columns. At the intersection of each row and
|
|
||||||
column is a quadratic pixel. A pixel consists of one or more sample
|
|
||||||
values. Each sample value represents one channel (e.g., the red
|
|
||||||
channel). Each sample value has a certain bit depth. The bit depth is
|
|
||||||
fixed for the entire image and can be as small as one bit. Valid bit
|
|
||||||
depths are 1, 8, or 16 bits per sample. If a device’s natural bit depth
|
|
||||||
is something else, it is up to the driver to scale the sample values
|
|
||||||
appropriately (e.g., a 4 bit sample could be scaled by a factor of four
|
|
||||||
to represent a sample value of depth 8).
|
|
||||||
|
|
||||||
Image Transmission
|
|
||||||
~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The SANE API transmits an image as a sequence of frames. Each frame
|
|
||||||
covers the same rectangular area as the entire image, but may contain
|
|
||||||
only a subset of the channels in the final image. For example, a
|
|
||||||
red/green/blue image could either be transmitted as a single frame that
|
|
||||||
contains the sample values for all three channels or it could be
|
|
||||||
transmitted as a sequence of three frames: the first frame containing
|
|
||||||
the red channel, the second the green channel, and the third the blue
|
|
||||||
channel.
|
|
||||||
|
|
||||||
Conceptually, each frame is transmitted a byte at a time. Each byte may
|
|
||||||
contain 8 sample values (for an image bit depth of 1), one full 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.
|
|
||||||
|
|
||||||
**Backend Implementation Note**
|
|
||||||
|
|
||||||
A network-based meta backend will have to ensure that the byte order
|
|
||||||
in image data is adjusted appropriately if necessary. For example,
|
|
||||||
when the meta backend attaches to the server proxy, the proxy may
|
|
||||||
inform the backend of the server’s byte order. The backend can then
|
|
||||||
apply the adjustment if necessary. In essence, this implements a
|
|
||||||
“receiver-makes-right” approach.
|
|
||||||
|
|
||||||
.. figure:: figs/xfer.*
|
|
||||||
:name: fig:xfer
|
|
||||||
:scale: 50%
|
|
||||||
:align: center
|
|
||||||
|
|
||||||
Transfer order of image data bytes
|
|
||||||
|
|
||||||
The order in which the sample values in a frame are transmitted is
|
|
||||||
illustrated in :numref:`fig:xfer`. As can be seen, the
|
|
||||||
values are transmitted row by row and each row is transmitted from
|
|
||||||
left-most to right-most column. The left-to-right, top-to-bottom
|
|
||||||
transmission order applies when the image is viewed in its normal
|
|
||||||
orientation (as it would be displayed on a screen, for example).
|
|
||||||
|
|
||||||
If a frame contains multiple channels, then the channels are transmitted
|
|
||||||
in an interleaved fashion. :numref:`fig:pixels`
|
|
||||||
illustrates this for the case where a frame contains a complete
|
|
||||||
red/green/blue image with a bit-depth of 8. For a bit depth of 1, each
|
|
||||||
byte contains 8 sample values of a *single* channel. In other words, a
|
|
||||||
bit depth 1 frame is transmitted in a byte interleaved fashion.
|
|
||||||
|
|
||||||
.. figure:: figs/image-data.*
|
|
||||||
:name: fig:pixels
|
|
||||||
:scale: 80%
|
|
||||||
:align: center
|
|
||||||
|
|
||||||
Bit and byte order or image data
|
|
||||||
|
|
||||||
When transmitting an image frame by frame, the frontend needs to know
|
|
||||||
what part of the image a frame represents (and how many frames it should
|
|
||||||
expect). For that purpose, the SANE API tags every frame with a type.
|
|
||||||
This version of the SANE standard supports the following frame types:
|
|
||||||
|
|
||||||
:macro:`SANE_FRAME_GRAY`:
|
|
||||||
The frame contains a single channel of data that represents
|
|
||||||
sample values from a spectral band that covers the human visual
|
|
||||||
range. The image consists of this frame only.
|
|
||||||
|
|
||||||
:macro:`SANE_FRAME_RGB`:
|
|
||||||
The frame contains three channels of data that represent sample
|
|
||||||
values from the red, green, and blue spectral bands. The sample
|
|
||||||
values are interleaved in the order red, green, and blue. The
|
|
||||||
image consists of this frame only.
|
|
||||||
|
|
||||||
:macro:`SANE_FRAME_RED`:
|
|
||||||
The frame contains one channel of data that represents sample
|
|
||||||
values from the red spectral band. The complete image consists
|
|
||||||
of three frames: :macro:`SANE_FRAME_RED`,
|
|
||||||
:macro:`SANE_FRAME_GREEN`, and
|
|
||||||
:macro:`SANE_FRAME_BLUE`. The order in which the
|
|
||||||
frames are transmitted chosen by the backend.
|
|
||||||
|
|
||||||
:macro:`SANE_FRAME_GREEN`:
|
|
||||||
The frame contains one channel of data that represents sample
|
|
||||||
values from the green spectral band. The complete image consists
|
|
||||||
of three frames: :macro:`SANE_FRAME_RED`,
|
|
||||||
:macro:`SANE_FRAME_GREEN`, and
|
|
||||||
:macro:`SANE_FRAME_BLUE`. The order in which the
|
|
||||||
frames are transmitted chosen by the backend.
|
|
||||||
|
|
||||||
:macro:`SANE_FRAME_BLUE`:
|
|
||||||
The frame contains one channel of data that represents sample
|
|
||||||
values from the blue spectral band. The complete image consists
|
|
||||||
of three frames: :macro:`SANE_FRAME_RED`,
|
|
||||||
:macro:`SANE_FRAME_GREEN`, and
|
|
||||||
:macro:`SANE_FRAME_BLUE`. The order in which the
|
|
||||||
frames are transmitted chosen by the backend.
|
|
||||||
|
|
||||||
.. _chap:api:
|
.. _chap:api:
|
||||||
|
|
||||||
The SANE Application Programmer Interface (API)
|
The SANE Application Programmer Interface (API)
|
||||||
|
@ -1893,30 +1586,6 @@ regarding these options:
|
||||||
- A frontend must work properly with any or all of these options
|
- A frontend must work properly with any or all of these options
|
||||||
missing.
|
missing.
|
||||||
|
|
||||||
.. include:: net.rst
|
|
||||||
|
|
||||||
.. index:: mailing list
|
|
||||||
.. _chap:contact:
|
|
||||||
|
|
||||||
Contact Information
|
|
||||||
===================
|
|
||||||
|
|
||||||
The SANE standard is discussed and evolved via a mailing list. Anybody
|
|
||||||
with email access to the Internet can automatically join and leave the
|
|
||||||
discussion group by sending mail to the following address.
|
|
||||||
|
|
||||||
mailto:majordomo@mostang.com
|
|
||||||
|
|
||||||
To subscribe, send a mail with the body “``subscribe sane-devel``” to
|
|
||||||
the above address.
|
|
||||||
|
|
||||||
A complete list of commands supported can be obtained by sending a mail
|
|
||||||
with a subject of “``help``” to the above address. The
|
|
||||||
mailing list is archived and available through the SANE home page at
|
|
||||||
URL:
|
|
||||||
|
|
||||||
http://www.mostang.com/sane/
|
|
||||||
|
|
||||||
.. [1]
|
.. [1]
|
||||||
This is different from ANSI C where any non-zero integer value
|
This is different from ANSI C where any non-zero integer value
|
||||||
represents logical TRUE.
|
represents logical TRUE.
|
|
@ -0,0 +1,22 @@
|
||||||
|
.. _chap:contact:
|
||||||
|
|
||||||
|
Contact Information
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. index:: mailing list
|
||||||
|
|
||||||
|
The SANE standard is discussed and evolved via a mailing list. Anybody
|
||||||
|
with email access to the Internet can automatically join and leave the
|
||||||
|
discussion group by sending mail to the following address.
|
||||||
|
|
||||||
|
mailto:majordomo@mostang.com
|
||||||
|
|
||||||
|
To subscribe, send a mail with the body “``subscribe sane-devel``” to
|
||||||
|
the above address.
|
||||||
|
|
||||||
|
A complete list of commands supported can be obtained by sending a mail
|
||||||
|
with a subject of “``help``” to the above address. The
|
||||||
|
mailing list is archived and available through the SANE home page at
|
||||||
|
URL:
|
||||||
|
|
||||||
|
http://www.mostang.com/sane/
|
|
@ -0,0 +1,232 @@
|
||||||
|
.. _chap:environ:
|
||||||
|
|
||||||
|
The SANE Environment
|
||||||
|
====================
|
||||||
|
|
||||||
|
SANE is defined as a C-callable library interface. Accessing a raster
|
||||||
|
scanner device typically consists of two phases: first, various controls
|
||||||
|
of the scanner need to be setup or queried. In the second phase, one or
|
||||||
|
more images are acquired.
|
||||||
|
|
||||||
|
Since the device controls are widely different from device to device,
|
||||||
|
SANE provides a generic interface that makes it easy for a frontend to
|
||||||
|
give a user access to all controls without having to understand each and
|
||||||
|
every device control. The design principle used here is to abstract each
|
||||||
|
device control into a SANE *option*. An option is a self-describing
|
||||||
|
name/value pair. For example, the brightness control of a camera might
|
||||||
|
be represented by an option called ``brightness`` whose
|
||||||
|
value is an integer in the range from 0 to 255.
|
||||||
|
|
||||||
|
With self-describing options, a backend need not be concerned with
|
||||||
|
*presentation* issues: the backend simply provides a list of options
|
||||||
|
that describe all the controls available in the device. Similarly, there
|
||||||
|
are benefits to the frontend: it need not be concerned with the
|
||||||
|
*meaning* of each option. It simply provides means to present and alter
|
||||||
|
the options defined by the backend.
|
||||||
|
|
||||||
|
Attaching to a SANE backend
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The process through which a SANE frontend connects to a backend is
|
||||||
|
platform dependent. Several possibilities exist:
|
||||||
|
|
||||||
|
- **Static linking:** A SANE backend may be linked directly into a
|
||||||
|
frontend. While the simplest method of attaching to a backend, it is
|
||||||
|
somewhat limited in functionality since the available devices is
|
||||||
|
limited to the ones for which support has been linked in when the
|
||||||
|
frontend was built. But even so static linking can be quite useful,
|
||||||
|
particularly when combined with a backend that can access scanners
|
||||||
|
via a network. Also, it is possible to support multiple backends
|
||||||
|
simultaneously by implementing a meta backend that manages several
|
||||||
|
backends that have been compiled in such a manner that they export
|
||||||
|
unique function names. For example, a backend called
|
||||||
|
``be`` would normally export a function called
|
||||||
|
:func:`sane_read()`. If each backend would provide such a
|
||||||
|
function, static linking would fail due to multiple conflicting
|
||||||
|
definitions of the same symbol. This can be resolved by having
|
||||||
|
backend ``be`` include a header file that has lines
|
||||||
|
of the form:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
#define sane_read be_sane_read
|
||||||
|
|
||||||
|
With definitions of this kind, backend ``be`` will
|
||||||
|
export function name ``be_sane_read()``. Thus, all
|
||||||
|
backends will export unique names. As long as a meta backend knows
|
||||||
|
about these names, it is possible to combine several backends at link
|
||||||
|
time and select and use them dynamically at runtime.
|
||||||
|
|
||||||
|
- **Dynamic linking:** A simpler yet more powerful way to support
|
||||||
|
multiple backends is to exploit dynamic linking on platforms that
|
||||||
|
support it. In this case, a frontend is linked against a shared
|
||||||
|
library that implements any SANE backend. Since each dynamically
|
||||||
|
linked backend exports the same set of global symbols (all starting
|
||||||
|
with the prefix ``sane_``), the dynamic library that
|
||||||
|
gets loaded at runtime does not necessarily have to be the same one
|
||||||
|
as one the frontend got linked against. In other words, it is
|
||||||
|
possible to switch the backend by installing the appropriate backend
|
||||||
|
dynamic library.
|
||||||
|
|
||||||
|
More importantly, dynamic linking makes it easy to implement a meta
|
||||||
|
backend that loads other backends *on demand*. This is a powerful
|
||||||
|
mechanism since it allows adding new backends merely by installing a
|
||||||
|
shared library and updating a configuration file.
|
||||||
|
|
||||||
|
- **Network connection:** Arguably the ultimate way to attach to a
|
||||||
|
scanner is by using the network to connect to a backend on a remote
|
||||||
|
machine. This makes it possible to scan images from any host in the
|
||||||
|
universe, as long as there is a network connection to that host and
|
||||||
|
provided the user is permitted to access that scanner.
|
||||||
|
|
||||||
|
.. figure:: figs/hierarchy.*
|
||||||
|
:name: fig:hierarchy
|
||||||
|
:scale: 100%
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
Example SANE Hiearchy
|
||||||
|
|
||||||
|
The above discussion lists just a few ways for frontends to attach to a
|
||||||
|
backend. It is of course possible to combine these solutions to provide
|
||||||
|
an entire hierarchy of SANE backends. Such a hierarchy is depicted in
|
||||||
|
:numref:`fig:hierarchy`. The figure shows that machine A
|
||||||
|
uses a dynamic-linking based meta backend called ``dll``
|
||||||
|
to access the backends called ``pnm``,
|
||||||
|
``mustek``, and ``net``. The first two
|
||||||
|
are real backends, whereas the last one is a meta backend that provides
|
||||||
|
network transparent access to remote scanners. In the figure, machine B
|
||||||
|
provides non-local access to its scanners through the SANE frontend
|
||||||
|
called ``saned``. The ``saned`` in turn
|
||||||
|
has access to the ``hp`` and ``autolum``
|
||||||
|
backends through another instance of the ``dll``
|
||||||
|
backend. The ``autolum`` meta backend is used to
|
||||||
|
automatically adjust the luminance (brightness) of the image data
|
||||||
|
acquired by the camera backend called ``qcam``.
|
||||||
|
|
||||||
|
Note that a meta backend really is both a frontend and a backend at the
|
||||||
|
same time. It is a frontend from the viewpoint of the backends that it
|
||||||
|
manages and a backend from the viewpoint of the frontends that access
|
||||||
|
it. The name “meta backend” was chosen primarily because the SANE
|
||||||
|
standard describes the interface from the viewpoint of a (real)
|
||||||
|
frontend.
|
||||||
|
|
||||||
|
.. index:: image data format
|
||||||
|
.. _sec:imageformat:
|
||||||
|
|
||||||
|
Image Data Format
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Arguably the most important aspect of an image acquisition system is how
|
||||||
|
images are represented. The SANE approach is to define a simple yet
|
||||||
|
powerful representation that is sufficient for vast majority of
|
||||||
|
applications and devices. While the representation is simple, the
|
||||||
|
interface has been defined carefully to allow extending it in the future
|
||||||
|
without breaking backwards compatibility. Thus, it will be possible to
|
||||||
|
accommodate future applications or devices that were not anticipated at
|
||||||
|
the time this standard was created.
|
||||||
|
|
||||||
|
A SANE image is a rectangular area. The rectangular area is subdivided
|
||||||
|
into a number of rows and columns. At the intersection of each row and
|
||||||
|
column is a quadratic pixel. A pixel consists of one or more sample
|
||||||
|
values. Each sample value represents one channel (e.g., the red
|
||||||
|
channel). Each sample value has a certain bit depth. The bit depth is
|
||||||
|
fixed for the entire image and can be as small as one bit. Valid bit
|
||||||
|
depths are 1, 8, or 16 bits per sample. If a device’s natural bit depth
|
||||||
|
is something else, it is up to the driver to scale the sample values
|
||||||
|
appropriately (e.g., a 4 bit sample could be scaled by a factor of four
|
||||||
|
to represent a sample value of depth 8).
|
||||||
|
|
||||||
|
Image Transmission
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The SANE API transmits an image as a sequence of frames. Each frame
|
||||||
|
covers the same rectangular area as the entire image, but may contain
|
||||||
|
only a subset of the channels in the final image. For example, a
|
||||||
|
red/green/blue image could either be transmitted as a single frame that
|
||||||
|
contains the sample values for all three channels or it could be
|
||||||
|
transmitted as a sequence of three frames: the first frame containing
|
||||||
|
the red channel, the second the green channel, and the third the blue
|
||||||
|
channel.
|
||||||
|
|
||||||
|
Conceptually, each frame is transmitted a byte at a time. Each byte may
|
||||||
|
contain 8 sample values (for an image bit depth of 1), one full 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.
|
||||||
|
|
||||||
|
**Backend Implementation Note**
|
||||||
|
|
||||||
|
A network-based meta backend will have to ensure that the byte order
|
||||||
|
in image data is adjusted appropriately if necessary. For example,
|
||||||
|
when the meta backend attaches to the server proxy, the proxy may
|
||||||
|
inform the backend of the server’s byte order. The backend can then
|
||||||
|
apply the adjustment if necessary. In essence, this implements a
|
||||||
|
“receiver-makes-right” approach.
|
||||||
|
|
||||||
|
.. figure:: figs/xfer.*
|
||||||
|
:name: fig:xfer
|
||||||
|
:scale: 50%
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
Transfer order of image data bytes
|
||||||
|
|
||||||
|
The order in which the sample values in a frame are transmitted is
|
||||||
|
illustrated in :numref:`fig:xfer`. As can be seen, the
|
||||||
|
values are transmitted row by row and each row is transmitted from
|
||||||
|
left-most to right-most column. The left-to-right, top-to-bottom
|
||||||
|
transmission order applies when the image is viewed in its normal
|
||||||
|
orientation (as it would be displayed on a screen, for example).
|
||||||
|
|
||||||
|
If a frame contains multiple channels, then the channels are transmitted
|
||||||
|
in an interleaved fashion. :numref:`fig:pixels`
|
||||||
|
illustrates this for the case where a frame contains a complete
|
||||||
|
red/green/blue image with a bit-depth of 8. For a bit depth of 1, each
|
||||||
|
byte contains 8 sample values of a *single* channel. In other words, a
|
||||||
|
bit depth 1 frame is transmitted in a byte interleaved fashion.
|
||||||
|
|
||||||
|
.. figure:: figs/image-data.*
|
||||||
|
:name: fig:pixels
|
||||||
|
:scale: 80%
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
Bit and byte order or image data
|
||||||
|
|
||||||
|
When transmitting an image frame by frame, the frontend needs to know
|
||||||
|
what part of the image a frame represents (and how many frames it should
|
||||||
|
expect). For that purpose, the SANE API tags every frame with a type.
|
||||||
|
This version of the SANE standard supports the following frame types:
|
||||||
|
|
||||||
|
:macro:`SANE_FRAME_GRAY`:
|
||||||
|
The frame contains a single channel of data that represents
|
||||||
|
sample values from a spectral band that covers the human visual
|
||||||
|
range. The image consists of this frame only.
|
||||||
|
|
||||||
|
:macro:`SANE_FRAME_RGB`:
|
||||||
|
The frame contains three channels of data that represent sample
|
||||||
|
values from the red, green, and blue spectral bands. The sample
|
||||||
|
values are interleaved in the order red, green, and blue. The
|
||||||
|
image consists of this frame only.
|
||||||
|
|
||||||
|
:macro:`SANE_FRAME_RED`:
|
||||||
|
The frame contains one channel of data that represents sample
|
||||||
|
values from the red spectral band. The complete image consists
|
||||||
|
of three frames: :macro:`SANE_FRAME_RED`,
|
||||||
|
:macro:`SANE_FRAME_GREEN`, and
|
||||||
|
:macro:`SANE_FRAME_BLUE`. The order in which the
|
||||||
|
frames are transmitted chosen by the backend.
|
||||||
|
|
||||||
|
:macro:`SANE_FRAME_GREEN`:
|
||||||
|
The frame contains one channel of data that represents sample
|
||||||
|
values from the green spectral band. The complete image consists
|
||||||
|
of three frames: :macro:`SANE_FRAME_RED`,
|
||||||
|
:macro:`SANE_FRAME_GREEN`, and
|
||||||
|
:macro:`SANE_FRAME_BLUE`. The order in which the
|
||||||
|
frames are transmitted chosen by the backend.
|
||||||
|
|
||||||
|
:macro:`SANE_FRAME_BLUE`:
|
||||||
|
The frame contains one channel of data that represents sample
|
||||||
|
values from the blue spectral band. The complete image consists
|
||||||
|
of three frames: :macro:`SANE_FRAME_RED`,
|
||||||
|
:macro:`SANE_FRAME_GREEN`, and
|
||||||
|
:macro:`SANE_FRAME_BLUE`. The order in which the
|
||||||
|
frames are transmitted chosen by the backend.
|
|
@ -6,7 +6,12 @@ SANE Standard
|
||||||
:maxdepth: 3
|
:maxdepth: 3
|
||||||
:caption: Contents:
|
:caption: Contents:
|
||||||
|
|
||||||
sane
|
preface
|
||||||
|
introduction
|
||||||
|
environment
|
||||||
|
api
|
||||||
|
net
|
||||||
|
contact
|
||||||
|
|
||||||
.. only:: html
|
.. only:: html
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,31 @@
|
||||||
|
.. _chap:intro:
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
SANE is an application programming interface (API) that provides
|
||||||
|
standardized access to any raster image scanner hardware. The
|
||||||
|
standardized interface allows to write just one driver for each scanner
|
||||||
|
device instead of one driver for each scanner and application. The
|
||||||
|
reduction in the number of required drivers provides significant savings
|
||||||
|
in development time. More importantly, SANE raises the level at which
|
||||||
|
applications can work. As such, it will enable applications that were
|
||||||
|
previously unheard of in the UNIX world. While SANE is primarily
|
||||||
|
targeted at a UNIX environment, the standard has been carefully designed
|
||||||
|
to make it possible to implement the API on virtually any hardware or
|
||||||
|
operating system.
|
||||||
|
|
||||||
|
SANE is an acronym for “Scanner Access Now Easy.” Also, the hope is that
|
||||||
|
SANE is sane in the sense that it will allow easy implementation of the
|
||||||
|
API while accommodating all features required by today’s scanner
|
||||||
|
hardware and applications. Specifically, SANE should be broad enough to
|
||||||
|
accommodate devices such as scanners, digital still and video cameras,
|
||||||
|
as well as virtual devices like image file filters.
|
||||||
|
|
||||||
|
Terminology
|
||||||
|
-----------
|
||||||
|
|
||||||
|
An application that uses the SANE interface is called a SANE *frontend*.
|
||||||
|
A driver that implements the SANE interface is called a SANE *backend*.
|
||||||
|
A *meta backend* provides some means to manage one or more other
|
||||||
|
backends.
|
8
net.rst
8
net.rst
|
@ -198,7 +198,7 @@ authentication calls.
|
||||||
In the reply, :data:`status` indicates the completion
|
In the reply, :data:`status` indicates the completion
|
||||||
status. If the value is anything other than
|
status. If the value is anything other than
|
||||||
:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has
|
:macro:`SANE_STATUS_SUCCESS`, the remainder of the reply has
|
||||||
undefined values. [3]_ The :data:`version_code` argument
|
undefined values. [2]_ The :data:`version_code` argument
|
||||||
returns the SANE version-code that the network daemon supports. See the
|
returns the SANE version-code that the network daemon supports. See the
|
||||||
comments in the previous paragraph on the meaning of the build-revision
|
comments in the previous paragraph on the meaning of the build-revision
|
||||||
in this version code.
|
in this version code.
|
||||||
|
@ -527,7 +527,7 @@ returned in the :data:`resource` argument of the RPC reply
|
||||||
that required this authorization call. The :data:`username`
|
that required this authorization call. The :data:`username`
|
||||||
and :data:`password` are the name of the user that is
|
and :data:`password` are the name of the user that is
|
||||||
accessing the resource and the password for the specified resource/user
|
accessing the resource and the password for the specified resource/user
|
||||||
pair. [2]_
|
pair. [1]_
|
||||||
|
|
||||||
In the reply, :data:`dummy` is completely unused. Note that
|
In the reply, :data:`dummy` is completely unused. Note that
|
||||||
there is no direct failure indication. This is unnecessary since a net
|
there is no direct failure indication. This is unnecessary since a net
|
||||||
|
@ -544,10 +544,10 @@ no request or reply arguments in this call. As a result of this call,
|
||||||
the connection between the client and the server that was established by
|
the connection between the client and the server that was established by
|
||||||
the :data:`SANE_NET_INIT` call will be closed.
|
the :data:`SANE_NET_INIT` call will be closed.
|
||||||
|
|
||||||
.. [2]
|
.. [1]
|
||||||
The sane network daemon should be careful not to leak information in
|
The sane network daemon should be careful not to leak information in
|
||||||
the undefined portion of the reply.
|
the undefined portion of the reply.
|
||||||
|
|
||||||
.. [3]
|
.. [2]
|
||||||
The username and password should be encrypted before network
|
The username and password should be encrypted before network
|
||||||
transmission but currently they are always in plain text.
|
transmission but currently they are always in plain text.
|
||||||
|
|
|
@ -0,0 +1,41 @@
|
||||||
|
Preface
|
||||||
|
=======
|
||||||
|
|
||||||
|
The SANE standard is being developed by a group of free-software
|
||||||
|
developers. The process is open to the public and comments as well as
|
||||||
|
suggestions for improvements are welcome. Information on how to join the
|
||||||
|
SANE development process can be found in Chapter
|
||||||
|
:numref:`chap:contact`.
|
||||||
|
|
||||||
|
The SANE standard is intended to streamline software development by
|
||||||
|
providing a standard application programming interface to access raster
|
||||||
|
scanner hardware. This should reduce the number of different driver
|
||||||
|
implementations, thereby reducing the need for reimplementing similar
|
||||||
|
code.
|
||||||
|
|
||||||
|
About This Document
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
This document is intended for developers who are creating either an
|
||||||
|
application that requires access to raster scanner hardware and for
|
||||||
|
developers who are implementing a SANE driver. It does not cover
|
||||||
|
specific implementations of SANE components. Its sole purpose is to
|
||||||
|
describe and define the SANE application interface that will enable any
|
||||||
|
application on any platform to interoperate with any SANE backend for
|
||||||
|
that platform.
|
||||||
|
|
||||||
|
The remainder of this document is organized as follows.
|
||||||
|
Chapter :numref:`chap:intro` provides introductional material.
|
||||||
|
Chapter :numref:`chap:environ` presents the environment SANE is
|
||||||
|
designed for. Chapter :numref:`chap:api` details the SANE
|
||||||
|
Application Programmer Interface. Chapter :numref:`chap:net`
|
||||||
|
specifies the network protocol that can be used to implement the SANE
|
||||||
|
API in a network transparent fashion. Finally,
|
||||||
|
Chapter :numref:`chap:contact` gives information on how to join
|
||||||
|
the SANE development process.
|
||||||
|
|
||||||
|
Typographic Conventions
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Changes since the last revision of this document are highlighted like
|
||||||
|
this:
|
Ładowanie…
Reference in New Issue