Member

Description

uStructSize

Size of this structure in bytes, for versioning. Use the sizeof() macro to calculate this value.

uFlags

Flags that determine the behavior of the hole punch removal process. Flags may be combined using a bitwise OR (|). Possible values are:

Value

Meaning

HOLEPUNCH_SINGLE_REGION

For each hole punch encountered by L_HolePunchRemoveBitmap, if the HOLEPUNCHREMOVECALLBACK function returns SUCCESS_REMOVE, the removed hole punch is added to an internal single region. If the callback returns SUCCESS_NOREMOVE, the hole punch is not added to the single region. When L_HolePunchRemoveBitmap returns, either pBitmapRegion or hRgn will reference a region that contains all the removed hole punches. If HOLEPUNCH_LEAD_REGION is also set, pBitmapRegion will be updated with a shallow copy of pBitmap that has a LEAD region that contains all the removed hole punch. If HOLEPUNCH_LEAD_REGION is not set, hRgn is updated with a Windows region that contains all the removed hole punches. When the region (either LEAD or Windows) is no longer needed, it must be destroyed (either pBitmapRegion->pRgnInfo or hRgn).

HOLEPUNCH_LEAD_REGION

When L_HolePunchRemoveBitmap returns, pBitmapRegion is updated with a shallow copy of pBitmap that also contains a region with all the removed hole punches. This flag must be used in conjunction with HOLEPUNCH_SINGLE_REGION. To use this flag declare a variable of type BITMAPHANDLE and point pBitmapRegion to this variable. Set uFlags to HOLEPUNCH_SINGLE_REGION | HOLEPUNCH_LEAD_REGION. This variable will be updated when L_HolePunchRemoveBitmap returns.

HOLEPUNCH_IMAGE_UNCHANGED

The original image is unchanged.

HOLEPUNCH_USE_DPI

The unit of measure for all fields of the HOLEPUNCH structure is thousandths of an inch. Use the image's DPI to convert to pixels. This allows the processing of many images with different DPI. If this flag is not set, the unit of measure for all fields of the HOLEPUNCH structure is pixels.

HOLEPUNCH_CALLBACK_REGION

HOLEPUNCHREMOVECALLBACK receives a Windows region that contains the current hole punch to be removed. Setting this flag lets the user create his or her own composite of removed hole punches by combining the regions received by the callback function, if the callback function returns SUCCESS_REMOVE. The regions can be combined using a logical OR operator. Combining all regions received when the callback function returns SUCCESS_REMOVE results in a region identical to the region created when HOLEPUNCH_SINGLE_REGION is set in uFlags. For an example, refer to L_HolePunchRemoveBitmap. When the region received by the callback function is no longer needed, it must be destroyed using DeleteObject().

HOLEPUNCH_USE_SIZE

Use the iMinHoleWidth, iMinHoleHeight, iMaxHoleWidth, iMaxHoleHeight members of the HOLEPUNCH structure to indicate the size of the hole punches to remove. If this flag is not set, default values for the four sizes will be used. If HOLEPUNCH_USE_DPI is set, the defaults are calculated from the image DPI. Otherwise, the defaults are calculated from the image width and height.

HOLEPUNCH_USE_COUNT

Use the iMinHoleCount and iMaxHoleCount members of the HOLEPUNCH structure to indicate the number of hole punches to remove. If this flag is not set, default values for the two count values will be used. These default values are as follows: iMinHoleCount = 3 and iMaxHoleCount = 3.

HOLEPUNCH_USE_LOCATION

Use the iLocation member of the HOLEPUNCH structure to indicate the location of the hole punches to remove. If this flag is not set, a default of HOLEPUNCH_LEFT will be used.

HOLEPUNCH_ALLFLAGS

Use all flags, the value of this flag equals to (

HOLEPUNCH_USE_DPI                     |
HOLEPUNCH_SINGLE_REGION         |
HOLEPUNCH_LEAD_REGION            |
HOLEPUNCH_CALLBACK_REGION   |
HOLEPUNCH_IMAGE_UNCHANGED  |
HOLEPUNCH_USE_SIZE                   |
HOLEPUNCH_USE_COUNT               |
HOLEPUNCH_USE_LOCATION)

iMinHoleCount

Minimum number of holes to detect. This member is valid only if HOLEPUNCH_USE_COUNT is set in uFlags.

iMaxHoleCount

Maximum number of holes to detect. This member is valid only if HOLEPUNCH_USE_COUNT is set in uFlags.

iMinHoleWidth

The minimum width of one of the holes of the hole punch configuration to be removed. If HOLEPUNCH_USE_DPI is set in uFlags, units are in thousandths of an inch, otherwise units are in pixels. This member is valid only if HOLEPUNCH_USE_SIZE is set in uFlags.

iMinHoleHeight

The minimum height of one of the holes of the hole punch configuration to be removed.. If HOLEPUNCH_USE_DPI is set in uFlags, units are in thousandths of an inch, otherwise units are in pixels. This member is valid only if HOLEPUNCH_USE_SIZE is set in uFlags.

iMaxHoleWidth

The maximum width of one of the holes of the hole punch configuration to be removed. If HOLEPUNCH_USE_DPI is set in uFlags, units are in thousandths of an inch, otherwise units are in pixels. This member is valid only if HOLEPUNCH_USE_SIZE is set in uFlags.

iMaxHoleHeight

The maximum height of one of the holes of the hole punch configuration to be removed. If HOLEPUNCH_USE_DPI is set in uFlags, units are in thousandths of an inch, otherwise units are in pixels. This member is valid only if HOLEPUNCH_USE_SIZE is set in uFlags.

iLocation

Indicates the location within the document of the hole punches to remove. Possible values are:

Value

Meaning

HOLEPUNCH_LEFT

Searches for the hole punch pattern on the left side of the document

HOLEPUNCH_RIGHT

Searches for the hole punch pattern on the right side of the document

HOLEPUNCH_TOP

Searches for the hole punch pattern across the top of the document

HOLEPUNCH_BOTTOM

Searches for the hole punch pattern across the bottom of the document

pBitmapRegion

Pointer to a variable of type BITMAPHANDLE. If HOLEPUNCH_SINGLE_REGION | HOLEPUNCH_LEAD_REGION have been set in uFlags, then when L_HolePunchRemoveBitmap returns, this is updated with a shallow copy of pBitmap that also has a region that contains the hole punches. To use this, declare a variable of type BITMAPHANDLE and point pBitmapRegion to this variable. Set uFlags to (HOLEPUNCH_SINGLE_REGION | HOLEPUNCH_LEAD_REGION). It is the programmer's responsibility to free the region using L_FreeBitmapRgn() when it is no longer needed. Refer to the L_HolePunchRemoveBitmap example to see how pBitmapRegion is used and freed.

uBitmapStructSize

Size of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).

hRgn

Handle to a windows region. When L_HolePunchRemoveBitmap returns, this is updated with a single windows region corresponding to all changes, only if HOLEPUNCH_SINGLE_REGION has been set in uFlags and HOLEPUNCH_LEAD_REGION has not been set. To use this, set the flags field to (HOLEPUNCH_SINGLE_REGION). It is the programmer's responsibility to delete this region using the windows API DeleteObject() when the region is no longer needed.