Invoke an ISIS pipe and run a zone.
Declaration:
 Copy Code |
|
|---|---|
AT_ERRCOUNT ACCUAPI IG_ISIS_run_zone(
HISISDRV hDriver,
LPBYTE lpBuffer,
WORD wSize
);
|
|
Arguments:
| hDriver | The handle of the head (first) driver in the ISIS pipe. Usually this is either a scanner driver or a file-reading driver. |
| lpBuffer | A pointer to a character array buffer used by IG_ISIS_run_zone. This array should be 8192 bytes in size, as a larger buffer area is not needed. |
| wSize | The size of lpBuffer. Must be at least 1 and at most 32K-1. We recommend always using a size of 8192. In testing various scanners, files, and ISIS pipes, this value produced maximum throughput without wasting memory. |
Return Value:
Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.
Supported Raster Image Formats:
Depends on the scanner driver.
Remarks:
The IG_ISIS_run_zone function combines the functionality of several independent stack, page, and zone functions to make invoking a pipe a one-step process.
IG_ISIS_run_zone is the easiest way to invoke an ISIS pipe. It causes the head (first) driver to start generating data and sending chunks of data to the next driver in the pipe. Each chunk of data is the amount that will fit into lpBuffer. This, in turn, causes data for a single run (usually a page) to flow through the pipe and produce output. Each IG_ISIS_run_zone call processes exactly one zone (which may be at most a page, and at least a sub-area of a page).
 |
A zone may be an entire page side, a sub-area of the page, or one of multiple sub-areas that can be defined with certain scanner drivers (by using IG_ISIS_TAG_WINDOW). In typical scanning cases, a zone is a single page. Your application can rely on a zone returning a page, as this is the default behavior for all scanners. Special programming is required to access any other type of behavior. |
Call IG_ISIS_run_zone only after properly loading, linking, and setting parameters on an ISIS pipe.
Calling IG_ISIS_run_zone on a scanner driver causes the scanner to scan a page and output data into the ISIS pipe to which the scanner driver is linked.
After calling IG_ISIS_run_zone, check the return value. If the return value is not IGE_SUCCESS, then an error occurred (for example, a paper jam), and the page should be considered incomplete. If the return value is IGE_SUCCESS, then the page (zone) completed and no more data is available. Another IG_ISIS_run_zone must be called to process the another page (zone).
IG_ISIS_run_zone consists of, among other functions, the following three key functions:
Omitted from these functions is IG_ISIS_drv_run_zone, which is used to pass tags to the head driver just before starting data transfer. This function is needed when the head driver is not a data generator but tags still need to be set. Therefore, there are several cases in which you may want to use the separate functions to invoke an ISIS pipe:
- The data is coming from a source that is not a part of the ISIS pipe; that is, the head (first) driver in the ISIS pipe is not a data generator. In this case, the IG_ISIS_drv_run_zone function can be used to pass data into the head driver of the ISIS pipe, even though the data originated outside the pipe.
- The data needs to be broken into small chunks in cases when you do not want to receive the entire page at once. The IG_ISIS_drv_run_step function can be used to specify the size of each "step" of data transfer.
- The operation needs to yield periodically, for example to give other applications a chance to use CPU cycles and to determine whether or not a Cancel Scan command has been received. This can be important, especially when using very slow scanners, such as color scanners that may take minutes to scan a page. (It may be more convenient to use the yield functionality built into the driver and accessed by IG_ISIS_TAG_YIELDPROC, if you are fortunate enough to be working with one of the few scanner drivers that implement this tag. Otherwise, use a yield process in this scanning loop to implement yielding on all scanners.)
Example:
The following example uses IG_ISIS_run_zone to implement a basic scanning loop. Compare this to the example of using the separate IG_ISIS_drv_run... functions.
| Copy Code |
|
|---|---|
#define BUFSIZE 8192 AT_ERRCOUNT ScanBatch(HISISDRV hDriver) { LONG lValue; AT_ERRCOUNT nErrCount; char Buffer[BUFSIZE]; nErrCount = IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED, &lValue); if (nErrCount != IGE_SUCCESS) return nErrCount; while (lValue & IG_ISIS_DRV_STACKPAGE) { nErrCount = IG_ISIS_run_zone(hDriver, Buffer, BUFSIZE); if (nErrCount != IGE_SUCCESS) return nErrCount; nErrCount = IG_ISIS_drv_is_page_loaded(hDriver, IG_ISIS_FEEDER_FEED, &lValue); if (nErrCount != IGE_SUCCESS) return nErrCount; } return IGE_SUCCESS; } |
|
Background
An ISIS pipe exists to transfer image data from one entity (scanner, file, memory) to another. IG_ISIS_run_zone invokes several separate ISIS functions that can also be called independently by an application, if desired. Following is the actual code that is used to define IG_ISIS_run_zone:
| Copy Code |
|
|---|---|
if ((nErrCount = IG_ISIS_drv_start_stack(hDriver, &hStack)) == IGE_SUCCESS) { if ((nErrCount = IG_ISIS_drv_start_page(hStack, &hPage)) == IGE_SUCCESS) { if ((nErrCount = IG_ISIS_drv_start_zone(hPage, &hZone)) == IGE_SUCCESS) { if ((nErrCount = IG_ISIS_drv_forward(hZone, 0)) == IGE_SUCCESS) nErrCount = IG_ISIS_drv_start_data(hZone); if (nErrCount == IGE_SUCCESS) { do { nErrCount = IG_ISIS_drv_put_data(hZone, buffer, size, 0); } while (nErrCount == IGE_SUCCESS); } nErrCount = IG_ISIS_drv_end_zone(hZone); } nErrCount = IG_ISIS_drv_end_page(hPage); } nErrCount = IG_ISIS_drv_end_stack(hStack); return nErrCount; |
|