ImageGear for C and C++ on Windows v19.1 - Updated
ART_image_burn_in
API Reference Guide > ART Component API Reference > ART Component Functions Reference > Image Utility Functions > ART_image_burn_in

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++.

Sample:

Annotation

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);

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:

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: