hqx/README

   1 hqx Library README
   2 ==================
   3
   4 Introduction
   5 ------------
   6 hqx is a fast, high-quality magnification filter designed for pixel art.
   7
   8 Install
   9 -------
  10 NOTE: DevIL library and development headers are required.
  11
  12     ./configure
  13     make && make install
  14
  15 For more information refer to INSTALL.
  16
  17 Usage
  18 -----
  19 hqx -s scaleBy input output
  20 Where scaleBy is either 2, 3 or 4
  21
  22 For example:
  23     hqx -s 4 test.png out.png
  24
  25 Example
  26 -------
  27 #include <stdint.h>
  28 #include <hqx.h>
  29
  30 uint32_t *src; // Pointer to source bitmap in RGB format
  31 size_t width, height; // Size of source bitmap
  32
  33 /*
  34  * Code to init src, width & height
  35  */
  36
  37 uint32_t *dest = (uint32_t *) malloc(width * 4 * height * 4 * sizeof(uint32_t));
  38 hqxInit();
  39 hq4x_32(src, dest, width, height);
  40
  41 Implementation
  42 --------------
  43 The first step is an analysis of the 3x3 area of the source pixel. At first, we
  44 calculate the color difference between the central pixel and its 8 nearest
  45 neighbors. Then that difference is compared to a predefined threshold, and these
  46 pixels are sorted into two categories: "close" and "distant" colored. There are
  47 8 neighbors, so we are getting 256 possible combinations.
  48
  49 For the next step, which is filtering, a lookup table with 256 entries is used,
  50 one entry per each combination of close/distant colored neighbors. Each entry
  51 describes how to mix the colors of the source pixels from 3x3 area to get
  52 interpolated pixels of the filtered image.
  53
  54 The present implementation is using YUV color space to calculate color
  55 differences, with more tolerance on Y (brightness) component, then on color
  56 components U and V. That color space conversion is quite easy to implement if
  57 the format of the source image is 16 bit per pixel, using a simple lookup table.
  58 It is also possible to calculate the color differences and compare them to a
  59 threshold very fast, using MMX instructions.
  60
  61 Creating a lookup table was the most difficult part - for each combination the
  62 most probable vector representation of the area has to be determined, with the
  63 idea of edges between the different colored areas of the image to be preserved,
  64 with the edge direction to be as close to a correct one as possible. That vector
  65 representation is then rasterised with higher (3x) resolution using
  66 anti-aliasing, and the result is stored in the lookup table.
  67
  68 The filter was not designed for photographs, but for images with clear sharp
  69 edges, like line graphics or cartoon sprites. It was also designed to be fast
  70 enough to process 256x256 images in real-time.