L_StartDithering

#include "l_bitmap.h"

L_INT EXT_FUNCTION L_StartDithering(pBitmap, pPalette, uColors)

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
LPRGBQUAD pPalette;	/* pointer to the palette */
L_UINT uColors;	/* number of colors used in the palette */

Initializes the buffered dithering of a bitmap. The dithering is then carried out by the L_DitherLine function and a function that you supply. It is ended by the L_StopDithering function. (Dithering is the process of using error diffusion to reduce the number of colors in an image.)

Parameter	Description
pBitmap	Pointer to the bitmap handle that has all the information about the input image. The bitmap does not have to exist, but the information must be complete. The DitheringMethod field in the bitmap handle specifies the dithering method to be used for color reduction.
pPalette	Pointer to the palette that the L_DitherLine function will use for dithering. You can specify your own palette, or use NULL for LEAD's fixed palette.
uColors	Number of colors used in the palette. If the palette contains more colors, only the first uColors colors are used. Valid values are 2 to 256.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

The following flow chart shows how the functions relate to each other:

$image\dithbuf.gif$

Before calling this function, the following fields must be specified in the bitmap handle:

$image\sqrblit.gif$ Bitmap.Width

$image\sqrblit.gif$ Bitmap.Height

$image\sqrblit.gif$ Bitmap.BitsPerPixel

$image\sqrblit.gif$ Bitmap.ColorOrder — if BitsPerPixel is greater than 8

$image\sqrblit.gif$ Bitmap.DitheringMethod — if BitsPerPixel is less than 16

Required DLLs and Libraries

LTKRN

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

Windows 95 / 98 / Me, Windows 2000 / XP, Windows CE.

See Also

Functions:	L_ConvertBuffer, L_DitherLine, L_StopDithering
Topics:	Raster Image Functions: Doing Color Expansion or Reduction
	Raster Image Functions: Doing Color Space Conversions

Example

/* This example dithers each line in one bitmap and writes it to another bitmap */
BITMAPHANDLE LeadBitmap;   /* Bitmap handle to hold the loaded image */
void TestFunction(void)
{
   L_UCHAR L_FAR *pInBuf; /* Buffer to hold the input row */
   HGLOBAL hInBuf; /* Handle to the input buffer */
   L_UCHAR L_FAR *pOutBuf; /* Buffer to hold the output row */
   HGLOBAL hOutBuf; /* Handle to the output buffer */
   BITMAPHANDLE TmpBitmap; /* Bitmap containing input data */
   RGBQUAD FixedPalette[256]; /* Fixed palette */
   int i; /* Loop counter */
   /* Load the input bitmap, at 24 bits per pixel */
   L_LoadBitmap (TEXT("IMAGE3.CMP"), &TmpBitmap, sizeof(BITMAPHANDLE), 24, ORDER_BGR, NULL, NULL);
   /* Allocate the input buffer for 24-bit data */
   hInBuf = GlobalAlloc(GMEM_MOVEABLE, TmpBitmap.Width * 3);
   pInBuf = (L_UCHAR L_FAR *)GlobalLock( hInBuf );
   /* Allocate the output buffer for 8-bit data */
   hOutBuf = GlobalAlloc(GMEM_MOVEABLE, TmpBitmap.Width);
   pOutBuf = (L_UCHAR L_FAR *)GlobalLock( hOutBuf );
   /* Get the LEAD fixed palette for an 8-bit image */
   L_GetFixedPalette(FixedPalette, 8);
   /* Create the new bitmap */
   L_CreateBitmap(&LeadBitmap, sizeof(BITMAPHANDLE), TYPE_CONV,
                  TmpBitmap.Width,
                  TmpBitmap.Height,
                  8,           /* 8 bits per pixel */
                  0,          /* Color order is not used */
                  NULL,    /* Use the fixed palette */
                  TmpBitmap.ViewPerspective, NULL, 0);
   /* Set the dithering method */
   TmpBitmap.DitheringMethod = STEVENSON_ARCE_DITHERING;
   /* Initialize the dithering process */
   L_StartDithering(&TmpBitmap, FixedPalette, 256);
   /* Use L_DitherLine to process each row in the bitmap */
   L_AccessBitmap(&LeadBitmap);
   L_AccessBitmap(&TmpBitmap);
   for(i=0; i < TmpBitmap.Height; i++)
   {
      L_GetBitmapRow(&TmpBitmap, pInBuf, i, TmpBitmap.BytesPerLine);
      L_DitherLine(&TmpBitmap, pInBuf, pOutBuf);
      L_PutBitmapRow(&LeadBitmap, pOutBuf, i, LeadBitmap.BytesPerLine);
   }
   L_ReleaseBitmap(&TmpBitmap);
   L_ReleaseBitmap(&LeadBitmap);
   /* End the dithering process */
   L_StopDithering(&TmpBitmap);
   /* Free memory that we no longer need */
   GlobalFree(hInBuf);
   GlobalFree(hOutBuf);
   return;
}