

                           Welcome to the

                  F R E E T Y P E    P R O J E C T

                          www.freetype.org

                           Release 1.2

                   The FREE TrueType Font Engine

    Copyright 1996 David Turner    <turner@enst.fr>
            - 1998 Robert Wilhelm  <robert@physiol.med.tu-muenchen.de>
                   Werner Lemberg  <wl@gnu.org>


Table Of Contents:

    A. Introduction

    B. The FreeType mini-FAQ

    C. How to use the test programs

    D. How to use the programs in the 'contrib' directory



A. Introduction:

  Please read the file `INSTALL' for installation instructions!

  The FreeType engine is a free and portable TrueType font rendering
  engine.  It  has been developed to  provide TT support  to a great
  variety of platforms and environments.
  
  Notice that  FreeType is a *library*.   It is *not*  a font server
  for your preferred environment, even though it has been written to
  allow the design of many font servers.

  To our knowledge, this  is the only royalty-free complete TrueType
  engine available.   Moreover, its  quality fully matches  these of
  Windows or  the Macintosh,  a thing that  cannot be said  for most
  other commercial engines available.

  FreeType is  a clean-room implementation that is  not derived from
  the original TrueType engine developed by Apple and Microsoft.  It
  has  been created  with the  sole help  of the  published TrueType
  specifications, which, to our  great surprise and pain, turned out
  to be extremely  poor or misleading in critical  areas.  Much hard
  work   has  been   undertaken  to   solve   numerous  ambiguities;
  nevertheless, its end result is a portable, fast quality renderer!

  The  library itself takes  about 55kByte  of Intel  code, complete
  with  a  TrueType  byte-code  interpreter and  a  high-performance
  scan-line converter.
  
  You will find in this release:

     - a TrueType engine, with source code in ANSI C and Pascal.

       The C source  code has been successfully compiled  and run on
       various platforms,  including MS-DOS, OS/2,  Amiga, Linux and
       several  other variants of  Unix.  It  should be  portable to
       many other platforms too.

       The Pascal code has been successfully compiled and run on DOS
       (Borland's BP7) and OS/2 (fPrint's Virtual Pascal).  A Delphi
       port is in beta (the code in freetype/pascal compiles).

     - An API  to be used  by client applications and  font servers,
       providing several low level  abstractions that can be used to
       open font files and collections, create point sizes and load,
       process and render glyph outlines and bitmaps.

     - Support for the following features:

         o Font smoothing, a.k.a. gray-level rendering.

             Just like  Win95, the renderer uses  a 'fine' algorithm
             that only smoothes  diagonals and curves, while keeping
             the horizontal and vertical stems intact.
             
             This results in glyphs that are much more legible than
             the "fuzzy" ones generated by programs like Acrobat.

         o Support for all character mapping formats.

         o A full-featured TrueType byte-code interpreter.

             The  engine  is able  to  hint  the  glyphs to  produce
             excellent  output  at small  sizes.   It was  extremely
             difficult  to  get this  component  right,  due to  the
             ambiguous   and  misleading   TrueType  specifications.
             However,   we  now   *match*   Windows  and   Macintosh
             qualities.

         o TrueType  collection  support,  when  several  fonts  are
           embedded in the same file.

         o Support for extensions.

             It is  now possible to  extend the library in  parts to
             support additional features,  like optional tables that
             are not considered by the current core engine.

         o Kerning support.

             Provided  as  a  sample  extension with  this  release,
             kerning tables can be accessed from a TrueType font for
             applications that need it.

         o New in 1.1: Support for vertical metrics.

             It  is  now  possible  to load  vertical  metrics  when
             they're  present  in  a  font  file.   Metrics  can  be
             retrieved  glyph  by glyph,  using  the  loader, or  in
             arrays with a new API.

         o New in 1.1: Support for thread-safety and re-entrancy.

             This support is now in beta.  You'll need to specialize
             the  file  "ttmutex.c"  for  your platform  to  include
             system-specific synchronization calls.

  Note also that:

   - Though development  of the library is mainly  performed on OS/2
     and Linux, the library does not contain system-specific code.
   
   - The  package contains some  graphics drivers  used by  the test
     programs for display purposes  on MS-DOS, OS/2, Amiga, and X11.
     These  drivers are  absolutely  not mandatory  for running  the
     FreeType engine.  Some console-mode test programs like 'ftlint'
     or 'ftdump' don't use graphics at all.
   
   - FreeType 1.1  is _not_ binary compatible with  1.0, which means
     that you will need to  recompile your programs if they used the
     engine as a shared library (libttf.so on Linux, or FreeType.dll
     on Windows).  See the file 'freetype/docs/changes.txt' for more
     information.


B. The FreeType mini-FAQ:

  Summary:

  0. Where to find the latest FreeType release?

  1. What do you mean by 'Public Release'?

  2. Did the API changed since the beta ?

  3. What does the 'Free' in FreeType means?
     Can you use it in a commercial product? (YES!)

  4. I have  made a small program  based on the test  programs but I
     would like to know how to do xxx?

  5. When will I  be able to use FreeType  to display TrueType fonts
     under X11, OS/2 or Wine? (NOW!)

  6. Trying  to  compile  the  FreeType  sources gives  me  lots  of
     warnings with my ANSI C compliant compiler!

  ------------------------------------------------------------------

  0. Where to find the latest FreeType release?

       The  latest package  is  usually uploaded  to various  source
       repositories, like SunSite, SimTel, or Hobbes.  There are two
       archive formats (zip and  tar.gz), which also differ by their
       CR/LF conventions.

       * for DOS and OS/2: 'ft-10.zip'

         which should be available at:

         Hobbes: ftp://ftp.cdrom.com/pub/os2/fonts
         SimTel: ftp://oak.oakland.edu/pub/simtel.net/msdos/graphics

       * for UNIX and Amiga: 'freetype-1.2.tar.gz'

         look at:

         SunSite: ftp://sunsite.unc.edu/pub/Linux/X11/fonts

       * As  uploading  can take  several  days  before the  package
         becomes available to the  public, we advise you to download
         it from our own ftp site  if you read this message few days
         after the announcement at:
       
         ftp://ftp.freetype.org/pub/freetype


       We have registered the  "freetype.org" domain.  Our main page
       is now at:

                        http://www.freetype.org

                       (Screen shots available)

       There are also four mailing lists:
       
         o freetype-announce@lists.lrz-muenchen.de 

             Announcements only  about new versions of FreeType
             and related packages. This list is moderated and
             expected to have very low traffic.

       
         o freetype@lists.lrz-muenchen.de 

             Discusses  general use of  FreeType, future  and needed
             additions,   as  well   as   many  other   font-related
             discussions which do not  always relate directly to the
             FreeType code itself...


         o freetype-devel@lists.lrz-muenchen.de

             Discusses  development,   design  choices,  portability
             issues, internals, specific licenses, etc.
       

         o freetype-bugs@freetype.org

             To  report bugs you  believe come  from the  engine :-)
             Notice the different address! If you want help fixing
             bigs, contact rober@freetype.org to be manually subscribed.


       To subscribe, send the usual subscription commands to:
       
           majordomo@lists.lrz-muenchen.de
       
       
       Any suggestions/bug reports are welcome.
       
  ------------------------------------------------------------------

  1. What do you mean by 'Public Release'?

       This release fixes some bugs found in FreeType  1.1.

       Note that FreeType will soon go under a major re-design.  The
       library will evolve from a TrueType-specific driver to a more
       general  and  high-level  text  rendering library,  with  the
       ability  to  support  several  font  file  formats  (bitmaps,
       TrueType, hopefully Type1  PostScript).  The first "try" will
       be  released as FreeType  2.0, but  the font  driver(s) alone
       will still be available for separate compilation.

       Of course, we keep the same license :-)


  ------------------------------------------------------------------

  2. Did the API change since the beta ?

       Yes, there were a few changes  that are summed up in the file
       'docs/changes.txt'.    Please   read   it  thorougly   before
       modifying your code to adapt to this release.

       Normally, if your source only  used the FreeType 1.0 API, and
       _didn't_  access  directly   the  outline  structures  (these
       changed in  the way), it  should recompile flawlessly  on the
       first try (with very small exceptions).


  ------------------------------------------------------------------

  3. What does the 'Free' in FreeType means?
     Can you use it in a commercial product? (YES!)

       We  have placed  this  release under  the  same old  FreeType
       license.
       
       It  was inspired by  the BSD,  Artistic and  IJG (Independent
       JPEG group)  ones, which  specifically encourage use  of this
       software in commercial products!

       The reason we did this is  that we believe that TrueType is a
       very useful technology, and want  to make it available on all
       machines and platforms.  The  license is there to ensure that
       the engine can be spread as widely as possible.

       However, free  does not mean  public domain.  This  engine is
       copyrighted  by its  authors, and  they will  fiercely defend
       their rights.
       

  ------------------------------------------------------------------

  4. I have  made a small program  based on the test  programs but I
     would like to know how to do xxx?

       (Where   xxx  is   a   feature  lacking   from  the   current
       implementation).

       First of  all, read the documentation.  The  user guide gives
       some basic hints and concepts.   You can also read the source
       code of the  test programs that you didn't  consider yet.  If
       you're really stuck, mail your question to:

                       freetype@lists.lrz-muenchen.de

       We'll try to help you.


  ------------------------------------------------------------------

  5. When will I  be able to use FreeType  to display TrueType fonts
     under X11, OS/2, or Wine?

       You can  already do  that under  X11 and OS/2  :-)  Go to the
       FreeType   web   page   (www.freetype.org)   for   up-to-date
       information.

       And yes, it looks terrific!

       For  X11,  you  could  also   take  a  look  at  "xfstt",  an
       independent TrueType font server  for Unix which doesn't rely
       on the FreeType code.

       You're welcome to volunteer for other platforms, like:

            Amiga, RISC OS, BeOS, and others

       Please contact  freetype-devel@lists.lrz-muenchen.de for more
       information.


  ------------------------------------------------------------------

  6. Trying  to  compile  the  FreeType  sources gives  me  lots  of
     warnings with my ANSI C compliant compiler!

       We use gcc as our reference compiler for warnings. This means
       that we use the "-ansi  -pedantic -Wall" flags and try to get
       rid of warnings in this situation.

       If you're compiling with  another compiler, you may encounter
       warnings, not errors.

       We have spent much efforts  to reduce seriously the number of
       warnings produced  by major compilers,  including Visual Age,
       Visual C++ and Borland C++.

       Note  that the  Borland  compilers seem  to  produce lots  of
       irrelevant warnings (like 'potential loss of precision').



C. How to use the test programs:

  This package includes several test programs in the "freetype/test"
  directory.  Read the "HOWTO" files to learn how to compile them.

  Note  that  all  test  programs   share  the  same  key  map  when
  displaying.  Using the arrow or function keys would have been good
  to but  we preferred  a common map  rather than specifying  it for
  each platform:

    x :   fine counter-clockwise rotation  (ftzoom only)
    c :   fine clockwise rotation          (ftzoom only)

    v :   fast counter-clockwise rotation  (ftzoom only)
    b :   fast clockwise rotation          (ftzoom only)

    h :   toggle hinting on/off

    + :   fast scale up
    - :   fast scale down
    u :   fine scale up
    j :   fine scale down

    l :   go to next glyph
    k :   go to previous glyph

    o :   go to tenth next glyph
    i :   go to tenth previous glyph

    9 :   go to hundredth next glyph (useful for CJK fonts)
    0 :   go to hundredth previous glyph

    ( :   go to 1000th next glyph
    ) :   go to 1000th previous glyph

    { :   go to 10000th next glyph
    } :   go to 10000th previous glyph

  ESC :
    q :   exit


  These keys were chosen because they're available on all platforms.


- FTTIMER:

  This is a simple performance timer for the engine.  It will load a
  TrueType font given as an argument and try to render each glyph as
  fast as possible, giving the total time elapsed.

  This program only times the scan-line converter's job by rendering
  all glyphs at a size of 400pt.

  (supports font-smoothing and display)


- FTZOOM:

  This program  is a very  simple glyph viewer.  Specify  a TrueType
  font as an argument, and it will  try to load it and allows you to
  view/scale/rotate  any  glyph  of  it.  Supports  font  smoothing.
  Doesn't hint glyphs.  Use the -p and -e flags to select a CMAP.
  

- FTLINT:

  This program will hint each glyph of a font file, at a given point
  size.  This is useful to detect bugs in the interpreter (or in the
  font file).


- FTVIEW:

  This program  will display  all glyphs in  a given  font, applying
  hinting to  each one.   Try it, the  results are  really pleasant.
  Supports font-smoothing.

  You can change the point  size whenever you want.  The OS/2 viewer
  comes  with a magnifying  sub-window that  lets you  inspect pixel
  details (like font-smoothing).


- FTDUMP:

  A simple TrueType font or collection dumper.


- FTSTRING:

  A  simple program  to show  off string  text generation.   Used to
  display  a given  message on  the screen  with a  given  font, and
  eventually resize it as you want.


- FTSTRPNM:

  Use this program to convert a rendered text string into the PGM or
  PBM format which can be  further converted to popular formats like
  GIF or PNG with the netpbm tool suite.


- FTERROR:

  This small test program  is UNIX-specific.  It tests the gettext()
  functionality for internationalized messages.



D. HOW TO USE THE PROGRAMS IN THE 'CONTRIB' DIRECTORY:

  These  programs   (currently  ftos2,  ttf2bmf,   and  ttf2pk)  are
  contributions to FreeType and not  really part of it.  Please read
  the documentation  files in  the respective subdirectories  how to
  compile and install them.


Of course,  all source  code is provided  'as is'.  Please  read the
file 'license.txt' for more information.

We hope  you'll find this engine  useful, and look  forward to file.
your feed-back.  We're of course  very interested in bug reports, as
well as FreeType success stories :-)


Thanks for your time and consideration,


    David Turner, Robert Wilhelm, Werner Lemberg,
    and all the FreeType enthusiasts...


--- end of readme.1st --
