NAME

       ascmap - defines main structures and function for image quantization libAfterImage/ascmap.h

NAMEascmap

       - Defines main structures and function for image quantization.

DESCRIPTION

       Image  quantization  is  needed  primarily  in order to be able to export images into file, with colormap
       format, such as GIF and XPM.  libAfterImage attempts to allocate colorcells to the most used colors,  and
       then approximate remaining colors with the closest colorcell.

       Since  quality  of  quantization  is  in  reverse  proportion  to the number of colors in original image,
       libAfterImage allows one to set arbitrary level of downsampling of the color spectrum in the range  of  8
       bit  per  channel  to 1 bit per channel. Downsampling is performed by simple dropping of less significant
       bits off of color values.

       In order to be able to determine closeness of colors, 3-channel RGB values are converted into flat  24bit
       (or  less  if downsampling is used) index. That is done by intermixing bits from different channels, like
       so : R8G8B8R7G7B7...R1G1B1. That flat index is used to arrange colors in ascending order, and later on to
       be able to find closest mapped color. Simple hashing technique is used to speed up the sorting/searching,
       as it allows one to limit linked lists traversals.

SEE ALSO

       Structures :
                ASColormapEntry
                ASColormap

       Functions :
                colormap_asimage(), destroy_colormap()

       Other libAfterImage modules :
                ascmap.h asfont.h asimage.h asvisual.h blender.h export.h
                import.h transform.h ximage.h

AUTHOR

       Sasha Vasko <sasha at aftercode dot net>
       libAfterImage/ASColormapEntry

NAMEASColormapEntry

       - ASColormapEntry represents single colorcell in the colormap.

SOURCE

           typedef struct ASColormapEntry {
               CARD8 red, green, blue; }ASColormapEntry;

       libAfterImage/ASColormap

NAMEASColormap

       - ASColormap represents entire colormap generated for the image.

SOURCE

           typedef struct ASColormap {
               ASColormapEntry *entries ;  /* array of colorcells */
               unsigned int count ;        /* number of used colorcells */
               ASSortedColorHash *hash ;   /* internal data */
               Bool has_opaque ;           /* If True then Image has opaque pixels */ }ASColormap;

       libAfterImage/colormap_asimage()

NAMEcolormap_asimage()

SYNOPSIS

       int *colormap_asimage( ASImage *im, ASColormap *cmap,
                              unsigned int max_colors, unsigned int dither,
                              int opaque_threshold );

INPUTS

       im     - pointer to valid ASImage structure.

       cmap   - preallocated structure to store colormap in.

       max_colors
              - maximum size of the colormap.

       dither - number of bits to strip off the color data ( 0...7 )

       opaque_threshold
              - alpha channel threshold at which pixel should be treated as opaque

RETURN VALUE

       pointer to the array of indexes representing pixel's colorcells. This  array  has  size  of  WIDTHxHEIGHT
       where WIDTH and HEIGHT are size of the source image.

DESCRIPTION

       This function is all that is needed to quantize the ASImage. In order to obtain colorcell of the pixel at
       (x,y) from result, the following code could be used : cmap->entries[res[y*width+x]] where res is returned
       pointer.  Recommended value for dither parameter is 4 while quantizing photos to 256 colors, and it could
       be less , if original has limited number of colors.
       libAfterImage/destroy_colormap()

NAMEdestroy_colormap()

SYNOPSIS

       void destroy_colormap( ASColormap *cmap, Bool reusable );

INPUTS

       cmap   - pointer to valid ASColormap structure.

       reusable
              - if True, then the memory pointed to by cmap will not be deallocated, as if it was  allocated  on
              stack

DESCRIPTION

       Destroys ASColormap object created using colormap_asimage.