

                           Welcome to the

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

                          Public  Release 1.0

                   The FREE TrueType Font Engine

    Copyright 1996 David Turner    <turner@enst.fr>
            - 1998 Robert Wilhelm  <robert@physiol.med.tu-muenchen.de>
                   Werner Lemberg  <a7971428@unet.univie.ac.at>


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:

  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).  We're
       interested in successful ports/compiles on Delphi.

     - 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.

  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.
   
     This package doesn't support thread-safety and re-entrancy yet.
     This will come in a  later release of the engine.  However, the
     API won't change.



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. Aren't you  afraid  that  some  companies  may make "unethical"
     profits by using and selling your code ? (NO!)

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

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

  7. 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-10.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.physiol.med.tu-muenchen.de/pub/freetype


       We also have a web page at:

         http://www.physiol.med.tu-muenchen.de/~robert/freetype.html

       (Screen shots available)

       There are also three mailing lists:
       
         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@physiol.med.tu-muenchen.de

                         ^^^^^^^^^^^^^^^^^^^^^^^
             To report bugs you believe come from the engine :-)
             Notice the different address !!


       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  important bugs  found in  the beta.
       Moreover, it is the first  release to be placed under the new
       FreeType license  (the previous alphas and  betas were placed
       under  the  LGPL), which  means  you're  now  able to  freely
       integrate the  library into your own products.   Read more on
       this in the file "license.txt".

       There will be  other releases, but this one  had the benefits
       of:

         a. working pretty well

         b. being under a BSD-like 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.

       We wanted  to avoid  that, but we  introduced a  few features
       that most people will find interesting and helpful.


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

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

       We have placed  this release of FreeType under  a new license
       which 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. Aren't you  afraid  that  some  companies  may make "unethical"
     profits by using and selling your code ?

       NO!   The idea  is to  raise free  _and_  commercial software
       alike to a  new level where digital type  is available to the
       masses!

       If a company just puts a wrapper around FreeType and sells it
       as  a 'independent'  product,  it will  still  be obliged  to
       credit us in its documentation.  Moreover, anybody can do the
       same for free if he feels like it.

       If  a  company  uses  FreeType, building  several  layers  of
       high-level  text and internationalization  management library
       on top  of it, they  simply produce add-value, and  should be
       paid back for their work.  They will still have to credit us,
       but the engine will only be  one of the 'base bricks' used to
       produce their software.

       If a company puts FreeType within a printer, that's great, as
       it  will be used  by people.   This also  means that  it will
       lower  the printer's cost  (not having  to license  an engine
       from, say,  Microsoft) or  increase its functionality  at the
       same price; consumers always benefit from one or the other in
       a competitive world.
     

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

  5. 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.


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

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

       There are already prototype  renderers for OS/2 and X11 based
       on FreeType in the work, and they should be released soon, if
       not already.

       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, but is already available and working.

       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.


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

  7. 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.
       
       The compilers that  give lots of warnings are  cc on Solaris,
       Borland C++ 5, and Visual C++.  Watcom and Visual Age for C++
       also produce  some warnings in  ANSI mode, but  the makefiles
       provided within this package disable them.



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 --
