The ImageGear filters API provides three saving functions that make your application much faster and more flexible when working with image saving:
-
IG_fltr_save_file(HIGEAR hIGear, const LPSTR lpszFileName, AT_LMODE lFormatType, UINT nPageNumber, AT_BOOL bOverwrite)
This function works similarly to the IG_save_file() function, but has additional arguments that provide additional functionality when saving the image in a multi-page file. The nPageNumberargument allows you to specify the number of the page in an already existing multi-page file where you want the saved page to be placed. The last argument bOverwrite allows you to determine the mode of how to work with multi-page image files. The TRUE value completely overwrites the file and places a single page there, but a FALSE value means that the existing file will be expanded with one additional page specified by the nPageNumber parameter.
-
IG_fltr_compressionlist_get(LPAT_DIB lpDIB, AT_MODE nFormatID, LPAT_MODE lpComprList, UINT nCListSize, LPUINT lpnCListCount)
This function allows you to get information about all compressions (as IG_COMPRESSION_constants returned in lpComprListlist) that are available when saving the image to the file format specified by the nFormatID(as IG_FORMAT_constant) parameters. The first parameter allows you to specify information about the image to be saved. If this parameter is NULL, then the function returns all available compressions, otherwise it returns compressions that are applicable to a given image. For example, G3/4 compressions are only applicable for bi-tonal images, but JPEG compression is only applicable for color images with 8 bits or more per pixel.
- IG_fltr_savelist_get(LPAT_DIB lpDIB, LPAT_MODE lpnFilterList, UINT nFListSize, LPAT_LMODE lpSaveList, UINT nSListSize, LPUINT lpnSListCount)
This function allows you to prepare the list of applicable compressions, not for a single format but for a list of formats. It provides the ability to quickly build a list of applicable parameters that can be used, for instance, for the third (lFormatType) parameter of IG_fltr_save_file(). The main returned value lpSaveList contains a list of combined values (nFormat | (nCompression<<16)) = (IG_FORMAT_ | IG_COMPRESSION_<<16) available for a given image to save. You can get values of nFormat from lpnFilterList provided through the second parameter. For instance, if you specified lpnFilterList as IG_FORMAT_TIF, then the returned lpSaveList will be looked at as a list of (IG_FORMAT_TIF | IG_COMPRESSION_ ) values where IG_COMPRESSION_ is a list of all the compressions available for the TIFF image with the current lpDIB. If lpnFilterList is NULL then this function uses all available formats registered in ImageGear and returns the list with all currently available formats and compressions.
You can process the IG_fltr_compressionlist_get() and/or IG_fltr_savelist_get() functions before using IG_fltr_save_file() to determine the file format and compression type you specified in the lFormatType argument (as IG_SAVE_ constant, see accucnst.h file).
Saving Images to Memory
The function IG_fltr_save_mem() allows you to save a HIGEAR image to memory. The result is a file image in memory that is identical to the file that would have resulted if you had used any other save function (such as IG_fltr_save_file()). However, instead of using a filename to call IG_save_mem(), you specify the address and size of the memory area to which to save. The allocation of memory is discussed further below.
If there already is a valid image file at the address you specify in an IG_fltr_save_mem() call, the effect is the same as when using IG_fltr_save_file() to save to an existing file. Specifically, it allows appending or inserting pages into an existing file stored in memory.
Before you call IG_fltr_save_mem(), you need to allocate a memory buffer, and you must supply the size of the allocated buffer to the function. You can determine the appropriate buffer size by making a call to IG_fltr_save_mem_size_calc(). The size returned by this function will include the size of the bitmap data, which can be a portion of the image (the image rectangle) or the whole image, plus any other structures, such as the header or palette. If you are going to add a page to an existing image in the memory buffer, pass the address of the buffer to IG_fltr_save_mem_size_calc(). The function will calculate and return the size necessary for storing the image after the addition of the page.
You can use these steps to save a multi-page file in a memory buffer:
- Call IG_fltr_save_mem_size_calc(), specifying the HIGEAR for the first page, and passing NULL to lpImage parameter. This will return the size of the first page, saved to the buffer.
- Allocate a memory buffer using the calculated size.
- Save first page to the memory buffer, using IG_fltr_save_mem().
- Call IG_fltr_save_mem_size_calc(), specifying the HIGEAR for the second page, and passing the pointer to the memory buffer you've allocated, to lpImage parameter. This will return the size of the first and second pages saved to the buffer.
- Reallocate memory buffer using the new size.
- Save second page.
- Continue for the rest of pages.
This process can be optimized. For example, you can allocate (size of first saved page) * (number of pages) bytes in the first place to reduce the number of reallocations.
IG_fltr_save_mem() will return the actual size that the file required when it was saved to memory.
See Also
Saving to a Disk File Using a File Descriptor Handle