The IG_save_...() family of functions is complementary to the IG_load_...() functions. The IG_save_...() functions allow you to save images to disk files or to memory, convert files from one file format to another, and to append or insert images as pages to a multi-page file. All IG_save_...() functions have the lFormatType parameter in common. This allows you to choose which ImageGear-supported file format and compression type (where applicable) to which to save. Whereas some functions, such as IG_info_get_ex(), have separate parameters for the format and compression types, the saving functions have one parameter that covers both. See Save Functions in the API Reference for information about each function in this group.

This section provides information about the following:

Saving to Disk

IG_save_file is the function normally used to save a HIGEAR image to disk.

IG_save_file(image, fileName, format);

The name of the file to which to save is specified with the second argument, and the format type and compression type (if applicable) in which to save it is specified in the third. If the file format being used supports more than one compression type, more than one constant will be available. The BMP format, for example, is provided with two values for lformatType: IG_SAVE_BMP_UNCOMP and IG_SAVE_BMP_RLE. The file accucnst.h defines the constants to which lFormatType may be set; these constants are also listed in enumIGSaveFormats.

If the file already exists, and the format supports multiple pages, IG_save_file() will append the new image(s) to the file. If the file already exists, and it is a single image format type, the file will be overwritten.

The following code example demonstrates the use of IG_save_file():

HIGEAR image;
AT_ERRCOUNT errorCount;

errorCount = IG_save_file(image, "picture.tif", IG_SAVE_TIF_UNCOMP);

If you do not know the file format, you may set lFormatType to IG_SAVE_UNKNOWN. ImageGear will check the file's extension and save the image accordingly. If you set lFormatType to a value other than IG_SAVE_UNKNOWN, ImageGear assumes that you are specifying the correct type and saves the image accordingly.

Before selecting a file format to which to save, you can refer to Format Bit Depths to ensure that you save to a format that supports the same bit depth as the original image.

Saving to a Multi-Page File

The simplest way to save to a multi-page file is to use IG_save_file. If the file type supports multiple pages (such as TIFF), the new page will be appended to the end.

To insert an image into a specific location in a multi-page file, use IG_fltr_save_file.

When manipulating multi-page images in memory, see Load and Save Pages in a Multi-Page Document.

Saving to Disk Using a File Descriptor Handle

You can use the  IG_save_FD() function to save a HIGEAR image to a file that has already been opened and for which you have a File Descriptor handle (for example, your application may have opened the file using the Windows function _lopen()). IG_save_FD() will permit you to insert an image into a multi-page file (instead of merely appending it, as IG_save_file() would do.)

IG_save_FD() is called with five arguments, of which the HIGEAR image handle and lFormatType have the same meaning as in a call to IG_save_file(). The other parameters are the File Descriptor handle, fd obtained by the Windows function call that opened the file, a reserved argument nReserved, which should always be set to 0, and nPageNum, which allows you to specify the page in which to insert the image. If you want to append image(s) to a file, you can set nPageNum to IG_APPEND_PAGE.

The following example shows IG_save_FD() being used to insert an image as page 3 into an existing a multi-page file:

HIGEAR image;
INT fileDescriptor;
UINT pageNumber;
UINT reserved;
AT_ERRCOUNT errorCount;

// Use Windows call to open file with write privileges.
fd = _lopen("picture.tif", WRITE);

// Save this image as page 3.
pageNumber = 3;
// Set to 0, always.
reserved = 0;

// Save the image as page 3 of file whose descriptor is fileDescriptor.
errorCount = IG_save_FD(image, fileDescriptor, pageNumber, reserved, IG_SAVE_TIF_JPG);

If the file "picture.tif" has five pages, the new image will be inserted into the position of the third page, and what was formerly page three will now be page four, and so on. Remember that ImageGear treats the first page of a multi-page file as page 1, not 0. Setting the nPageNum parameter to 0 will append your image(s) to the file. If you set nFormatType to a type that doesn't support multiple pages, then the file will be overwritten with a single image.

Inserting pages to a multi-page file does not physically rearrange the image in the file. Rather, the offset table is adjusted to hold the new address(es) of the inserted page(s), and the new order of the image within the file.

lFormatType should be set to one of the IG_SAVE_ constants, which also include the compression type. Note that TIFF has more than one compression type, and that there are different constants to represent TIFF with each type of compression. If you call IG_save_FD() for a multiple-page file, you must supply the format type (from accucnst.h and also listed in enumIGSaveFormats) for the image to be appended to the file. If you do not know the format of the destination file, first call IG_info_get_FD_ex() and use the format information returned to decide which format to use.

The following pseudo-code example demonstrates how to write a multi-page image using IG_save_FD():

fileDescriptor = _lopen (file, OF_READWRITE);

for (i = 1; i<=nPages; i++)
{
    // Seek to the beginning of the file before writing each page.
    // ImageGear will automatically find the correct file position of the new page.
    seek(fileDescriptor, 0, SEEK_SET);
        
    // Write each next page.
    errorCount = IG_save_FD(hIGear, fileDescriptor, i, 0, IG_SAVE_TIF_UNCOMP);
}
close(fileDescriptor);

When you call OS SEEK or an equivalent function to set the file pointer, the stream needs to be positioned at the FIRST byte of a multi-page image. This is the only way in which a filter can recognize that the image is multi-page.

A file should be opened with both READ and WRITE access.

Saving to Memory

ImageGear allows you to save images to memory in the same way as you save images to a disk file.

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.

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:

1. 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.
2. Allocate a memory buffer using the calculated size.
3. Save first page to the memory buffer, using IG_fltr_save_mem().
4. 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.
5. Reallocate memory buffer using the new size.
6. Save second page.
7. 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.

Remarks

To get a list of compression types available for an image for a file format, use IG_fltr_compressionlist_get_ex.

To get a complete list of available format and compression combinations, use IG_fltr_savelist_get_ex.