LFile::LoadCMYKArray

#include "ltwrappr.h"

L_INT LFile::LoadCMYKArray(ppBitmapArray, uBitmapArrayCount, uStructSize, nBitsPerPixel, uFlags, pLoadFileOption, pFileInfo)

pBITMAPHANDLE *ppBitmapArray;	/* array of pointers to BITMAPHANDLE handles */
L_UINT uBitmapArrayCount;	/* number of items in the bitmap array */
L_UINT uStructSize;	/* size in bytes, of each BITMAPHANDLE structure */
L_INT nBitsPerPixel;	/* desired number of bits per pixel for each plane */
L_UINT uFlags;	/* flags that determine the function behavior */
pLOADFILEOPTION pLoadFileOption;	/* pointer to optional extended load options */
pFILEINFO pFileInfo;	/* pointer to a FILEINFO structure */

Loads CMYK TIFF files as CMYK and avoids the color space conversion to RGB.

Parameter	Description
ppBitmapArray	An array of pointers to the bitmaps to be filled with each color plane. There should be 4 or 5 members in the array, depending on whether the alpha channel information needs to be loaded. The uBitmapArrayCount parameter indicates how many pointers are stored in the array. The bitmaps are in this order: C, M, Y, K, Alpha (optional).
uBitmapArrayCount	The number of bitmaps present in ppBitmapArray. Pass 4 if the alpha bitmap is not needed, or 5 if the alpha bitmap is needed.
uStructSize	The size of each BITMAPHANDLE structure. Pass sizeof(BITMAPHANDLE).
nBitsPerPixel	The resulting bitmap pixel depth. Possible values are:
	Value	Meaning
	8	Each plane will be a grayscale 8 bits per pixel bitmap
	16	Each plane will be a grayscale 16 bits per pixel bitmap
uFlags	Binary flags that determine the behavior of LFile::LoadCMYKArray. You can specify one or more of the following values:
	Value	Meaning
	LOADFILE_ALLOCATE	[0x0001] The function allocates memory for the specified bitmap. (This takes place in addition to the actions of the callback function.)
	LOADFILE_STORE	[0x0002] The function loads data into the specified bitmap. (This takes place in addition to the actions of the callback function.)
	LOADFILE_NOINITBITMAP	[0x0020] The function does not initialize the bitmap handle when it loads the file. Use this flag only if you are supplying all of the required information in the BITMAPHANDLE structure.
	LOADFILE_SUPERCOMPRESSED	[0x0080] (Document/Medical only) Load 8-bit images as super compressed. This flag is ignored if the bitmaps are loaded as 16-bit.
pLoadFileOption	Pointer to optional extended load options. It can be used to specify the start page, IFD, etc. Pass NULL to use the default load options.
pFileInfo	Pointer to a FILEINFO structure. This structure may contain file information used in loading an image, or it may be updated with information about the file being loaded.
	If nothing is known about the file, pass NULL for this parameter, or declare a variable of type FILEINFO and set the FILEINFO.Flags to 0, then pass the address of the FILEINFO structure in this parameter. In this case, if the address of a FILEINFO structure is passed, the FILEINFO structure will be updated with the results of LFile::GetInfo.
	If only the file type is known, set pFileInfo.Format to the file type and set pFileInfo.Flags to FILEINFO_FORMATVALID. This can also be done if LFile::GetInfo has been called previously, but values that affect the size of the image loaded have been changed (for example, by calling LFileSettings::SetPCDResolution or LFileSettings::SetWMFResolution). In this case the FILEINFO structure pointed to by pFileInfo will be updated with the results of LFile::GetInfo.
	If LFile::GetInfohas been called prior to calling this function, and no changes have been made to the contents of the structure filled by LFile::GetInfo, then the address of the filled FILEINFO structure can be passed for this parameter. In this case, the FILEINFO.Flags member should be set to FILEINFO_INFOVALID. The LFile::GetInfo function will set the FILEINFO.Flags to FILEINFO_INFOVALID. In this case the load will be faster since this function does not have to query the file filters for the file type.
	Note: Local variables are not initialized, since they are placed on the stack. Therefore, if the FILEINFO structure is a local variable, the value of its Flags parameter is undefined, and may actually have FILEINFO_INFOVALID or FILEINFO_FORMATVALID set. That is why it is important to initialize FILEINFO.Flags before passing the address of the FILEINFO structure to the function.

Returns

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

Comments

If the data does not have to be loaded as CMYK, use the regular load functions LFile::Load, LMemoryFile::Load, LFile::LoadResize, LFile::LoadFile, LFile::LoadOffset, LMemoryFile::LoadMemory, or LMemoryFile::LoadMemoryTile.

Support for 16-bit grayscale images is only available in the Document/Medical Imaging editions.

The following members of LOADFILEOPTION are important for this function:

