Clearize
Applies a 3-to-1 horizontal scaling with color component
misregistration, similar to Microsoft's ClearType
By Damian Yerrick
Release 20020113


=== General description ===

ClearType(TM) refers to Microsoft's technology used in recent
versions of its Windows operating systems that exploits the inherent
misregistration in some computer display devices to draw the lines
and curves of text and graphics to sub-pixel accuracy.  The Apple II
family had used a very similar technique two decades earlier.

Normal software treats computer displays as containing square
white pixels. On the other hand, actual pixels on a color LCD
are tall rectangles of red, green, and blue, and the hardware
can generally address the individual components of a pixel
separately.  A 4x3 pixel section of a display looks like this:

+-+-+-+-+-+-+-+-+-+-+-+-+
| | | | | | | | | | | | |
|R|G|B|R|G|B|R|G|B|R|G|B|
+-+-+-+-+-+-+-+-+-+-+-+-+
| | | | | | | | | | | | |
|R|G|B|R|G|B|R|G|B|R|G|B|
+-+-+-+-+-+-+-+-+-+-+-+-+
| | | | | | | | | | | | |
|R|G|B|R|G|B|R|G|B|R|G|B|
+-+-+-+-+-+-+-+-+-+-+-+-+

Thus, if software treats RGB as a single unit, an image of
all red pixels will be offset 1/3 pixel to the left of an
image of all green pixels, and an image of all blue pixels
will be offset 1/3 pixel to the right.

To start, apply a low-pass filter (the 5-tap FIR filter
[1 3 4 3 1]/12 works well) to the image to avoid color
fringing caused by beats with the color subcarrier.  Then
sample alternately red, green, and blue components of
successive pixels to produce a final image at nearly
triple the horizontal resolution of an ordinary image.

Clearize implements this algorithm on common bitmap image formats
such as BMP and PCX.  It assumes that the input image has been
rendered three times wider than the target size.  Use it for font
images, title screens, anything.


=== Building Clearize ===

You need the Allegro library and a version of GCC for a platform that
Allegro supports, such as the following platforms:
  Linux and BSD with X11
  DOS (DJGPP, at http://www.delorie.com/djgpp/)
  Win32 (MinGW, at http://www.mingw.org/)
  BeOS
  QNX

Download the Allegro library at http://alleg.sourceforge.net/

To compile on DOS or Windows:
  1. Install Allegro.
  2. Enter the directory containing the source file and
     gcc -O3 clearize.c -lalleg -o clearize.exe

To compile on UNIX clones:
  1. Install Allegro.
  2. Enter the directory containing the source file and
     gcc -O3 clearize.c `allegro-config --libs` -o clearize

Because many users of Microsoft operating systems do not have the
time to download a compiler or the technical ability to install one,
I have provided a DOS compatible binary.  Note that it requires a
DPMI server present to run under plain DOS as opposed to a virtual
machine in Windows.  You can obtain the free CWSDPMI by going to
  http://www.simtel.net/pub/djgpp/v2misc/
and downloading csdpmi5b.zip (whose source code is csdpmi5s.zip).



=== Using Clearize ===

To use the program, open a commandline and type a command.

General syntax:
  clearize [options] infile outfile

-- options --

Options can contain zero or more of the following:

  -b    This reverses the usual RGB order to BGR.  Use this if your
        display is known to be BGR instead of RGB (such as Game Boy
        Advance and some iBooks).

-- infile and outfile --

Specify a source bitmap and a destination bitmap.  The source can
be indexed or truecolor, but the output will always be truecolor.

-- Example --

To convert from a 720x160 bitmap to a 240x160 bitmap designed for a
BGR display (such as Game Boy Advance):

E:\gbadev\tetyais>clearize -b titlescr.bmp titlescr-ct.bmp


=== File types ===

Clearize compiled with the default installation of Allegro will
recognize BMP, LBM, PCX, and TGA images on input and can output
BMP, PCX, and TGA images.  To add support for PNG or JPEG images,
download and install add-on libraries from http://www.allegro.cc/ and
place their register_*_file_type() functions in clearize.c's main()
before the initial call to load_bitmap().


=== Legal information ===

Copyright (c) 2002 Damian Yerrick

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

Pin Eight is a trademark of Damian Yerrick.  Microsoft, ClearType,
and Windows are trademarks of Microsoft Corporation.
