IG_save

This function saves the image referenced by hIGear in a memory block.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_save_mem( HIGEAR hIGear, LPVOID lpImage, AT_UINT nImageSize, AT_UINT nBufferSize, UINT nPage, UINT nReserved, AT_LMODE lFormatType, LPAT_UINT lpActualSize );

Arguments:

Name	Type	Description
hIGear	HIGEAR	HIGEAR handle of image to save.
lpImage	LPVOID	Pointer to first byte of memory area in which to save.
nImageSize	AT_UINT	Size of the image if it already exists in the buffer, 0 otherwise.
nBufferSize	AT_UINT	Size of the memory buffer.
nPage	UINT	If saving to a multi-page file, set this to the page number to insert this page as. Note that page numbers begin at 1, not 0. Otherwise set to 1.
nReserved	UINT	Reserved, should always be set = 0 for now.
lFormatType	AT_LMODE	Specifies the format to use for saving, and also the compression scheme if applicable. See enumIGSaveFormats.
lpActualSize	LPAT_UINT	Size of new file in memory will be returned in the variable pointed by this parameter. NULL is allowed.

Return Value:

Returns 0 if successful. Otherwise, returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++.

Example:

	Copy Code
AT_ERRCOUNT nErrcount; // Count of returned errors on stack HIGEAR hIGear; // ImageGear handle AT_BYTE* lpMemoryBlock; // Memory block to save the image to AT_UINT nMaxSize; // Size of the memory block nErrcount = IG_load_file("picture.bmp", &hIGear); if(nErrcount == 0) { // Get a required size of the memory block nErrcount = IG_save_file_size_calc ( hIGear, IG_SAVE_BMP_UNCOMP, &nMaxSize); // Allocate a memory block lpMemoryBlock = (AT_BYTE*)malloc(nMaxSize); // Save image to the memory block in BMP format without compression: nErrcount = IG_save_mem(hIGear, lpMemoryBlock, 0, nMaxSize, 1, 0, IG_SAVE_BMP_UNCOMP, NULL); // Destroy the image IG_image_delete(hIGear); // Some usage of the image in the memory //... free(lpMemoryBlock); }

Copy Code

AT_ERRCOUNT     nErrcount;            // Count of returned errors on stack
HIGEAR hIGear;                        // ImageGear handle
AT_BYTE* lpMemoryBlock;                // Memory block to save the image to
AT_UINT nMaxSize;                    // Size of the memory block
nErrcount = IG_load_file("picture.bmp", &hIGear);

if(nErrcount == 0)
{
    // Get a required size of the memory block
    nErrcount = IG_save_file_size_calc ( hIGear, IG_SAVE_BMP_UNCOMP, &nMaxSize);
    // Allocate a memory block
    lpMemoryBlock = (AT_BYTE*)malloc(nMaxSize);
    // Save image to the memory block in BMP format without compression:
    nErrcount = IG_save_mem(hIGear, lpMemoryBlock, 0, nMaxSize, 1, 0, IG_SAVE_BMP_UNCOMP, NULL);
    // Destroy the image
    IG_image_delete(hIGear);
    // Some usage of the image in the memory
    //...
    free(lpMemoryBlock);
}

Remarks:

You provide the total size of your memory area, nBufferSize, so ImageGear can avoid writing beyond the area you have reserved for the file image. The image file that results will be identical to what would have been written to disk had you used IG_save_FD: it will begin with a header, and will be in the format you have declared by argument lFormatType. After writing the entire new file to memory, the actual size of this in-memory file is returned to you in the AT_UINT variable pointed to by lpActualSize.

If the file format is multi-page, and if there already is a valid file of that format at location *lpImage, then the HIGEAR image you are saving will be inserted as the page number you've indicated by nPage. If you want to append your image to the multi-page file, set nPage = IG_APPEND_PAGE. If the file format is not multi-page, then any file image already at location lpImage will be overwritten. Set nPage = 1 for non-multi-page file formats.

It is your application's responsibility to allocate the memory to hold the file image, and to free this memory when it is no longer needed. You may call function IG_save_file_size_calc to determine the maximum amount of memory you need to allocate. (If you have not allocated enough memory an error will be set and *lpImage will contain an unfinished image. The image left in memory after this condition should not be used.)

In order for an ImageGear append page operation to work properly, the memory buffer must point to the very beginning of the existing image, rather than to one of its pages, start of pixel data, or any custom wrapper preceding the image.

Appending and Inserting: While IG_APPEND_PAGE assures you that your loaded image will be appended to a pre-existing multi-page file, there are two other instances in which the value you assign to nPage will cause an append: if you set nPage to less than 1, or if you set nPage to greater than the number of pages in the file to which you are saving.

To summarize: ImageGear will insert your image to a pre-existing multi-image file if you set nPage to a value between 1 and the number of the last page in the file.

ImageGear supports the writing of tiled images for specific image formats, but does not support the insertion, replacement or appending of individual tiles.