PageNumber: specifies the start page. Page 0 is the first page, page 1 is the second page, etc. The pages will be read starting with this page.
Flags: specifies whether to use the IFD.
IFD: used only if Flags contains the ELO_USEIFD flag set.

This function will fail if the input file is not TIFF CMYK. However, not all pages in the file have to be CMYK, as long as the page to be loaded is CMYK.

Use LPaint::PaintDCCMYKArray to display the array and LFile::SaveCMYKArray to save this array as a CMYK TIFF file.

Note that if you pass 5 bitmaps to LFile::LoadCMYKArray and the file does not have alpha information, the 5th bitmap in the array will not be allocated.

To convert the CMYK array to a regular BGR bitmap and use the other functions, or to save to a file format other than TIFF CMYK, use LBitmap::ColorMerge and pass COLORSEP_CMYK for the uFlags parameter. If alpha information is included, use LBitmapBase::SetAlpha to set the alpha bitmap.

Image processing can be performed on each individual bitmap in the array, thereby processing each color plane separately.

To load a non-CMYK file as an array of color planes, use LFile::Load, LMemoryFile::Load, LFile::LoadResize, LFile::LoadFile, LFile::LoadOffset, LMemoryFile::LoadMemory, or LMemoryFile::LoadMemoryTile and then call LBitmap::ColorSeparate and LBitmapBase::CreateAlphaBitmap.

Note: You should never pass an uninitialized FILEINFO structure to this function.

Required DLLs and Libraries

LTFIL

LFTIF

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

Win32, x64.

See Also

Functions:	LPaint::PaintDCCMYKArray, LFile::SaveCMYKArray, LFile::LoadFile, LBaseFile::GetDefaultLoadFileOption, LBitmap::ColorMerge, LBitmap::ColorSeparate, LBitmapBase::CreateAlphaBitmap, LBitmapBase::SetAlpha, LFileSettings::SetWMFResolution
Topics:	Handling CMYK Files as Separate Bitmaps
	Loading and Saving Images
	Raster Image Functions: Loading Files

Example

This example will load all CMYK TIFF file, increase the brightness of the K plane only (which will darken the image) and save the file as CMYK TIFF.

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName
L_INT LFile__LoadCMYKArrayExample() 
{
   L_INT nRet;
   FILEINFO FileInfo;
   LFile file, fileRes ;
   L_UINT u;
   LBitmap CMYKBitmapsArray[4];
   pBITMAPHANDLE CMYKHandlesArray[4] = {CMYKBitmapsArray[0].GetHandle(), CMYKBitmapsArray[1].GetHandle(),CMYKBitmapsArray[2].GetHandle(), CMYKBitmapsArray[3].GetHandle()};
   file.SetFileName(MAKE_IMAGE_PATH(TEXT("ET\\src_cmyk_image.tif"))) ;
   memset(&FileInfo, 0,sizeof(FileInfo)) ;
   nRet = file.GetInfo(&FileInfo, sizeof(FileInfo), 0, NULL);
   if(nRet != SUCCESS)
   {
      MessageBox(NULL, TEXT("Invalid source file"), TEXT("Error"), MB_OK);
      return nRet;
   }
   nRet = file.LoadCMYKArray(CMYKHandlesArray, 4, sizeof(BITMAPHANDLE), 8, LOADFILE_ALLOCATE|LOADFILE_STORE, NULL, NULL/*&FileInfo*/);
   if(nRet != SUCCESS)
   {
      MessageBox(NULL, TEXT("LoadCMYKArray failed!"), TEXT("Error"), MB_OK);
      return nRet;
   }
   /* The load has succeeded. 
   Increase the brightness of the K (black) plane by 50%
   Note that this will DARKEN the image, because we increased the amount of black! */
   nRet = CMYKBitmapsArray[3].ChangeIntensity(500);
   if(nRet != SUCCESS)
   {
      MessageBox(NULL, TEXT("ChangeIntensity failed!"), TEXT("Error"), MB_OK);
      return nRet;
   }
   else
   {
      fileRes.SetFileName(MAKE_IMAGE_PATH(TEXT("myCMYK.tif"))) ;
      nRet = fileRes.SaveCMYKArray(CMYKHandlesArray, 4, FILE_TIFLZW_CMYK, 8, 2, 0, NULL);
      if(nRet != SUCCESS)
      {
         MessageBox(NULL, TEXT("SaveCMYKArray failed!"), TEXT("Error"), MB_OK);
         return nRet;
      }
   }
   // free the CMYK array allocated by LoadCMYKArray
   for(u = 0; u < 4; u++)
   {
      L_TCHAR s[_MAX_PATH];
      wsprintf(s, MAKE_IMAGE_PATH(TEXT("plane%d.tif")), u);
      nRet = CMYKBitmapsArray[u].Save(s, FILE_TIF, 0, 2, 0,NULL);
      nRet = CMYKBitmapsArray[u].Free();
   }
   MessageBox(NULL, TEXT("Done"), NULL, MB_OK) ;
   return SUCCESS;
}