DragonFly On-Line Manual Pages

DITHER(3)             DragonFly Library Functions Manual             DITHER(3)

NAME
       dithermap, bwdithermap, make_square, dithergb, ditherbw - functions for
              dithering color or black and white images.

SYNOPSIS
       dithermap( levels, gamma, rgbmap, divN, modN, magic )
       int levels;
       double gamma;
       int rgbmap[][3], divN[256], modN[256], magic[16][16];

       bwdithermap( levels, gamma, bwmap, divN, modN, magic )
       int levels;
       double gamma;
       int bwmap[], int divN[256], modN[256], magic[16][16];

       make_square( N, divN, modN, magic )
       double N;
       int divN[256], modN[256], magic[16][16];

       dithergb( x, y, r, g, b, levels, divN, modN, magic )
       int x, y, r, g, b, levels;
       int divN[256], modN[256], magic[16][16];

       ditherbw( x, y, val, divN, modN, magic )
       int x, y, val, divN[256], modN[256], magic[16][16];

DESCRIPTION
       These functions provide a common set of routines for dithering a full
       color or gray scale image into a lower resolution color map.

       Dithermap computes a color map and some auxiliary parameters for
       dithering a full color (24 bit) image to fewer bits.  The argument
       levels tells how many different intensity levels per primary color
       should be computed.  To get maximum use of a 256 entry color map, use
       levels=6.  The computed map uses levels^3 entries.  The gamma argument
       provides for gamma compensation of the generated color map (that is,
       the values in the map will be adjusted to give a linear intensity
       variation on a display with the given gamma).  The computed color map
       will be returned in the array rgbmap.  divN and modN are auxiliary
       arrays for computing the dithering pattern (see below), and magic is
       the magic square dither pattern.

       To compute a color map for dithering a black and white image to fewer
       intensity levels, use bwdithermap.  The arguments are as for dithermap,
       but only a single channel color map is computed.  The value of levels
       can be larger than for dithermap, as the computed map only has levels
       entries.

       To just build the magic square and other parameters, use make_square.
       The argument N should be equal to 255.0 divided by the desired number
       of intensity levels less one (i.e., N = 255.0 / (levels - 1)).  The
       other arguments are filled in as above.

       The color map index for a dithered full color pixel is computed by
       dithergb.  Since the pattern depends on the screen location, the first
       two arguments x and y, specify that location.  The true color of the
       pixel at that location is given by the triple r, g, and b.  The number
       of intensity levels and the dithering parameter matrices computed by
       dithermap are also passed to dithergb.

       The color map index for a dithered gray scale pixel is computed by
       ditherbw.  Again, the screen position is specified, and the intensity
       value of the pixel is supplied in val.  The dithering parameters must
       also be supplied.

       Alternatively, the dithering may be done in line instead of incurring
       the extra overhead of a function call, which can be significant when
       repeated a million times.  The computation is as follows:
                 row = y % 16;
                 col = x % 16;
            #define DMAP(v,col,row) (divN[v] + (modN[v]>magic[col][row] ? 1 : 0))
                 pix = DMAP(r,col,row) + DMAP(g,col,row)*levels +
                      DMAP(b,col,row)*levels*levels;
       For a gray scale image, it is a little simpler:
                 pix = DMAP(val,row,col);
       And on a single bit display (assuming a 1 means white):
                 pix = divN[val] > magic[col][row] ? 1 : 0

SEE ALSO
       rgb_to_bw(3), librle(3), RLE(5).

AUTHOR
       Spencer W. Thomas
       University of Utah

4th Berkeley Distribution           2/2/87                           DITHER(3)