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).

      Spencer W. Thomas
      University of Utah















































9