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:
-
IG_fltr_ctrl_list(DWORD dwFormatID, LPUINT lpnCount, LPDWORD lpArray, DWORD dwArraySizeInBytes)
This function allows the application to get the list of names of all control parameters supported by the format filter identified by dwFormatID. The Application is responsible for allocating the buffer lpArray, but ImageGear sets the elements of this array as pointers to strings with control parameter names. You can use the control parameter names as input values for the second argument of the next two functions.
- IG_fltr_ctrl_get(DWORD dwFormatID, const LPCHAR lpcsCtrlName, AT_BOOL bGetDefault, LPAT_MODE lpnValueType, LPDWORD lpdwValueSize, LPVOID lpBuffer, DWORD dwBufferSize)
This function is used to get the value of a given control parameter of a given format filter, and it may return either its current value or its default value - that is controlled by the bGetDefault argument. A TRUE value returns the default value, but FALSE returns the current value. The value itself is copied into a buffer that the application provides through the dwBufferSize argument. You can use the control parameter names from IG_fltr_ctrl_list as input values for the lpcsCtrlName argument. - IG_fltr_ctrl_set(DWORD dwFormatID, const LPCHAR lpcsCtrlName, LPVOID lpValue, DWORD dwValueSize)
This function allows you to set a new value for the control parameter. You can use the control parameter names from IG_fltr_ctrl_list as input values for the lpcsCtrlName argument. The last two arguments of this function specify the data to be set, and ImageGear always treats this data as a type that can be gotten by the _get() function. If the actual size of the new value is less than 4 bytes, then lpValue is treated as the value itself, otherwise it is treated as a pointer to the value.
This example demonstrates how to get the names of all supported control parameters for the TIFF format filter:
 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":
| 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. |