LFile::LoadCMYKArray

Summary

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

Syntax

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

Parameters

pBITMAPHANDLE *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).

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

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 LFile::LoadCMYKArray. You can specify one or more of the following values:

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

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

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