doc/filters_resize.txt

   1 Resize filters
   2 --------------
   3
   4 Common API
   5 ~~~~~~~~~~
   6
   7 [source,c]
   8 -------------------------------------------------------------------------------
   9 #include <GP.h>
  10 /* or */
  11 #include <filters/GP_Resize.h>
  12
  13 typedef enum GP_InterpolationType {
  14         GP_INTERP_NN,            /* Nearest Neighbour                         */
  15         GP_INTERP_LINEAR_INT,    /* Bilinear - fixed point arithmetics        */
  16         GP_INTERP_LINEAR_LF_INT, /* Bilinear + low pass filter on downscaling */
  17         GP_INTERP_CUBIC,         /* Bicubic                                   */
  18         GP_INTERP_CUBIC_INT,     /* Bicubic - fixed point arithmetics         */
  19         GP_INTERP_MAX = GP_INTERP_CUBIC_INT,
  20 } GP_InterpolationType;
  21
  22 const char *GP_InterpolationTypeName(enum GP_InterpolationType interp_type);
  23
  24 int GP_FilterResize(const GP_Pixmap *src, GP_Pixmap *dst,
  25                     GP_InterpolationType type,
  26                     GP_ProgressCallback *callback);
  27
  28 GP_Pixmap *GP_FilterResizeAlloc(const GP_Pixmap *src,
  29                                  GP_Size w, GP_Size h,
  30                                  GP_InterpolationType type,
  31                                  GP_ProgressCallback *callback);
  32 -------------------------------------------------------------------------------
  33
  34 Interpolate (resize) the pixmap.
  35
  36 Resize image given size and interpolation type.
  37
  38 GP_FilterResize
  39 ^^^^^^^^^^^^^^^
  40
  41 The +GP_FilterReize()+ function resizes 'src' to fit 'dst' exactly.
  42
  43 Both 'src' and 'dst' must have the same pixel type.
  44
  45 Returns zero on success, non-zero on failure and sets errno.
  46
  47 GP_FilterResizeAlloc
  48 ^^^^^^^^^^^^^^^^^^^^
  49
  50 The +GP_FilterResizeAlloc()+ allocates the destination give it's size.
  51
  52 Returns pointer to newly allocated pixmap or NULL in case of failure and
  53 errno is set.
  54
  55 Nearest Neighbour Interpolation
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  57
  58 [source,c]
  59 -------------------------------------------------------------------------------
  60 #include <GP.h>
  61 /* or */
  62 #include <filters/GP_ResizeNN.h>
  63
  64 int GP_FilterResizeNN(const GP_Pixmap *src, GP_Pixmap *dst,
  65                       GP_ProgressCallback *callback);
  66
  67 static inline GP_Pixmap *GP_FilterResizeNNAlloc(const GP_Pixmap *src,
  68                                    GP_Size w, GP_Size h,
  69                                    GP_ProgressCallback *callback);
  70 -------------------------------------------------------------------------------
  71
  72 Pixel value is choosen as value of the closest pixel in the source bitmap
  73 (after destination coodinates are mapped to the source coordinates).
  74
  75 Fast, but produces "pixelated" images. May however work better for images with
  76 sharp edges mostly consisting of big one color regions (it doesn't blur the
  77 result on upscaling).
  78
  79 Is commonly used to show preview before you resample the image correctly.
  80
  81 Bilinear Interpolation
  82 ~~~~~~~~~~~~~~~~~~~~~~
  83
  84 [source,c]
  85 -------------------------------------------------------------------------------
  86 #include <GP.h>
  87 /* or */
  88 #include <filters/GP_ResizeLinear.h>
  89
  90 int GP_FilterResizeLinearInt(const GP_Pixmap *src, GP_Pixmap *dst,
  91                              GP_ProgressCallback *callback);
  92
  93 int GP_FilterResizeLinearLFInt(const GP_Pixmap *src, GP_Pixmap *dst,
  94                              GP_ProgressCallback *callback);
  95
  96 GP_Pixmap *GP_FilterResizeLinearIntAlloc(const GP_Pixmap *src,
  97                                           GP_Size w, GP_Size h,
  98                                           GP_ProgressCallback *callback);
  99
 100 GP_Pixmap *GP_FilterResizeLinearLFIntAlloc(const GP_Pixmap *src,
 101                                             GP_Size w, GP_Size h,
 102                                             GP_ProgressCallback *callback);
 103 -------------------------------------------------------------------------------
 104
 105 Bilinear is faster than bicubic interpolation and produces quite good results
 106 especially the low pass (LF) variant doesn't need additional low-pass filter
 107 on down-sampling.
 108
 109 Bicubic Interpolation
 110 ~~~~~~~~~~~~~~~~~~~~~
 111
 112 [source,c]
 113 -------------------------------------------------------------------------------
 114 #include <GP.h>
 115 /* or */
 116 #include <filters/GP_ResizeCubic.h>
 117
 118 int GP_FilterResizeCubicInt(const GP_Pixmap *src, GP_Pixmap *dst,
 119                              GP_ProgressCallback *callback);
 120
 121 int GP_FilterResizeCubic(const GP_Pixmap *src, GP_Pixmap *dst,
 122                          GP_ProgressCallback *callback);
 123
 124 GP_Pixmap *GP_FilterResizeCubicIntAlloc(const GP_Pixmap *src,
 125                                          GP_Size w, GP_Size h,
 126                                          GP_ProgressCallback *callback);
 127
 128 GP_Pixmap *GP_FilterResizeCubicAlloc(const GP_Pixmap *src,
 129                                       GP_Size w, GP_Size h,
 130                                       GP_ProgressCallback *callback);
 131 -------------------------------------------------------------------------------
 132
 133 Works well as is on image upscaling. To get decent result on downscaling
 134 low-pass filter (Gaussian blur) must be used on original image before actual
 135 downscaling.
 136
 137 To do this reasonably fast we could cheat a little: first resize big images a
 138 little without the low-pass filter, then apply low-pass filter and finally
 139 downscale it to desired size.