summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype/freetype-1.5/docs/optimize.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/freetype/freetype-1.5/docs/optimize.txt')
-rw-r--r--Build/source/libs/freetype/freetype-1.5/docs/optimize.txt181
1 files changed, 181 insertions, 0 deletions
diff --git a/Build/source/libs/freetype/freetype-1.5/docs/optimize.txt b/Build/source/libs/freetype/freetype-1.5/docs/optimize.txt
new file mode 100644
index 00000000000..2f7af918eca
--- /dev/null
+++ b/Build/source/libs/freetype/freetype-1.5/docs/optimize.txt
@@ -0,0 +1,181 @@
+
+ FreeType Optimization HOWTO
+
+
+
+Introduction
+============
+
+ This file describes several ways to improve the performance of the
+ FreeType engine on specific builds. Each `trick' has some
+ drawbacks, be it on code size or portability.
+
+ The performance improvement cannot be quantified here simply
+ because id depends significantly on platforms _and_ compilers.
+
+
+
+I. Tweaking the configuration file
+==================================
+
+ The FreeType configuration file is named `ft_conf.h' and contains
+ the definition of various macros that are used to configure the
+ engine at build time.
+
+ Apart from the Unix configuration file, which is generated when
+ calling the `configure' script from the template called
+
+ freetype/ft_conf.h.in ,
+
+ all configuration files are located in
+
+ freetype/lib/arch/<system>/ft_conf.h ,
+
+ where <system> stands for your platform. This release also
+ provides an `ansi' build, i.e., the directory `lib/arch/ansi' used
+ to compile with any ANSI-compliant compiler.
+
+ The configuration macros that relate to performance are described
+ next.
+
+
+ 1. TT_CONFIG_OPTION_INTERPRETER_SWITCH
+ --------------------------------------
+
+ If set, this macro builds a bytecode interpreter which uses a
+ huge `switch' statement to parse the bytecode stream during
+ glyph hinting.
+
+ If unset, the interpreter uses a big jump table to call each
+ bytecode's routine.
+
+ This macro is *set* by default. However, it may be worthwile on
+ some platforms to unset it.
+
+ Note that this macro is ignored until
+ TT_CONFIG_OPTION_BYTECODE_INTERPRETER is set.
+
+
+ 2. TT_CONFIG_OPTION_STATIC_INTERPRETER
+ --------------------------------------
+
+ If set, this macro builds a bytecode interpreter which uses a
+ static variable to store its state. On some processors, this
+ will produce code which is bigger but slightly faster.
+
+ Note that you should NOT DEFINE this macro when building a
+ thread-safe version of the engine.
+
+ This macro is *unset* by default.
+
+
+ 3. TT_CONFIG_OPTION_STATIC_RASTER
+ ---------------------------------
+
+ If set, this macro builds a scan-line converter which uses a
+ static variable to store its state. On some processors, though
+ depending on the compiler used, this will produce code which is
+ bigger but moderately faster.
+
+ Note that you should NOT DEFINE this macro when building a
+ thread-safe version of the engine.
+
+ This macro is *unset* by default. We do not recommend using it
+ except for extreme cases where a performance `edge' is needed.
+
+
+ 4. TT_USE_LONG_LONG
+ -------------------
+
+ Define TT_USE_LONG_LONG if you want to enable the use of the
+ 'long long' 64-bit type provided by gcc and other compilers.
+ Note that:
+
+ 1. The type wasn't ANSI C in 1989 (but is now OK with the new
+ C99), and thus will produce many warnings during library
+ compilation with many compilers, including gcc 2.8.x.
+
+ 2. Though the generated object files are slightly smaller, the
+ resulting executables are bigger of about 4kB! gcc must be
+ linking some extra code in there!
+
+ 3. There is really no speed gain in doing so (but it may help
+ debug the ttcalc component).
+
+ IMPORTANT NOTE: You don't need to define it on 64-bits machines!
+
+ NOTE 2 : This flag used to be _GNUC_LONG64_
+
+
+
+II. Replacing some components with optimized versions
+=====================================================
+
+ You can also, in order to improve performance, replace one or more
+ components from the original source files. Here are our
+ suggestions.
+
+
+ 1. Use memory-mapped files whenever available
+ ---------------------------------------------
+
+ Loading a glyph from a TrueType file needs many random seeks,
+ which take a lot of time when using disk-based files.
+
+ Whenever possible, use memory-mappings to improve load
+ performance dramatically. For an example, see the source file
+
+ freetype/lib/arch/unix/ttmmap.c
+
+ which uses Unix memory-mapped files.
+
+
+ 2. Replace the computation routines in `ttcalc.c'
+ ---------------------------------------------------
+
+ This file contains many computation routines that can easily be
+ replaced by inline-assembly, tailored for a specific processor
+ and/or compiler.
+
+ After heavy testing, we have found that these functions,
+ especially TT_MulDiv(), are the ones that are most extensively
+ used and called when loading glyphs from a font file.
+
+ We do not provide inline-assembly with this release, as we want
+ to emphasize the portability of our library. However, when
+ working on a specific project where the hardware is known to be
+ fixed (like on an embedded system), great performance gains
+ could be achieved by replacing these routines.
+
+ (By the way, the square root function is not optimal, but it is
+ very seldom called. However, its accuracy is _critical_.
+ Replacing it with a fast but inaccurate algorithm will ruin the
+ rendering of glyphs at small sizes.)
+
+
+
+III. Measuring performance improvements
+=======================================
+
+ Once you have chosen some improvements and rebuilt the library,
+ some quick ways to measure the `new' speed are:
+
+ - Run the test program `ftlint' on a directory containing many
+ TrueType fonts, and measure the time it takes. On Unix, you can
+ use the shell command `time' to do it like in
+
+ % time test/ftlint 10 /ttfonts/*.ttf
+
+ This will measure the performance improvement of the TrueType
+ interpreter.
+
+ - Run the test program `fttimer' on a font containing many complex
+ glyphs (the latest available versions of Times or Arial should
+ do it), probaby using anti-aliasing, as in:
+
+ % time test/fttimer -g /ttfonts/arial.ttf
+
+ Compare the results of several of these runs for each build.
+
+
+--- end of OPTIMIZE ---