/*!

\page scan_apis Scan APIs (aka the problems)

All scan APIs provides similar features:

- Read/write access to scanner/sources options
- Access to scanner/sources options constraint (valid resolution range, valid
  modes, etc)
- Obtaining images

Some APIs provide extra features but it is simply not humanely possible
to support them all in this library.

# Sane

- Operating systems:
  - Linux
  - FreeBSD, OpenBSD, NetBSD, etc
  - MacOSX (not supported)
  - Microsoft Windows (network scanners only ; not supported)

@startuml
object Scanner

Scanner *-- "Option 'resolution'"
"Option 'resolution'" : value type
"Option 'resolution'" : constraint
"Option 'resolution'" : value

Scanner *-- "Option 'mode'"
"Option 'mode'" : value type
"Option 'mode'" : constraint
"Option 'mode'" : value

Scanner *-- "Option 'source'"
"Option 'source'" : value type
"Option 'source'" : constraint: ['Flatbed', 'Feeder', etc]
"Option 'source'" : value
@enduml


![Sane drivers can implement any options they want, how they want](sane.png)

[Sane API](http://sane-project.org/html/doc009.html) is a simple and flexible API.

Each scanner is always a single scan source.
For each scanner, there are a list of options that can be set.
Each option has its constraints. Option names are not hard-coded and may
differ from one driver to another. There are however some
[well-known options](http://sane.alioth.debian.org/sane2/0.08/doc014.html)
that are found on most drivers and scanners .. but not all. Sane specifications
says drivers *should* implements those option, not that they *must*.

Most features of Sane are supported by Libinsane.

Sane on Windows is not supported by Libinsane. Contributions are welcome.

Sane on MacOSX is not supported by Libinsane. Contributions are welcome.
Please note that I (Jerome Flesch) don't own a Mac so if you do add this
support, you will have to:

- Deploy a gitlab-runner to run the tests automatically.
- Maintain it.


Limitations of Libinsane support:

- Some Sane options that accepted complex values (arrays, etc) are not
  supported and are ignored by Libinsane.


# TWAIN

- Operating systems:
  - Microsoft Windows
  - MacOSX (half-dead ? ; not supported)
  - Linux (dead ? ; not supported)

\todo TODO

![Twain is the oldest of the 3 APIs](twain.png)

TWAIN on Linux is not supported by Libinsane. Contributions are welcome.

TWAIN on MacOSX is not supported by Libinsane. Contributions are welcome.
Please note that I (Jerome Flesch) don't own a Mac so if you do add this
support, you will have to:

- Deploy a gitlab-runner to run the tests automatically.
- Maintain it.


# WIA2

- Operating systems:
  - Microsoft Windows

@startuml
object "Scanner (WIAItem)" as scanner
object "Option 'image format'" as format
object "Option 'mode'" as mode1
object "Option 'mode'" as mode2
object "Option 'resolution'" as res1
object "Option 'resolution'" as res2

scanner *-- "Flatbed (WIAItem)"
scanner *-- "Feeder (WIAItem)"

scanner *-- format
format : value type
format : constraint
format : value

"Flatbed (WIAItem)" *-- res1
res1 : value type
res1 : constraint
res1 : value

"Flatbed (WIAItem)" *-- mode1
mode1 : value type
mode1 : constraint
mode1 : value

"Feeder (WIAItem)" *-- res2
res2 : value type
res2 : constraint
res2 : value

"Feeder (WIAItem)" *-- mode2
mode2 : value type
mode2 : constraint
mode2 : value
@enduml

![WIA2](wia.png)

[Windows Image Acquisition](https://msdn.microsoft.com/en-us/library/windows/desktop/ms630368(v=vs.85).aspx)
is a Microsoft API.

For each scanner, there are many scan sources. The scanner itself and each of
its scan sources are all WIAItems. They all have their own options.

Possible options are limited to what is defined in `wia.h`. However
value types and constraint types are not.

There are actually 2 implementations for the WIA API:

- The first one uses the low-level WIA API. It is able to pass it a stream
  object to get the image, and therefore is able to get the image as the
  scan goes. This is the implementation used by Libinsane.
- The second one uses the WIA automation layer. It can only store the
  scan directly in a file. Therefore displaying the scan as it goes is
  actually a hack reading the file as it is being written.
  This implementation is not used by Libinsane.

WIA2 provides also features that Libinsane doesn't support:

- Access to devices other than scanners (camera, etc)
- Access to file storages on devices
- Windows Dialogs (why in hell are there dialogs in a scan API in a first place !?)


# ImageKit

[API doc](https://developer.apple.com/library/content/documentation/Carbon/Conceptual/ImageCaptureServicesProgrammingGuide/02Overview/02Overview.html)

- Operating systems:
  - MacOSX (not supported)

Not supported by Libinsane. Contributions are welcome.
Please note that I (Jerome Flesch) don't own a Mac so if you do add this
support, you will have to:

- Deploy a gitlab-runner to run the tests automatically.
- Maintain it.

*/
