mlib_ImageColorDitherInit(3MLIB)			    mediaLib Library Functions				  mlib_ImageColorDitherInit(3MLIB)

NAME

       mlib_ImageColorDitherInit - initialization for image dithering

SYNOPSIS

       cc [ flag... ] file... -lmlib [ library... ]
       #include <mlib.h>

       mlib_status  mlib_ImageColorDitherInit(void **colormap, const mlib_s32 *dimensions, mlib_type intype, mlib_type outtype, mlib_s32 channels,
       mlib_s32 entries, mlib_s32 offset, void **lut);

DESCRIPTION

       The mlib_ImageColorDitherInit() function creates an internal data structure, colormap, which can be used by one of the following  functions
       for image dithering:

       mlib_ImageColorErrorDiffusion3x3
       mlib_ImageColorErrorDiffusionMxN
       mlib_ImageColorOrderedDither8x8
       mlib_ImageColorOrderedDitherMxN

       The lut might have either 1 or 3 channels. The type of the lut can be one of the following:

       MLIB_BYTE in, MLIB_BYTE out (i.e., BYTE-to-BYTE)
       MLIB_BIT in, MLIB_BYTE out (i.e., BIT-to-BYTE)

       If dimensions == NULL, then no colorcube will be created. In this case, the user-provided lookup table, lut, will be used for dithering.

       If dimensions != NULL, then a colorcube is created from scratch in a way shown in the following example.

       To dither an RGB image of type MLIB_BYTE to a color-indexed image of type MLIB_BYTE, we can use the following parameters:

       mlib_s32  dimensions[] = {2, 3, 4};
       mlib_type intype = MLIB_BYTE;
       mlib_type outtype = MLIB_BYTE;
       mlib_s32  channels = 3;
       mlib_s32  offset = 6;

       These  values would lead to the creation of a colorcube that would dither red values in the source image to one of 2 red levels, green val-
       ues to one of 3 green levels, and blue values to one of 4 blue levels.  You could picture this colorcube as a cube with dimensions of 2, 3,
       and 4.  The index values assigned to the elements in that cube can be described by the following lookup table:

       Indexes		Red Values	Green Values	 Blue Values
       0
       ...
       5
       6		0		0		 0
       7		255		0		 0
       8		0		128		 0
       9		255		128		 0
       10		0		255		 0
       11		255		255		 0
       12		0		0		 85
       13		255		0		 85
       14		0		128		 85
       15		255		128		 85
       16		0		255		 85
       17		255		255		 85
       18		0		0		 170

       19		255		0		 170
       20		0		128		 170
       21		255		128		 170
       22		0		255		 170
       23		255		255		 170
       24		0		0		 255
       25		255		0		 255
       26		0		128		 255
       27		255		128		 255
       28		0		255		 255
       29		255		255		 255
       ...

       The distance between level changes in each channel of the lookup table is determined by the following formulas:

       multipliers[0] = signof(dimensions[0])*1;
       multipliers[i] = signof(dimensions[i])*
			abs(multipliers[i-1]*dimension[i-1]);

       A  negative  dimensions[i],  so	as  to a negative multipliers[i], indicates that the values in a color ramp for channel i should appear in
       decreasing as opposed to increasing order.

       For each channel i, the values of the levels are determined by the following formulas:

       double delta = (dataMax - dataMin)/(abs(dimensions[i]) - 1);
       int levels[j] = (int)(j*delta + 0.5);

       where dataMax and dataMin are the maximum and minimum values, respectively, for data type intype.

       Whenever a colorcube is created, if lut != NULL, the lookup table will be filled according to the colorcube and	supplied  parameters  like
       offset.	 For  the example shown above, the lookup table will start from line 6.  In this case, it is the user's responsibility to allocate
       memory for the lookup table.

PARAMETERS

       The function takes the following arguments:

       colormap        Internal data structure for image dithering.

       dimensions	Dimensions of the colorcube in the colormap structure.

       intype	       Data type of the source image and the lookup table.

       outtype	       Data type of the destination indexed image.

       channels        Number of channels of the lookup table and source image.

       entries	       Number of entries of the lookup table.

       offset	       Index offset of the lookup table.

       lut	       Lookup table.

RETURN VALUES

       The function returns MLIB_SUCCESS if successful. Otherwise it returns MLIB_FAILURE.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       mlib_ImageColorDitherFree(3MLIB), mlib_ImageColorErrorDiffusion3x3(3MLIB), mlib_ImageColorErrorDiffusionMxN(3MLIB), mlib_ImageColorOrdered-
       Dither8x8(3MLIB), mlib_ImageColorOrderedDitherMxN(3MLIB), attributes(5)

SunOS 5.10							    10 Nov 2004 				  mlib_ImageColorDitherInit(3MLIB)