freetype1/docs/optimize.txt

   1
   2                     FreeType Optimization HOWTO
   3
   4
   5
   6 Introduction
   7 ============
   8
   9   This file describes several ways to improve the performance of the
  10   FreeType  engine  on  specific  builds.   Each  `trick'  has  some
  11   drawbacks, be it on code size or portability.
  12
  13   The  performance  improvement  cannot  be quantified  here  simply
  14   because id depends significantly on platforms _and_ compilers.
  15
  16
  17
  18 I. Tweaking the configuration file
  19 ==================================
  20
  21   The FreeType configuration file  is named `ft_conf.h' and contains
  22   the definition  of various macros  that are used to  configure the
  23   engine at build time.
  24
  25   Apart from  the Unix configuration  file, which is  generated when
  26   calling the `configure' script from the template called
  27
  28     freetype/ft_conf.h.in    ,
  29
  30   all configuration files are located in
  31
  32     freetype/lib/arch/<system>/ft_conf.h    ,
  33
  34   where  <system>  stands  for  your platform.   This  release  also
  35   provides an `ansi' build, i.e., the directory `lib/arch/ansi' used
  36   to compile with any ANSI-compliant compiler.
  37
  38   The configuration macros that  relate to performance are described
  39   next.
  40
  41
  42   1. TT_CONFIG_OPTION_INTERPRETER_SWITCH
  43   --------------------------------------
  44
  45     If set,  this macro builds  a bytecode interpreter which  uses a
  46     huge  `switch' statement  to  parse the  bytecode stream  during
  47     glyph hinting.
  48
  49     If unset,  the interpreter  uses a big  jump table to  call each
  50     bytecode's routine.
  51
  52     This macro is *set* by default.  However, it may be worthwile on
  53     some platforms to unset it.
  54
  55     Note      that      this      macro      is      ignored      if
  56     TT_CONFIG_OPTION_NO_INTERPRETER is set.
  57
  58
  59   2. TT_CONFIG_OPTION_STATIC_INTERPRETER
  60   --------------------------------------
  61
  62     If set,  this macro builds  a bytecode interpreter which  uses a
  63     static variable  to store its  state.  On some  processors, this
  64     will produce code which is bigger but slightly faster.
  65
  66     Note  that you  should NOT  DEFINE  this macro  when building  a
  67     thread-safe version of the engine.
  68
  69     This macro is *unset* by default.
  70
  71
  72   3. TT_CONFIG_OPTION_STATIC_RASTER
  73   ---------------------------------
  74
  75     If set,  this macro  builds a scan-line  converter which  uses a
  76     static variable to store  its state.  On some processors, though
  77     depending on the compiler used,  this will produce code which is
  78     bigger but moderately faster.
  79
  80     Note  that you  should NOT  DEFINE  this macro  when building  a
  81     thread-safe version of the engine.
  82
  83     This macro is *unset* by  default.  We do not recommend using it
  84     except for extreme cases where a performance `edge' is needed.
  85
  86
  87
  88 II. Replacing some components with optimized versions
  89 =====================================================
  90
  91   You can also, in order to improve performance, replace one or more
  92   components  from   the  original  source  files.    Here  are  our
  93   suggestions.
  94
  95
  96   1. Use memory-mapped files whenever available
  97   ---------------------------------------------
  98
  99     Loading a  glyph from a  TrueType file needs many  random seeks,
 100     which take a lot of time when using disk-based files.
 101
 102     Whenever   possible,  use   memory-mappings   to  improve   load
 103     performance dramatically.  For an example, see the source file
 104
 105       freetype/lib/arch/unix/ttmmap.c
 106
 107     which uses Unix memory-mapped files.
 108
 109
 110   2. Replace the computation routines in `ttcalc.c'
 111   ---------------------------------------------------
 112
 113     This file contains many  computation routines that can easily be
 114     replaced by  inline-assembly, tailored for  a specific processor
 115     and/or compiler.
 116
 117     After  heavy  testing,  we  have  found  that  these  functions,
 118     especially TT_MulDiv(),  are the ones that  are most extensively
 119     used and called when loading glyphs from a font file.
 120
 121     We do not provide inline-assembly  with this release, as we want
 122     to  emphasize the  portability  of our  library.  However,  when
 123     working on a specific project  where the hardware is known to be
 124     fixed  (like on  an  embedded system),  great performance  gains
 125     could be achieved by replacing these routines.
 126
 127     (By the way, the square root  function is not optimal, but it is
 128     very  seldom  called.   However,  its  accuracy  is  _critical_.
 129     Replacing it with a fast  but inaccurate algorithm will ruin the
 130     rendering of glyphs at small sizes.)
 131
 132
 133
 134 III. Measuring performance improvements
 135 =======================================
 136
 137   Once you  have chosen some  improvements and rebuilt  the library,
 138   some quick ways to measure the `new' speed are:
 139
 140   - Run  the test program  `ftlint' on  a directory  containing many
 141     TrueType fonts, and measure the time it takes.  On Unix, you can
 142     use the shell command `time' to do it like in
 143
 144       % time test/ftlint 10 /ttfonts/*.ttf
 145
 146     This will  measure the  performance improvement of  the TrueType
 147     interpreter.
 148
 149   - Run the test program `fttimer' on a font containing many complex
 150     glyphs (the  latest available versions of Times  or Arial should
 151     do it), probaby using anti-aliasing, as in:
 152
 153       % time test/fttimer -g /ttfonts/arial.ttf
 154
 155   Compare the results of several of these runs for each build.
 156
 157
 158 --- end of OPTIMIZE ---