

                           Welcome to the

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

                      http://www.freetype.org

                            Release 1.5

                   The FREE TrueType Font Engine

    Copyright 1996 David Turner    <david.turner@freetype.org>
            - 2001 Robert Wilhelm  <robert.wilhelm@freetype.org>
                   Werner Lemberg  <werner.lemberg@freetype.org>


  Table of Contents
  -----------------

    I. Introduction

   II. The FreeType mini-FAQ

  III. How to use the test programs

      1. ftzoom
      2. ftlint
      3. ftview
      4. fttimer
      5. ftdump
      6. ftstring
      7. ftstrpnm
      8. fterror
      9. ftsbit
     10. ftmetric
     11. ftstrtto

   IV. How to use the programs in the `contrib' directory

    V. Final remarks


I. 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 TrueType 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 53 kByte 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.  It 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.

  - 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 Windows 95,  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 Support for vertical metrics.

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

    o Support for thread-safety and re-entrancy.

      You will only need to specialize the file `ttmutex.c' for your
      platform to include system-specific synchronization calls.

    o Support for embedded bitmaps.

      This feature is  already used in x-tt,  a TrueType font server
      for X Window System.

    o Support for  OpenType.  With this release, GSUB  and GPOS have
      been completely implemented.

  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, X11, and
    Windows.  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.
   
  - There was a Pascal version that was distributed along with the C
    version.  Unfortunately, it  is not up to date  when compared to
    the C version, so we decided  to split the two projects.  If you
    are  interested, you  can find  the Pascal  version  in packages
    named like `ftpascal-1.x.tar.gz' or `ftpas1x.zip'.
    


