Updated May 2016; see History
xcall AUI, AUI_IMAGE, IMGOP_ACQUIRE, handle, status, filespec, attribs {,appname, pages, scanflags, pagesize}
IMGOP_ACQUIRE invokes a TWAIN "Acquire" to retrieve an image from the default TWAIN input device (aka "Data Source"). In the most common case, which involves scanners, this is equivalent to "scan-and-save-image". Manufacturers of image input devices such as scanners typically provide a TWAIN driver and user interface which allows the user to access the functionality of the device. This way, the application does not need to know any details about the device (such as what kinds of controls and options it has). It just knows that once the Acquire operation is started, it will return with a file (if successful) or an error code (if not).
IMGOP_ACQUIRE provides support for scanning multiple pages; see the following topic, Multi-Page Scanning, for more information.
Parameters
handle (Num) [in]
is not used here, is included only for conformity with the other opcodes.NumString
status (Num) [out]
returns 0 for success, else an error; see Status Codes.
filespec
is the specification of the file (AMOS or native format) to store the image in. The extension you specify will determine the image format and must be one of the file types listed in the comp following table (e.g. test.jpg or dsk9:test.bmp[100,20]).
attribs [in]
defines various attributes for the scan, mapped as shown below.
map1 attribs,b,4 ! compress, pixel type, resolution attributes
map1 attribsx,@attribs ! overlay to break out fields
map2 comp,b,1 ! compression options; see below)
map2 pixtype,b,1 ! pixel type: (see below)
map2 resx,b,1 ! x resolution (in multiples of 25 DPI)
map2 resy,b,1 ! y resolution (in multiples of 25 DIP)
comp [in]
is a compression-related factor determined by the image type:
Type |
Explanation |
|||
|---|---|---|---|---|
JPG |
Values range from 1 to 100, with 100 being maximum size and quality—i.e., minimum compression. 75 is the default and is generally considered the point below which you start to perceive the loss of quality. |
|||
TIF |
Symbol |
Value |
Meaning |
|
TIFCF_NONE |
0 |
No compression |
||
TIFCF_PACKBITS |
2 |
Pack Bits |
||
TIFCF_GROUP3 |
3 |
Group 3 |
||
TIFCF_GROUP4 |
4 |
Group 4 |
||
TIFCF_CCITT3 |
5 |
CCITT Group 3 |
||
BMP,PCX |
Ignored, not used |
|||
PNG |
Symbol |
Value |
Meaning |
|
PNGF_ALL |
0 |
Use best filter for each row (best compression) |
||
PNGF_NONE |
2 |
No filter (fastest) |
||
PNGF_SUB |
4 |
Difference filter with adjacent pixel |
||
PNGF_UP |
6 |
Difference filter with previous row |
||
PNGF_AVG |
8 |
Average filter |
||
PNGF_PAETH |
10 |
Paeth filter |
||
To save as an interlaced file, add PNGF_INTERLACE (+1) to any of the above. |
||||
pixtype [in]
The pixtype options are shown in the following table. The first three of these are standard for most scanners, the others are somewhat exotic and may not be supported.
Value |
Definition |
|---|---|
1 |
Black and white (bi-level) |
2 |
Grayscale (8 bit) |
3 |
RGG (24 bit) |
4 |
Palette |
5 |
CMY |
6 |
CMYK |
7 |
YUV |
8 |
YUVK |
9 |
CIEXYZ |
resx, resy [in]
these fields are scaled to multiples of 25 DPI (i.e. 12=300 DPI), in order to fit a reasonable range of possible resolutions in 8 bits.
For each of the pixtype, resx, and resy fields, 0 is interpreted as no change to the existing or default settings. So existing programs that pass only the old comp value will continue to work as before.
Note that for many scanners, setting the pixel type and resolution options may not have an effect unless the IMGSF_HIDEUI flag is set in the scanflags parameter. That is, displaying the scanner's user interface may override the application settings with the scanner's own previously saved settings.
appname (String) [in]
is an optional string containing the name of your application, which, depending on the particular TWAIN driver, may be displayed in the title bar of the device’s user interface window.
pages (Num) [in/out]
specifies the desired (or maximum) number of pages to scan. On return, it will contain the actual number scanned.
scanflags (Num) [in]
specifies flags (defined in ashell.def) affecting the scanning operation:
Symbol |
Value |
Meaning |
|---|---|---|
IMGSF_HIDEUI |
&h0001 |
Hide the scanner's user interface dialog, forcing the user to scan based on the settings previously established. |
IMGSF_ADFOUT |
&h0002 |
Quit when the Automatic Document Feeder (ADF) is out of paper (even if less than the number of pages requested) |
IMGSF_CONTINUE |
&h0004 |
Keep scanning until the requested # of pages is received, or the operator terminates the operation, or an unrecoverable error. This may be the same as the default operation, although in cases where there is no ADF, it may be necessary in order to force the operation to continue for multiple pages, since otherwise the scanner may return an ambiguous status, making it unclear to the application whether the operator decided not to continue, or the scanner just didn't now how to do multiple scans in one call. |
pagesize (Num) [in]
sets pagesize. Options are defined in the ASHINC:ashell.def file, the most common options being: TWSS_A4LETTER = 1, TWSS_USLETTER = 3, TWSS_USLEGAL = 4
Comments
Note that the acquisition (scanning) of the image data is independent of the saving of the image file, so it is up to you to specify an image format (via the file extension) that is compatible with the type of scan. (Or conversely, for the scanning operator to select options compatible with the file format.) For example, PCX only supports 1 and 8 bit data, so a 24-bit scan will result in an error while attempting to save the file.
See the program IMAGE.BP in EXLIB:[908,32] for an example of using the pages and scanflags parameters.
History
2016 April, A-Shell 6.3.1512: Add ability to set the page size via the pagesize parameter.
2016 April, A-Shell 6.3.1510: Old comp parameter redefined as attribs. Note that existing/older programs which simply use the comp parameter remain upward compatible with the attribs interpretation; the layout above guarantees that the comp value is interpreted the same either way, and the other fields would just be considered zero, meaning use the current defaults.
2016 April, A-Shell 6.3.1510: the IMGSF_HIDEUI option in the scanflags parameter now works in single-page scanning mode. Previously single page scans (pages=1) always displayed the scanner's user interface regardless of the scanflags.
2012 June, A-Shell 6.2.1306: Add support for multi-page scanning via the pages and scanflags parameters.
