home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: SysTools / SysTools.zip / ft-beta.zip / freetype / HOWTO < prev    next >
Text File  |  1997-10-06  |  20KB  |  574 lines
  1. The FreeType compilation HOWTO
  2.  
  3.  
  4. Introduction
  5.  
  6. I. Quick compilation
  7.  
  8.   1. Unix
  9.   2. OS/2
  10.   3. MS-DOS
  11.   4. Amiga
  12.  
  13. II. Package layout
  14.  
  15.   1. The library
  16.   2. The test programs
  17.   3. ttf2bdf
  18.  
  19. III. Compilation steps
  20.  
  21.   1. Compiling the library
  22.   2. Compiling the graphics subsystem & driver
  23.   3. Compiling the test programs
  24.  
  25. IV. Test programs usage and additional notes
  26.  
  27.   1. zoom
  28.   2. lint
  29.   3. view
  30.   4. timer
  31.   5. ftdump
  32.   6. ftstring
  33.  
  34. ---------------------------------------------------------------------------
  35.  
  36. Introduction:
  37.  
  38. This  file describes  the steps  that are  necessary to  compile the
  39. files  found in this  package.  Section  I contains  instructions to
  40. compile   the    package   'out-of-the-box'   on    a   variety   of
  41. platforms/compilers.  Section  II gives  the detailed layout  of the
  42. package's  files,   a  necessary  understanding   for  the  detailed
  43. compilation steps given in section III.
  44.  
  45. This package,  known as the  FreeType Public Beta,  contains several
  46. things:
  47.  
  48.  - a beta  version of the  FreeType library, contained in  the 'lib'
  49.    directory. The library  is written in portable ANSI  C. It should
  50.    compile fine with any type of ANSI C compiler.
  51.  
  52.    Note  that 16  bit compilers  are  not fully  supported yet  (the
  53.    library compiles, though).
  54.  
  55.  - a  set of  test programs,  found  in the  directory 'test'  which
  56.    provide:
  57.  
  58.     - A  small  graphics  subsystem  used  to  display  the  bitmaps
  59.       produced by the  library, on a great variety  of systems.  The
  60.       subsystem is made of several files:
  61.  
  62.         - a  set of  common files  (gmain.h, gmain.c,  gdriver.h and
  63.           gevents.h)
  64.  
  65.         - some  system-specific   drivers  used  to   implement  the
  66.           interface found in 'gdriver.h' and 'gevents.h' (gfs_dos.c,
  67.           gfs_os2.c, gwin_x11.c, etc).  The X11 driver is located in
  68.           "test", while others  are located in architecture-specific
  69.           directories (example: "test/arch/os2/gpm_os2.c").
  70.  
  71.     - Several test  programs which use the library  and the graphics
  72.       subsystem:
  73.  
  74.         - zoom:     A simple glyph viewer.  Supports composite glyph
  75.                     loading, font smoothing.
  76.  
  77.         - lint:     A  simple glyph  instruction verifier.   Used to
  78.                     execute all glyphs  instructions found in a font
  79.                     file at a given  ppem size.  Useful to find bugs
  80.                     in the library and/or font files.
  81.  
  82.         - view:     A simple  font viewer.  Supports  font smoothing
  83.                     and hinting!
  84.  
  85.         - timer:    Performance   timer   used   to  benchmark   the
  86.                     scan-line   converter.   Supports   display  and
  87.                     font-smoothing.
  88.  
  89.         - ftdump:   A very simple font information dumper.
  90.  
  91.         - ftstring: A  simple program to  display a given  string or
  92.                     message in a given  font, at a given point size.
  93.                     Note  that  the advance  width  is not  computed
  94.                     correctly yet in some cases.
  95.  
  96.   - a  conversion  tool, called  ttf2bdf,  which  uses the  FreeType
  97.     library to produce bitmaps in  BDF format (used with X Windows),
  98.     located in the directory "tools/ttf2bdf/".
  99.  
  100. -----------------------------------------------------------------------------
  101.  
  102. I. Quick compilation:
  103.  
  104.   NOTE: With  the exception of Unix,  all system-dependent makefiles
  105.         and  configuration  files  are  located in  the  directories
  106.         lib/arch/platform/ and test/arch/platform/.
  107.  
  108.   1. Unix:
  109.  
  110.     We provide  a 'configure' script that  will automatically create
  111.     configuration and Makefile files in all relevant directories.
  112.  
  113.     Graphics display is performed through X11 only, which means that
  114.     the performance measured by 'timer' with display 'on' should not
  115.     be considered as 'informative'.
  116.  
  117.     You  will need gcc  and GNU  make to  compile currently.   It is
  118.     however  possible  to   compile  everything  with  another  ANSI
  119.     compiler by modifying only the Makefiles.
  120.  
  121.     Go to your 'freetype' directory, then type 'configure'.
  122.  
  123.     After several seconds, you'll be able to launch GNU make (either
  124.     'make' or 'gmake') to build the package.  You'll then be able to
  125.     run the test programs with your font files.
  126.     
  127.     Please jump to section IV for usage descriptions.
  128.  
  129.     If not using  gcc and gmake, please read sections  II and III to
  130.     learn how to compile the package for your own system.
  131.  
  132.     NOTE: beware that 'view' is often  used as an alias for the 'vi'
  133.           editor  on  some  Unix  systems.  In these  cases,  it  is
  134.           preferable  to type './view  ppem fontfile.ttf'  to invoke
  135.           the program.
  136.  
  137.           If you  end up stuck in  'vi', type ':q' or  ':q!' to exit
  138.           it...
  139.  
  140.  
  141.   2. OS/2:
  142.  
  143.     We  provide two  makefiles for  OS/2, located  in test/arch/os2.
  144.     Note  that you  must be  located  in the  "test" directory  when
  145.     invoking these files.
  146.  
  147.     makefile.emx: This file must be  used with GNU make and gcc/emx.
  148.                   It builds a version  of the test programs that use
  149.                   a PM  display window (xxx.exe) and  a version that
  150.                   uses the full-screen display driver (xxxfs.exe).
  151.  
  152.                   To use it, go to your 'test' directory, then type:
  153.  
  154.                      make -f arch/os2/makefile.emx
  155.  
  156.                   Note  that PM display  programs like  'timer' hide
  157.                   their output. To view the messages, go to the OS/2
  158.                   prompt and redirect stderr with
  159.  
  160.                       timer  -v  arial 2> log.txt
  161.  
  162.                   Then view "log.txt"
  163.  
  164.     makefile.icc: This  file must be  used with Visual Age  C++.  It
  165.                   uses  the full-screen  display  driver (PM  hasn't
  166.                   been tested yet) but can be easily modified.
  167.  
  168.                   You need  nmake. Go to the  'test' directory, then
  169.                   type:
  170.  
  171.                      nmake arch\os2\makefile.icc
  172.  
  173.     For other compilers, please read sections II and III to know how
  174.     to compile  the package on  your system.  You're welcome  to add
  175.     new makefiles and  send them to us, as long  as they respect our
  176.     current location conventions.
  177.  
  178.  
  179.   3. MS-DOS and clones:
  180.  
  181.     We  only  provide one  makefile  for  the  gcc/emx compiler  for
  182.     MS-DOS.  Please read the  note relative  to makefile.emx  in the
  183.     OS/2 section above, replacing 'arch/os2' by 'arch/msdos'.
  184.  
  185.     There is only one full-screen display driver for MS-DOS.
  186.  
  187.     For other compilers, please read sections II and III to know how
  188.     to compile  the package on  your system.  You're welcome  to add
  189.     new makefiles and  send them to us, as long  as they respect our
  190.     current location conventions.
  191.  
  192.  
  193.   4. Amiga:
  194.  
  195.     You will need gcc and GNU make for Amiga to compile the package.
  196.     Go to the 'test' directory, then type:
  197.  
  198.       make -f arch/amigaos/makefile.gcc
  199.  
  200.     The arch/amigaos  contains two display drivers  (full screen and
  201.     windowed).  The default driver is the windowed one, but this can
  202.     be changed easily in the makefile.
  203.  
  204.     For other compilers, please read sections II and III to know how
  205.     to compile the package on your system. You're welcome to add new
  206.     makefiles  and send  them to  us, as  long as  they  respect our
  207.     current location conventions.
  208.  
  209. ----------------------------------------------------------------------------
  210.  
  211. II. Package Layout:
  212.  
  213.   Here is  a more  thorough description of  the package's  files and
  214.   layout.
  215.  
  216.  # The 'test' directory:
  217.  
  218.     Contains the graphics subsystem's common files.
  219.  
  220.        gmain.h
  221.        gmain.c
  222.        gdriver.h
  223.        gevents.h
  224.  
  225.     where 'gdriver.h'  is the interface that must  be implemented by
  226.     all display drivers used by the subsystem.
  227.  
  228.     Note that the  graphics subsystem is _not_ part  of the library,
  229.     it's just a  way we found to display  the engine's production on
  230.     several systems.
  231.  
  232.     The  Unix X11  windowed  driver is  called  'gwin_x11.c' and  is
  233.     located in  the 'test' directory.  For all  other platforms, the
  234.     drivers are located in architecture dependent directories of the
  235.     form:
  236.  
  237.        test/arch/system
  238.  
  239.     where 'system' can be 'os2', 'amigaos' or 'dos' currently.
  240.  
  241.     We  provide  several  display  driver  implementations  on  some
  242.     platforms:
  243.  
  244.        test/arch/os2/gfs_os2.c  - full-screen OS/2 driver
  245.        test/arch/os2/gpm_os2.c  - PM OS/2 driver
  246.  
  247.        test/arch/amigaos/gfsamiga.c  - full-screen Amiga driver
  248.        test/arch/amigaos/gw_amiga.c  - windowed Aniga driver
  249.  
  250.        test/arch/msdos/gfs_dos.c  - full-screen DOS driver
  251.  
  252.     You'll need to compile one of these drivers for your system, and
  253.     link  it  to  the  test  programs  together  with  the  compiled
  254.     'gmain.c'.
  255.  
  256.     It also contains several test files:
  257.  
  258.        view.c     -- font viewer
  259.        lint.c     -- font instruction checker.  Text mode only.
  260.        timer.c    -- performance tester
  261.        zoom.c     -- simple glyph viewer
  262.        ftdump.c   -- simple font dumper
  263.        ftstring.c -- simple string text generation program
  264.  
  265.        fdebug.c   -- short debugger;  you need to  compile ttdebug.c
  266.                   -- and  ttins.c in  the c/lib  directory  with the
  267.                   -- DEBUG  constant defined  to use  it.  Text mode
  268.                   -- only.  Makes sense for development only.
  269.  
  270.  # The 'lib' directory:
  271.  
  272.     Contains the engine's source code.
  273.  
  274.     The engine  is made of  several components, each one  having its
  275.     name  beginning  with  a  'tt'  prefix  like  ttmemory,  ttfile,
  276.     ttraster, etc.
  277.  
  278.     All components rely on the 'freetype.h' interface file (which is
  279.     doomed to become the only  high level interface to the library),
  280.     and  'ttconfig.h'  (which  is  used  to  generate  configuration
  281.     macros).
  282.  
  283.     Note  that   'ttconfig.h'  relies  heavily  on   a  file  called
  284.     'ft_conf.h'  that  contains information  related  to the  target
  285.     platform.  The  ft_conf.h file  is generated by  the 'configure'
  286.     script  under Unix.   For other  systems, it  is located  in the
  287.     lib/arch/system/ directory:
  288.  
  289.        lib/arch/os2/ft_conf.h
  290.        lib/arch/amigaos/ft_conf.h
  291.        lib/arch/msdos/ft_conf.h
  292.  
  293.     It should be pretty obvious  to create a new ft_conf.h file from
  294.     a current one: just copy  it and define/undefine the macros that
  295.     are relevant to your platform.
  296.  
  297.  # The 'lib/extend' directory:
  298.  
  299.     This directory  contains the current core  engine extensions. To
  300.     know  more  about  extensions,  read  the user  guide  found  in
  301.     "docs/user.txt".
  302.  
  303. ----------------------------------------------------------------------------
  304.  
  305. III. Detailed Compilation Steps:
  306.  
  307.   You must  perform the following  steps to compile this  package by
  308.   hand:
  309.  
  310.   1. Compile the library:
  311.  
  312.      with gcc, go to the 'lib' directory, then type
  313.  
  314.        gcc -c -Wall -ansi -pedantic -O2 tt*.c -I.. -Iextend
  315.  
  316.      for Unixish systems or
  317.  
  318.        gcc -c -Wall -ansi -pedantic -O2 tt*.c -Iarch/system -Iextend
  319.  
  320.      for other platforms.
  321.  
  322.      The flags mean:
  323.  
  324.        -c        : compile only.
  325.  
  326.        -Wall     : display all warnings during compilation.
  327.  
  328.        -ansi     : check for ANSI conventions.
  329.  
  330.        -pedantic : be _very_ pedantic when checking ANSI convention.
  331.  
  332.        -O        : optimization level.
  333.  
  334.        -I..      : add  '..'  or 'arch/system'  as  an include  dir.
  335.                    This  line is  requested  to give  access to  the
  336.                    'ft_conf.h' file.
  337.  
  338.  
  339.   2. Compile the graphics subsystem:
  340.  
  341.      a. compile the subsystem in the 'test' dir:
  342.  
  343.        gcc -c -ansi -Wall gmain.c
  344.  
  345.      b. compile the display driver in the 'test' dir:
  346.  
  347.        gcc -c -Wall gwin_x11.c -o gdriver.o
  348.  
  349.      for Unixish systems (see note below) or
  350.  
  351.        gcc -c -Wall arch/system/yourdriver.c -o gdriver.o
  352.  
  353.      for other platforms.   Of course, don't forget to  add the path
  354.      to your system's display libraries.
  355.  
  356.      NOTE: You may need to  include the path to your 'ft_conf.h' and
  357.            to the  library directory for some  drivers (for example,
  358.            the X11 driver relies on 'tttypes.h', which relies itself
  359.            on 'ft_conf.h').
  360.  
  361.  
  362.   3. Compile the test programs in the 'test' directory:
  363.  
  364.      Usually with something like:
  365.  
  366.         gcc -ansi -Wall -O testprogram.c \
  367.             ../lib/*.o gmain.o gdriver.o \
  368.             -I<path_to_ft_conf.h> -I../lib
  369.  
  370.      with additional libraries ('\' indicate a line continuation).
  371.  
  372.      Have a look  at the supplied makefiles to get  a better idea of
  373.      the required flags/commands.
  374.  
  375.      You should now be able to run the test programs.
  376.  
  377. ----------------------------------------------------------------------------
  378.  
  379. IV. Test programs usage:
  380.  
  381.   NOTE: All  test programs having  a graphic interface use  the same
  382.         key convention:
  383.  
  384.     x :   fine counter_clockwise rotation (not implemented yet)
  385.     c :   fine clockwise rotation (not implemented yet)
  386.  
  387.     v :   fast counter_clockwise rotation (not implemented yet)
  388.     b :   fast clockwise rotation (not implemented yet)
  389.  
  390.     + :   fast scale up
  391.     - :   fast scale down
  392.     u :   fine scale up
  393.     j :   fine scale down
  394.  
  395.     l :   go to next glyph
  396.     k :   go to previous glyph
  397.  
  398.     o :   go to tenth next glyph
  399.     i :   go to tenth previous glyph
  400.  
  401.     9 :   go to hundredth next glyph (useful for CJK fonts)
  402.     0 :   go to hundredth previous glyph
  403.  
  404.     h :   in view,  this key disables glyph hinting.  This is useful
  405.           to spot incorrect glyphs in  a broken font file (or simply
  406.           when the  font file has a "feature"  that isn't recognized
  407.           by the interpreter yet... damn TrueType specs!)
  408.  
  409.     q :
  410.   ESC :   exit
  411.  
  412.   These  keys  were  chosen   because  they  are  available  on  all
  413.   platforms.  Note also that each program uses only a subset of this
  414.   key map.
  415.  
  416.  
  417.   1. Zoom:
  418.  
  419.        Zoom is  a very simple  glyph viewer that  supports composite
  420.        glyph loading as well as font smoothing. Its usage is:
  421.  
  422.           zoom [-g] [-p platform -e encodingID] fontfilename
  423.  
  424.        For example:
  425.  
  426.          zoom arial.ttf             to show the glyphs found
  427.                                     in the Arial font
  428.          zoom -g times.ttf          to show smoothed version of
  429.                                     Times's glyphs.
  430.          zoom -p 3 -e 1 uwjmg3.ttf  use cmap for platform 3,
  431.                                     encoding ID 1 for this Japanese
  432.                                     font.
  433.  
  434.  
  435.   2. Lint:
  436.  
  437.        Lint is  used to execute  all glyphs instructions found  in a
  438.        font file at a given ppem size. Its usage is:
  439.  
  440.           lint pointsize fontfilename [fontfilename] ...
  441.  
  442.        For example:
  443.  
  444.           lint 12 arial.ttf
  445.           lint 15 times.ttf
  446.  
  447.        It reports error  codes and faulty glyph numbers.   This is a
  448.        console tool that doesn't need the graphics subsystem.
  449.  
  450.        It's  a  production  tool,  so  don't get  surprised  to  see
  451.        numerical   error   codes   (the   list  is   in   the   file
  452.        'lib/freetype.h' anyway).
  453.  
  454.        NOTE: Trying to hint at sizes smaller than 7 is irrelevant.
  455.  
  456.   3. View:
  457.  
  458.        A font  viewer that supports hinting and  font smoothing. Its
  459.        usage:
  460.  
  461.           view [-g] pointsize fontfilename
  462.  
  463.        like in:
  464.  
  465.          view 12 arial.ttf       show the hinted Arial at size 12pt.
  466.  
  467.          view -g 15 timesi.ttf   show the hinted and font-smoothed
  468.                                  Times at size 15pt.
  469.  
  470.        Note  that it  is possible  to change  the point  size during
  471.        display  with the  keys 'u',  'j', '+'  and '-'.  It  is also
  472.        possible to  browse the  whole glyph set  with the  'k', 'l',
  473.        'i', 'o', '9' and '0' keys (see key map above).
  474.  
  475.        The  OS/2  PM  driver  comes with  an  additional  magnifying
  476.        window.   The magnified  zone is  set with  the  mouse, while
  477.        scale is changed with the help of 'PageUp' and 'PageDown'.
  478.  
  479.        Note1: the engine uses the font's CVT program to determine at
  480.               which size to enable  or disable glyph hinting.  Don't
  481.               be surprised to see unhinted glyphs at sizes < 7pt.
  482.  
  483.        Note2: the  current  gray-scaling  algorithm  doesn't use  an
  484.               intermediate bitmap to produce filtered pixmaps.  This
  485.               implies (for  some technical reasons)  that it doesn't
  486.               perform  horizontal dropout  controls.   This results,
  487.               for  badly  hinted glyphs,  in  disappearance of  some
  488.               horizontal stems at small sizes.
  489.  
  490.               This is  more a  feature than a  bug, as  its solution
  491.               lies in changing the test programs, and not the engine
  492.               itself.  We'll fix them in the final FreeType release.
  493.  
  494.   4. Timer:
  495.  
  496.        This program  is used to  benchmark FreeType's scan-converter
  497.        (the  component in  charge of  translating a  vectorial shape
  498.        description  into a bitmap).   It does  so in  preloading all
  499.        glyphs  from a  font file,  then  rendering them  as fast  as
  500.        possible  in a 640x450  buffer.  The  glyphs are  rendered at
  501.        size 400pt / 96dpi, which is _quite_ big.
  502.  
  503.        Its usage is:
  504.  
  505.           timer [-g] [-v] fontfilename
  506.  
  507.        where
  508.  
  509.           -g : asks for  gray-level rendering at  size 200pt instead
  510.                (a.k.a. font-smoothing)
  511.  
  512.           -v : asks  for the display of the  produced bitmap. Beware
  513.                that  display slows  things down  (display on  X11 is
  514.                _terrible_, especially with  gray-levels, but this is
  515.                not a problem for us :-).
  516.  
  517.        When comparing measured  performances across machines, please
  518.        only consider the undisplayed  ones.  We're interested in all
  519.        kinds of results (please provide the following information:
  520.  
  521.            font file
  522.            number of rendered glyphs
  523.            render time
  524.            total time
  525.            glyphs / s
  526.            processor type
  527.            CPU clock
  528.  
  529.            and compiler used  (with optimization involved)! This can
  530.            make a great difference!
  531.  
  532.            etc.)
  533.  
  534.   5. ftdump:
  535.  
  536.        This program  is a very  simple font dumper.  In  its current
  537.        incarnation,  it  will  only  output  a  font's  name  table,
  538.        character encoding maps IDs and total memory consumption.
  539.  
  540.        The "total memory  used" reported is the amount  that is used
  541.        by the  engine to load one  face, with one  instance (a point
  542.        size).
  543.  
  544.        Each  additional  instance  takes  only a  fraction  of  that
  545.        amount, and is labeled by "instance object".  As you can see,
  546.        FreeType isn't really greedy.
  547.  
  548.        Usage:   ftdump fontpathname[.ttf|.ttc]
  549.  
  550.  
  551.   6. ftstring:
  552.  
  553.        This  program demonstrates  string text  generation.  It only
  554.        displays a given  message on the screen, and  lets you resize
  555.        it with the classic key bindings "u", "j", "+" and "-".
  556.  
  557.        Usage:
  558.  
  559.           ftstring  ptsize  fontname[.ttf|.ttc]  [message_string]
  560.  
  561.        If  the message  is omitted,  it will  revert to  the classic
  562.        typographic test sentence:
  563.  
  564.           The quick brown fox jumps over the lazy dog
  565.  
  566.        which is made of all letters of the English alphabet.
  567.  
  568.        Ftstring only  works with font  files that contain  a Unicode
  569.        character  mapping  table (either  Windows  Unicode or  Apple
  570.        Unicode).  For  the moment, the  message can however  only be
  571.        written in ASCII, as accents aren't supported yet.
  572.  
  573. --- end of HOWTO ---
  574.