ImageGear for C and C++ on Windows v19.6 - Updated
Use File Format Filters
User Guide > How to Work with... > Common Operations > Loading and Saving > Use File Format Filters

This topic provides information about the following:

Getting Information about a Format Filter

ImageGear provides a set of API functions that simplify the handling of different file formats in the application.

To get information about an ImageGear format filter use the IG_fltr_info_get() function. It returns information about the features supported by ImageGear for this file format (as IG_FLTR_ flags), the short and full names of the filter's file format and the names of the default file's extension:

C and C++
Copy Code
nErrCount = [lpfn]IG_fltr_info_get( nFormat, &dwFlags, szShortName,
sizeof(szShortName), szFullName, sizeof(szFullName), szDefExt, sizeof(szDefExt) );

Together with this function, you can use the IG_fltr_formatlist_sort() function to sort file formats in alphabetic order based on the short name returned by the IG_fltr_info_get() function through its third lpShortNameparameter.

If you want to determine the list of filters that support the IG_FLTR_ features you can use the function:

C and C++
Copy Code
IG_fltr_formatlist_get(DWORD dwFlags, LPAT_MODE lpFormatList, UINT nFListSize,
LPUINT lpnFListCount)

Through the dwFlagsargument, you can specify any combination of features (for instance, IG_FLTR_DETECTSUPPORT | IG_FLTR_PAGEREADSUPPORT | IG_FLTR_MPAGEREADPSUPPORT), and a list of filters that support those features will be returned through the second parameter (lpFormatList). See the description of this function in the Core Component API Function Reference for detailed information about the parameters. If you want to determine the value of the nFListSizeargument, first set lpFormatListto NULL. You can also use this function together with IG_fltr_formatlist_sort() to get the list of filters that support necessary features and sort them by filter name:

C and C++
Copy Code
UINT              nFilterSize;
UINT              nFListSize;
LPAT_MODE         FList = NULL;
LPCHAR            lpFilter = NULL;
LPSTR                   str;
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, NULL, 0, &nFListSize );
FList = malloc( nFListSize*sizeof(AT_MODE) );
if( FList!=NULL )
{
IG_fltr_formatlist_get( IG_FLTR_PAGEREADSUPPORT, FList, nFListSize, NULL );
IG_fltr_formatlist_sort( FList, nFListSize );
...
}

You can get information about any page of a multi-page file without loading it into memory if you use the function IG_fltr_pageinfo_get(). Return information consists of the name of the file format (as IG_FORMAT_ constant), the type of image compression (as IG_COMPRESSION_ constant), and such info as bpp, width and height of the page-image.

Another two IG_fltr_...() functions allow you to work with pages in a multi-page file without loading it in memory:

C and C++
Copy Code
IG_fltr_pageswap_file (const LPSTR   lpszFileName, AT_MODE  nFormatType,  UINT
Page1, UINT  Page2)

IG_fltr_pagedelete_file (const LPSTR   lpszFileName, AT_MODE  nFormatType,  UINT
nStartPage, UINT  nRange)

Both functions accept the filename of the multi-page image, format filter ID, and two integer parameters as page numbers (assuming numeration from 1). The first function swaps pages in a multi-page image specified by page numbers, but the second function deletes pages from it.

Before using these functions you have to determine whether or not ImageGear supports the corresponding features for the necessary file format. This can be done using the function IG_fltr_info_get() and inspecting flags returned through the second parameter for the specified file formats. If this value contains the flag IG_FLTR_PAGESWAPSUPPORT, then the format filter does support the IG_fltr_pageswap_file() operation. If it also has the flag IG_FLTR_PAGEDELETESUPPORT, then it supports the IG_fltr_pagedelete_file() operation.

SWAP and DELETE operations may or may not physically reorder multi-page files. For example, the page delete operation may not really reduce the size of the file - just update the file format structures and remove the specified pages from it.

Each format filter has its own list of supported features determined by IG_FLTR_ flags. The table below describes the meaning of each of these flags:

Flag Name This Flag Supports...
IG_FLTR_DETECTSUPPORT Auto-detection.
IG_FLTR_PAGEREADSUPPORT Reading a single page file.
IG_FLTR_MPAGEREADPSUPPORT Reading a multi-page file.
IG_FLTR_PAGEINSERTSUPPORT Writing a single-page file.
IG_FLTR_MPAGEWRITEPSUPPORT Writing multi-page file.
IG_FLTR_PAGEDELETESUPPORT Deleting a page from a multi-page file.
IG_FLTR_PAGESWAPSUPPORT Page-swapping in multi-page files.
IG_FLTR_MPDATASUPPORT Faster multi-page access by storing private format data (used only with IG_mpi_... and IG_mpf_... API).

Using File Filter Control Parameters

Almost every format filter in ImageGear has some attributes on which it depends while processing operations such as READ, WRITE, etc. Those attributes may be attributes declared by the format filter specification or may be specific to its implementation by ImageGear. ImageGear has a general public interface implemented and named as format filter control parameters. Every such control parameter is identified by the format filter and string name and has an associated type of acceptable value, the value itself, and the default value. Each control parameter is filter specific. The ImageGear Supported File Formats Reference describes the filters, and also describes each control parameter for each format filter.

The ImageGear Filters API has three functions that allow you to get/set info about every supported filter control parameter:

This example demonstrates how to get the names of all supported control parameters for the TIFF format filter:

C and C++
Copy Code
/* getting the total number of parameters */
nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, &nCount, NULL, 0);
if(!nErrCount && nCount > 0)
{
/* allocate required buffer to keep all names */
lpOptList = malloc(nCount * sizeof(DWORD));
        if(lpArray)
        {
        nErrCount = IG_fltr_ctrl_list(IG_FORMAT_TIF, NULL, lpOptList, nCount *
sizeof(DWORD));
The filter control parameters you work with using IG_fltr_ctrl_...() functions are strings. Refer to the "Filter Control Parameters" Tables for each file format in the ImageGear Supported File Formats Reference section.

This example demonstrates how to get and set the value of the TIFF control parameter named "BIG_ENDIAN":

C and C++
Copy Code
char DocumentName[_MAX_PATH];
AT_BOOL bDefBigEndian, bOldBigEndian;
...
/* get current value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", FALSE, NULL, NULL,
(LPVOID)&bOldBigEndian, sizeof(hOldBigEndian));
/* get default value of BIG_ENDIAN control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "BIG_ENDIAN", TRUE, NULL, NULL,
(LPVOID)&bDefBigEndian, sizeof(hDefBigEndian));
/* get current value of DOCUMENT_NAME control parameter */
IG_fltr_ctrl_get(IG_FORMAT_TIF, "DOCUMENT_NAME", FALSE, NULL, NULL, DocumentName,
sizeof(DocumentName));
/* set new value to BIG_ENDIAN control parameter */
IG_fltr_ctrl_set(IG_FORMAT_TIF, "BIG_ENDIAN", (LPVOID)TRUE, sizeof(AT_BOOL));
/* set new value to DOCUMENT_NAME control parameter */
strcpy( DocumentName, "This is a test string for DocumentName" );
IG_fltr_ctrl_set(IG_FORMAT_TIF, "DOCUMENT_NAME", (LPVOID)DocumentName,
sizeof(DocumentName));
For the TXT Filter, to set the LINES_PER_PAGE and CHAR_PER_LINE control parameters, set the POINT_SIZE control parameter to zero; setting the PAGE_WIDTH, PAGE_HEIGHT, and POINT_SIZE parameters provides a sufficient page description, and LINES_PER_PAGE and CHAR_PER_LINE options are ignored.