freetype1/README

   1
   2
   3                            Welcome to the
   4
   5                   F R E E T Y P E    P R O J E C T
   6
   7                       http://www.freetype.org
   8
   9                             Release 1.3.1
  10
  11                    The FREE TrueType Font Engine
  12
  13     Copyright 1996 David Turner    <david.turner@freetype.org>
  14             - 1999 Robert Wilhelm  <robert.wilhelm@freetype.org>
  15                    Werner Lemberg  <werner.lemberg@freetype.org>
  16
  17
  18   Table of Contents
  19   -----------------
  20
  21     I. Introduction
  22
  23    II. The FreeType mini-FAQ
  24
  25   III. How to use the test programs
  26
  27       1. ftzoom
  28       2. ftlint
  29       3. ftview
  30       4. fttimer
  31       5. ftdump
  32       6. ftstring
  33       7. ftstrpnm
  34       8. fterror
  35       9. ftsbit
  36      10. ftmetric
  37      11. ftstrtto
  38
  39    IV. How to use the programs in the `contrib' directory
  40
  41     V. Final remarks
  42
  43
  44 I. Introduction
  45 ===============
  46
  47   Please read the file `INSTALL' for installation instructions!
  48
  49   The FreeType engine is a free and portable TrueType font rendering
  50   engine.  It  has been developed  to provide TrueType support  to a
  51   great variety of platforms and environments.
  52
  53   Notice that  FreeType is a *library*.   It is *not*  a font server
  54   for your preferred environment, even though it has been written to
  55   allow the design of many font servers.
  56
  57   To our knowledge, this  is the only royalty-free complete TrueType
  58   engine available.   Moreover, its  quality fully matches  these of
  59   Windows or  the Macintosh,  a thing that  cannot be said  for most
  60   other commercial engines available.
  61
  62   FreeType is  a clean-room implementation that is  not derived from
  63   the original TrueType engine developed by Apple and Microsoft.  It
  64   has  been created  with the  sole help  of the  published TrueType
  65   specifications, which, to our  great surprise and pain, turned out
  66   to be extremely  poor or misleading in critical  areas.  Much hard
  67   work   has  been   undertaken  to   solve   numerous  ambiguities;
  68   nevertheless, its end result is a portable, fast quality renderer!
  69
  70   The  library itself takes  about 55kByte  of Intel  code, complete
  71   with  a  TrueType  byte-code  interpreter and  a  high-performance
  72   scan-line converter.
  73
  74   You will find in this release:
  75
  76   - A TrueType engine, with source code in ANSI C and Pascal.
  77
  78     The  C source  code has  been successfully  compiled and  run on
  79     various  platforms, including  MS-DOS, OS/2,  Amiga,  Linux, and
  80     several other variants  of Unix.  It should be  portable to many
  81     other platforms too.
  82
  83     The Pascal  code has been  successfully compiled and run  on DOS
  84     (Borland's BP7)  and OS/2  (fPrint's Virtual Pascal).   A Delphi
  85     port  is  in  beta   (the  code  in  freetype/pascal  compiles).
  86     Unfortunately, it is not up to date compared to the C version.
  87
  88   - An  API to  be used  by  client applications  and font  servers,
  89     providing  several low level  abstractions that  can be  used to
  90     open font  files and collections,  create point sizes  and load,
  91     process and render glyph outlines and bitmaps.
  92
  93   - Support for the following features:
  94
  95     o Font smoothing, a.k.a. gray-level rendering.
  96
  97       Just  like Windows 95,  the renderer  uses a  `fine' algorithm
  98       that  only smoothes  diagonals and  curves, while  keeping the
  99       horizontal and vertical stems intact.
 100
 101       This results  in glyphs  that are much  more legible  than the
 102       `fuzzy' ones generated by programs like Acrobat.
 103
 104     o Support for all character mapping formats.
 105
 106     o A full-featured TrueType byte-code interpreter.
 107
 108       The engine  is able  to hint the  glyphs to  produce excellent
 109       output at small sizes.  It was extremely difficult to get this
 110       component right, due to  the ambiguous and misleading TrueType
 111       specifications.  However, we now *match* Windows and Macintosh
 112       qualities.
 113
 114     o TrueType  collection support, when several  fonts are embedded
 115       in the same file.
 116
 117     o Support for extensions.
 118
 119       It is now  possible to extend the library  in parts to support
 120       additional  features,  like   optional  tables  that  are  not
 121       considered by the current core engine.
 122
 123     o Kerning support.
 124
 125       Provided  as a  sample  extension with  this release,  kerning
 126       tables can  be accessed from a TrueType  font for applications
 127       that need it.
 128
 129     o Support for vertical metrics.
 130
 131       It is possible to load  vertical metrics when they are present
 132       in  a font  file.  Metrics  can be  retrieved glyph  by glyph,
 133       using the loader, or in arrays with a new API.
 134
 135     o Support for thread-safety and re-entrancy.
 136
 137       You will only need to specialize the file `ttmutex.c' for your
 138       platform to include system-specific synchronization calls.
 139
 140     o New in 1.3:  Support for embedded bitmaps.
 141
 142       This feature is already used in xtt, a TrueType font server
 143       for X Window System.
 144
 145   Note also that:
 146
 147   - Though development  of the library  is mainly performed  on OS/2
 148     and Linux, the library does not contain system-specific code.
 149
 150   - The  package contains  some graphics  drivers used  by  the test
 151     programs for  display purposes on MS-DOS, OS/2,  Amiga, and X11.
 152     These  drivers  are absolutely  not  mandatory  for running  the
 153     FreeType engine.  Some  console-mode test programs like `ftlint'
 154     or `ftdump' don't use graphics at all.
 155
 156   - FreeType 1.3 is binary compatible with 1.2, which means that you
 157     won't need to recompile your programs if they used the engine as
 158     a  shared  library  (libttf.so  on  Linux,  or  FreeType.dll  on
 159     Windows).   See the  file  `freetype/docs/changes.txt' for  more
 160     information about (minimal) API changes.
 161
 162
 163 II. The FreeType mini-FAQ
 164 =========================
 165
 166   Summary
 167
 168   0. Where to find the latest FreeType release?
 169
 170   1. Did the API change?
 171
 172   2. What does  the `Free' in FreeType  means?  Can you use  it in a
 173      commercial product? (YES!)
 174
 175   3. I have  made a small program  based on the test  programs but I
 176      would like to know how to do xxx?
 177
 178   4. When will I  be able to use FreeType  to display TrueType fonts
 179      under X11, OS/2 or Wine? (NOW!)
 180
 181   5. Trying  to  compile  the  FreeType  sources gives  me  lots  of
 182      warnings with my ANSI C compliant compiler!
 183
 184   ------------------------------------------------------------------
 185
 186   0. Where to find the latest FreeType release?
 187
 188      The  latest  package  is  usually uploaded  to  various  source
 189      repositories, like  SunSite, SimTel, or Hobbes.   There are two
 190      archive formats  (zip and tar.gz),  which also differ  by their
 191      CR/LF conventions.
 192
 193      * for DOS and OS/2: `ft-13.zip'
 194
 195        which should be available at:
 196
 197        Hobbes: ftp://ftp.cdrom.com/pub/os2/fonts
 198        SimTel: ftp://oak.oakland.edu/pub/simtel.net/msdos/graphics
 199
 200      * for UNIX and Amiga: `freetype-1.3.tar.gz'
 201
 202        look at:
 203
 204        SunSite: ftp://sunsite.unc.edu/pub/Linux/X11/fonts
 205
 206      * As uploading can take several days before the package becomes
 207        available to  the public, we  advise you to download  it from
 208        our own ftp site if you  read this message few days after the
 209        announcement at:
 210
 211          ftp://ftp.freetype.org/pub/freetype
 212
 213        Our home page is at:
 214
 215          http://www.freetype.org
 216
 217        Screen shots are available!
 218
 219        There are also three mailing lists:
 220
 221        o freetype-announce@freetype.org
 222
 223          Announcements  only  about  new  versions of  FreeType  and
 224          related packages.   This list is moderated  and expected to
 225          have very low traffic.
 226
 227        o freetype@freetype.org
 228
 229          Discusses  general  use  of  FreeType, future,  and  needed
 230          additions, as  well as many  other font-related discussions
 231          which do  not always relate  directly to the  FreeType code
 232          itself...
 233
 234        o devel@freetype.org
 235
 236          Discusses development,  design choices, portability issues,
 237          internals, specific licenses, etc.
 238
 239        To subscribe, send the usual subscription commands to:
 240
 241            majordomo@freetype.org
 242
 243        To  report bugs  please  use  send an  email  to the  address
 244        bugs@freetype.org --  if you  want help fixing  bugs, contact
 245        robert.wilhelm@freetype.org to be manually subscribed to this
 246        closed list.
 247
 248   ------------------------------------------------------------------
 249
 250   1. Did the API change since the version 1.2?
 251
 252      Only very marginally.  Please refer to `changes.txt'.
 253
 254   ------------------------------------------------------------------
 255
 256   2. What does  the `Free' in FreeType  means?  Can you use  it in a
 257      commercial product? (YES!)
 258
 259      We have placed this release under our special FreeType license.
 260
 261      It was inspired by the BSD, Artistic, and IJG (Independent JPEG
 262      group) licences,  which specifically encourage the  use of this
 263      software in commercial products!
 264
 265      The reason  we did this is  that we believe that  TrueType is a
 266      very useful  technology, and want  to make it available  on all
 267      machines and  platforms.  The license  is there to  ensure that
 268      the engine can be spread as widely as possible.
 269
 270      However,  free does  not mean  public domain.   This  engine is
 271      copyrighted by its authors, and they will fiercely defend their
 272      rights.
 273
 274   ------------------------------------------------------------------
 275
 276   3. I have  made a small program  based on the test  programs but I
 277      would like to know how to do xxx?
 278
 279      (Where   xxx   is   a   feature  lacking   from   the   current
 280      implementation).
 281
 282      First  of all, read  the documentation.   The user  guide gives
 283      some basic  hints and concepts.   You can also read  the source
 284      code of  the test  programs that you  didn't consider  yet.  If
 285      you're really stuck, mail your question to:
 286
 287        freetype@freetype.org
 288
 289      We'll try to help you.
 290
 291   ------------------------------------------------------------------
 292
 293   4. When will I  be able to use FreeType  to display TrueType fonts
 294      under X11, OS/2, or Wine?
 295
 296      You  can already  do that  under  X11 and  OS/2 :-)  Go to  the
 297      FreeType  web  page  (http://www.freetype.org)  for  up-to-date
 298      information.
 299
 300      And yes, it looks terrific!
 301
 302      For X11, you could also  take a look at `xfstt', an independent
 303      TrueType  font  server  for  Unix  which doesn't  rely  on  the
 304      FreeType code.
 305
 306      You're welcome to volunteer for other platforms, like:
 307
 308        Amiga, RISC OS, BeOS, and others
 309
 310      Please contact devel@freetype.org for more information.
 311
 312   ------------------------------------------------------------------
 313
 314   5. Trying  to  compile  the  FreeType  sources gives  me  lots  of
 315      warnings with my ANSI C compliant compiler!
 316
 317      We use gcc  as our reference compiler for  warnings. This means
 318      that we  use the `-ansi -pedantic  -Wall' flags and  try to get
 319      rid of warnings in this situation.
 320
 321      If you're  compiling with  another compiler, you  may encounter
 322      warnings, not errors.
 323
 324      We have  spent much efforts  to reduce seriously the  number of
 325      warnings  produced by  major compilers,  including  Visual Age,
 326      Visual C++ and Borland C++.
 327
 328      Note  that  the  Borland  compilers  seem to  produce  lots  of
 329      irrelevant warnings (like `potential loss of precision').
 330
 331
 332 III. How to use the test programs
 333 =================================
 334
 335   All  test programs  having a  graphic interface  use the  same key
 336   convention:
 337
 338     x :   fine counter_clockwise rotation
 339     c :   fine clockwise rotation
 340
 341     v :   fast counter_clockwise rotation
 342     b :   fast clockwise rotation
 343
 344     h :   toggle hinting on/off
 345     K :   toggle kerning on/off
 346     B :   toggle display of embedded bitmaps on/off
 347     G :   toggle GSUB on/off
 348
 349     + :   fast scale up
 350     - :   fast scale down
 351     u :   fine scale up
 352     j :   fine scale down
 353
 354     l :   go to next glyph
 355     k :   go to previous glyph
 356
 357     o :   go to tenth next glyph
 358     i :   go to tenth previous glyph
 359
 360     0 :   go to hundredth next glyph (useful for CJK fonts)
 361     9 :   go to hundredth previous glyph
 362
 363     ) :   go to thousandth next glyph
 364     ( :   go to thousandth previous glyph
 365
 366     } :   go to tenthousandth next glyph
 367     { :   go to tenthousandth previous glyph
 368
 369     q :
 370   ESC :   exit
 371
 372   These  keys  were  chosen   because  they  are  available  on  all
 373   platforms.  Note also that each program uses only a subset of this
 374   key map.
 375
 376   1. FTZOOM
 377   ---------
 378
 379     `ftzoom'  is  a very  simple  glyph  viewer  that supports  font
 380     smoothing.  Its usage is:
 381
 382         ftzoom [-g] [-p platformID -e encodingID]
 383                [-r resolution] [-z magnification] [-n] fontfilename
 384
 385     With -g you can  select gray-scaling;  with -n you can  suppress
 386     usage of the `post' table in the TrueType font.
 387
 388     For example:
 389
 390         ftzoom arial.ttf             to show the glyphs found
 391                                      in the Arial font
 392         ftzoom -g times.ttf          to show smoothed version of
 393                                      Times's glyphs.
 394         ftzoom -p 3 -e 1 uwjmg3.ttf  use cmap for platform ID 3,
 395                                      encoding ID 1 for this Japanese
 396                                      font.
 397
 398   2. FTLINT
 399   ---------
 400
 401     `ftlint' is used  to execute all glyphs instructions  found in a
 402     font file at a given char size size.  Its usage is:
 403
 404         ftlint pointsize fontfilename [fontfilename] ...
 405
 406     For example:
 407
 408         ftlint 12 arial.ttf
 409         ftlint 15 times.ttf
 410
 411     It  reports error  codes and  faulty glyph  numbers.  This  is a
 412     console tool that doesn't need the graphics subsystem.
 413
 414     NOTE: Trying to hint at sizes smaller than 7 is irrelevant.
 415
 416   3. FTVIEW
 417   ---------
 418
 419     A  font viewer that  supports hinting  and font  smoothing.  Its
 420     usage:
 421
 422         ftview [-g] -[r resolution] [-B] pointsize fontfilename
 423
 424     like in:
 425
 426         ftview 12 arial.ttf      show the hinted Arial at size 12pt.
 427
 428         ftview -g 15 timesi.ttf  show the hinted and font-smoothed
 429                                  Times at size 15pt.
 430
 431     `-r'  selects the resolution;  `-B' forces  the use  of embedded
 432     bitmaps.
 433
 434     Note that it is possible to change the point size during display
 435     with the  keys `u', `j', `+',  and `-'.  It is  also possible to
 436     browse the  whole glyph  set with the  `k', `l', `i',  `o', `0',
 437     `9', `(', `)', `{', and `}' keys (see key map above).
 438
 439     The OS/2  PM driver comes with an  additional magnifying window.
 440     The magnified  zone is  set with the  mouse, while the  scale is
 441     changed with the help of `PageUp' and `PageDown'.
 442
 443     Note 1: The  engine uses the font's CVT  program to determine at
 444             which size to enable or disable glyph hinting.  Don't be
 445             surprised to see unhinted glyphs at sizes < 7pt.
 446
 447     Note 2: Vertical drop-out  control has  been  added to  the gray
 448             scaling renderer.  As a consequence, the library doesn't
 449             produce  unpleasant results  at small  ppems  with badly
 450             hinted glyphs.
 451
 452   4. FTTIMER
 453   ----------
 454
 455     This program is used to benchmark FreeType's scan-converter (the
 456     component in charge of translating a vectorial shape description
 457     into a bitmap).  It does so in preloading all glyphs from a font
 458     file,  then rendering  them as  fast  as possible  in a  640x450
 459     buffer.  The glyphs are rendered at size 400pt / 96dpi, which is
 460     _quite_ big.
 461
 462     Its usage is:
 463
 464         fttimer [-g] [-v] fontfilename
 465
 466     where
 467
 468         -g : Asks for  gray-level  rendering  at size  200pt instead
 469              (a.k.a. font-smoothing).
 470
 471         -v : Asks for  the display of  the produced  bitmap.  Beware
 472              that  display  slows things  down  (display  on X11  is
 473              _terrible_,  especially with  gray-levels, but  this is
 474              not a problem for us :-).
 475
 476     Note that the returned numbers are not a benchmark of FreeType's
 477     overall  performance!   Only of  the  scan-line renderer  (which
 478     seems quite fast, apparently :-).
 479
 480     When  comparing measured  performances  across machines,  please
 481     only  consider the  undisplayed ones.   We're interested  in all
 482     kinds of results (please provide the following information:
 483
 484         font file
 485         number of rendered glyphs
 486         render time
 487         total time
 488         glyphs / s
 489         processor type
 490         CPU clock
 491
 492         and which compiler  used (with optimization involved)!  This
 493         can make a great difference!
 494
 495         etc.)
 496
 497   5. FTDUMP
 498   ---------
 499
 500     This  program is  a very  simple  font dumper.   In its  current
 501     incarnation, it will only  output a font's name table, character
 502     encoding maps  IDs and  total memory consumption.   For TrueType
 503     Open files, the available GSUB tables are also shown.
 504
 505     The `total memory  used' reported is the amount  that is used by
 506     the engine to load one face, with one instance (a point size).
 507
 508     Each additional  instance takes only a fraction  of that amount,
 509     and is labeled  by `instance object'.  As you  can see, FreeType
 510     isn't really greedy.
 511
 512        Usage:   ftdump fontpathname[.ttf|.ttc]
 513
 514   6. FTSTRING
 515   -----------
 516
 517     This  program  demonstrates  string  text generation.   It  only
 518     displays a given  message on the screen, and  lets you resize it
 519     with the classic key bindings `u', `j', `+', and `-'.
 520
 521     Usage:
 522
 523         ftstring  ptsize  fontname[.ttf|.ttc]  [message_string]
 524
 525     If  the  message is  omitted,  it  will  revert to  the  classic
 526     typographic test sentence:
 527
 528         The quick brown fox jumps over the lazy dog
 529
 530     which is made of all letters of the English alphabet.
 531
 532     `ftstring'  only works with  font files  that contain  a Unicode
 533     character  mapping  table   (either  Windows  Unicode  or  Apple
 534     Unicode).   For the  moment,  the message  can  however only  be
 535     written in ASCII, as accents aren't supported yet.
 536
 537   7. FTSTRPNM
 538   -----------
 539
 540     Usage:
 541
 542         ftstrpnm [options] filename [string]
 543
 544     Options:
 545
 546       -g      gray-level rendering (default: off)
 547       -h      hinting off (default: on)
 548       -r X    resolution X dpi (default: 96)
 549       -p X    pointsize X pt (default: 12)
 550       -b X    border X pixels wide (default: 0)
 551
 552     This  program is  quite  similar to  ftstring  but converts  the
 553     rendered image of  the specified string into a  bitmap in PBM or
 554     PGM  format written  to stdout;  PBM (Portable  BitMap)  and PGM
 555     (Portable GrayMap)  formats can be further  converted to popular
 556     graphics  formats like  GIF or  PNG with  the netpbm  tool suite
 557     available via Internet.
 558
 559   8. FTERROR
 560   ----------
 561
 562     This program tests the gettext() functionality on UNIX platforms
 563     (usually provided  in the GNU gettext package).   It will return
 564     language specific  error and warning messages  depending on your
 565     locale.   Currently French,  Dutch, Spanish,  German,  and Czech
 566     translations of the FreeType  messages are included -- we invite
 567     you to contribute more translations.
 568
 569     Typically, you have to set the LANG environment variable to your
 570     locale to get localized messages.  Example:
 571
 572       LANG=de fterror
 573
 574     Note  that providing  message strings  for FreeType's  error and
 575     warning messages  is an extension  and not part of  the FreeType
 576     library  itself.  Please  refer to  `docs/i18n.txt'  for further
 577     details.
 578
 579   9. FTSBIT
 580   ---------
 581
 582     Usage:
 583
 584         ftsbit ppem fontname[.ttf|.ttc] glyph_index [glyph_index2..]
 585
 586     This  tool dumps  the  information in  the  tables for  embedded
 587     bitmaps.  Additionally,  it prints  (to the console)  a selected
 588     glyph bitmap.
 589
 590  10. FTMETRIC
 591  ------------
 592
 593     Usage:
 594
 595         ftmetric [options below] point fontname[.ttf|.ttc] ...
 596
 597         -B        show sbit's metrics (default: none)
 598         -c C      use C'th font index of TrueType collection
 599                   (default: 0)
 600         -i index  glyph index (default: 0)
 601         -r R      use resolution R dpi (default: 72dpi)
 602
 603     With this  small program  you can inspect  the metric data  of a
 604     given glyph; additionally, it  dumps the particular glyph to the
 605     console.
 606
 607   11. FTSTRTTO
 608   ------------
 609
 610     Usage:
 611
 612         ftstrtto [options below] ppem fontname[.ttf|.ttc] [string|-]
 613
 614         -c C   use font with index C in TrueType collection
 615                (default: 0)
 616         -f F   use feature F (can be specified more than once)
 617         -g     gray-level rendering
 618         -l L   use language L
 619         -r R   use resolution R dpi (default: 96dpi)
 620         -s S   use script S
 621         -u     interpret input data as UTF8-encoded
 622         -v     display string vertically
 623         -x     display string from right to left
 624
 625       F, L, and S must be specified as 4-character tags.
 626       Specifying only F and S selects default language system of S.
 627       Specifying only L and S selects the req. feature of L only
 628       (if any).
 629
 630       If `-' is specified as input string, stdin is read instead.
 631
 632     This program uses  almost all features of FreeType  to display a
 633     string on screen.   Its usage is similar to  `ftstring', but you
 634     can additionally select GSUB features, the collection in a font,
 635     toggle kerning and embedded bitmaps interactively, and input the
 636     optional string in UTF8 encoding.
 637
 638     For  a list  of  available script,  language,  and feature  tags
 639     please   refer   to   the   TrueType   Open   (resp.   OpenType)
 640     specification.
 641
 642     Example:
 643
 644       ftstrtto -s "latn" -l "DEU " -f "liga" -f "frac" \
 645                40 pala.ttf "fi ff ffi ffl 1/2"
 646
 647     Note  that you can  inspect the  available tags  in a  font with
 648     `ftdump'.
 649
 650     The features `init', `medi',  and `fina', and `isol' are treated
 651     specially.    Internally,  ftstrtto  assigns   initial,  medial,
 652     isolated, and final properties to Arabic characters in the input
 653     string.  If one of the  features is switched on, all glyphs with
 654     the corresponding property are modified (if covered).
 655
 656     Example:
 657
 658       ftstrtto -s arab -f init -f medi -f fina -f isol \
 659                -f liga -f mset -x -u 20 trado.ttf - < arab.utf8
 660
 661     `mset' is another, Arabic specific feature to position combining
 662     marks.
 663
 664     If  you   select  the   swash  feature  `swsh',   the  displayed
 665     alternative in the string is always the first available one.
 666
 667
 668
 669 IV. HOW TO USE THE PROGRAMS IN THE `CONTRIB' DIRECTORY
 670 ======================================================
 671
 672   These programs  are contributions to FreeType and  not really part
 673   of  it.  Please  read the  documentation files  in  the respective
 674   subdirectories how to compile and install them.
 675
 676
 677 V. FINAL REMARKS
 678 ================
 679
 680 Of course,  all source  code is provided  `as is'.  Please  read the
 681 file `license.txt' for more information.
 682
 683 We hope you will find this  engine useful, and look forward to file.
 684 your feed-back.  We're of course  very interested in bug reports, as
 685 well as FreeType success stories :-)
 686
 687
 688 Thanks for your time and consideration,
 689
 690
 691     David Turner, Robert Wilhelm, Werner Lemberg,
 692     and all the FreeType enthusiasts...
 693
 694
 695 --- end of README ---