DTWAIN_SetUpdateDibProc

The DTWAIN_SetUpdateDibProc allows an application to use a callback function to an acquired image from a TWAIN device, and allows a new image to replace the acquired image.

DTWAIN_DIBUPDATE_PROC DTWAIN_SetUpdateDibProc ( DTWAIN_DIBUPDATE_PROC lpProc );

Parameters

lpProc

A pointer to a function that will be called whenever an image is acquired.

Return Values

If a callback function was previously set, this function returns the last callback function. Otherwise a NULL is returned.

Comments

DTWAIN_SetUpdateDibProc allows an application to use a callback function for access to the image that is acquired, and return a new image that will be processed instead of the original image. The image being sent and returned are in the form of a Device Independent Bitmap (DIB). The incoming image is the image directly acquired from the TWAIN device.

The DTWAIN_DIBUPDATE_PROC is a function pointer with the following prototype:

HANDLE CALLBACK DibUpdateCallbackProc( DTWAIN_SOURCE Source, LONG CurrentPage, HANDLE hDib );

The return value will be either 0, or a HANDLE to a new DIB that the application will replace with the current DIB. If the return value is 0, then the original DIB, denoted by hDib is used by DTWAIN in further processing. The Source argument is the current DTWAIN_SOURCE that acquired the image. The CurrentPage is the current page number of the DIB. The hDib is the HANDLE to the image that was acquired for page CurrentPage.

Example use cases for the callback function:

The DibUpdateCallbackProc callback is allowed to replace the DIB represented by hDib with another DIB if that is what is desired. For example, the application may want to access the DIB, and then do some image processing on the DIB before returning from the callback function.

If your application desires to inspect and possibly change the DIB in some way, you can use this callback function for this purpose. For example, if you are using another imaging library that adjusts the DIB (maybe rotate it, change the bits-per-pixel, etc.), you can accomplish it by using the callback.

There are rules if you plan to take the DIB hDib and change it in any way:

•	The hDib cannot be changed directly. Your application must create a new DIB and reflect the changes in the new DIB. This DIB is then returned by your callback function.

•	The hDib is a HANDLE, therefore your application must call the Windows API GlobalLock to access the DIB

•	The new DIB must have its memory allocated with the Windows API function GlobalAlloc.

TWAIN State Transitions

None.

Prerequisite Function Call(s)

DTWAIN_SysInitialize

DTWAIN_EnableMsgNotify