DTWAIN_SetAcquireArea2

Top  Previous  Next

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

 

DTWAIN_BOOL DTWAIN_SetAcquireArea2 (

DTWAIN_SOURCE

Source,

DTWAIN_FLOAT

left,

DTWAIN_FLOAT

top,

DTWAIN_FLOAT

right,

DTWAIN_FLOAT

bottom,

LONG

Unit,

LONG

Flags );

 

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:

 clip0001

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

 

 

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:

 

DTWAIN_AcquireBuffer acquisitions that specify a compressed data stream or in other words, the data being transferred is not a Device Independent Bitmap (DIB).

DTWAIN_AcquireFile when the DTWAIN_USESOURCEMODE flag is set.

 

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_SysInitialize

 

DTWAIN Source Selection Function

 

 

See Also

Setting / Getting Acquisition Area