L_TransformFile

#include "l_bitmap.h"

L_LTFIL_API L_INT L_TransformFile(pszFileSrc, pszFileDst, uTransform, pfnCallback, pUserData, pLoadOptions)

L_TCHAR* pszFileSrc;

/* name of the source file */

L_TCHAR* pszFileDst;

/* name of the destination file */

L_UINT uTransform;

/* the transformation to perform */

TRANSFORMFILECALLBACK pfnCallback;

/* optional callback function */

L_VOID* pUserData;

/* pointer to more parameters for the callback */

pLOADFILEOPTION pLoadOptions;

/* pointer to optional extended load options */

Performs a lossless transformation for certain formats. Currently, only JPEG, CMP and JPEG TIFF formats are supported.

Parameter

Description

pszFileSrc

Character string containing the name of the source file.

pszFileDst

Character string containing the name of the destination file.

uTransform

Binary flags that indicate the transform to be performed. Possible values are:

 

Value

Meaning

 

FILE_TRANSFORM_FLIP

[0x0001] Flip the image.

 

FILE_TRANSFORM_REVERSE

[0x0002] Reverse the image.

 

FILE_TRANSFORM_ROTATE90

[0x0004] Rotate the image clockwise by 90 degrees.

 

FILE_TRANSFORM_ROTATE180

[0x0008] Rotate the image clockwise by 180 degrees.

 

FILE_TRANSFORM_ROTATE270

[0x000C] Rotate the image clockwise by 270 degrees.

 

0

Do nothing.

pfnCallback

Optional callback function for processing custom markers. (This is useful for rotating JPEG files only). When transforming JPEG files, the function will enumerate all the markers contained in the file and it will pass them to this callback. The user has the ability to control the transformation for all the markers. For additional information on JPEG markers, please consult the JPEG specification.

 

If you do not provide a callback function, use NULL as the value of this parameter and no JPEG markers will be transformed.

 

If you do provide a callback function, use the function pointer as the value of this parameter.

 

The callback function must adhere to the function prototype described in TRANSFORMFILECALLBACK Function.

pUserData

Void pointer that you can use to pass one or more additional parameters that the callback function needs.

 

To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID  *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure.

 

If the additional parameters are not needed, you can pass NULL in this parameter.

pLoadOptions

Pointer to optional extended load options. Pass NULL to use the default load options. This is useful only for transforming JPEG TIFF files. The load options will specify the page to transform.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

Only one of the rotate flags can be specified.

The files transformed by this function will be read transformed by other applications capable of reading these file formats.

JPEG and Exif JPEG stamps are transformed according to the flags specified in uTransform. Please note that some JPEG stamps will not be transformed by this function. Specifically, stamps stored in markers other than APP0 and APP1 will not be transformed. Use the TRANSFORMFILECALLBACK function to handle these cases. For example, if a stamp is in the APP14 marker, check for this in the TRANSFORMFILECALLBACK function and write your own stamp using L_WriteFileStamp.

For JPEG files, the size of the image might be changed. The image width and height is adjusted to be a multiple of 8 or 16 depending on the subsampling present in the image. If the image is 4:4:4, the width and height is adjusted to be a multiple of 16. If the image is 422, the original width is adjusted to be a multiple of 16 and the height to be a multiple of 8. After rotation, the width might become height. If the image is 411, the width and height are adjusted to be a multiple of 16.

The transformation is lossless. It is better than loading the image, transforming it using L_RotateBitmap, L_FlipBitmap or L_ReverseBitmap and resaving it. Repeated load and save process will cause image degradation, but calling this function will not cause any image degradation.

The rotation transformations are performed before the flip/reverse operations.

Required DLLs and Libraries

LTFIL

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Windows 2000 / XP/Vista, Windows CE.

See Also

Functions:

L_LoadFile, L_RotateBitmap, L_FlipBitmap, L_ReverseBitmap, L_LoadMarkers

Topics:

Raster Image Functions: Doing Geometric Transformations

 

Raster Image Functions: Processing an Image

Example

/* This example rotates the file by 90 degrees */
 L_INT TransformFileExample(L_VOID)
{
   L_INT nRet;
   nRet = L_TransformFile (TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\WithAudio.JPG"), TEXT("%UserProfile%\\My Documents\\LEADTOOLS Images\\Transformed.JPG"), FILE_TRANSFORM_ROTATE90, NULL, NULL, NULL);
   if(nRet != SUCCESS)
      return nRet;
   return SUCCESS;
}