ImageGear for C and C++ on Windows v19.1 - Updated
IG_ISIS_drv_split
API Reference Guide > ISIS Component API Reference > ISIS Component Functions Reference > Pipe Functions > IG_ISIS_drv_split

Split an ISIS pipe into the inputs of two drivers.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_drv_split(
        HISISDRV hDriver1,
        HISISDRV hDriver2
);

Arguments:

Name Type Description
hDriver1 HISISDRV A handle to the sibling pointer of the driver to which the ISIS pipe was linked by a previous IG_ISIS_drv_link call.
hDriver2 HISISDRV The handle of the driver that is to receive the same input as lpDriver1.

Return Value:

Error count.

Supported Raster Image Formats:

This function does not process image pixels.

Remarks:

IG_ISIS_drv_split takes the input to Driver 1 and routes it to the input of Driver 2 as well. In this way, an ISIS pipe can be made to perform two or more operations simultaneously. For example, a pipe could be made that saves two different types of image files simultaneously.

IG_ISIS_drv_split is used with IG_ISIS_drv_link to establish ISIS pipes. A pipe is a group of linked drivers that processes image data in a stream. For example, an application could link together a scanner driver, a set of compression drivers, and a file writing driver. When the pipe is invoked, image data moves in a stream from the scanner's output through each driver and is saved in a file in one operation. (In this example, the entire image never exists in memory at one time.).

IG_ISIS_drv_split splits the input of a driver to the input of another driver. It does not reference the output of any driver A common mistake is to pass in the handle of the driver whose output you want instead of a handle to a driver whose input is desired.

For example, to split the output of driver A into drivers B and C:

Incorrect Correct
IG_ISIS_drv_link(A, B); IG_ISIS_drv_split(A, C); IG_ISIS_drv_link(A, B); IG_ISIS_drv_split(B, C);

Where IG_ISIS_drv_link establishes a parent-child relationship between two drivers, IG_ISIS_drv_split establishes a sibling relationship between two drivers.

To understand IG_ISIS_drv_split, it is necessary to understand that each ISIS driver has a child pointer and a sibling pointer. The child pointer references data processed by the driver and points to the next driver in a pipe. The sibling pointer represents data that has not yet been processed by the driver and can be used to point to a driver that is split from the pipe.

To undo a split, use IG_ISIS_drv_split with hDriver2set to zero (0):

 
Copy Code
INT32 IG_ISIS_drv_split(hDriver1, 0);

Note that IG_ISIS_drv_split can split the input of a driver into only one other driver. To split a pipe into more than two drivers, you must call IG_ISIS_drv_split multiple times, as shown under "Example" below.

IG_ISIS_drv_split is used in as part of a set of four related functions: IG_ISIS_drv_load which loads individual drivers, IG_ISIS_drv_init which initializes both individual drivers and entire linked pipes of drivers, and IG_ISIS_drv_link and IG_ISIS_drv_split which establish relationships between the loaded drivers. Although the IG_ISIS_drv_load_init_pipe function loads, initializes, and links drivers in a single step, it cannot be used when you need to split an ISIS pipe.

A driver can be split to only one other driver. If, for example, a pipe must be split into three drivers, the input of Driver B can be split to Driver C. However, the input of Driver B cannot then be split to Driver D. Instead, the input of Driver C must be split to Driver D. (The end result is the same.)

The following example shows how an ISIS pipe can be established which takes the output of Driver A and sends it to both Driver B and Driver C, and then takes the output of Driver C and sends it to Driver D, Driver E, and Driver F. This example assumes that all five drivers have already been loaded and initialized.

 
Copy Code
IG_ISIS_drv_link(A, B);IG_ISIS_drv_split(B C);IG_ISIS_drv_link(C, D);IG_ISIS_drv_split(D, E);IG_ISIS_drv_split(E F);

The above code creates the pipe depicted in the following diagram:

Notice that the last line of the example correctly splits the input of driver E to F. If instead the input of driver D were split again (IG_ISIS_drv_split(D, F)), the split between driver D and E established in the fourth line of the example would be invalidated.

Also note that if you call IG_ISIS_drv_split(D, 0), the link between Driver D and Driver F will be broken.

The foundation of using ISIS is understanding ISIS pipes. An ISIS pipe is a linked set of drivers that is established prior to any scanning or image processing. Once all desired drivers are linked, messages from other ISIS functions are sent to the head driver (the first driver in the pipe). The head driver processes the messages and passes them on to the next driver in the pipe. All drivers receive all messages, and either respond to them or ignore them as appropriate. After all necessary configuration and settings are complete, IG_ISIS_run_zone is used to invoke the pipe, causing each driver to perform its intended operation in turn. This pipe structure requires that the desired functionality be implemented as drivers, and allows large image files to be processed without copying the image data from one full-page buffer to another. The result is much faster and more efficient than alternative image processing schemes.

See Also:

IG_ISIS_drv_init

IG_ISIS_drv_link

IG_ISIS_drv_load

IG_ISIS_drv_load_init_pipe

IG_ISIS_run_zone