IG_save_FD

This function saves the image to a file using user-defined callback functions. This is an obsolete function, see Remarks.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_save_FD_CB( AT_INT fd, UINT nPage, UINT nReserved, AT_LMODE lFormatType, LPFNIG_RASTER_GET lpfnRasterGet, LPFNIG_DIB_GET lpfnDIBGet, 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.
lpfnDIBGet	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:

Indexed RGB - 1, 4, 8 bpp;
Grayscale - 9...16 bpp;
RGB - 24 bpp;
CMYK - 32 bpp.

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 MyDIBGet( LPVOID lpPrivate, // Private data passed in LPAT_DIB lpDIB, // DIB structure to return LPAT_RGBQUAD lpRGB // DIB palette to be set ) { // Convert user DIB info into (*lpDIB) structure and copy a user palette to lpRGB return 0; } AT_ERRCOUNT ACCUAPI MyRasterGet( 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() { 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((AT_INT)fd, 1, 0, IG_SAVE_TIF_UNCOMP, MyRasterGet, MyDIBGet, NULL); CloseHandle(fd); } // Destroy the image IG_image_delete(hIGear); } }

Copy Code

AT_ERRCOUNT ACCUAPI MyDIBGet( 
    LPVOID lpPrivate,    // Private data passed in
    LPAT_DIB lpDIB,     // DIB structure to return
    LPAT_RGBQUAD lpRGB    // DIB palette to be set
    )
{
    // Convert user DIB info into (*lpDIB) structure and copy a user palette to lpRGB
    return 0;
}

AT_ERRCOUNT ACCUAPI MyRasterGet( 
    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()
{
    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((AT_INT)fd, 1, 0, IG_SAVE_TIF_UNCOMP, MyRasterGet, MyDIBGet, NULL); 
            CloseHandle(fd);
        }
        // Destroy the image
        IG_image_delete(hIGear);
    }
}

Remarks:

This function is only kept for backward compatibility reasons. Please use IG_save_FD_CB_ex instead.

First, your lpfnDIBGet() 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 DIB header. If the image requires a palette, this callback function also supplies the palette.

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

Refer to the descriptions for callback function types LPFNIG_DIB_GET and LPFNIG_RASTER_GET in this chapter.

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 that you are saving to.

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.