ImageGear for C and C++ on Linux v18.8 - Updated
IG_image_convert
API Reference Guide > Core Component API Reference > Core Component Functions Reference > General Image Functions > IG_image_convert

This function allows you to transform image file without decoding it completely and avoiding the need to load it into a memory.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_image_convert(
        char* lpszSrcFileName,
        char* lpszDstFileName,
        AT_LMODE lFormatType,
        AT_LMODE lCommand,
        AT_LMODE lOptions
);

Arguments:

Name Type Description
lpszSrcFileName char* The filename of the source file.
lpszDstFileName char* The filename of the destination file.
lFormatType AT_LMODE The format type of output image to save.
lCommand AT_LMODE The type of operation to perform (IG_CONVERT_ type constant).
lOptions AT_LMODE Conversion options (bit mask).

Return Value:

Number of errors occurred during the function call.

Supported Raster Image Formats:

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

Remarks:

The following types of transformations are currently supported:

PostScript format is not supported on Linux 64-bit platform.

This function does not process image's metadata. This is responsibility of the user. See filter sample for an example of working with metadata.

Lossless Conversion of JPEG Compressed Image Files

This function allows you to apply certain operations on JPEG compressed image files, such as rotation, flipping, etc, without degradation of image quality. It can be used also for lossless conversion between JFIF JPEG and EXIF JPEG file formats, and for adding a thumbnail to a JFIF or EXIF file.

Transformation is done on the DCT coefficients rather than on decompressed pixels, so the lossy decompression/compression stages are not involved.

In contrast, the usual way (to load, rotate and save image) results in significant image degradation, especially when a high compression rate is used.

This function can be useful for converting photographic images between portrait and landscape layouts.

The following lossless operations (lCommand argument) are supported:

IG_CONVERT_NONE No conversion.
IG_CONVERT_ROTATE_90 Rotate 90 degrees.
IG_CONVERT_ROTATE_180 Rotate 180 degrees.
IG_CONVERT_ROTATE_270 Rotate 270 degrees.
IG_CONVERT_FLIP_HORIZONTAL Flip horizontal.
IG_CONVERT_FLIP_VERTICAL Flip vertical.
IG_CONVERT_TRANSPOSE Flip about upper left - lower right diagonal.
IG_CONVERT_TRANSVERSE Flip about upper right - lower left diagonal.

IG_CONVERT_NONE mode can be used for converting between JFIF JPEG and EXIF JPEG format, or for adding a thumbnail to the image.

lOption parameter is a bit mask. Only one bit flag is supported:

IG_CONVERT_OPTION_TRIM = 1

An inherent limitation of such conversions is that the source image dimensions must be multiples of the DCT matrix size (typically 8 or 16) to preserve the entire image. If they are not, the remaining pixels at the right and/or bottom are undefined after transform. The function fills them with a mirror projection of the preceding pixels. This may work well enough for many photographic pictures. If you prefer not to keep the mirrored edge, set lOption parameter to IG_CONVERT_OPTION_TRIM. With this option set, the function will trim result image dimensions to a multiple of DCT size. In particular:

IG_CONVERT_NONE Resulting image dimensions will not be modified.
IG_CONVERT_ROTATE_90 Resulting image width can be trimmed.
IG_CONVERT_ROTATE_180 Resulting image width and height can be trimmed.
IG_CONVERT_ROTATE_270 Resulting image height can be trimmed.
IG_CONVERT_FLIP_HORIZONTAL Resulting image width can be trimmed.
IG_CONVERT_FLIP_VERTICAL Resulting image height can be trimmed.
IG_CONVERT_TRANSPOSE Resulting image dimensions will not be modified.
IG_CONVERT_TRANSVERSE Resulting image width and height can be trimmed.

The following formats are supported as both source and destination: JFIF-JPEG, EXIF-JPEG. Only Lossy and Progressive compressions are supported. If any other format is used for either source or destination, the function will return an error.

If lFormatType == IG_FORMAT_UNKNOWN, the function will recognize source file format and use it for the destination file to save.

This function also converts the image's thumbnail, if it is present. If the thumbnail is JPEG compressed, it will be converted without degradation of quality. If the source image does not contain a thumbnail, and destination filter's "SAVE_THUMBNAIL" control parameter is set to TRUE, the function will create a thumbnail from the source image.

Conversion between PDF and PostScript Formats

This function can also be used for conversion of the entire document from PDF to PostScript or back. The function's arguments should be set as follows:

lpszSrcFileName Name of the input PDF or PS document to convert.
lpszDstFileName Name of the output PDF or PS document.
lFormatType Save format, either IG_FORMAT_PDF or IG_FORMAT_POSTSCRIPT.
lCommand IG_CONVERT_NONE.
lOptions Not used, set to 0.