Some format filters, such as EXIF-JPEG, EXIF-TIFF, TIFF, JPEG, PNG and some others contain non-image data, generally referred to as metadata. ImageGear provides a mechanism for reading the metadata during image loading and modifying it during image saving. Non-image data itself can be of any possible complex type, depending on the nature of the file format. ImageGear processes this complex data through a single interface and allows uniform processing that does not depend on the actual data format, and starts from information fields of such simple formats as BMP and PCX, up to the complex metadata support in the EXIF filter and the IPTC non-image data format in such filters as TIFF and JPEG.

While EXIF-JPEG and EXIF-TIFF are separate image file formats using JPEG or TIFF image data compressions, IPTC is a format used only for non-image data storage in such imaging format filters as JPEG and TIFF. For more detailed information about these formats, see the EXIF-TIFF Non-Image Data Structure, EXIF-JPEG Non-image Data Structure, and the IPTC Non-Image Data Structure sections in Non-Image Data Storage as well as the EXIF-JPEG and EXIF-TIFF sections in the File Format Reference.

ImageGear is responsible for translating this format-dependent data into a standard uniform format. There are at least two operations that include such data processing:

• Image loading - during image loading, some additional data needs to be loaded and uncompressed into the set of values of standard types for further processing.
• Image saving - during image saving, there should be a way to change existing defined values and add new values.

This section provides the following information:

• Work with Single-Page Images (HIGEAR)
• Work with Multi-Page Documents (HMIGEAR)
• • Create and Delete a Multi-Page Image Object
  • Open and Close an External Image File
  • Load and Save Pages in a Multi-Page Document
  • Reorder Pages in a Multi-Page Document
  • Use the Multi-Page Image Callback Function
• Access Image Pixels
• Work with Image Utility Functions
• • Creating DIBs and DDBs
  • Deleting DIBs and DDBs
  • Reading and Writing Palettes
  • Getting Information about a HIGEAR Image
• Access Image Metadata

This topic provides the following information:

Non-Image Data Format

The key thing of non-image data processing in ImageGear is a uniform data format that is used to convert to and from the format filter. As soon as the format filter decodes the data fields one after another during the loading operation, and encodes it in the reverse direction during the saving operation, all data consists of the set of items where each item is a minimal atom of information. The order of items is fixed, and the format filter processes item after item in the given order. The same order is used when data is passed through the stream.

The low-level format of the data consists of the list of items where each item represents a minimal unit of information. Each item also should have some unique name that allows you to connect it with the physical value inside of the file format. The definition of the data item can be described by the following fields:

typedef struct tagAT_DATALIST_ITEM{
        AT_MODE         FormatID
        LPCHAR          Name;
        DWORD           Id;
        AT_MODE                 Type;
        LPVOID          Value;
        AT_MODE                 ValueType;
        DWORD           Length;
        AT_MODE                 ValueAccessMode;
        }AT_DATALIST_ITEM;

Please see the descriptions of these fields below:

So, this data structure allows you to "linearize" hierarchical and complex data into an array of simplest data types.

You can transfer different non-image data using the general data structure described in this section. Please see Non-Image Data Storage.

Processing Non-Image Data

There are two working scenarios of how ImageGear processes non-image data.

The first one is the LOAD operation:

1. Application registers special callback function of type LPAFT_IG_METAD_ITEM_GET_CB.
2. The application calls some of the filter loading functions (like IG_fltr_load_file()), and during the LOAD operation, the format filter calls the registered callback function to pass data for each item decoded from the image.

The reverse WRITE operation is more complex:

1. Application registers callback functions of types LPAFT_IG_METAD_ITEM_SET_CB and LPAFT_IG_METAD_ITEM_ADD_CB.
2. Application calls some filter writing functions (like IG_fltr_save_file()).
3. While performing WRITE operation ImageGear uses callback functions to modify existing items or add additional items to required dataset.
   
   ImageGear provides special LPAFT_ callback functions for the non-image data processing described in this section. It also preserves the "old" callback functionality (LPFNIG_ callback functions) required for image processing control and perfection. Please see Working with ImageGear Callback Functions for detailed information about the structure of the ImageGear callback functionality.

