ART_image_burn

This function merges annotation marks permanently into an image. The fOptions parameter specifies which marks are merged, and whether the marks should be preserved or removed after merging into the image.

Declaration:

	Copy Code
AT_ERRCOUNT ART_image_burn_in( HIGEAR hIGear, HWND hWnd, DWORD dwGrpID, AT_MODE fOptions, const LPSTR szGroup, LPART_MARK_INDEX lpMarkIndex, UINT nMarkCount );

Arguments:

Name	Type	Description
hIGear	HIGEAR	HIGEAR handle to the image.
hWnd	HWND	HWND handle to the window.
dwGrpID	DWORD	Identifier of group.
fOptions	AT_MODE	An ART-defined constant ( a bit flag) that tells what type of marks to burn in to the HIGEAR image. These are defined in ARTAPI.H, and are shown below.
szGroup	const LPSTR	A far pointer to a null-terminated string that tells ART what group of marks to merge, when the ART_BURN_IN_GROUP bit is set.
lpMarkIndex	LPART_MARK_INDEX	A far pointer to the mark identifier, used when the ART_BURN_IN_LIST bit is set.
hMarkCount	UINT	The count of marks or groups, ignored unless the ART_BURN_IN_LIST bit is set.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++.

Example:

	Copy Code
HIGEAR hIGear; /* HIGEAR handle of image / HWND hWnd; DWORD dwGrpID; / Burn in all visible marks in the group / / "Unclassified" */ dwGrpID = IG_GRP_DEFAULT; ART_image_burn_in(hIGear, hWnd, dwGrpID, ART_BURN_IN_VISIBLE\|ART_BURN_IN_GROUP, "Unclassified", NULL, 0L);

Copy Code

HIGEAR hIGear; /* HIGEAR handle of image */
HWND hWnd;
DWORD dwGrpID;
/* Burn in all visible marks in the group  */
/* "Unclassified"     */
dwGrpID = IG_GRP_DEFAULT;
ART_image_burn_in(hIGear, hWnd, dwGrpID,
ART_BURN_IN_VISIBLE|ART_BURN_IN_GROUP, 
"Unclassified", NULL, 0L);

Remarks:

fOptions may be a bitwise combination of any of the following values:

ART_BURN_IN_ALL	Burns in all annotation marks.
ART_BURN_IN_DELETE_MARKS	Deletes affected marks after burning them in.
ART_BURN_IN_GROUP	Burns in a group of marks.
ART_BURN_IN_LIST	Burns in a list of marks.
ART_BURN_IN_VISIBLE	Burns in visible marks.
ART_BURN_IN_SELECTED	Burns in selected marks.
ART_BURN_IN_AUTO_PROMOTE	Automatically promotes image.
ART_BURN_IN_NO_PROMOTE	No promotion before burn-in.

The szGroup parameter is ignored, unless fOptions includes ART_BURN_IN_GROUP. The lpMarkIndex parameter is ignored, unless fOptions includes ART_BURN_IN_LIST. nMarkCount is the count of items in the list pointed to by lpMarkIndex.

To restrict the number of marks that are burned into the image, set more options. For example, if ART_BURN_IN_GROUP, ART_BURN_IN_SELECTED and ART_BURN_IN_VISIBLE are set, only those marks that are in the group szGroup, that are selected and visible, are burned into the image.

An error is set if any of the following conditions are met:

hIGear does not reference a valid ImageGear handle.
fOptions includes ART_BURN_IN_LIST and the memory pointed to by lpMarkIndex is invalid.

The settings ART_BURN_IN_AUTO_PROMOTE and ART_BURN_IN_NO_PROMOTE affect whether the IGPage image undergoes a bit depth promotion before the marks are burned in.

There are three variants of this function behavior for the bit depth promotion:

Default behavior (neither ART_BURN_IN_AUTO_PROMOTE nor ART_BURN_IN_NO_PROMOTE is used):
- For 1-bit images: promote to 8, burn-in, then reduce back to 1.
- For 4 and 8: promote to 24, burn-in, then reduce to original bit depth.
- For 24: no promote, burn-in, and no reducing.
When ART_BURN_IN_NO_PROMOTE is used, all promotion is suppressed.

When ART_BURN_IN_AUTO_PROMOTE is used:
- For 1 and 4-bit images: promote to 24, burn-in, then reduce to 4 bits per pixel.
- For 8-bit images: promote to 24, burn-in, then reduce to 8 bits per pixel.
- For 24: no promote, burn-in, and no reducing.