L_LoadFileCMYKArray

#include "l_bitmap.h"

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

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

Parameters

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

pBITMAPHANDLE* ppBitmapArray

An array of pointers to the bitmaps to be filled with each color plane. There should be at least 4 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 1 (optional), Alpha 2 (optional), etc.

L_UINT uArrayCount

The number of bitmaps present in ppBitmapArray. Pass 4 if the alpha bitmap is not needed, or >= 5 if the alpha bitmaps are needed.

L_UINT uStructSize

The size of each BITMAPHANDLE structure. Pass sizeof(BITMAPHANDLE).

L_INT nBitsPerPixel

The resulting bitmap pixel depth. Possible values are:

L_UINT uFlags

Binary flags that determine the behavior of L_LoadFileCMYKArray. You can specify one or more of the following values:

FILEREADCALLBACK 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.

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.

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

pLOADFILEOPTION 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 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

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
• 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.

#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; 
}