PyFT 0.65 - FreeType Wrappers for Python
=======================================
(by Robert Kern <kern@caltech.edu>)

Who wants to render TrueType fonts from Python?  Okay, all three of
you can put your hands down now.

Seriously though, PyFT wraps FreeType 1.3.x, an engine that renders
TrueType fonts.  FreeType is the child of the FreeType Project, and
its primary authors are David Turner, Robert Wilhelm, and Werner
Lemberg.  Thanks, guys!

A brief rundown of PyFT's capabilities:

 * You can render text onto a 2-color bitmap.  You can also render
   anti-aliased text onto a 256-grayscale pixmap.  The FreeType object
   is readily converted to PIL Image either through an intermediate
   string or a buffer object.

 * You can get the outline of a glyph for use by other drawing tools 
   (e.g. PIDDLE).

 * If you are a TrueType wizard, you can get the raw data contained in the 
   font's tables.

 * The metrics of a font are available without rendering.

 * Affinely transformed text.

 * You have access to the kerning (no relation :-)) tables embedded in
   the font.  I haven't figured out how to use these tables yet, but
   I'm sure they are in there for a reason.

 * Probably a couple of other things that I am too lazy to look up.
   Look at the FreeType web site for more information.
   http://freetype.sourceforge.net

New in 0.65:

I've added PyFT.py, a Python OO wrapper around the low-level API
exposed by freetype.py .  See the docstrings for more information.

Installation
------------

This version of PyFT is based on FreeType 1.3.x.  If you do not have
access to a binary of PyFT or libttf, you will need to grab the
source for FreeType 1.3.x, too.  I will provide a Win32 binary for PyFT
and the FreeType library unless you really want to compile it
yourself.

Win32 binary installation is easy.  Drop 'freetype.py',
'freetypec.pyd', and 'libttf.dll' into a convenient directory,
probably one on your PYTHONPATH.

To compile from the source, you will also need to compile the FreeType
library.  In general, simply follow FreeType's installation
instructions.  You will probably need to #define
TT_CONFIG_OPTION_THREAD_SAFE, but I am not sure.  You will definitely
need to #define TT_CONFIG_OPTION_EXTEND_ENGINE as PyFT uses several
engine extensions.

Specifically, the extensions that you need to be sure are in your
library are as follows:

  ftxkern
  ftxcmap
  ftxgasp
  ftxpost
  ftxwidth
  ftxerr18

If you read FreeType's instructions, you will know how to do this.

PyFT is split into two parts, a C extension 'freetypec' and a Python
module 'freetype' that thinly wraps 'freetypec'.  Simply use
'freetype' for the sake of shared sanity.

Both parts are automatically generated by SWIG from the interface
definition file 'freetype.i'.  You do not need SWIG in order to use
PyFT.  Both 'freetype.py' and 'freetype_wrap.c', the source code for
'freetypec' are provided.  They were generated with SWIG 1.1 build
833.

Compilation of the extension is standard.  Just be sure to have
FreeType's include file, 'freetype.h', on the include path and the
FreeType library on the library search path.


Documentation
-------------

PyFT's main documentation is in the files 'PyFT.html' and 'PyFT.doc'.
The content is the same; the first is, obviously, HTML, and the latter
is ASCII.

The FreeType library's relevant documentation files are included in
the 'docs' subdirectory of the binary distribution.  They are also
available online at http://www.freetype.org

Recommended Reading:

You will want to read the User Guide 
<URL: http://www.freetype.org/docs/user/user.txt>, skim the API Reference 
<URL: http://www.freetype.org/docs/api/freetype1.txt>, and read the 
Introduction to Glyphs <URL: http://www.freetype.org/glyphs/index.html>.


Directory Structure
-------------------

Source Distribution:

    PyFT-0.65/
	README
	LICENSE

	src/
	    freetype.i       # SWIG interface file
	    freetype_inc.py  # Python file that gets included into 
			     # 'freetype.py' by SWIG
	    freetype.py	     # SWIG-generated Python module
	    PyFT.py	     # OO Python wrapper around the low-level stuff
	    freetype_wrap.c  # SWIG-generated C source for 'freetypec' 
			     # extension
	    Setup.w32	     # the Setup file for Win32

	docs/
	    PyFT.html  # SWIG-generated HTML documentation for PyFT
	    PyFT.doc   # ASCII version of the same


Win32 Binary Distribution:

    PyFT-0.65/
	README
	LICENSE
	freetypec.pyd
	freetype.py
	PyFT.py

	libttf.dll   # The FreeType library in DLL form.  Keep it with 
		     # 'freetypec.pyd'

	docs/
	    PyFT.html
	    PyFT.doc
	    
	    user.txt
	    apiref.txt
	    bitmaps.txt
	    raster.doc
	    glyphs.htm
	    image/
	        *.*  # images for the HTML version of the glyphs documentation

'PyFT.html' and 'PyFT.doc' are the same files in both distributions.
Go ahead; unarchive both of them into the same directory.


Feedback
--------

I must have feedback.  I've crashed the extension badly before.  I
think I solved those problems, but others are no doubt lurking.

Please report bugs and any other random thought to <kern@caltech.edu>
or whatever my new e-mail is at the time.  Check the bottom of the WWW
page http://starship.python.net/crew/kernr for my current e-mail.

Lot's of luck (you'll probably need it with my software),

Robert Kern
kern@caltech.edu