DTWAIN_SetAcquireArea2

The DTWAIN_SetAcquireArea2 function sets or resets the current image acquisition area.

DTWAIN_SOURCE	Source,
DTWAIN_FLOAT	left,
DTWAIN_FLOAT	top,
DTWAIN_FLOAT	right,
DTWAIN_FLOAT	bottom,
LONG	Unit,
LONG	Flags );

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.

Unit	Definition
DTWAIN_INCHES	Units are specified in inches.
DTWAIN_CENTIMETERS	Units are specified in centimeters.
DTWAIN_PIXELS	Units are specified in pixels.
DTWAIN_PICAS	Units are specified in picas (6 picas per inch).
DTWAIN_POINTS	Units are specified in points (72 points per inch)
DTWAIN_TWIPS	Units are specified in twips (1,440 twips per inch)

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.