II. The FreeType mini-FAQ
=========================

  Summary

  0. Where to find the latest FreeType release?

  1. Did the API change?

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

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

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

  5. 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-15.zip'

       which should be available at:

       Hobbes: ftp://ftp.cdrom.com/pub/os2/misc
       SimTel: ftp://ftp.simtel.net/pub/msdos/graphics

     * for UNIX and Amiga: `freetype-1.5.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/freetype/

     Our home page is at:

       http://www.freetype.org

     Screen shots are available!

     There are also three mailing lists:
       
     o announce@freetype.org

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

     o freetype@freetype.org

         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 devel@freetype.org

         Discusses development,  design choices, portability issues,
         internals, specific licenses, etc.
       
     To subscribe, send the usual "subscribe" command to:

         announce-request@freetype.org
         freetype-request@freetype.org
         devel-request@freetype.org

     To report bugs please use send an e-mail to devel@freetype.org.

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

  1. Did the API change since the version 1.2?

     Only very marginally.  Please refer to `changes.txt'.

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

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

     We have placed this release under our special FreeType license.
       
     It was inspired by the BSD, Artistic, and IJG (Independent JPEG
     group) licences,  which specifically encourage the  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.

     Since version 1.5,  you can also  optionally choose  to use the
     GNU Public Licence (GPL) instead. The GPL is used only to allow
     GPL-ed  applications  to use  FreeType  (since the  "disclaimer
     clause" is  considered  an  unacceptable  "restriction"  in GNU
     speak); for a commercial product, you should avoid the GPL, and
     then elect the FreeType licence.

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

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

  3. 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 are really stuck, mail your question to:

       freetype@freetype.org

     We shall try to help you.

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

  4. 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  (http://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 are welcome to volunteer for other platforms, like:

       Amiga, RISC OS, BeOS, and others

     [Note that the FreeType library is already available with Amiga
     and BeOS.]

     Please contact devel@freetype.org for more information.

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

  5. 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 are 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').


III. How to use the test programs
=================================

  All  test programs  having a  graphic interface  use the  same key
  convention:

    x :   fine counter_clockwise rotation
    c :   fine clockwise rotation

    v :   fast counter_clockwise rotation
    b :   fast clockwise rotation

    h :   toggle hinting on/off
    K :   toggle kerning on/off
    B :   toggle display of embedded bitmaps on/off
    S :   toggle GSUB on/off
    P :   toggle GPOS 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

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

    ) :   go to thousandth next glyph
    ( :   go to thousandth previous glyph

    } :   go to tenthousandth next glyph
    { :   go to tenthousandth previous glyph

    q :
  ESC :   exit

  These  keys  were  chosen   because  they  are  available  on  all
  platforms.  Note also that each program uses only a subset of this
  key map.

  1. FTZOOM
  ---------

    `ftzoom'  is  a very  simple  glyph  viewer  that supports  font
    smoothing.  Its usage is:

        ftzoom [-g] [-p platformID -e encodingID] 
               [-r resolution] [-z magnification] [-n] fontfilename

    With -g you can  select gray-scaling;  with -n you can  suppress
    usage of the `post' table in the TrueType font.

    For example:

        ftzoom arial.ttf             to show the glyphs found
                                     in the Arial font
        ftzoom -g times.ttf          to show smoothed version of
                                     Times's glyphs.
        ftzoom -p 3 -e 1 uwjmg3.ttf  use cmap for platform ID 3,
                                     encoding ID 1 for this Japanese
                                     font.

  2. FTLINT
  ---------

    `ftlint' is used  to execute all glyphs instructions  found in a
    font file at a given char size size.  Its usage is:

        ftlint pointsize fontfilename [fontfilename] ...

    For example:

        ftlint 12 arial.ttf
        ftlint 15 times.ttf

    It  reports error  codes and  faulty glyph  numbers.  This  is a
    console tool that doesn't need the graphics subsystem.

    NOTE: Trying to hint at sizes smaller than 7 is irrelevant.

  3. FTVIEW
  ---------

    A  font viewer that  supports hinting  and font  smoothing.  Its
    usage:

        ftview [-g] -[r resolution] [-B] pointsize fontfilename

    like in:

        ftview 12 arial.ttf      show the hinted Arial at size 12pt.

        ftview -g 15 timesi.ttf  show the hinted and font-smoothed
                                 Times at size 15pt.

    `-r'  selects the resolution;  `-B' forces  the use  of embedded
    bitmaps.

    Note that it is possible to change the point size during display
    with the  keys `u', `j', `+',  and `-'.  It is  also possible to
    browse the  whole glyph  set with the  `k', `l', `i',  `o', `0',
    `9', `(', `)', `{', and `}' keys (see key map above).

    The OS/2  PM driver comes with an  additional magnifying window.
    The magnified  zone is  set with the  mouse, while the  scale is
    changed with the help of `PageUp' and `PageDown'.

    Note 1: The  engine uses the font's CVT  program to determine at
            which size to enable or disable glyph hinting.  Don't be
            surprised to see unhinted glyphs at sizes < 7pt.

    Note 2: Vertical drop-out  control has  been  added to  the gray
            scaling renderer.  As a consequence, the library doesn't
            produce  unpleasant results  at small  ppems  with badly
            hinted glyphs.

  4. FTTIMER
  ----------

    This program is used to benchmark FreeType's scan-converter (the
    component in charge of translating a vectorial shape description
    into a bitmap).  It does so in preloading all glyphs from a font
    file,  then rendering  them as  fast  as possible  in a  640x450
    buffer.  The glyphs are rendered at size 400pt / 96dpi, which is
    _quite_ big.

    Its usage is:

        fttimer [-g] [-v] fontfilename

    where

        -g : Asks for  gray-level  rendering  at size  200pt instead
             (a.k.a. font-smoothing).

        -v : Asks for  the display of  the produced  bitmap.  Beware
             that  display  slows things  down  (display  on X11  is
             _terrible_,  especially with  gray-levels, but  this is
             not a problem for us :-).

    Note that the returned numbers are not a benchmark of FreeType's
    overall  performance!   Only of  the  scan-line renderer  (which
    seems quite fast, apparently :-).

    When  comparing measured  performances  across machines,  please
    only  consider the  undisplayed ones.   We're interested  in all
    kinds of results (please provide the following information:

        font file
        number of rendered glyphs
        render time
        total time
        glyphs / s
        processor type
        CPU clock

        and which compiler  used (with optimization involved)!  This
        can make a great difference!

        etc.)

  5. FTDUMP
  ---------

    This  program is  a very  simple  font dumper.   In its  current
    incarnation, it will only  output a font's name table, character
    encoding maps  IDs and  total memory consumption.   For TrueType
    Open files, the available GSUB and GPOS tables are also shown.

    The `total memory  used' reported is the amount  that is used by
    the engine to load one face, with one instance (a point size).

    Each additional  instance takes only a fraction  of that amount,
    and is labeled  by `instance object'.  As you  can see, FreeType
    isn't really greedy.

       Usage:   ftdump fontpathname[.ttf|.ttc]

  6. FTSTRING
  -----------

    This  program  demonstrates  string  text generation.   It  only
    displays a given  message on the screen, and  lets you resize it
    with the classic key bindings `u', `j', `+', and `-'.

    Usage:

        ftstring  ptsize  fontname[.ttf|.ttc]  [message_string]

    If  the  message is  omitted,  it  will  revert to  the  classic
    typographic test sentence:

        The quick brown fox jumps over the lazy dog

    which is made of all letters of the English alphabet.

    `ftstring'  only works with  font files  that contain  a Unicode
    character  mapping  table   (either  Windows  Unicode  or  Apple
    Unicode).   For the  moment,  the message  can  however only  be
    written in ASCII, as accents aren't supported yet.

  7. FTSTRPNM
  -----------

    Usage:

        ftstrpnm [options] filename [string]

    Options:

      -g      gray-level rendering (default: off)
      -h      hinting off (default: on)
      -r X    resolution X dpi (default: 96)
      -p X    pointsize X pt (default: 12)
      -b X    border X pixels wide (default: 0)

    This  program is  quite  similar to  ftstring  but converts  the
    rendered image of  the specified string into a  bitmap in PBM or
    PGM  format written  to stdout;  PBM (Portable  BitMap)  and PGM
    (Portable GrayMap)  formats can be further  converted to popular
    graphics  formats like  GIF or  PNG with  the netpbm  tool suite
    available via Internet.

  8. FTERROR
  ----------

    This program tests the gettext() functionality on UNIX platforms
    (usually provided  in the GNU gettext package).   It will return
    language specific  error and warning messages  depending on your
    locale.   Currently Czech,  Dutch, French,  German,  and Spanish
    translations of the FreeType  messages are included -- we invite
    you to contribute more translations.

    Typically, you have to set the LANG environment variable to your
    locale to get localized messages.  Example:

      LANG=de fterror

    fterror also gives you a  textual interpretation of a particular
    (numerical)  error code, as  returned by  the Freetype  library.
    Example:

      LANG=fr fterror 0x40E

    Note  that providing  message strings  for FreeType's  error and
    warning messages  is an extension  and not part of  the FreeType
    library  itself.  Please  refer to  `docs/i18n.txt'  for further
    details.

  9. FTSBIT
  ---------

    Usage:

        ftsbit ppem fontname[.ttf|.ttc] glyph_index [glyph_index2..]

    This  tool dumps  the  information in  the  tables for  embedded
    bitmaps.  Additionally,  it prints  (to the console)  a selected
    glyph bitmap.

 10. FTMETRIC
 ------------

    Usage:

        ftmetric [options below] point fontname[.ttf|.ttc] ...

        -B        show sbit's metrics (default: none)
        -c C      use C'th font index of TrueType collection
                  (default: 0)
        -i index  glyph index (default: 0)
        -r R      use resolution R dpi (default: 72dpi)

    With this  small program  you can inspect  the metric data  of a
    given glyph; additionally, it  dumps the particular glyph to the
    console.

  11. FTSTRTTO
  ------------

    Usage:

        ftstrtto [options below] ppem fontname[.ttf|.ttc] [string|-]

        -c C   use font with index C in TrueType collection
               (default: 0)
        -f F   use feature F (can be specified more than once)
        -g     gray-level rendering
        -l L   use language L
        -r R   use resolution R dpi (default: 96dpi)
        -s S   use script S
        -u     interpret input data as UTF8-encoded
        -v     display string vertically
        -x     display string from right to left

      F, L, and S must be specified as 4-character tags.
      Specifying only F and S selects default language system of S.
      Specifying only L and S selects the req. feature of L only
      (if any).

      If `-' is specified as input string, stdin is read instead.

    This program uses  almost all features of FreeType  to display a
    string on screen.   Its usage is similar to  `ftstring', but you
    can additionally select  GSUB and GPOS features,  the collection
    in a font,  toggle kerning  and embedded bitmaps  interactively,
    and input the optional string in UTF8 encoding.

    For  a list  of  available script,  language,  and feature  tags
    please   refer   to   the   TrueType   Open   (resp.   OpenType)
    specification.

    Example:

      ftstrtto -s "latn" -l "DEU " -f "liga" -f "frac" \
               40 pala.ttf "fi ff ffi ffl 1/2"

    Note  that you can  inspect the  available tags  in a  font with
    `ftdump'.

    The features `init', `medi',  and `fina', and `isol' are treated
    specially.    Internally,  ftstrtto  assigns   initial,  medial,
    isolated, and final properties to Arabic characters in the input
    string.  If one of the  features is switched on, all glyphs with
    the corresponding property are modified (if covered).

    Example:

      ftstrtto -s arab -f init -f medi -f fina -f isol \
               -f liga -f mset -x -u 20 trado.ttf - < arab.utf8

    `mset' is another, Arabic specific feature to position combining
    marks.

    If  you   select  the   swash  feature  `swsh',   the  displayed
    alternative in the string is always the first available one.



IV. HOW TO USE THE PROGRAMS IN THE `CONTRIB' DIRECTORY
======================================================

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


V. FINAL REMARKS
================

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

We hope you will 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 ---
