

                           Welcome to the

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

                      http://www.freetype.org

                            Release 1.4

                   The FREE TrueType Font Engine

    Copyright 1996 David Turner    <david.turner@freetype.org>
            - 2000 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. 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 60 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 Pascal,  that has  been
    successfully  compiled and  run on MS-DOS (Borland's  BP7), OS/2
    (fPrint's  Virtual Pascal),  and Windows  (Delphi).  A FPC  port
    is in beta (the code compiles, but has not been fully tested).

  - 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 Basic support for 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 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.

  Note also that:

  - The  package contains  some graphics  drivers used  by  the test
    programs for  display  purposes  on MS-DOS,  OS/2,  and Windows.
    These  drivers  are absolutely  not  mandatory  for running  the
    FreeType engine.  Some console-mode test programs like `lint' or
    `dump' don't use graphics at all.
   

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  MS-DOS,  OS/2  or  Wine,  using  Pascal  as  programming
     language? (NOW!)

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

  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: `ftpas-14.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: `ftpascal-1.4.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/ftpascal

       Our home page is at:

         http://www.freetype.org

       Screen shots are available!

       There are also three mailing lists:
       
       o freetype-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 subscription commands to:

           majordomo@freetype.org

       To  report bugs  please  use  send an  email  to the  address
       bugs@freetype.org --  if you  want help fixing  bugs, contact
       robert.wilhelm@freetype.org to be manually subscribed to this
       closed list.

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

  1. Did the API change since the version 1.3?

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

     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're really stuck, mail your question to:

       freetype@freetype.org

     We'll 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're welcome to volunteer for other platforms, like:

       Amiga, RISC OS, BeOS, and others

     Please contact devel@freetype.org for more information.



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.


IV. 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, Antoine Leca,
    and all the FreeType enthusiasts...


--- end of README ---
