doc/filters_dithering.txt

   1 Dithering
   2 ---------
   3
   4 Currently there are two dithering algorithms implemented. Both takes an RGB888
   5 24bit image as input and are able to produce any RGB or Grayscale image.
   6 This filters doesn't work 'in-place' as the result has different pixel type.
   7
   8 Floyd-Steinberg
   9 ~~~~~~~~~~~~~~~
  10
  11 Classical Floyd-Steinberg. Produces good results and is a little faster than
  12 the Hilbert-Peano dithering.
  13
  14 The error is distributed to neighbor pixels as follows:
  15
  16 [width="10%"]
  17 |===================
  18 |      |   X  | 7/16
  19 | 3/16 | 5/16 | 1/16
  20 |===================
  21
  22 And is throwed away at the image borders.
  23
  24 [source,c]
  25 -------------------------------------------------------------------------------
  26 #include <GP.h>
  27 /* or */
  28 #include <filters/GP_Dither.h>
  29
  30 int GP_FilterFloydSteinberg(const GP_Pixmap *src, GP_Pixmap *dst,
  31                             GP_ProgressCallback *callback);
  32 -------------------------------------------------------------------------------
  33
  34 Renders Floyd Steinberg dithering directly into passed pixmap. The
  35 destination must be at least as large as source.
  36
  37 If operation was aborted by a callback, non-zero is returned.
  38
  39 Not all pixel types all supported. If particular combination is not supported
  40 the function returns non-zero and sets errno to 'ENOSYS'.
  41
  42 [source,c]
  43 -------------------------------------------------------------------------------
  44 #include <GP.h>
  45 /* or */
  46 #include <filters/GP_Dither.h>
  47
  48 GP_Pixmap *GP_FilterFloydSteinbergAlloc(const GP_Pixmap *src,
  49                                          GP_PixelType pixel_type,
  50                                          GP_ProgressCallback *callback);
  51 -------------------------------------------------------------------------------
  52
  53 Returns pointer to allocated pixmap of given pixel_type.
  54
  55 If 'malloc(2)' has failed, or operation was aborted by a callback NULL is
  56 returned.
  57
  58 Not all pixel types all supported. If particular combination is not supported
  59 the function returns NULL and sets errno to 'ENOSYS'.
  60
  61 Hilbert-Peano
  62 ~~~~~~~~~~~~~
  63
  64 Hilbert-Peano space filling curve based dithering.
  65
  66 The error value is distributed around the Hilbert curve.
  67
  68 The result is a little more noisy, but doesn't create repeating patterns like
  69 Floyd-Steinberg which looks generally better to human eye. On the other hand
  70 edges tend to be less sharp.
  71
  72 [source,c]
  73 -------------------------------------------------------------------------------
  74 #include <GP.h>
  75 /* or */
  76 #include <filters/GP_Dither.h>
  77
  78 int GP_FilterHilbertPeano(const GP_Pixmap *src, GP_Pixmap *dst,
  79                           GP_ProgressCallback *callback);
  80 -------------------------------------------------------------------------------
  81
  82 Renders Hilbert Peano dithering directly into passed pixmap. The
  83 destination must be at least as large as source.
  84
  85 If operation was aborted by a callback, non-zero is returned.
  86
  87 Not all pixel types all supported. If particular combination is not supported
  88 the function returns NULL and sets errno to 'ENOSYS'.
  89
  90 [source,c]
  91 -------------------------------------------------------------------------------
  92 #include <GP.h>
  93 /* or */
  94 #include <filters/GP_Dither.h>
  95
  96 GP_Pixmap *GP_FilterHilbertPeanoAlloc(const GP_Pixmap *src,
  97                                        GP_PixelType pixel_type,
  98                                        GP_ProgressCallback *callback);
  99 -------------------------------------------------------------------------------
 100
 101 Returns pointer to allocated pixmap of given pixel_type.
 102
 103 If 'malloc(2)' has failed, or operation was aborted by a callback NULL is
 104 returned.
 105
 106 Not all pixel types all supported. If particular combination is not supported
 107 the function returns NULL and sets errno to 'ENOSYS'.
 108
 109 include::images/convert/images.txt[]
 110 include::images/floyd_steinberg/images.txt[]
 111 include::images/hilbert_peano/images.txt[]