|
DTWAIN_GetCurrentAcquiredImage |
Top Previous Next |
|
The DTWAIN_GetCurrentAcquiredImage function returns the handle to the last image that was acquired successfully.
HANDLE DTWAIN_GetCurrentAcquiredImage (
Parameters Source The DTWAIN_SOURCE that is acquiring images.
Return Values If the function succeeds, an image block is returned. If the function fails, NULL is returned.
Comments DTWAIN_GetCurrentAcquiredImage returns a HANDLE to the last image that was acquired successfully. You must use the Windows API GlobalLock on the return value to access the data. At some point in your application, you must call the Windows API GlobalUnlock (if it was locked) and GlobalFree to destroy the data.
This function is useful if you are acquiring a series of images, and you desire to process each image as it is being acquired successfully. The easiest way to do this is to use DTWAIN Notification Processing and capture one of the two notifications, DTWAIN_TN_PROCESSEDDIB or DTWAIN_TN_PROCESSEDDIBFINAL.
When the DTWAIN_TN_PROCESSEDDIB is sent, the image returned by DTWAIN_GetCurrentAcquiredImage is the original image as outputted by the TWAIN device, untouched by DTWAIN. When DTWAIN_TN_PROCESSEDDIB is sent, if your application processes this notification, your application must return a value when processing this notification. Your application must return 0 to indicate that you do not want DTWAIN to do further processing on the image and to leave the image as originally acquired, or return 1 to have DTWAIN continue processing the image.
If your application desires to keep the image, but your application returns 1 when DTWAIN_TN_PROCESSEDDIB is sent, the image handle that your application will have will possibly become invalid due to further processing done on the image by DTWAIN.
When the DTWAIN_TN_PROCESSEDDIBFINAL is sent, the image has been fully processed by DTWAIN (i.e. cropped, resized, etc. depending on the DTWAIN functions that are used on the image, such as DTWAIN_SetAcquireImageScale). When DTWAIN_TN_PROCESSEDDIBFINAL is sent, if your application processes this notification, your application must return a value when processing this notification -- 0 to indicate that you do not want DTWAIN to do further processing on the image, or 1 to have DTWAIN continue processing the image.
DTWAIN_GetCurrentAcquiredImage is only valid for DTWAIN_AcquireNative, DTWAIN_AcquireBuffered or DTWAIN_AcquireToClipboard. The DTWAIN_AcquireFile and DTWAIN_AcquireFileEx do not create or store the image data in memory, so DTWAIN_GetCurrentAcquiredImage will return NULL if it is called during a file acquisition.
The returned HANDLE can be a Device Independent Bitmap, or if calling DTWAIN_AcquireBuffered using compression, a HANDLE to a series of bytes representing compressed image data (to get the number of bytes of compressed image data, use the Windows API GlobalSize function on the returned HANDLE, or call DTWAIN_GetCompressionSize function).
TWAIN State Transitions None
Prerequisite Function Call(s) DTWAIN Source Selection Function DTWAIN Acquisition Function (DTWAIN_AcquireNative or DTWAIN_AcquireBuffered)
See Also |