L_LoadFileCMYKArray

#include "l_bitmap.h"

L_LTFIL_API L_INT L_LoadFileCMYKArray(pszFile, ppBitmapArray, uArrayCount, uStructSize, nBitsPerPixel, uFlags, pfnCallback, pUserData, pLoadFileOption, pFileInfo);

L_TCHAR* pszFile;	name of the file to load
pBITMAPHANDLE* ppBitmapArray;	array of pointers to BITMAPHANDLE handles
L_UINT uArrayCount;	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
FILEREADCALLBACK pfnCallback;	optional callback function
L_VOID * pUserData;	pointer to more parameters for the callback
pLOADFILEOPTION pLoadFileOption;	pointer to optional extended load options
pFILEINFO pFileInfo;	pointer to a FILEINFO structure

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

Parameter	Description
pszFile	Character string that contains the name of the file to load. The file must be CMYK, otherwise the function will fail and return the ERROR_INV_COLORSPACE error code.
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. uArrayCount indicates how many pointers are stored in the array. The bitmaps are in this order: C, M, Y, K, Alpha (optional).
uArrayCount	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 L_LoadFileCMYKArray. 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 and Medical Imaging toolkits) Load 8-bit images as super compressed. This flag is ignored if the bitmaps are loaded as 16-bit.
	LOADFILE_MULTITHREADED	[0x2000] Use Multithreaded load
pfnCallback	Optional callback function for additional processing. This function will be called while the bitmap planes are loaded. It will be called for each plane and each row.
	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 function prototype described in FILEREADCALLBACK 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.
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 L_FileInfo.
	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 L_FileInfo has been called previously, but values that affect the size of the image loaded have been changed (for example, by calling L_SetPCDResolution or L_SetWMFResolution). In this case the FILEINFO structure pointed to by pFileInfo will be updated with the results of L_FileInfo.
	If L_FileInfo has been called prior to calling this function, and no changes have been made to the contents of the structure filled by L_FileInfo, 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 L_FileInfo 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 CodesReturns.

Comments

If the data does not have to be loaded as CMYK, use the regular load functions L_LoadBitmap, L_LoadBitmapMemory, L_LoadBitmapResize, L_LoadFile, L_LoadFileOffset, or L_LoadMemory.

Support for 16-bit grayscale images is only available in the Document and 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 or JPEG CMYK. However, not all pages in the file have to be CMYK, as long as the page to be loaded is CMYK.

Use L_PaintDCCMYKArray to display the array and L_SaveFileCMYKArray to save this array as a CMYK TIFF file.

Note that if you pass 5 bitmaps to L_LoadFileCMYKArray 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 or JPEG CMYK, use L_ColorMergeBitmap and pass COLORSEP_CMYK for uFlags parameter. If alpha information is included, use L_SetBitmapAlpha 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 L_LoadBitmap, L_LoadBitmapMemory, L_LoadBitmapResize, L_LoadFile, L_LoadFileOffset, or L_LoadMemory and then call L_ColorSeparateBitmap and L_GetBitmapAlpha.

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, Linux.

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 
#define CMYK_FILE MAKE_IMAGE_PATH(TEXT("ET\\src_cmyk_image.tif")) 
L_INT LoadFileCMYKArrayExample(HWND hWnd) 
{ 
   L_INT    nRet; 
   FILEINFO FileInfo; 
   BITMAPHANDLE   BitmapC, BitmapM, BitmapY, BitmapK; 
   pBITMAPHANDLE  CMYKArray[4] = {&BitmapC, &BitmapM, &BitmapY, &BitmapK}; 
   L_UINT   u; 
   memset(&FileInfo, 0, sizeof(FILEINFO)); 
   FileInfo.uStructSize = sizeof(FILEINFO); 
   nRet = L_FileInfo(CMYK_FILE, &FileInfo, sizeof(FILEINFO), 0, NULL); 
   if(nRet != SUCCESS) 
   { 
      MessageBox(hWnd, TEXT("Invalid source file"),TEXT( "Error"), MB_OK); 
      return nRet; 
   } 
   nRet = L_LoadFileCMYKArray(CMYK_FILE, CMYKArray, 4, sizeof(BITMAPHANDLE), 8, 
   LOADFILE_ALLOCATE|LOADFILE_STORE, NULL, NULL, NULL, &FileInfo); 
   if(nRet != SUCCESS) 
   { 
      MessageBox(hWnd, TEXT("L_LoadFileCMYKArray 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 = L_ChangeBitmapIntensity(CMYKArray[3], 500, 0); 
   if(nRet != SUCCESS) 
   { 
      MessageBox(hWnd, TEXT("L_ChangeBitmapIntensity failed!"),TEXT( "Error"), MB_OK); 
      return nRet; 
   } 
   else 
   { 
      nRet = L_SaveFileCMYKArray (MAKE_IMAGE_PATH(TEXT("myCMYK.tif")), CMYKArray, 4, FILE_TIFLZW_CMYK, 8, 2, 0, NULL, NULL, NULL); 
      if(nRet != SUCCESS) 
      { 
         MessageBox(hWnd, TEXT("L_LoadFileCMYKArray failed!"),TEXT("Error"), MB_OK); 
         return nRet; 
      } 
   } 
   // free the CMYK array allocated by L_LoadFileCMYKArray 
   for(u = 0; u < 4; u++) 
   { 
      L_TCHAR s[_MAX_PATH]; 
      wsprintf(s, MAKE_IMAGE_PATH(TEXT("plane%d.tif")), u); 
      nRet = L_SaveBitmap(s, CMYKArray[u], FILE_TIF, 0, 0, NULL); 
      if(nRet != SUCCESS) 
         return nRet; 
      L_FreeBitmap(CMYKArray[u]); 
   } 
   SetWindowText(hWnd, TEXT("Done")); 
   return SUCCESS; 
}

Help Version 19.0.2017.10.27

Functions:	L_PaintDCCMYKArray, L_SaveFileCMYKArray, L_LoadFile, L_GetDefaultLoadFileOption, L_ColorMergeBitmap, L_ColorSeparateBitmap, L_GetBitmapAlpha, L_SetBitmapAlpha.
Topics:	Handling CMYK Files as Separate Bitmaps
	Loading and Saving Images
	Raster Image Functions: Loading Files