You can see from the declaration below that LPAFT_IG_METAD_ITEM_GET_CB accepts parameters that provide all necessary information about one data item. All parameters except the first one are fields of the data structure AT_DATALIST_ITEM described in "Non-Image Data Format" above:

LPAFT_IG_METAD_ITEM_GET_CB(LPVOID lpPrivate, LPCHAR ItemName,  DWORD ItemID, AT_MODE
ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL
ReadOnlyValue )

By implementing and providing a callback function of this type, the application can receive every decoded item and process it as needed.

Some items from the dataset are informational only and cannot be changed during the WRITE operation. So, if the ReadOnlyValue field is set to TRUE, then the item will not be changed during the WRITE operation. Actually, during this operation, the format filter prepares all necessary items and puts required values to them to make sure that the file format itself is not violated. For example, if an item requires a particular number of strips in the image, then if the value of this item is changed, the image cannot be loaded.

The format filter prepares a minimal set of items and default values for them, and before writing its values to the output stream it calls the callback function of type LPAFT_IG_METAD_ITEM_SET_CB so that the application can change its values. In addition, the format filter may call the function of type LPAFT_IG_METAD_ITEM_ADD_CB to get additional items to append the dataset. The application should provide its implementation in such a way that it returns TRUE until it is necessary to insert more items. If this function returns FALSE, all custom items have been added, and the filter can proceed.

The exact specification of the callback function types can be found in Core Component API Function Reference, but the following is a quick reference for better understanding:

LPAFT_IG_METAD_ITEM_SET_CB)(LPVOID lpPrivate, LPCHAR ItemName, DWORD ItemID, AT_MODE
ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL
ReadOnlyValue, LPVOID *NewItemValue, LPAT_MODE *NewValueType, LPDWORD
*NewValueLength )

*NewItemValue, *NewValueType, *NewValueLength are arguments with a new value for a given item. If ReadOnlyValue is TRUE, the value of this item is unchangeable.

You can add a new non-image item during the filter WRITE operation using the callback function prototype:

LPAFT_IG_METAD_ITEM_ADD_CB(LPVOID lpPrivate, LPCHAR ItemName,  DWORD ItemID, AT_MODE
ItemType, LPVOID ItemValue, AT_MODE ValueType, DWORD ValueLength, AT_BOOL
ReadOnlyValue )

All arguments in this function are parameters for the new item and its value.

To exchange the non-image tag information provided by these three callback functions between the application and the internal ImageGear structure levels, you should use two functions:

IG_fltr_metad_callback_get(LPVOID *lpPrivate, LPAFT_IG_METAD_ITEM_SET_CB
*lplpfnSetCB, LPAFT_IG_METAD_ITEM_ADD_CB  *lplpfnAddCB,
LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB )

IG_fltr_metad_callback_set(LPVOID *lpPrivate, LPAFT_IG_METAD_ITEM_SET_CB
*lplpfnSetCB, LPAFT_IG_METAD_ITEM_ADD_CB  *lplpfnAddCB,
LPAFT_IG_METAD_ITEM_GET_CB *lplpfnGetCB )

The first function allows you to provide the current callback non-image tag data from the internal ImageGear structure to an application level during load/save processes. If some callback information is not necessary, you can set the respective argument of this function to NULL. For instance, if you do not need information about newly added non-image items, set lplpfnAddCB = NULL.

The second _set() function provides the new non-image callback data from the application level to the internal ImageGear level during the load/save processes. Again, if some callback information is not necessary, you can set the respective argument of this function to NULL.

An example of how to use these callback functions is too complex to include in this manual. The GUI implementation that is provided in the source form demonstrates all aspects of working with these callback functions.