ImageGear for C and C++ on Linux v19.10 - Updated
IG_save_FD_CB_ex
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Save Functions > IG_save_FD_CB_ex

This function saves the image to a file using user-defined callback functions.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_save_FD_CB_ex(
   AT_INT fd,
   UINT nPage,
   UINT nReserved,
   AT_LMODE lFormatType,
   LPFNIG_RASTER_GET lpfnRasterGet,
   LPFNIG_DIB_GET_EX lpfnDIBGetEx,
   LPVOID lpPrivateData
);

Arguments:

Name Type Description
fd AT_INT Handle of the open file for saving the image. This handle can be obtained from Microsoft Windows function such as CreateFile(), and cast to AT_INT for passing to the function parameter. FILE pointers returned by functions such as fopen(), and file handles returned by functions such as _sopen_s() are not supported.
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 be set to 0 for now.
lFormatType AT_LMODE Specifies the format to use for saving, and also the compression scheme if applicable. See enumIGSaveFormats.
lpfnRasterGet LPFNIG_RASTER_GET Pointer to a function of type LPFNIG_RASTER_GET, which will be called for each raster line of the image, before that line is saved.
lpfnDIBGetEx LPFNIG_DIB_GET Pointer to a function of type LPFNIG_DIB_GET, which will be called just prior to saving the DIB header.
lpPrivateData LPVOID Pointer to a private data area. This pointer will be passed to the above two callback functions each time they are called.

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++.

Actual set of pixel formats supported by this function can be narrower, depending on the implementation of the user-defined callback functions.

Example:

 
Copy Code
AT_ERRCOUNT ACCUAPI MyDIBGetEx( 
    LPVOID lpPrivate,    // Private data passed in
    HIGDIBINFO* lphDIB  // DIB info object to return
    )
{
    // Convert user DIB info into lphDIB
    return 0;
}

AT_ERRCOUNT ACCUAPI MyRasterGetEx( 
    LPVOID lpPrivate,    // Private data passed in
    LPAT_PIXEL lpRaster,// Raster line to set
    AT_PIXPOS row,      // Y position in the image
    DWORD rasterSize    // Size of the raster line
    )
{
    // Copy user pixel data to lpRaster in the appropriate format
    return 0;
}
void Example_IG_save_FD_CB_ex()
{
    HANDLE  fd;                            // File Descriptor handle
    AT_ERRCOUNT     nErrcount;            // Count of returned errors on stack
    HIGEAR hIGear;                        //ImageGear handle
    nErrcount = IG_load_file("picture.tif", &hIGear);
    if(nErrcount == 0)
    {
        // Create a file for writing
        fd = CreateFile(_T("picture_new.tif"), GENERIC_WRITE,
            0, NULL, OPEN_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);

        if(fd != INVALID_HANDLE_VALUE)
        {
            nErrcount = IG_save_FD_CB_ex((AT_INT)fd, 1, 0, IG_SAVE_TIF_UNCOMP, MyRasterGetEx, MyDIBGetEx, NULL); 
            CloseHandle(fd);
        }
        // Destroy the image
        IG_image_delete(hIGear);
    }
}

Remarks:

First, your lpfnDIBGetEx() callback is called. This function supplies ImageGear with the image's width, height, bits per pixel, and all DIB information in the form of a HIGDIBINFO object.

ImageGear then writes a header out to file fd, in the lFormatType format. Next, lpfnRasterGet() is called once for each raster line. ImageGear gets the raster line from the callback function. Then, it compresses the raster line (according to lFormatType) and writes the line to fd. (Note that the calls for the raster lines are not necessarily in order.)

In order for an ImageGear append page operation to work properly, the file handle 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.