DTWAIN_SetAcquireArea2
|
The DTWAIN_SetAcquireArea2 function sets or resets the current image acquisition area.
DTWAIN_BOOL DTWAIN_SetAcquireArea2 (
Parameters Source An open TWAIN Source.
left Indicates upper left of rectangle to acquire.
top Indicates top of rectangle to acquire.
right Indicates right of rectangle to acquire.
bottom Indicates bottom of rectangle to acquire.
Unit Unit of measure used to describe left, top, right, and bottom of rectangle
Flags Optional flags. Currently only TRUE or FALSE is supported.
Return Values The return value is TRUE if successful. Otherwise FALSE is returned.
Comments The DTWAIN_SetAcquireArea2 function sets or resets the image acquisition area of the Source Source. The DTWAIN_SetAcquireArea2 does not use the TWAIN device's settings for valid acquisition areas. Note that DTWAIN_SetAcquireArea2 is the more reliable function than DTWAIN_SetAcquireArea in setting the area to acquire, due to the fact that DTWAIN_SetAcquireArea relies solely on the TWAIN Source to set the acquisition area. Many times, the Source will not set the area specified in DTWAIN_SetAcquireArea.
Use DTWAIN_SetAcquireArea if you need to set the acquisition area for non-DIB image data (i.e. DTWAIN_AcquireBuffered for compressed streams, or DTWAIN_AcquireFile / DTWAIN_AcquireFileEx with the DTWAIN_USESOURCEMODE flag set).
The following illustration shows the definition of the image area of acquisition and left, top, right, and bottom values denote: The origin of the page (top left-hand corner) always has an (x,y) coordinate of (0,0). Going right from the origin, the x-values increase. Going down from the origin, the y-values increase. There are no negative coordinates.
The Unit parameter can be any one of the following
Regardless of the current unit of measure used by the TWAIN Source, the application can specify the area to acquire in any of the above units. DTWAIN_SetAcquireArea2 will perform the correct conversion from the unit specified to the actual unit the Source uses to acquire the image. For example, if the Source's unit of measure is inches, and DTWAIN_SetAcquireArea2 specifies DTWAIN_POINTS, the left, top, right, and bottom units are converted internally from points to inches. This makes it easier for an application to specify and use just one unit of measure instead of keeping track of the current unit of measure used by the TWAIN source and writing code to do the conversion.
The flags parameter can either be TRUE or FALSE. If TRUE, the acquisition area is set to the left, top, right, and bottom arguments. If FALSE, the acquisition area is not used when acquiring an image and the left, top, right, and bottom arguments are ignored. In future versions of DTWAIN, the flags parameter will expand to other values.
Even though DTWAIN_SetAcquireArea2 does not use the TWAIN Source to set the area of acquisition, the Source must provide the unit of measure, and for images whose dimensions are determined after the page has been scanned, the Source must provide the image information after the page has been acquired. If the TWAIN device cannot provide this information, DTWAIN_SetAcquireArea2 will not work correctly, and the entire page is returned.
Note: All TWAIN Sources support getting the unit of measure and retrieving the image information before and after a page is acquired. If not, the Source is not TWAIN compliant.
For most acquisitions, the DTWAIN_SetAcquireArea2 function is preferred over DTWAIN_SetAcquireArea. However, DTWAIN_SetAcquireArea2 cannot be used for the following:
For languages that have difficulties with DTWAIN_FLOAT parameters, the alternate function that can be used as a replacement for DTWAIN_SetAcquireArea2 is DTWAIN_SetAcquireArea2String.
TWAIN State Transitions The Source must be in State 4. or higher (depending on the capability).
Prerequisite Function Call(s)
DTWAIN Source Selection Function
See Also |
