L_SaveFileCMYKArray

Summary

This function saves an array of bitmaps as a CMYK TIFF file.

Syntax

#include "l_bitmap.h"

L_LTFIL_API L_INT L_SaveFileCMYKArray (pszFile, ppBitmapArray, uBitmapArrayCount, nFormat, nBitsPerPixel, nQFactor, uFlags, pfnCallback, pUserData, pSaveOptions);

Parameters

L_TCHAR* pszFile

Character string containing the name of the image file to save.

pBITMAPHANDLE* ppBitmapArray

Array of pointers to the bitmaps that contain each color plane. There should be 4 or 5 members in the array, depending on whether there is alpha channel information to save.

All the bitmaps must have the same width, height, bits per pixel and palette. uBitmapArrayCount indicates how many pointers are stored in the array. The bitmaps are in this order: C, M, Y, K, Alpha (optional).

L_UINT uBitmapArrayCount

Number of bitmaps present in ppBitmapArray.

L_INT nFormat

Output file format. Possible values are:

Value	Meaning
FILE_TIF_CMYK	[85] Tagged Image File, with no compression and with CMYK color space.
FILE_TIF_PACKBITS_CMYK	[88] Tagged Image File with PackBits Compression and CMYK color space.
FILE_TIFLZW_CMYK	[86] Tagged Image File with LZW Compression and CMYK color space.
FILE_JPEG_CMYK	[391] JPEG file with CMYK color space and 4:4:4 subsampling.
FILE_JPEG_CMYK_411	[392] JPEG file with CMYK color space and 4:1:1 subsampling.
FILE_JPEG_CMYK_422	[393] JPEG file with CMYK color space and 4:2:2 subsampling.
FILE_TIF_JPEG_CMYK	[394] Tagged Image File with JPEG Compression, CMYK color space and 4:4:4 subsampling.
FILE_TIF_JPEG_CMYK_411	[395] Tagged Image File with JPEG Compression, CMYK color space and 4:1:1 subsampling.
FILE_TIF_JPEG_CMYK_422	[396] Tagged Image File with JPEG Compression, CMYK color space and 4:2:2 subsampling.

L_INT nBitsPerPixel

Resulting bits per pixel for each plane. Possible values are:

Value	Meaning
0	Default bits per pixel. LEADTOOLS will pick the closest valid value.
8	Save 8 bits per component. The generated file will contain 32 bits (no alpha) or 40 bits (with alpha). Note that L_FileInfo will report 8 bits less (24 or 32-bit).
16	Save 16 bits per component. The generated file will contain 64 bits (no alpha) or 80 bits (with alpha). Note that L_FileInfo will report 16 bits less (48 or 64-bit).

L_INT nQFactor

Reserved for future use. This parameter is ignored at the moment.

L_UINT uFlags

Binary flags that determine the behavior of L_SaveFileCMYKArray. You can specify one of the following values:

Value	Meaning
0	[0x0000] If the output file exists, it will be overwritten.
SAVEFILE_MULTIPAGE	[0x0004] If the output file exists and is a valid TIFF file, the new image is appended to the end of the file. More advanced options can be passed using `pSaveOptions`.

FILESAVECALLBACK pfnCallback

Optional callback function for additional processing.

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

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

The callback function must adhere to the syntax described in FILESAVECALLBACK Function.

L_VOID* 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.

pSAVEFILEOPTION pSaveOptions

Pointer to optional extended save options. Pass NULL to use the default save options.

Returns

Value	Meaning
SUCCESS	The function was successful.
ERROR_INV_COLORSPACE	Invalid color space.
< 1	An error occurred. Refer to Return Codes.

Comments

This function will save a CMYK file without performing a color conversion. Each bitmap in the array will contain one of the C, M, Y, K, or Alpha planes. The Alpha plane is optional. The ppBitmapArray should contain:

4 elements if no Alpha information is included or
5 elements if the Alpha information is included (this is not available when saving files with JPEG compression)

To load the array of bitmaps, use L_LoadFileCMYKArray.

To save the array of bitmaps as a file format not supported by this function, create a BGR bitmap and save the generated bitmap using L_SaveFile. You can create the BGR bitmap using L_ColorMergeBitmap or L_ClrConvertCMYKArray.

CMYK TIFF files can be saved as planar (each bitmap in its own plane) or chunky (the data from all the bitmaps is interleaved while saving). Planar images will be saved faster, while chunky images are more compatible (some TIFF readers will not read planar files) and require less memory during the load process. The default is to save chunky files.

To select the planar save mode, set SAVEFILEOPTION.Flags2 to ESO2_SAVEPLANAR [0x00000002]. Note that this option is set in the Flags2 member, not the Flags member (the SAVEFILEOPTION structure has two flag members: Flags and Flags2).

You can convert one file format to another when you save a file. You can also use the high-level function, L_FileConvert, to convert any possible format to any other possible format.

To save a region inside a TIFF file, you must have an unlocked Document, Vector, or Medical Imaging license.