In general, IG_TWAIN_acquire() is used to scan a single image from the flatbed area of the scanner, while IG_TWAIN_scan_pages() and IG_TWAIN_scan_pages_to_file() are used to scan any number of pages from an automatic document feeder (ADF), which is an optional scanner accessory.

The key difference between these functions is that IG_TWAIN_acquire() scans a single image to a DIB in memory (unless the Disk File Transfer mode is used), while IG_TWAIN_scan_pages() can scan one or more pages and IG_TWAIN_scan_pages_to_file() saves your images to disk.

Using the User Interface (UI)

You should decide when using IG_TWAIN_acquire(), IG_TWAIN_scan_pages() or IG_TWAIN_scan_pages_to_file() whether or not to display the Data Source User-Interface dialog box (UI). The UI, which is supplied by the scanner manufacturer, allows the user to preview the image, select the portion of the image to be acquired, and to set those controls that specify image characteristics particular to the device in use. Setting the parameter bShowUI to TRUE allows the UI displaying, while setting it to FALSE disables the display. The UI specific to the Hewlett-Packard ScanJet 4c scanner is shown on the picture below:

If you set bShowUI to FALSE, you can still set the device capabilities by including a call to IG_TWAIN_cap_set(). This may actually be preferable to using the UI, because it can offer you more control in some cases.

The following example code demonstrates using IG_TWAIN_acquire() with the UI displayed, and also shows a call to IG_TWAIN_driver_info_get().

AT_ERRCOUNT AcquireImage(HWND hWnd, HIGEAR *image)
{
    AT_ERRCOUNT errorCount = 0;
    INT nTwainVerMajor = 0, nTwainVerMinor = 0;
    char message[1024];
    BOOL bShowUI = TRUE;

    // Get version information.
    errorCount = IG_TWAIN_driver_info_get(&nTwainVerMajor, &nTwainVerMinor);
    if (errorCount == IGE_SUCCESS)
    {
        wsprintf(message, "TWAIN Working Group\n\nVersion %d.%d", nTwainVerMajor, nTwainVerMinor);
        MessageBox(hWnd, message, "TWAIN Protocol", MB_ICONINFORMATION);
    }

    // Acquire the image.
    errorCount += IG_TWAIN_acquire(image, bShowUI);

    return errorCount;
}       

If you are scanning with IG_TWAIN_scan_pages() or IG_TWAIN_scan_pages_to_file() and have set bShowUI to TRUE, be aware that the UI box will only appear once (before the first page is scanned). But the settings you make with the UI box will be applied to all pages scanned during this session.

Using Disk File Transfer and IG_TWAIN_acquire()

IG_TWAIN_acquire() can be used with any of the TWAIN transfer modes. If you use Buffered Memory or Native, the file is scanned into memory and assigned a HIGEAR handle; if you use Disk File Transfer mode, the image is stored directly to disk. As described in the section Setting the Filename and Format Type for Disk File Transfer, when acquiring an image using the Disk File Transfer syntax, the image acquired is stored to the specified file with the specified file format type. To set the filename when using the Disk File Transfer mode, use the function IG_TWAIN_ctrl_set().

Formatting Scanned Image

Calling IG_TWAIN_acquire() results in the creation of a DIB to hold your acquired image, and it returns an ImageGear HIGEAR handle. Use IG_save_file() or IG_fltr_save_file() to save the image to a disk file using any of the writable format types supported by ImageGear. See Saving Images and Using Format Filters API for Image Saving for more information.

If you scan multiple pages using IG_TWAIN_scan_pages_to_file() , in combination with the Native or Buffered Memory transfer modes, the images are saved directly to a disk file with the format specified by the nFileFormat parameter. If the chosen format supports storage of multiple images, one file will be created; if the chosen format supports storage of one image per file, a separate file will be created for each image scanned from the ADF.

You can force ImageGear to save pages separately even for multi-page formats using the setting IG_TW_CTRL_SAVE_PAGES_SEPARATELY with IG_TWAIN_ctrl_set(). For instructions on saving a file to a different file formats, see Saving.

12-bit Gray Level Scanning

You can use ImageGear to scan 12-bit gray level images from Vidar and Lumisys X-ray digitizers using TWAIN interface.