Controlling Progressive Loads and Saves

The LEAD and JPEG (JFIF) file formats can be extended to support progressive loading and saving of images. Progressive loading is useful for transmitting images, because the first part of the file contains the full dimensions of the image. Therefore, in a paint-while-load routine, you can display the whole image, then progressively clarify it as the rest of the file loads.

Since the progressive formats are newer, some existing applications do not support them. Therefore, especially when saving a file that may be read by another application, you must pay attention to the Passes field in the SAVEFILEOPTION structure.

To avoid saving a progressive file (to save an ordinary LEAD or JPEG file) use the SAVEFILEOPTION structure to set the number of passes to 0 before calling the function that saves the file.

Technically, only files with more than three passes are progressive files. They include full color in the low-resolution first pass; subsequent passes improve the resolution. Files that contain two or three passes are multiscan files. They include grayscale information in the first pass, and color information in the subsequent pass or passes.

If you want to save a progressive file or take advantage of this feature when loading a progressive file, you can control the number of passes that are required to complete the image. For more information, refer to the Passes field in the SAVEFILEOPTION structure.

JBIG also supports progressive loading of an image. For more information on this, refer to Implementing JBIG Features.

JPEG 2000 also supports progressive loading of images. For more information on this, refer to Implementing JPEG 2000 Plug in Features.

The following example shows how to save a progressive LEAD then implement a progressive paint-while-load:

/*******************************************************************************************
This example uses L_LoadFile with a callback function to implement a progressive
paint-while-load feature. Refer to the FILEREADCALLBACK
function to see how the callback function paints the image data.

The sample code uses the following global declarations: */

HINSTANCE hInst;   /* Current instance of the application, set by the InitInstance function */
RECT rClientSize;          /* RECT for the client area */
RECT rLeadDest;            /* Destination rectangle for painting */     
RECT rLeadSource;          /* Source rectangle for painting */  
BITMAPHANDLE LeadBitmap;   /* Bitmap handle to hold the loaded image */
FILEINFO FileInfo;         /* LEAD File Information structure. */

/* Structure used for the callback function's user data */
typedef struct tagIMAGECBPARM
{
   HWND hwnd;     /* Current window */
   HDC hdc;       /* Device context for the current window */
} IMAGECBPARM;

/* Prototype for the FILEREADCALLBACK function */
L_INT L_EXPORT EXT_CALLBACK LoadImageCB(pFILEINFO pFileInfo, pBITMAPHANDLE pBitmap, 
             L_UCHAR L_FAR *pBuffer,
             L_UINT uFlags, L_INT nRow, L_INT nLines, IMAGECBPARM L_FAR* pUserData );
/*********************************************************************************************/

void TestLoad(L_TCHAR L_FAR * pszFilename, HWND hWnd)
{
   static IMAGECBPARM UserData; /* Structure used for the callback function's user data */
   LOADFILEOPTION LoadFileOption;  /* Structure for progressive options */
   SAVEFILEOPTION SaveFileOption;  /* Structure for progressive options */
   FILEREADCALLBACK lpfnCallBack;

   /* Load a bitmap */
   L_LoadBitmap(pszFilename, &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL);

   /* Get the current EXTFILEOPTION values and save the current Passes value */
   L_GetDefaultLoadFileOption(&LoadFileOption, sizeof(LOADFILEOPTION));
   L_GetDefaultSaveFileOption(&SaveFileOption, sizeof(SAVEFILEOPTION));

   /* Set the number of passes for a progressive LEAD file */
   SaveFileOption.Passes = 8;

   /* Save the file */
   L_SaveBitmap(TEXT("E:\\LEAD Technologies, Inc\\LEADTOOLS\\images\\TEST.CMP"), &LeadBitmap, FILE_CMP, 24, PQ2, &SaveFileOption);

   /* Set the number of callback passes for loading a progressive LEAD file */
   LoadFileOption.Passes = CALLBACK_WHEN_MEANINGFUL;

   /* Get the client area of the window. We assume that elsewhere in the program, the
   L_FileInfo function has been used to update the FileInfo structure and that the
   window dimensions have been adjusted to the bitmap's aspect ratio. */
   GetClientRect(hWnd,&rClientSize);

   /* Make the destination rectangle for painting the same as the client area */
   rLeadDest = rClientSize;

   /* Initialize the bitmap handle */
   L_InitBitmap( &LeadBitmap, sizeof(BITMAPHANDLE), FileInfo.Width, FileInfo.Height, FileInfo.BitsPerPixel );
   LeadBitmap.ViewPerspective = FileInfo.ViewPerspective;

   /* Set the user data used for the callback in the L_LoadFile function */
   UserData.hwnd = hWnd;         /* Current window */
   UserData.hdc = GetDC( hWnd ); /* Device context for the current window */

   /* Set the callback function for the L_LoadFile function.*/
   lpfnCallBack = (FILEREADCALLBACK) MakeProcInstance(
      (FARPROC) LoadImageCB, hInst );

   /* Load the file, calling lpfnCallBack to paint the bitmap. */
   L_LoadFile(TEXT("E:\\LEAD Technologies, Inc\\LEADTOOLS\\TEST.CMP"),
               &LeadBitmap, sizeof(BITMAPHANDLE),
               0,
               ORDER_BGR,
               LOADFILE_ALLOCATE |  LOADFILE_STORE,
               lpfnCallBack,
               &UserData,
               &LoadFileOption);
   FreeProcInstance ((FARPROC) lpfnCallBack);
   /* Avoid an unnecessary repaint */
   ValidateRect(hWnd, &rLeadDest);

   return;
}