shithub: freetype+ttf2subf

Download patch

ref: b190572be574f04b46bb28b77dc53f44a462a588
parent: 5fe4c00ed29e6d85f348a79d2dfd9ea8f9a88b27
author: David Turner <david@freetype.org>
date: Wed Jul 26 15:07:15 EDT 2000

updated documentation

git/fs: mount .git/fs: mount/attach disallowed
--- /dev/null
+++ b/docs/freetype2.html
@@ -1,0 +1,352 @@
+<html>
+<head>
+<title>FreeType 2 Introduction</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+  P { text-align=justify }
+  H1 { text-align=center }
+  H2 { text-align=center }
+  LI { text-align=justify }
+</style>
+</head>
+
+<body text="#000000"
+      bgcolor="#FFFFFF"
+      link="#0000EF"
+      vlink="#51188E"
+      alink="#FF0000">
+
+
+<font size=1>http://www.freetype.org</font><p> 
+
+<center>
+  <a href="freetype.html">
+  <img src="image/freetype.jpg" width=550 height=105 alt="The FreeType Project" border=0></a>
+  <h1>An Introduction to FreeType 2</h1>
+</center>
+
+<center><table width=750 cellspacing=10 cellpadding=30><tr><td>
+<hr><p>
+
+DOCUMENT INDEX:<br>
+<ul>
+  <li><a href="#what">What is FreeType 2 ?</a>
+  <li><a href="#features">Features</a>
+  <li><a href="#requirements">Requirements</a>
+  <li><a href="#patents">Patents issues</a>
+</ul><p>
+
+
+<hr><p>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="what">What is FreeType 2 ?</h2>
+</td></tr><tr><td>
+
+<p>The FreeType project is a team of volunteers who develop free, portable
+and high-quality software solutions for digital typography. We specifically
+target embedded systems and focus on bringing small, efficient and
+ubiquitous products.</p>
+
+<p>the FreeType 2 library is our new software font engine. It has been
+   designed to provide the following important features:</p>
+
+  <ul>
+  <li><p>
+    <b>A universal and simple API to manage font files:</b><br>
+    <ul>
+      <p>The FreeType 2 API is simple and easy to use. It supports both
+         bitmapped and scalable fonts and is well-suited to manage font
+	 files of all formats. Unlike other font libraries, FreeType 2
+	 returns and manages outline font data (images & metrics).</p>
+   </ul>
+   </p></li>
+ 
+  <li><p>
+    <b>Support for several font formats through loadable modules:</b><br>
+    <ul>
+      <p>FreeType 2 uses <em>"font drivers"</em>. Each driver is a loadable
+         module used to support one specific font format. Each driver can also
+	 provide specific extensions used to access format-specific features of
+	 the font.</p>
+    </ul>
+  </p></li>
+  
+  
+  <li><p>
+    <b>High-quality anti-aliasing:</b><br>
+    <ul>
+      <p>FreeType 2 produces etremely smooth outlines at small sizes, with its new
+         anti-aliasing renderer, which produces bitmaps with 256-levels of gray.
+	 It uses a new algorithm that has been specifically designed to render
+	 small complex shapes (like glyphs) at high speed. Indeed, it's even
+	 faster than the monochrome renderer for small character sizes (under
+	 20 pixels) !!
+      </p>
+    </ul>
+
+
+ <li><b>High portability & performance:</b><br>
+     <ul>
+       <p>The FreeType 2 source code is written in ANSI C and runs on any
+          platform with a compliant compiler. Client applications can
+	  provide their own memory manager or input stream to the library
+	  (which means that font files can come from any place: disk,
+	  memory, compressed file, network, etc..).
+       </p>
+     </ul>
+     	    
+  </ul>
+  
+  <p>Note that <em>the beta of FreeType 2 is available <b>now</b></em>. For more
+  info, check our <a href="download.html">Download page</a> or see the source
+  and its diffs through our <a href="cgi-bin/cvsweb.cgi">CVS Web interface</a>.
+  </p>
+</ul>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="features">Features</h2>
+</td></tr><tr><td>
+
+<h3>Supported font formats</h3>
+
+<p>FreeType 2 readily supports the following font formats:</p>
+
+<ul>
+  <li>TrueType files (.ttf) and collections (.ttc)</li>
+  <li>Type 1 font files both in ASCII (.pfa) or binary (.pfb) format</li>
+  <li>Type 1 Multiple Master fonts. The FreeType 2 API also provides
+      routines to manage design instances easily</li>
+  <li>Type 1 CID-keyed fonts</li>
+  <li>OpenType/CFF (.otf) fonts</li>
+  <li>CFF/Type 2 fonts</li>
+  <li>Adobe CEF fonts (.cef), used to embed fonts in SVG documents
+      with the Adobe SVG viewer plugin.</li>
+  <li>Windows FNT/FON bitmap fonts</li>
+</ul>
+
+<p>Note that Apple's TrueType GX fonts are supported as normal TTFs,
+   (the advanced tables are ignored).</p>
+
+<p>Besides, it's possible to add support for new font formats by providing
+   a specific <em>font driver</em> module. Modules can be added either at
+   build time (when recompiling the library), or at <em>run-time</em>;
+   this allows, for example, applications to register their own
+   font driver to support program-specific formats.</p>
+
+
+<h3>Patent-free automatic hinter</h3>
+
+<p>TrueType fonts are normally renderered (hinted) with the help of a
+   specific bytecode where the behaviour of a few opcodes is patented by
+   Apple. We're currently in contact with Apple to discuss the importance
+   of such patents and their use in open source projects like FreeType.
+   </p>
+   
+<p>In the meantime, we have developped our own alternative technology that
+   is capable of automatically hinting scalable glyph images. It is
+   now part of the FreeType 2 source tree as the "autohint" module,
+   and is used to hint glyphs when the bytecode interpreter is disabled
+   (through a configuration macro when building the engine). Note that
+   the auto-hinter is also used to handle glyphs in other formats like
+   CFF and Type 1.</p>
+
+<p>The auto-hinter provides pretty good results (in some cases, it even
+   significantly improves the output of poorly hinted fonts) but we'll
+   continue to improve it with each new release of FreeType to achieve
+   the highest possible quality.</p>
+
+
+<h3>Modular design:</h3>
+
+<p>The design of FreeType 2 is extremely modular as most features are
+   supported through optional modules. This means it's easily possible to
+   only compile the features you need. As each module is between
+   10 and 20 Kb in size, it's possible to build a bare-bones
+   font engine that supports anti-aliasing in about 30 Kb !!</p>
+   
+<p>Configuration is performed by  modifications of only two header
+   files (one to select global features, another one to select modules)
+   and don't need tweaking of source code. Note that it is however
+   possible to provide your own implementation of certain components.</p>
+   
+<p>For example, when building on Unix, the engine will automatically
+   use memory-mapped files when available on the target platform,
+   thus significantly increasing font file i/o.</p>
+
+
+<p>Due to its very flexible design, it is possible to add, remove and
+   upgrade modules at run-time.</p>
+
+
+
+<h3>Advanced glyph management</h3>
+
+<p>The API comes with a standard extension used to extract individual
+   glyph images from font files. These images can be bitmaps, scalable
+   bezier outlines or even anything else. (e.g. bi-color or metafont
+   glyphs, as long as they're supported by a module).</p>
+   
+<p>Each scalable glyph image can be transformed, measured and
+   rendered into a monochrome or anti-aliased bitmaps easily
+   through a uniform interface.
+
+   This allows client applications to easily cache glyphs or
+   perform text rendering effects with minimal difficulty
+   (look at the FreeType 2 Tutorial to see how to render
+    rotated text with very few lines of code).
+</p>
+
+
+
+<h3>Advanced font access</h3>
+
+<p>The FreeType 2 API is useful to retrieve advanced information from
+   various fonts:</p>
+   
+<ul>
+  <li>vertical metrics are available whenever found in the font file</li>
+  
+  <li>kerning distances are available when found in the font file. It
+      is also possible to "attach" a given additional file to a given
+      font face. This is useful to load kerning distances from an
+      .afm file into a Type 1 face for example.</li>
+
+  <li>provides ASCII glyph names whenever available in the font
+      (TrueType, OpenType, Type1, etc..)</li>
+      
+  <li>provides access to important tables for SFNT-based font formats
+      (i.e. TrueType, OpenType, CEF, etc..), like the name table,
+      font header, maximum profile, etc...</li>
+
+  <li>automatic synthesis of Unicode-based character maps for
+      those fonts or formats that do not provide one. This is
+      extremely useful with Type 1 fonts which are normally
+      limited to a stupid 256-characters encoding.</li>
+</ul>      
+
+  
+<h3>Simple & clean API</h3>
+
+<p>The FreeType 2 high-level API is simple and straightforward, as it
+   has been specifically designed to make the most commmon font operations
+   easy</p>
+   
+<p>As a comparison, the number of function calls needed to perform a
+   the tasks of font face creation/opening and glyph loading/rendering
+   has been reduced by a factor of 4 !!</p>
+
+<p>The API is also independent of any font-format specific issue, though
+   it provides standard extensions to access format-specific tables and
+   information. More extensions can also be easily added through new
+   modules</p>
+   
+
+<h3>Robust & Portable code</h3>
+
+<p>Because it is written in industry-standard ANSI C, FreeType 2 compiles
+   on all platforms with a compliant compiler. Because the default build
+   only relies on the C library, it is free of any system-specific
+   dependencies, even if it is possible to "enhance" certain components
+   by providing a specific implementation.</p>
+
+<p>The code doesn't use global or static variables. Client applications
+   can provide their own memory manager. Font files can be read from
+   a disk file, memory, or through a client-provided input stream. This
+   allows to support compressed font files, remote fonts, fonts embedded
+   in other streams (e.g. Type42 fonts), etc..</p>
+   
+<p>An advanced i/o sub-system is used to optimise file access, as well
+   as reduce memory usage of the library when the file is memory-based
+   ( ROM, RAM, memory-mapped ).</p>
+
+
+<h3>Open Source & Vendor Independence</h3>
+
+<p>Finally, FreeType 2 is released under its own BSD-like open source
+   license, one of the less restricting licenses available, and this
+   means that:</p>
+   
+<ul>
+  <li><p>
+    It can be included in all kinds of products, be they proprietary
+    or not.
+  </p></li>
+  
+  <li><p>
+    As any module can be added or replaced anytime, any third party
+    vendor  has the ability to provide its own set of modules (under
+    its own license) in order to support proprietary font formats or
+    more advanced features (e.g. a new auto-hinter, or a new
+    anti-aliasing renderer for LCDs or TV screens).
+  </p></li>
+</ul>
+
+<p>One could even imagine an application using the FreeType 2 API with
+   a "wrapper" module used to access system-specific fonts (like through
+   the Windows GDI). This would mean native font support with more portable
+   application code (as simply changing the wrapper module would be required
+   to port the application to another system).</p>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="requirements">Requirements</h2>
+</td></tr><tr><td>
+
+<p>FreeType 2 is written in ANSI&nbsp;C and should compile with no problems
+   on a great variety of platforms. We have taken care of removing all
+   compilation warnings from major compliant compilers. Detailed compilation
+   instructions are provided in the software archive.</p>
+
+<p>This version of the library has been succesfully compiled and run
+   under the following systems: Dos, OS/2, Windows, Macintosh, Unix
+   (including the 64-bits DEC Unix, a.k.a. "True64"). You should not
+   encounter major problems compiling it on any other kind of platform.
+   In all cases, contact us if you do.</p>
+
+<p>Note that a small set of demonstration programs is also separately
+   available. They include a tiny graphics sub-system that is used to
+   display and show-off the library's capabilities on the following
+   platforms: X11, MacOS, OS/2 & Windows.</p>
+
+<p>Please visit our <a href="http://www.freetype.org/download.html">
+   Download section</a> to access the software archives.</p>
+
+</ul>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="patents">Patents issues</h2>
+</td></tr><tr><td>
+
+<p>The FreeType 2 source code includes a TrueType bytecode interpreter that
+   is covered by the Apple patents. However, this piece of code is never
+   compiled by default in this release (unlike in previous betas) making
+   a default build of the library <em>entirely patent-free !!</em></p>
+   
+<p>Note that in order to compile the interpreter, one needs to define
+   the configuration macro <tt><b>TT_CONFIG_OPTION_BYTECODE_INTERPRETER</b></tt> configuration
+   macro in the file "<tt>ftoption.h</tt>". More details are available in
+   the software archive. Note that the use of the interpreter is normally
+   protected by US, UK and French patents. In the event you'd absolutely
+   need it, you may have to <a href="mailto:patents@apple.org">contact
+   Apple legal department</a> for licensing conditions, depending on your
+   location and the places you distribute/sell your products.</p>
+
+<p>Please do not ask us any detailed information regarding licensing, as
+   we're still discussing with Apple this issue, we're unable to inform
+   the public of what's currently going on..</p>
+
+</td></tr></table>
+
+<hr>
+<p>
+<a href="index.html">Back to FreeType homepage</a><p>
+
+</td></tr></table>
+</body>
+</html>
--- /dev/null
+++ b/docs/ft2faq.html
@@ -1,0 +1,502 @@
+<html>
+<head>
+<title>FreeType 2 FAQ</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+  P { text-align=justify }
+  H1 { text-align=center }
+  H2 { text-align=center }
+  LI { text-align=justify }
+</style>
+</head>
+
+<body text="#000000"
+      bgcolor="#FFFFFF"
+      link="#0000EF"
+      vlink="#51188E"
+      alink="#FF0000">
+
+
+<font size=1>http://www.freetype.org</font><p>
+
+<center>
+  <a href="freetype.html">
+  <img src="image/freetype.jpg" width=550 height=105 alt="The FreeType Project" border=0></a>
+  <h1>The FreeType 2 FAQ</h1>
+</center>
+
+<center><table width=750 cellspacing=10 cellpadding=30><tr><td>
+<hr><p>
+
+DOCUMENT INDEX:<br>
+<ul>
+  <li><p><a href="#general">General</a>
+    <ul>
+      <li><a href="#general-dead">I thought the FreeType project was dead. It this true?</a></li>
+      <li><a href="#general-long">Why did it take so long to release FreeType 2?</a></li>
+      <li><a href="#general-unix">Is FreeType 2 a Unix-only project?</a></li>
+      <li><a href="#general-x11">When will X11 support anti-aliased glyphs?</a></li>
+      <li><a href="#general-ft1">Is FreeType 2 backwards compatible with 1.x?</a></li>
+      <li><a href="#general-edit">Can I use FreeType 2 to edit fonts or create new ones?</a></li>
+    </ul></p>
+  </li>
+  <li><p><a href="#builds">Compilation & Configuration</a>
+    <ul>
+      <li><a href="#builds-compile">How do I compile the FreeType 2 library?</a></li>
+      <li><a href="#builds-config">How do I configure my library build?</a></li>
+      <li><a href="#builds-modules">How do I select the modules I need?</a></li>
+      <li><a href="#builds-flat">How do I compile all FreeType 2 files in a single directory?</a></li>
+    </ul>
+  </p></li>
+  <li><p><a href="#library">Using the FreeType 2 library</a></p></li>
+  <li><p><a href="#autohint">The FreeType 2 Autohinter</a>
+    <ul>
+      <li><a href="#autohint-license">Under which license is the auto-hinter released ?</a></li>
+      <li><a href="#autohint-work">How does auto-hinting work in FreeType 2 ?</a></li>
+      <li><a href="#autohint-cjk">Why doesn't the auto-hinter work well with CJK fonts ?</a></li>
+    </ul>
+  </p></li>
+  <li><p><a href="#other">Other questions</a>
+    <ul>
+      <li><a href="#other-antialias">What is the anti-aliasing algorithm used in the FreeType 2 renderer?</a></li>
+      <li><a href="#other-opentype">When will FreeType 2 support OpenType ?</a></li>
+    </ul></p>
+  </li>
+</ul><p>
+
+
+<hr><p>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="general">General questions & answers</h2>
+</td></tr><tr><td>
+
+<a name="general-dead">
+<h3>I.1. I though the FreeType project was dead. Is this true?</h3>
+<ul>
+  <p>Well, not exactly :-) It's true that the TrueType patents issues
+     have been less than a graceful event to handle but it didn't not
+     really killed the project per se, as Apple hasn't made an official
+     statement yet regarding the use of the patented "technology" in
+     open source projects (or other products).</p>
+
+  <p>We have thus continued updating FreeType 1.x, and started developping
+     FreeType 2 with the idea of providing this time a completely patent
+     free font engine. However, we largely preferred not to broadly
+     communicate about it until we've got a satisfying implementation
+     to show.</p>
+</ul>
+
+
+<a name="general-long">
+<h3>I.2. Why did it take so long to release FreeType 2?</h3>
+<ul>
+  <p>Several factors come to mind. The first one is that FreeType 2 is
+     a much more complex and dense project that was mostly developed
+     on non-working hours. And surely some important changes in the
+     life (like marriage, new jobs and kids) of some the FreeType
+     developers cannot be ignored :-)</p>
+
+  <p>A second one is that a first version of the library was designed
+     one year ago (and already worked with a multitude of font drivers),
+     though with a design that was judged by its authors as well as
+     beta testers as not enough flexible or consistent. In short, it worked
+     well but we were not exactly proud of it (call us perfectionists).
+     It has then be significantly reworked to become what we're now
+     distributing as FreeType 2</p>
+
+  <p>Finally, it would have been hard to distribute such a library without
+     an alternative technology to replace the patented bytecode interpreter.
+     This involved significant research work that could only be performed
+     correctly full-time, and we had to found a company to fund such a
+     development and still make it available under a BSD-like license.
+     Huge thanks to <a href="http://www.catharon.com">Catharon Productions, Inc.</a>
+     for their commitment to this project.</p>
+
+  <p>And of course, we added support for more font files, and we'll
+     continue to as long as the specs are available and that we find an
+     interest in it. For example,  FreeType 2 is to date the only
+     software library available on the market that supports the new
+     Adobe "CEF" font format.</p>
+</ul>
+
+<a name="general-unix">
+<h3>I.3. Is FreeType 2 a Unix-only project?</h3>
+<ul>
+  <p>Absolutely not, even though many people still seem to think so :-)
+     FreeType 2, just like version 1.x, can be compiled on any platform with
+     an ANSI compiler. Some beta versions of the library are even heavily
+     used in brand new OSes (see the <a href="http://www.atheos.cx">AtheOS
+     </a> screenshots for examples).</p>
+
+  <p>The library is itself mainly developped on several platforms
+     (Windows & Linux, though a great deal has also been achieved on OS/2)
+     and the code is highly generic and modular to adapt even the most
+     strict environments like low-memory embedded systems.</p>
+
+</ul>
+
+<a name="general-x11">
+<h3>I.4. When will X11/XFree support anti-aliased text?</h3>
+<ul>
+  <p>This question isn't exactly related to FreeType as we have no direct
+     connection to the XFree people, but we've been asked so frequently
+     about it that it deserves a prominent place in this FAQ :-)</p>
+
+  <p>FreeType has been capable of anti-aliasing since version 1.0. The
+     reason why XFree doesn't support it is directly related to the
+     limitations of the design and specification of X11. More specifically:</p>
+
+  <ul>
+    <li><p>
+       X11 assumes that all glyph images are monochrome bitmaps,
+       hence the X font library and server are unable to send anything
+       else to the X server.
+    </p></li>
+
+    <li><p>
+       Even if the X font library/server was able to generate anti-aliased
+       bitmaps (and this has been already done through extensions), the X
+       rendering model doesn't allow translucent composition of "gray" pixmaps
+       onto an arbitrary drawable.
+    </p></li>
+  </ul>
+
+  <p>As both the font and rendering models of X11 are limited, it's basically
+     impossible to draw anti-aliased glyphs without performing <em>huge</em>
+     hacks within the server.</p>
+
+  <p>Note that Keith Packard, from XFree fame, has recently started working
+     on a new rendering model for X11 in order to support new features
+     (mainly transparency and anti-aliased fonts). This will be provided
+     through protocol extensions. The question of knowing wether legacy X
+     applications will be able to display anti-aliased text is still very
+     uncertain.
+     </p>
+</ul>
+
+<a name="general-ft1">
+<h3>I.5. Is FreeType 2 backwards compatible with FreeType 1.x?</h3>
+<ul>
+  <p>Not directly, though we had the project to provide an optional binary
+     compatibility layer on top of it in order to easily re-link applications
+     with the new version. However, this idea has been dropped as it is
+     possible to install and use the two versions independtly on any
+     system (read: no namespace conflicts).</p>
+
+  <p>The FreeType 2 API is a lot simpler than the one in 1.x while being
+     much more powerful. We thus encourage you to adapt your source code
+     to it as this should not involve much work.</p>
+
+</ul>
+
+<a name="general-edit">
+<h3>I.6. Can I use FreeType 2 to edit fonts or create new ones?</h3>
+<ul>
+  <p>The answer is a definitive NO, because the library was specifically
+     designed to <em>read</em> font files with small code size and very
+     low memory usage.</p>
+
+  <p>We thus do not plan to support editing or creation in the font
+     engine in any way, as this would imply a complete rewrite. This
+     doesn't mean that we won't introduce a font editing/creation library
+     in the future, as this really depends on how many people are asking
+     for it (or how much they would be willing to pay for it), as well as
+     the time of the FreeType developers.</p>
+
+  <p>Do not expect anything in this direction until we officially announce
+     something though. There are other axis of development for this project
+     (like text-layout capabilities, glyph caching, etc..) that may be more
+     important to us at the moment..</p>
+</ul>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="builds">Compilation & Configuration</h2>
+</td></tr><tr><td>
+
+<a name="builds-compile">
+<h3>II.1. How do I compile the FreeType 2 library?</h3>
+<ul>
+  <p>The library can be compiled in various ways, and a detailed documentation
+     is available in the file "<tt>freetype2/docs/BUILD</tt>". However, we'll
+     summarize the process to a few cases:</p>
+
+  <h3>a. by using the command-line 2 build system</h3>
+
+  <p>The engine comes with a sophisticated build system that is used
+     to configure and compile a build of the library. You'll need
+     <em>GNU Make</em> installed on your platform (NOTE: It will <b>not</b>
+     work with other Make tools).</p>
+
+  <p>Basically, you'll need to invoke <tt>make</tt> a first time in the
+     top-level FreeType 2 directory in order to setup the build. This will
+     detect your current platform and choose a configuration sub-makefile to
+     drive the build. A specific compiler can be selected on some platforms
+     by providing an additional target. For example, on Win32:</p>
+
+  <ul>
+    <li><b><tt>make visualc</tt></b> will select the Visual C++ compiler</li>
+    <li><b><tt>make lcc</tt></b> will select the Win32-lcc compiler</li>
+  </ul>
+
+  <p>Note that on Unix, the first time make is called, a configure script
+     located in "<tt>freetype2/builds/unix</tt>" will be run in order to
+     automatically detect the platform & compiler.</p>
+
+  <p>A summary will be displayed showing the detected platform and compiler
+     selected. You'll then be able to start the build by invoking <tt>make</tt>
+     a second time. In case of problem, consult the <tt>BUILD</tt> document.</p>
+
+
+  <h3>b. by direct compilation</h3>
+
+  <p>You can also directly compile the library from the command line by
+     using these simple rules:</p>
+
+  <ul>
+    <li><p>
+       You should place the directories "<tt>freetype2/include</tt>" and
+       "<tt>freetype2/src</tt>" in your include path in order to compile
+       any component of the library. You can also add the system-specific
+       build directory (i.e. "<tt>builds/<em>system</em>/</tt>") in the
+       case where an alternate implementation of some of the components
+       is available there (e.g. the memory-mapped i/o implementation
+       on some Unix systems).
+    </p></li>
+
+    <li><p>
+       The components of the library are located in sub-directories of
+       "<tt>src</tt>", for example: "<tt>src/base</tt>",
+       "<tt>src/truetype</tt>", etc..
+    </p></li>
+
+    <li><p>
+       Each component is normally compiled through a single C file that
+       "wraps" other sources in the component's directory. For example,
+       your should compile the TrueType font driver by compiling the
+       file "<tt>src/truetype/truetype.c</tt>". The list of C files to
+       compile for a feature-complete build of the library is given in
+       the <tt>BUILD</tt> document.
+    </p></li>
+  </ul>
+
+  <h3>c. in a graphical IDE</h3>
+  <ul>
+    <p>Well, the process is vastly similar to the one described in b.,
+       except that you need to set the include paths, source code paths,
+       etc.. in dialog boxes before running the compilation.
+    </p>
+  </ul>
+
+</ul>
+
+<a name="builds-config">
+<h3>II.2. How do I configure my build of the library?</h3>
+<ul>
+  <p>Each build of the library is configured through two header files
+     located in "<tt>include/freetype/config</tt>":</p>
+
+  <ul>
+    <li><p><b><tt>ftoption.h</tt></b><br>
+        This file contains various configuration macros whose definition
+	can be toggled on a per-build basis. Each macro is heavily
+	commented in this file's comment, and we invite you to refer
+	to it directly.</p></li>
+
+    <li><p><b><tt>ftmodule.h</tt></b><br>
+        This file contains the list of all the modules that are initially
+	registered (added) when the function <b><tt>FT_Init_FreeType</tt></b>
+	is called. See the next answer to know how to change it and
+	why it may be important.</p></li>
+  </ul>
+
+  <p>Alternatively, some specific implementations of some FT2 components
+     can be provided in a "<tt>builds/<em>system</em>/</tt>" directory
+     (e.g. the Unix-specific <tt>ftsystem.c</tt> that uses memory-mapped
+     file for i/o).</p>
+</ul>
+
+<a name="builds-modules">
+<h3>II.3. How do I select the modules I need in my build?</h3>
+<ul>
+  <p>The function <tt><b>FT_Init_FreeType</b></tt> creates a new instance
+     of the FT2 library and registers a set of "default" modules before
+     returning to the calling application. Its default implementation
+     is in the file "<tt>src/base/ftinit.c</tt>".</p>
+
+  <p>The list of default modules used by <tt>ftinit.c</tt> is located in
+     the configuration file "<tt>include/freetype/config/ftmodule.h</tt>".
+     It is normally automatically generated by the build system by
+     invoking the "<tt><b>make modules</b></tt>" command in the top
+     level FT2 directory (note: only works with GNU Make, you can
+     edit the file by hand otherwise). It does so by parsing all
+     sub-directories of "<tt>src</tt>" that contain a file named
+     <tt>module.mk</tt>.</p>
+
+  <p>Note that a specific port or project is free to provide its own
+     implementation of <tt>ftinit.c</tt> in order to ensure a different
+     initialisation sequence. For example, one could do something like:</p>
+
+  <ul>
+    <li><p>compile each module as a shared library (DLL or .so) with
+           a common "entry point" to retrieve a pointer to its
+	   module class (there is already some code that allows this
+	   when compiling each module).</p></li>
+
+    <li><p>place these modules in a directory like
+          "<tt>/usr/lib/freetype2/modules/</tt>"</p></li>
+
+    <li><p>provide an implementation of <tt>ftinit.c</tt> that would
+           scan the directory for valid modules.</p></li>
+  </ul>
+
+  <p>This example only emphasize the flexibility that is left to
+     developers when building the library.</p>
+
+</ul>
+
+<a name="builds-flat">
+<h3>II.4. How do I compile all FreeType 2 files in a single directory?</h3>
+<ul>
+  <p>Some projects may need, for the sake of simplicity or ease of
+     building, to compile the FT2 library with all source files
+     copied to a single directory. This is possible.</p>
+
+  <p>To do so, you'll need to copy all source files located under
+     "<tt>src</tt>" to your own directory (you must retain the
+     include files in a distinct hierarchy though), then compile
+     each of the FreeType 2 component with the macro
+     <tt><b>FT_FLAT_COMPILE</b></tt>. This will change the way
+     <tt><b>#include</b></tt> works during the build.</p>
+</ul>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="library">Using the FreeType 2 library</h2>
+</td></tr><tr><td>
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="autohint">The FreeType 2 auto-hinter</h2>
+</td></tr><tr><td>
+
+<a name="autohint-license">
+<h3>IV.1. Under which license is the FreeType 2 auto-hinter released</h3>
+<ul>
+  <p>The auto-hinter was initially designed and implemented under contract
+     for <a href="http://www.catharon.com">Catharon Productions, Inc</a>
+     which gladly accepted to released it under an open-source license
+     compatible with the FreeType one.</p>
+
+  <p>This license can be found in "<tt>src/autohint/CatharonLicense.txt</tt>"
+     and requires that you cite Catharon Productions in your documentation
+     (just like you do with FreeType) when using the auto-hinting module.</p>
+
+  <p>Other than that, you still have the same freedom than with the good old
+     FreeType license. Enjoy !</p>
+</ul>
+
+<a name="autohint-work">
+<h3>IV.2. How does the auto-hinter works ?</h3>
+<ul>
+  <p>Well, a complete description would be difficult. Have a look at the
+     dedicated <a href="autohinting/index.html">auto-hinter pages</a> on the FreeType
+     site, as they describe most of its details with graphics and explanations.
+     You could also look at the source code if you want to :-)</p>
+
+  <p>To give a few details, the auto-hinter is used to perform grid-fitting
+     on scalable font formats that use bezier outlines as their primary glyph
+     image format (this means nearly all scalable font formats today). When
+     a given font driver doesn't provide its own hinter, the auto-hinter is
+     used by default. When a format-specific hinter is provided, it is still
+     possible to use the auto-hinter using the
+     <tt><b>FT_LOAD_FORCE_AUTOHINT</b></tt> bit flag when calling
+     <tt>FT_Load_Glyph</tt>.</p>
+
+  <p>The auto-hinter currently doesn't use external hints to do its job,
+     as it automatically computes global metrics (when it "opens" a font
+     for the first time) and glyph "hints" from their outline. Note that
+     we plan the ability to specify external hints, given that it is based
+     on a constraint system. That could be used to support native hints
+     in Type 1/Type 2 fonts, for example.</p>
+</ul>
+
+<a name="autohint-cjk">
+<h3>IV.3. Why does the auto-hinter doesn't work correctly with CJK fonts ?</h3>
+<ul>
+  <p>The auto-hinter was first designed to manage and hint latin-based fonts,
+     as they consist of most of the fonts available today. It doesn't hint
+     asian fonts, as well as a few other complex scripts, because we didn't
+     put enough research on the topic yet. Hinting CJK isn't really more
+     difficult than latin, just different with a set of different constraints
+     (basically, more distortion of glyphs is acceptable as long as certain
+     features like triple-stem positions are respected more strictly..).</p>
+
+  <p>We thus plan to handle such a case rather rapidly.. Please be patient.</p>
+</ul>
+
+
+</td></tr></table>
+
+<table width="100%" cellspacing=5><tr bgcolor="#CCCCEE"><td>
+<h2 align=center><a name="other">Other questions</h2>
+</td></tr><tr><td>
+
+<a name="other-antialias">
+<h3>V.1. What is the anti-aliasing algorithm used by FreeType 2 ?</h3>
+<ul>
+  <p>The algorithm has been specifically designed for FreeType. It is
+     based on ideas that were originally found in the implementation
+     of the <a href="http://www.levien.com/libart">libArt</a> graphics
+     library to compute the <em>exact pixel coverage</em> of a vector
+     image with absolutely now sub-sampling/filtering.
+     </p>
+
+  <p>However, these two implementations are radically distinct and use
+     vastly different models. The FreeType 2 renderer is optimized
+     specifically for rendering small complex shapes, like glyphs, at
+     very high speed while using very few memory; while libArt shines
+     at general shape/polygon processing, especially large ones.</p>
+
+  <p>The FT2 anti-aliasing renderer is indeed <em>faster</em> than the
+     monochrome renderer for small character sizes (typically &lt; 20 pixels).
+     This is explained because the monochrome renderer must perform two
+     passes on the outline in order to perform drop-out control according
+     to the TrueType spec (we could drop this requirement later though).</p>
+
+  <p>We'll try to document its design in a later document, though this is
+     not a priority for now.</p>
+</ul>
+
+<a name="other-opentype">
+<h3>V.2. When will FreeType 2 support OpenType ?</h3>
+<ul>
+  <p>Well, the engine already reads OpenType/CFF files perfectly. What it
+     doesn't do is handle "OpenType Layout" tables yet.</p>
+     
+  <p>FreeType 1 comes with a set of extensions that are used to load
+     and manage OpenType Layout tables. It even has a demonstration program
+     named "<tt>ftstrtto</tt>" used to demonstrate its capabilities that
+     runs pretty smooth.</p>
+     
+  <p>For FreeType 2, we have decided that the layout operations provided
+     through these tables is better placed in a specific text-layout library,
+     (many people having asked for such a thing). This new engine would not
+     depend on FT2 explicitely and will be developed as a separate project.
+     We plan to announce it in a few weeks with all gory details,
+     once the definitive 2.0 release of FreeType has been made.</p>
+</ul>
+
+</td></tr></table>
+
+<hr>
+<p>
+<a href="index.html">Back to FreeType homepage</a><p>
+
+</td></tr></table>
+</body>
+</html>
--- a/docs/tutorial/step1.html
+++ b/docs/tutorial/step1.html
@@ -542,10 +542,11 @@
       </font>
      
       <p>The parameter <tt>render_mode</tt> is a set of bit flags used
-         to specify how to render the glyph image. Set it to 0 to render
-         a monochrome bitmap, or to <tt>ft_render_mode_antialias</tt> to
-         generate a high-quality (256 gray levels) anti-aliased bitmap
-         from the glyph image.</p>
+         to specify how to render the glyph image. Set it to 0, or the
+         equivalent <tt>ft_render_mode_normal</tt> to render a high-quality
+         anti-aliased (256 gray levels) bitmap, as this is the default.
+         You can alternatively use <tt>ft_render_mode_mono</tt> if you
+         want to generate a 1-bit monochrome bitmap.</p>
 
       <p>Once you have a bitmapped glyph image, you can access it directly
          through <tt><b>glyph->bitmap</b></tt> (a simple bitmap descriptor),
@@ -675,10 +676,23 @@
          of (0,0) will be used). The vector coordinates are expressed in
          1/64th of a pixel (also known as 26.6 fixed floats).</p>
      
-      <p><em>NOTA BENE: The transform is applied every glyph that is loaded
-         through <tt>FT_Load_Glyph</tt>. Note that loading a glyph bitmap
-         with a non-trivial transform will produce an error..</em></p>
-     
+      <font color="red">
+      <p>NOTA BENE: The transform is applied to every glyph that is loaded
+         through <tt>FT_Load_Glyph</tt> and is <b>completely independent
+         of any hinting process.</b> This means that you won't get the same
+         results if you load a glyph at the size of 24 pixels, or a glyph at
+         the size at 12 pixels scaled by 2 through a transform, because the
+         hints will have been computed differently (unless, of course you
+         disabled hints).</em></p></font>
+
+      <p>If you ever need to use a non-orthogonal transform with optimal
+         hints, you first need to decompose your transform into a scaling part
+         and a rotation/shearing part. Use the scaling part to compute a new
+         character pixel size, then the other one to call FT_Set_Transform.
+         This is explained in details in a later section of this tutorial.</p>
+         
+      <p>Note also that loading a glyph bitmap with a non-identity transform
+         will produce an error..</p>
       <hr>
 
     <h3>
@@ -721,7 +735,7 @@
          if (error) continue;  // ignore errors
          
          // convert to an anti-aliased bitmap
-         error = FT_Render_Glyph( face->glyph, ft_render_mode_antialias );
+         error = FT_Render_Glyph( face->glyph, ft_render_mode_normal );
          if (error) continue;
          
          // now, draw to our target surface
@@ -790,7 +804,7 @@
        for ( n = 0; n &lt; num_chars; n++ )
        {
          // load glyph image into the slot (erase previous one)
-         error = FT_Load_Char( face, text[n], FT_LOAD_RENDER | FT_LOAD_ANTI_ALIAS );
+         error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
          if (error) continue;  // ignore errors
          
          // now, draw to our target surface
@@ -815,12 +829,15 @@
       
       <li><p>
           We do not use <tt>FT_LOAD_DEFAULT</tt> for the loading mode, but
-          the two bit flags <tt><b>FT_LOAD_RENDER</b></tt> and
-          <tt><b>FT_LOAD_ANTI_ALIAS</b></tt>. The first flag indicates that
-          the glyph image must be immediately converted to a bitmap, and
-          the second that it should be renderer anti-aliased. Of course, this
-          is also a shortcut that avoids calling <tt>FT_Render_Glyph</tt>
-          explicitely but is strictly equivalent..
+          the bit flag <tt><b>FT_LOAD_RENDER</b></tt>. It indicates that
+          the glyph image must be immediately converted to an anti-aliased
+          bitmap. This is of course a shortcut that avoids calling
+          <tt>FT_Render_Glyph</tt> explicitely but is strictly equivalent.</p>
+          
+          <p>
+          Note that you can also specify that you want a monochrome bitmap
+          instead by using the addition <tt><b>FT_LOAD_MONOCHROME</b></tt>
+          load flag.
       </p></li>
     </ul>  
     
@@ -857,7 +874,7 @@
          FT_Set_Transform( face, &matrix, &pen );
          
          // load glyph image into the slot (erase previous one)
-         error = FT_Load_Char( face, text[n], FT_LOAD_RENDER | FT_LOAD_ANTI_ALIAS );
+         error = FT_Load_Char( face, text[n], FT_LOAD_RENDER );
          if (error) continue;  // ignore errors
          
          // now, draw to our target surface (convert position)
@@ -908,6 +925,9 @@
        complex than the previous one, it is strictly equivalent
        for the case where the transform is the identity.. Hence it can
        be used as a replacement (but a more powerful one).</p>
+
+    <p>It has however a few short comings that we will explain, and solve,
+       in the next part of this tutorial.</p>
 
     <hr>
 
--- /dev/null
+++ b/docs/tutorial/step2.html
@@ -1,0 +1,1399 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+  <meta http-equiv="Content-Type"
+        content="text/html; charset=iso-8859-1">
+  <meta name="Author"
+        content="David Turner">
+  <title>FreeType 2 Tutorial</title>
+</head>
+
+<body text="#000000"
+      bgcolor="#FFFFFF"
+      link="#0000EF"
+      vlink="#51188E"
+      alink="#FF0000">
+
+<h1 align=center>
+  FreeType 2.0 Tutorial<br>
+  Step 2 - managing glyphs
+</h1>
+
+<h3 align=center>
+  &copy; 2000 David Turner
+    (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
+  &copy; 2000 The FreeType Development Team
+    (<a href="http://www.freetype.org">www.freetype.org</a>)
+</h3>
+
+<center>
+<table width="70%">
+<tr><td>
+
+  <hr>
+
+  <h2>
+    Introduction
+  </h2>
+
+  <p>This is the second section of the FreeType 2 tutorial. It will teach
+     you the following:</p>
+  
+  <ul>
+    <li>how to retrieve glyph metrics</li>
+    <li>how to easily manage glyph images</li>
+    <li>how to retrieve global metrics (including kerning)</li>
+    <li>how to render a simple string of text, with kerning</li>
+    <li>how to render a centered string of text (with kerning)</li>
+    <li>how to render a transformed string of text (with centering)</li>
+    <li>finally, how to access metrics in design font units when needed,
+        and how to scale them to device space.</li>
+  </ul>
+    
+    <hr>
+    
+    <h3>
+      1. Glyph metrics:
+    </h3>
+
+    <p>Glyph metrics are, as their name suggests, certain distances associated
+       to each glyph in order to describe how to use it to layout text.</p>
+
+    <p>There are usually two sets of metrics for a single glyph: those used to
+       layout the glyph in horizontal text layouts (like latin, cyrillic,
+       arabic, hebrew, etc..), and those used to layout the glyph in vertical
+       text layouts (like some layouts of Chinese, Japanese, Korean, and
+       others..).</p>
+
+    <p>Note that only a few font formats provide vertical metrics. You can
+       test wether a given face object contains them by using the macro
+       <tt><b>FT_HAS_VERTICAL(face)</b></tt>, which is true when appropriate.</p>
+       
+    <p>Individual glyph metrics can be accessed by first loading the glyph
+       in a face's glyph slot, then accessing them through the
+       <tt><b>face->glyph->metrics</b></tt> structure. This will be detailed
+       later, for now, we'll see that it contains the following fields:</p>
+    
+    <center><table width="90%" cellpadding=5><tr valign=top><td>
+    <tt><b>width</b></tt>
+    </td><td>
+    <p>This is the width of the glyph image's bounding box. It is independent
+       of layout direction.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>height</b></tt>
+    </td><td>
+    <p>This is the height of the glyph image's bounding box. It is independent
+       of layout direction.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>horiBearingX</b></tt>
+    </td><td>
+    <p>For <em>horizontal text layouts</em>, this is the horizontal distance from
+       the current cursor position to the left-most border of the glyph image's
+       bounding box.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>horiBearingY</b></tt>
+    </td><td>
+    <p>For <em>horizontal text layouts</em>, this is the vertical distance from
+       the current cursor position (on the baseline) to the top-most border of
+       the glyph image's bounding box.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>horiAdvance</b></tt>
+    </td><td>
+    <p>For <em>horizontal text layouts</em>, this is the horizontal distance
+       used to increment the pen position when the glyph is drawn as part of
+       a string of text.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>vertBearingX</b></tt>
+    </td><td>
+    <p>For <em>vertical text layouts</em>, this is the horizontal distance from
+       the current cursor position to the left-most border of the glyph image's
+       bounding box.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>vertBearingY</b></tt>
+    </td><td>
+    <p>For <em>vertical text layouts</em>, this is the vertical distance from
+       the current cursor position (on the baseline) to the top-most border of
+       the glyph image's bounding box.</p>
+    </td></tr><tr valign=top><td>
+    <tt><b>vertAdvance</b></tt>
+    </td><td>
+    <p>For <em>vertical text layouts</em>, this is the vertical distance
+       used to increment the pen position when the glyph is drawn as part of
+       a string of text.</p>
+    </td></tr></table></center>
+
+    <p><font color="red">NOTA BENE: As all fonts do not contain vertical
+       metrics, the values of <tt>vertBearingX</tt>, <tt>vertBearingY</tt>
+       and <tt>vertAdvance</tt> should not be considered reliable when
+       <tt><b>FT_HAS_VERTICAL(face)</b></tt> is false.</font></p>
+
+    <p>The following graphics illustrate the metrics more clearly. First, for
+       horizontal metrics, where the baseline is the horizontal axis :</p>
+       
+    <center><img src="metrics.png" width=388 height=253></center>
+    
+    <p>For vertical text layouts, the baseline is vertical and is the
+       vertical axis:</p>
+                            
+    <center><img src="metrics2.png" width=294 height=278></center>
+
+
+    <p>The metrics found in <tt>face->glyph->metrics</tt> are normally
+       expressed in 26.6 pixels (i.e 1/64th of pixels), unless you use
+       the <tt><b>FT_LOAD_NO_SCALE</b></tt> flag when calling
+       <tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>. In this case,
+       the metrics will be expressed in original font units.</p>
+           
+    <p>The glyph slot object has also a few other interesting fields
+       that will ease a developer's work. You can access them though
+       <tt><b>face->glyph->???</b></tt> :</p>
+
+    <center><table width="90%" cellpadding=5><tr valign=top><td>
+    <b><tt>advance</tt></b>
+    </td><td>
+    <p>This field is a <tt>FT_Vector</tt> which holds the transformed
+    advance for the glyph. That's useful when you're using a transform
+    through <tt>FT_Set_Transform</tt>, as shown in the rotated text
+    example of section I. Other than that, its value is
+    by default (metrics.horiAdvance,0), unless you specify
+    <tt><b>FT_LOAD_VERTICAL</b></tt> when loading the glyph image;
+    it will then be (0,metrics.vertAdvance)</p>
+    </td></tr><tr valign=top><td>
+    <b><tt>linearHoriAdvance</tt></b>
+    </td><td>
+    <p>
+    This field contains the linearly-scaled value of the glyph's horizontal
+    advance width. Indeed, the value of <tt>metrics.horiAdvance</tt> that is
+    returned in the glyph slot is normally rounded to integer pixel
+    coordinates (i.e., it will be a multiple of 64) by the font driver used
+    to load the glyph image. <tt>linearHoriAdvance</tt> is a 16.16 fixed float
+    number that gives the value of the original glyph advance width in
+    1/65536th of pixels. It can be use to perform pseudo device-independent
+    text layouts.</p>
+    </td></tr><tr valign=top><td>          
+    <b><tt>linearVertAdvance</tt></b>
+    </td><td>
+    <p>This is the same thing as <tt><b>linearHoriAdvance</b></tt> for the
+    glyph's vertical advance height. Its value is only reliable if the font
+    face contains vertical metrics.</p>
+    </td></tr></table></center>
+       
+
+
+  <hr>
+
+  <h3>
+    2. Managing glyph images:
+  </h3>
+
+  <p>The glyph image that is loaded in a glyph slot can be converted into
+     a bitmap, either by using <tt>FT_LOAD_RENDER</tt> when loading it, or
+     by calling <tt>FT_Render_Glyph</tt>. Each time you load a new glyph
+     image, the previous one is erased from the glyph slot.</p>
+    
+  <p>There are times however where you may need to extract this image from
+     the glyph slot, in order to cache it within your application, and
+     even perform additional transforms and measures on it before converting
+     it to a bitmap.
+  </p>
+
+  <p>The FreeType 2 API has a specific extension which is capable of dealing
+     with glyph images in a flexible and generic way. To use it, you first need
+     to include the "<tt>ftglyph.h</tt>" header file, as in:</p>
+     
+  <pre><font color="blue">
+      #include &lt;freetype/ftglyph.h&gt;
+  </font></pre>
+
+  <p>We will now explain how to use the functions defined in this file:</p>
+  
+  <h4>a. Extracting the glyph image:</h4>
+
+  <p>You can extract a single glyph image very easily. Here's some code
+     that shows how to do it:</p>
+
+  <pre><font color="blue">
+       FT_Glyph    glyph;    <font color="gray">// handle to glyph image</font>
+       
+       ....
+       error = FT_Load_Glyph( face, glyph, FT_LOAD_NORMAL );
+       if (error) { .... }
+       
+       error = FT_Get_Glyph( face->glyph, &glyph );
+       if (error) { .... }
+  </font></pre>
+
+  <p>As you see, we have:</p>
+  
+  <ul>
+     <li><p>
+       Created a variable, named <tt>glyph</tt>, of type <tt>FT_Glyph</tt>.
+       This is a handle (pointer) to an individual glyph image.
+     </p></li>
+         
+     <li><p>
+       Loaded the glyph image normally in the face's glyph slot. We did not
+       use <tt>FT_LOAD_RENDER</tt> because we want to grab a scalable glyph
+       image, in order to later transform it.
+     </p></li>
+
+     <li><p>
+       Copy the glyph image from the slot into a new <tt>FT_Glyph</tt> object,
+       by calling <tt><b>FT_Get_Glyph</b></tt>. This function returns an error
+       code and sets <tt>glyph</tt>.
+     </p></li>
+  </ul>
+  
+  <p>It is important to note that the extracted glyph is in the same format
+     than the original one that is still in the slot. For example, if we're
+     loading a glyph from a TrueType font file, the glyph image will really
+     be a scalable vector outline.</p>
+
+  <p>You can access the field <tt><b>glyph->format</b></tt> if you want to
+     know exactly how the glyph is modeled and stored. A new glyph object can
+     be destroyed with a call to <tt><b>FT_Done_Glyph</b></tt>.</p>
+
+  <p>The glyph object contains exactly one glyph image and a 2D vector
+     representing the glyph's advance in 16.16 fixed float coordinates.
+     The latter can be accessed directly as <tt><b>glyph->advance</b></tt>
+     </p>
+
+  <p><font color="red">Note that unlike
+     other FreeType objects, the library doesn't keeps a list of all
+     allocated glyph objects. This means you'll need to destroy them
+     yourself, instead of relying on <tt>FT_Done_FreeType</tt> doing
+     all the clean-up.</font></p>
+     
+  <h4>b. Transforming & copying the glyph image</h4>
+
+  <p>If the glyph image is scalable (i.e. if <tt>glyph->format</tt> is not
+     equal to <tt>ft_glyph_format_bitmap</tt>), it is possible to transform
+     the image anytime by a call to <tt><b>FT_Glyph_Transform</b></tt>.</p>
+     
+  <p>You can also copy a single glyph image with <tt><b>FT_Glyph_Copy</b></tt>.
+     Here's some example code:</p>
+     
+  <pre><font color="blue">
+    FT_Glyph  glyph, glyph2;
+    FT_Matrix matrix;
+    FT_Vector delta;
+    
+    ......
+    .. load glyph image in "glyph" ..
+    
+    <font color="gray">// copy glyph to glyph2
+    //</font>
+    error = FT_Glyph_Copy( glyph, &glyph2 );
+    if (error) { ... could not copy (out of memory) }
+    
+    <font color="gray">// translate "glyph"
+    //</font>    
+    delta.x = -100 * 64;   // coordinates are in 26.6 pixels
+    delta.y =  50  * 64;
+    
+    FT_Glyph_Transform( glyph, 0, &delta );
+    
+    <font color="gray">// transform glyph2 (horizontal shear)
+    //</font>
+    matrix.xx = 0x10000;
+    matrix.xy = 0;
+    matrix.yx = 0.12 * 0x10000;
+    matrix.yy = 0x10000;
+    
+    FT_Glyph_Transform( glyph2, &matrix, 0 );
+  </font></pre>
+
+  <p>Note that the 2x2 transform matrix is always applied to the 16.16
+     advance vector in the glyph, you thus don't need to recompute it..</p>
+
+  <h4>c. Measuring the glyph image</h4>
+  
+  <p>You can also retrieve the control (bounding) box of any glyph image
+     (scalable or not), through the <tt><b>FT_Glyph_Get_CBox</b></tt> function,
+     as in:
+     </p>
+
+  <pre><font color="blue">
+     FT_BBox   bbox;
+     ...
+     FT_Glyph_BBox(  glyph, <em>bbox_mode</em>, &bbox );
+  </font></pre>
+
+  <p>Coordinates are relative to the glyph origin, i.e. (0,0), using the
+     Y_upwards convention. This function takes a special argument, the
+     "bbox mode", that is a set of bit flags used to indicate how
+     box coordinates are expressed. If <tt><b>ft_glyph_bbox_subpixels</b></tt>
+     is set in the bbox mode, the coordinates are returned in 26.6 pixels
+     (i.e. 1/64th of pixels). Otherwise, they're in integer pixels.</p>
+
+  <p>Note that the box's maximum coordinates are exclusive, which means
+     that you can always compute the width and height of the glyph image,
+     be in in integer or 26.6 pixels with:</p>
+     
+  <pre><font color="blue">     
+     width  = bbox.xMax - bbox.xMin;
+     height = bbox.yMax - bbox.yMin;
+  </font></pre>
+
+  <p>Note also that for 26.6 coordinates, if
+     <tt><b>ft_glyph_bbox_gridfit</b></tt> is set in the bbox mode,
+     the coordinates will also be grid-fitted, which corresponds to:</p>
+     
+  <pre><font color="blue">
+     bbox.xMin = FLOOR(bbox.xMin)
+     bbox.yMin = FLOOR(bbox.yMin)
+     bbox.xMax = CEILING(bbox.xMax)
+     bbox.yMax = CEILING(bbox.yMax)
+  </font></pre>
+
+  <p>The default value for the bbox mode, which is 0, corresponds to
+     <b><tt>ft_glyph_bbox_pixels</tt></b> (i.e. integer pixel coordinates).</p>
+
+
+  <h4>d. Converting the glyph image to a bitmap</h4>
+  
+  <p>You may need to convert the glyph object to a bitmap once you have
+     convienently cached or transformed it. This can be done easily with
+     the <b><tt>FT_Glyph_To_Bitmap</tt></b> function. It is chared of
+     converting any glyph object into a bitmap, as in:</p>
+     
+  <pre><font color="blue">
+    FT_Vector  origin;
+    
+    origin.x = 32;   <font color="gray">/* 1/2 pixel in 26.26 format */</font>
+    origin.y = 0;
+    
+    error = FT_Glyph_To_Bitmap( &glyph,
+                                <em>render_mode</em>,
+                                &origin,
+                                1 );        <font color="gray">// destroy original image == true</font>
+  </font></pre>
+
+  <p>We will know details this function's parameters:</p>
+  
+  <ul>
+     <li><p>
+       the first parameter is <em>the address of the source glyph's handle</em>.
+       When the function is called, it reads its to access the source
+       glyph object. After the call, the handle will point to a
+       <b><em>new</em></b> glyph object that contains the rendered bitmap.
+     </p></li>
+     
+     <li><p>
+       the second parameter is a standard render mode, that is used to specify
+       what kind of bitmap we want. It can be <tt>ft_render_mode_default</tt>
+       for an 8-bit anti-aliased pixmap, or <tt>ft_render_mode_mono</tt> for
+       a 1-bit monochrome bitmap.
+     </p></li>
+     
+     <li><p>
+       the third parameter is a pointer to a 2D vector that is used to
+       translate the source glyph image before the conversion. Note that
+       the source image will be translated back to its original position
+       (and will thus be left unchanged) after the call. If you do not need
+       to translate the source glyph before rendering, set this pointer to 0.
+     </p></li>
+     
+     <li><p>
+       the last parameter is a boolean that indicates wether the source
+       glyph object should be destroyed by the function. By default, the
+       original glyph object is never destroyed, even if its handle is
+       lost (it's up to client applications to keep it).
+     </p></li>
+  </ul>
+  
+  <p>The new glyph object always contain a bitmap (when no error is returned),
+     and you must <b><em>typecast</em></b> its handle to the
+     <tt><b>FT_BitmapGlyph</b></tt> type in order to access its content.
+     This type is a sort of "subclass" of <tt>FT_Glyph</tt> that contains
+     additional fields:</p>
+  
+  <center><table width="80%" cellpadding=5><tr valign=top><td>
+  <tt><b>left</b></tt>
+  </td><td>
+  <p>Just like the <tt><b>bitmap_left</b></tt> field of a glyph slot, this is the
+  horizontal distance from the glyph origin (0,0) to the left-most pixel
+  of the glyph bitmap. It is expressed in integer pixels.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>top</b></tt>
+  </td><td>
+  <p>Just like the <tt><b>bitmap_top</b></tt> field of a glyph slot, this is the
+  vertical distance from the glyph origin (0,0) to the top-most pixel
+  of the glyph bitmap (more exactly, to the pixel just above the bitmap).
+  This distance is expressed in integer pixels, and is positive for upwards
+  Y.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>bitmap</b></tt>
+  </td><td>
+  <p>This is a bitmap descriptor for the glyph object, just like the
+  <tt><b>bitmap</b></tt> field in a glyph slot.</p>
+  </td></tr></table></center>
+  
+  <hr>
+  <h3>
+    3. Global glyph metrics:
+  </h3>
+  
+  <p>Unlike glyph metrics, global ones are used to describe distances
+     and features of a whole font face. They can be expressed either in
+     26.6 pixels or in design "font units" for scalable formats.</p>
+
+  <h4>
+    a. Design Global Metrics:
+  </h4>
+
+  <p>For scalable formats, all global metrics are expressed in font units
+     in order to be later scaled to device space, according to the rules
+     described in the last chapter of this section of the tutorial. You
+     can access them directly as simple fields of a <tt>FT_Face</tt>
+     handle.</p>
+     
+  <p>However, you need to check that the font face's format is scalable
+     before using them. One can do it by using the macro
+     <tt><b>FT_IS_SCALABLE(face)</b></tt> which returns true when
+     appropriate.</p>
+
+  <p>In this case, you can access the global design metrics as:</p>
+
+  <center><table width="90%" cellpadding=5><tr valign=top><td>
+  <tt><b>units_per_EM</b></tt>
+  </td><td>
+  <p>This is the size of the EM square for the font face. It is used by scalable
+     formats to scale design coordinates to device pixels, as described by the
+     last chapter of this section. Its value usually is 2048 (for TrueType)
+     or 1000 (for Type1), but others are possible too. It is set to 1 for
+     fixed-size formats like FNT/FON/PCF/BDF.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>global_bbox</b></tt>
+  </td><td>
+  <p>The global bounding box is defined as the largest rectangle that can
+     enclose all the glyphs in a font face. It is defined for horizontal
+     layouts only.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>ascender</b></tt>
+  </td><td>
+  <p>The ascender is the vertical distance from the horizontal baseline to
+     the highest "character" coordinate in a font face. <em>Unfortunately, font
+     formats define the ascender differently</em>. For some, it represents
+     the ascent of all capital latin characters, without accents, for others
+     it's the ascent of the highest accented character, and finally, other
+     formats define it as being equal to <tt>global_bbox.yMax</tt>.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>descender</b></tt>
+  </td><td>
+  <p>The descender is the vertical distance from the horizontal baseline to
+     the lowest "character" coordinate in a font face. <em>Unfortunately, font
+     formats define the descender differently</em>. For some, it represents
+     the descent of all capital latin characters, without accents, for others
+     it's the ascent of the lowest accented character, and finally, other
+     formats define it as being equal to <tt>global_bbox.yMin</tt>.
+     <em><b>This field is usually negative</b></em></p>
+  </td></tr><tr valign=top><td>
+  <tt><b>text_height</b></tt>
+  </td><td>
+  <p>This field is simply used to compute a default line spacing (i.e. the
+  baseline-to-baseline distance) when writing text with this font. Note that
+  it usually is larger than the sum of the ascender and descender taken in
+  absolute value. There is also no guarantee that no glyphs can extend
+  above or below subsequent baselines when using this distance.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>max_advance_width</b></tt>
+  </td><td>
+  <p>This field gives the maximum horizontal cursor advance for all glyphs
+  in the font. It can be used to quickly compute the maximum advance width
+  of a string of text. <em>It doesn't correspond to the maximum glyph image
+  width !!</em></p>
+  </td></tr><tr valign=top><td>
+  <tt><b>max_advance_height</b></tt>
+  </td><td>
+  <p>Same as <tt>max_advance_width</tt> but for vertical text layout. It is
+  only available in fonts providing vertical glyph metrics.</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>underline_position</b></tt>
+  </td><td>
+  <p>When displaying or rendering underlined text, this value corresponds to
+  the vertical position, relative to the baseline, of the underline bar. It
+  noramlly is negative (as it's below the baseline).</p>
+  </td></tr><tr valign=top><td>
+  <tt><b>underline_thickness</b></tt>
+  </td><td>
+  <p>When displaying or rendering underlined text, this value corresponds to
+  the vertical thickness of the underline.</p>
+  </td></tr></table></center>
+  
+  <p>Notice how, unfortunately, the values of the ascender and the descender
+     are not reliable (due to various discrepancies in font formats).</p>       
+  
+  <h4>
+    b. Scaled Global Metrics:
+  </h4>
+
+  <p>Each size object also contains a scaled versions of some of the global
+     metrics described above. They can be accessed directly through the
+     <tt><b>face->size->metrics</b></tt> structure.</p>
+     
+  <p>Note that these values correspond to scaled versions of the design
+     global metrics, <em>with no rounding/grid-fitting performed.</em>.
+     They are also completely independent of any hinting process. In other
+     words, don't rely on them to get exact metrics at the pixel level.
+     They're expressed in 26.6 pixels.</p>
+
+  <center><table width="80%" cellpadding=5><tr valign=top><td>
+  <b><tt>ascender</tt></b>
+  </td><td>
+  <p>This is the scaled version of the original design ascender.</p>
+  </td></tr><tr valign=top><td>
+  <b><tt>descender</tt></b>
+  </td><td>
+  <p>This is the scaled version of the original design descender.</p>
+  </td></tr><tr valign=top><td>
+  <b><tt>height</tt></b>
+  </td><td>
+  <p>This is the scaled version of the original design text height.
+  That probably is the only field you should really use in this structure.</p>
+  </td></tr><tr valign=top><td>
+  <b><tt>max_advance</tt></b>
+  </td><td>
+  <p>Thi is the scaled version of the original design max advance.</p>
+  </td></tr></table></center>
+
+  <p>Note that the <tt><b>face->size->metrics</b></tt> structure contains other
+  fields that are used to scale design coordinates to device space. They're
+  described, in the last chapter.</p>
+
+  <h4>
+    c. Kerning:
+  </h4>  
+  
+  <p>Kerning is the process of adjusting the position of two subsequent
+     glyph images in a string of text, in order to improve the general
+     appearance of text. Basically, it means that when the glyph for an
+     "A" is followed by the glyph for a "V", the space between them can
+     be slightly reduced to avoid extra "diagonal whitespace".</p>
+     
+  <p>Note that in theory, kerning can happen both in the horizontal and
+     vertical direction between two glyphs; however, it only happens in
+     the horizontal direction in nearly all cases except really extreme
+     ones.</p>
+
+  <p>Note all font formats contain kerning information. Instead, they sometimes
+     rely on an additional file that contains various glyph metrics, including
+     kerning, but no glyph images. A good example would be the Type 1 format,
+     where glyph images are stored in a file with extension ".pfa" or ".pfb",
+     and where kerning metrics can be found in an additional file with extension
+     ".afm" or ".pfm".</p>
+     
+  <p>FreeType 2 allows you to deal with this, by providing the
+     <tt><b>FT_Attach_File</b></tt> and <tt><b>FT_Attach_Stream</b></tt> APIs.
+     Both functions are used to load additional metrics into a face object,
+     by reading them from an additional format-specific file. For example,
+     you could open a Type 1 font by doing the following:</p>
+     
+  <pre><font color="blue">
+      error = FT_New_Face( library, "/usr/shared/fonts/cour.pfb", 0, &face );
+      if (error) { ... }
+      
+      error = FT_Attach_File( face, "/usr/shared/fonts/cour.afm" );
+      if (error) { .. could not read kerning and additional metrics .. }
+  </font></pre>
+
+  <p>Note that <tt><b>FT_Attach_Stream</b></tt> is similar to
+     <tt><b>FT_Attach_File</b></tt> except that it doesn't take a C string
+     to name the extra file, but a <tt>FT_Stream</tt> handle. Also,
+     <em>reading a metrics file is in no way, mandatory</em>.</p>
+
+  <p>Finally, the file attachment APIs are very generic and can be used to
+     load any kind of extra information for a given face. The nature of the
+     additional content is entirely font format specific.</p>
+
+  <p>FreeType 2 allows you to retrieve the kerning information between
+     two glyphs through the <tt><b>FT_Get_Kerning</b></tt> function, whose
+     interface looks like:</p>
+     
+  <pre><font color="blue">
+     FT_Vector  kerning;
+     ...
+     error = FT_Get_Kerning( face,                  <font color="gray">// handle to face object</font>
+                             left,                  <font color="gray">// left glyph index</font>
+                             right,                 <font color="gray">// right glyph index</font>
+                             <em>kerning_mode</em>,          <font color="gray">// kerning mode</font>
+                             &kerning );            <font color="gray">// target vector</font>
+  </font></pre>
+
+  <p>As you see, the function takes a handle to a face object, the indices
+     of the left and right glyphs for which the kerning value is desired,
+     as well as an integer, called the "kerning mode", and a pointer to
+     a destination vector that receives the corresponding distances.</p>
+  
+  <p>The kerning mode is very similar to the "bbox mode" described in a
+     previous chapter. It's a enumeration that indicates how the
+     kerning distances are expressed in the target vector.</p>
+     
+  <p>The default value is <tt><b>ft_kerning_mode_default</b></tt> which
+     has value 0. It corresponds to kerning distances expressed in 26.6
+     grid-fitted pixels (which means that the values are multiples of 64).
+     For scalable formats, this means that the design kerning distance is
+     scaled then rounded.</p>
+     
+  <p>The value <tt><b>ft_kerning_mode_unfitted</b></tt> corresponds to kerning
+     distances expressed in 26.6 unfitted pixels (i.e. that do not correspond
+     to integer coordinates). It's the design kerning distance that is simply
+     scaled without rounding.</p>
+     
+  <p>Finally, the value <tt><b>ft_kerning_mode_unscaled</b></tt> is used to
+     return the design kerning distance, expressed in font units. You can
+     later scale it to device space using the computations explained in the
+     last chapter of this section.</p>
+
+  <p>Note that the "left" and "right" positions correspond to the <em>visual
+     order</em> of the glyphs in the string of text. This is important for
+
+     bi-directional text, or simply when writing right-to-left text..</p>
+     
+  <hr>
+
+  <h3>
+    4. Simple text rendering: kerning + centering:
+  </h3>  
+
+  <p>In order to show off what we just learned, we will now show how to modify
+     the example code that was provided in section I to render a string of text,
+     and enhance it to support kerning and delayed rendering.</p>
+
+   <h4>
+     a. Kerning support:
+   </h4>
+   
+   <p>Adding support for kerning to our code is trivial, as long as we consider
+      that we're still dealing with a left-to-right script like Latin. We
+      simply need to retrieve the kerning distance between two glyphs in order
+      to alter the pen position appropriately. The code looks like:</p>
+      
+   <font color="blue"><pre>
+      FT_GlyphSlot  slot = face->glyph;  // a small shortcut
+      FT_UInt       glyph_index;
+      FT_Bool       use_kerning;
+      FT_UInt       previous;
+      int           pen_x, pen_y, n;
+
+      .. initialise library ..
+      .. create face object ..
+      .. set character size ..
+      
+      pen_x = 300;
+      pen_y = 200;
+      
+      use_kerning = FT_HAS_KERNING(face);
+      previous    = 0;
+      
+      for ( n = 0; n &lt; num_chars; n++ )
+      {
+        <font color="gray">// convert character code to glyph index</font>
+        glyph_index = FT_Get_Char_Index( face, text[n] );
+        
+        <font color="gray">// retrieve kerning distance and move pen position</font>
+        if ( use_kerning && previous && glyph_index )
+        {
+          FT_Vector  delta;
+          
+          FT_Get_Kerning( face, previous, glyph_index,
+                          ft_kerning_mode_default, &delta );
+                          
+          pen_x += delta.x >> 6;
+        }
+      
+        <font color="gray">// load glyph image into the slot (erase previous one)</font>
+        error = FT_Load_Glyph( face, glyph_index, FT_LOAD_RENDER );
+        if (error) continue;  <font color="gray">// ignore errors</font>
+        
+        <font color="gray">// now, draw to our target surface</font>
+        my_draw_bitmap( &slot->bitmap,
+                        pen_x + slot->bitmap_left,
+                        pen_y - slot->bitmap_top );
+                        
+        <font color="gray">// increment pen position</font>
+        pen_x += slot->advance.x >> 6;
+        
+        <font color="gray">// record current glyph index</font>
+        previous = glyph_index
+      }
+   </pre></font>   
+
+   <p>That's it. You'll notice that:</p>
+   
+   <ul>
+     <li><p>
+        As kerning is determined from glyph indices, we need to explicitely
+        convert our character code into a glyph index, then later call
+        <tt>FT_Load_Glyph</tt> instead of <tt>FT_Load_Char</tt>. No big
+        deal, if you ask me :-)
+     </p></li>
+     
+     <li><p>
+        We use a boolean named <tt>use_kerning</tt> which is set with the
+        result of the macro <tt><b>FT_HAS_KERNING(face)</b></tt>. It's
+        certainly faster not to call <tt>FT_Get_Kerning</tt> when we know
+        that the font face does not contain kerning information.
+     </p></li>
+     
+     <li><p>
+        We move the position of the pen <em>before</em> a new glyph is drawn.
+     </p></li>
+     
+     <li><p>
+        We did initialize the variable <tt>previous</tt> with the value 0,
+        which always correspond to the "missing glyph" (also called
+        <tt>.notdef</tt> in the Postscript world). There is never any
+        kerning distance associated with this glyph.
+     </p></li>
+     
+     <li><p>
+        We do not check the error code returned by <tt>FT_get_Kerning</tt>.
+        This is because the function always set the content of <tt>delta</tt>
+        to (0,0) when an error occurs.
+     </p></li>
+   </ul>
+
+   <p>As you see, this is not terribly complex :-)</p>
+
+  <h4>
+    b. Centering:
+  </h4>
+
+   <p>Our code begins to become interesting but it's still a bit too simple
+      for normal uses. For example, the position of the pen is determined
+      before we do the rendering when in a normal situation, you would want
+      to layout the text and measure it before computing its final position
+      (e.g. centering) or perform things like word-wrapping.</p>
+      
+   <p>We're thus now going to decompose our text rendering function into two
+      distinct but successive parts: the first one will position individual
+      glyph images on the baseline, while the second one will render the
+      glyphs. As we'll see, this has many advantages.</p>
+      
+   <p>We will thus start by storing individual glyph images, as well as their
+      position on the baseline. This can be done with code like:</p>
+      
+   <font color="blue"><pre>
+      FT_GlyphSlot  slot = face->glyph;  <font color="gray">// a small shortcut</font>
+      FT_UInt       glyph_index;
+      FT_Bool       use_kerning;
+      FT_UInt       previous;
+      int           pen_x, pen_y, n;
+      
+      FT_Glyph      glyphs[ MAX_GLYPHS ];   <font color="gray">// glyph image</font>
+      FT_Vector     pos   [ MAX_GLYPHS ];   <font color="gray">// glyph position</font>
+      FT_UInt       num_glyphs;
+
+      .. initialise library ..
+      .. create face object ..
+      .. set character size ..
+      
+      pen_x = 0;   <font color="gray">/* start at (0,0) !! */</font>
+      pen_y = 0;
+      
+      num_glyphs  = 0;
+      use_kerning = FT_HAS_KERNING(face);
+      previous    = 0;
+      
+      for ( n = 0; n &lt; num_chars; n++ )
+      {
+        <font color="gray">// convert character code to glyph index</font>
+        glyph_index = FT_Get_Char_Index( face, text[n] );
+        
+        <font color="gray">// retrieve kerning distance and move pen position</font>
+        if ( use_kerning && previous && glyph_index )
+        {
+          FT_Vector  delta;
+          
+          FT_Get_Kerning( face, previous, glyph_index,
+                          ft_kerning_mode_default, &delta );
+                          
+          pen_x += delta.x >> 6;
+        }
+      
+        <font color="gray">// store current pen position</font>
+        pos[ num_glyphs ].x = pen_x;
+        pos[ num_glyphs ].y = pen_y;
+      
+        <font color="gray">// load glyph image into the slot. DO NOT RENDER IT !!</font>
+        error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
+        if (error) continue;  // ignore errors, jump to next glyph
+        
+        <font color="gray">// extract glyph image and store it in our table</font>
+        error = FT_Get_Glyph( face->glyph, & glyphs[num_glyphs] );
+        if (error) continue;  // ignore errors, jump to next glyph
+        
+        <font color="gray">// increment pen position</font>
+        pen_x += slot->advance.x >> 6;
+        
+        <font color="gray">// record current glyph index</font>
+        previous = glyph_index
+        
+        <font color="gray">// increment number of glyphs</font>
+        num_glyphs++;
+      }
+   </pre></font>   
+      
+   <p>As you see, this is a very simple variation of our previous code
+      where we extract each glyph image from the slot, and store it, along
+      with the corresponding position, in our tables.</p>
+   
+   <p>Note also that "pen_x" contains the total advance for the string of
+      text. We can now compute the bounding box of the text string with
+      a simple function like:</p>
+      
+      
+   <font color="blue"><pre>
+      void   compute_string_bbox( FT_BBox  *abbox )
+      {
+        FT_BBox  bbox;
+        
+        <font color="gray">// initialise string bbox to "empty" values</font>
+        bbox.xMin = bbox.yMin =  32000;
+        bbox.xMax = bbox.yMax = -32000;
+        
+        <font color="gray">// for each glyph image, compute its bounding box, translate it,
+        // and grow the string bbox</font>
+        for ( n = 0; n &lt; num_glyphs; n++ )
+        {
+          FT_BBox   glyph_bbox;
+
+          FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox );
+
+          glyph_bbox.xMin += pos[n].x;
+          glyph_bbox.xMax += pos[n].x;
+          glyph_bbox.yMin += pos[n].y;
+          glyph_bbox.yMax += pos[n].y;
+
+          if (glyph_bbox.xMin &lt; bbox.xMin)
+            bbox.xMin = glyph_bbox.xMin;
+
+          if (glyph_bbox.yMin &lt; bbox.yMin)
+            bbox.yMin = glyph_bbox.yMin;
+
+          if (glyph_bbox.xMax &gt; bbox.xMax)
+            bbox.xMax = glyph_bbox.xMax;
+
+          if (glyph_bbox.yMax &gy; bbox.yMax)
+            bbox.yMax = glyph_bbox.yMax;
+        }
+        
+        <font color="gray">// check that we really grew the string bbox</font>
+        if ( bbox.xMin > bbox.xMax )
+        {
+          bbox.xMin = 0;
+          bbox.yMin = 0;
+          bbox.xMax = 0;
+          bbox.yMax = 0;
+        }
+        
+        <font color="gray">// return string bbox</font>
+        *abbox = bbox;
+      }
+   </pre></font>
+
+   <p>The resulting bounding box dimensions can then be used to compute the
+      final pen position before rendering the string as in:</p>
+
+   <font color="blue"><pre>
+      <font color="gray">// compute string dimensions in integer pixels</font>
+      string_width  = (string_bbox.xMax - string_bbox.xMin)/64;
+      string_height = (string_bbox.yMax - string_bbox.yMin)/64;
+   
+      <font color="gray">// compute start pen position in 26.6 cartesian pixels</font>
+      start_x = (( my_target_width  - string_width )/2)*64;
+      start_y = (( my_target_height - string_height)/2)*64;
+      
+      for ( n = 0; n &lt; num_glyphs; n++ )
+      {
+        FT_Glyph  image;
+        FT_Vector pen;
+        
+        image = glyphs[n];
+        
+        pen.x = start_x + pos[n].x;
+        pen.y = start_y + pos[n].y;
+        
+        error = FT_Glyph_To_Bitmap( &image, ft_render_mode_normal,
+                                    &pen.x, 0 );
+        if (!error)
+        {
+          FT_BitmapGlyph  bit = (FT_BitmapGlyph)image;
+          
+          my_draw_bitmap( bitmap->bitmap,
+                          bitmap->left,
+                          my_target_height - bitmap->top );
+                          
+          FT_Done_Glyph( image );
+        }
+      }
+   </pre></font>
+   
+   <p>You'll take note that:</p>
+   
+   <ul>
+     <li><p>
+       The pen position is expressed in the cartesian space (i.e. Y upwards).
+     </p></li>
+     
+     <li><p>
+       We call <tt><b>FT_Glyph_To_Bitmap</b></tt> with the <tt>destroy</tt>
+       parameter set to 0 (false), in order to avoid destroying the original
+       glyph image. The new glyph bitmap is accessed through <tt>image</tt>
+       after the call and is typecasted to a <tt>FT_BitmapGlyph</tt>.
+     </p></li>
+     
+     <li><p>
+       We use translation when calling <tt>FT_Glyph_To_Bitmap</tt>. This
+       ensures that the <tt><b>left</b></tt> and <tt><b>top</b></tt> fields
+       of the bitmap glyph object are already set to the correct pixel
+       coordinates in the cartesian space.
+     </p></li>
+     
+     <li><p>
+       Of course, we still need to convert pixel coordinates from cartesian
+       to device space before rendering, hence the <tt>my_target_height -
+       bitmap->top</tt> in the call to <tt>my_draw_bitmap</tt>.
+     </p></li>
+     
+   </ul>
+   
+   <p>The same loop can be used to render the string anywhere on our display
+      surface, without the need to reload our glyph images each time.. We
+      could also decide to implement word wrapping, and only draw</p>
+
+  <hr>
+  <h3>
+    5. Advanced text rendering:  transform + centering + kerning:
+  </h3>
+
+  <p>We are now going to modify our code in order to be able to easily
+     transform the rendered string, for example to rotate it. We will
+     start by performing a few minor improvements:</p>
+
+  <h4>a. packing & translating glyphs:</h4>
+  
+  <p>We'll start by packing the information related to a single glyph image
+     into a single structure, instead of parallel arrays. We thus define the
+     following structure type:</p>
+     
+  <font color="blue"><pre>
+     typedef struct TGlyph_
+     {
+       FT_UInt    index;    <font color="gray">// glyph index</font>
+       FT_Vector  pos;      <font color="gray">// glyph origin on the baseline</font>
+       FT_Glyph   image;    <font color="gray">// glyph image</font>
+     
+     } TGlyph, *PGlyph;
+  </pre></font>
+
+  <p>We will also translate each glyph image directly after it is loaded
+     to its position on the baseline at load time. As we'll see, this
+     as several advantages. Our glyph sequence loader thus becomes:</p>
+
+   <font color="blue"><pre>
+      FT_GlyphSlot  slot = face->glyph;  <font color="gray">// a small shortcut</font>
+      FT_UInt       glyph_index;
+      FT_Bool       use_kerning;
+      FT_UInt       previous;
+      int           pen_x, pen_y, n;
+      
+      TGlyph        glyphs[ MAX_GLYPHS ];   <font color="gray">// glyphs table</font>
+      PGlyph        glyph;                  <font color="gray">// current glyph in table</font>
+      FT_UInt       num_glyphs;
+
+      .. initialise library ..
+      .. create face object ..
+      .. set character size ..
+      
+      pen_x = 0;   <font color="gray">/* start at (0,0) !! */</font>
+      pen_y = 0;
+      
+      num_glyphs  = 0;
+      use_kerning = FT_HAS_KERNING(face);
+      previous    = 0;
+
+      glyph = glyphs;      
+      for ( n = 0; n &lt; num_chars; n++ )
+      {
+        glyph->index = FT_Get_Char_Index( face, text[n] );
+        
+        if ( use_kerning && previous && glyph->index )
+        {
+          FT_Vector  delta;
+          
+          FT_Get_Kerning( face, previous, glyph->index,
+                          ft_kerning_mode_default, &delta );
+                          
+          pen_x += delta.x >> 6;
+        }
+      
+        <font color="gray">// store current pen position</font>
+        glyph->pos.x = pen_x;
+        glyph->pos.y = pen_y;
+      
+        error = FT_Load_Glyph( face, glyph_index, FT_LOAD_DEFAULT );
+        if (error) continue;
+        
+        error = FT_Get_Glyph( face->glyph, &glyph->image );
+        if (error) continue;
+        
+        <font color="gray">// translate the glyph image now..</font>
+        FT_Glyph_Transform( glyph->image, 0, &glyph->pos );
+        
+        pen_x   += slot->advance.x >> 6;
+        previous = glyph->index
+        
+        <font color="gray">// increment number of glyphs</font>
+        glyph++;
+      }
+      <font color="gray">// count number of glyphs loaded..</font>
+      num_glyphs = glyph - glyphs;
+   </pre></font>   
+
+   <p>Note that translating glyphs now has several advantages. The first
+      one, is that we don't need to translate the glyph bbox when we compute
+      the string's bounding box. The code becomes:</p>
+
+   <font color="blue"><pre>
+      void   compute_string_bbox( FT_BBox  *abbox )
+      {
+        FT_BBox  bbox;
+        
+        bbox.xMin = bbox.yMin =  32000;
+        bbox.xMax = bbox.yMax = -32000;
+        
+        for ( n = 0; n &lt; num_glyphs; n++ )
+        {
+          FT_BBox   glyph_bbox;
+
+          FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox );
+
+          if (glyph_bbox.xMin &lt; bbox.xMin)
+            bbox.xMin = glyph_bbox.xMin;
+
+          if (glyph_bbox.yMin &lt; bbox.yMin)
+            bbox.yMin = glyph_bbox.yMin;
+
+          if (glyph_bbox.xMax &gt; bbox.xMax)
+            bbox.xMax = glyph_bbox.xMax;
+
+          if (glyph_bbox.yMax &gy; bbox.yMax)
+            bbox.yMax = glyph_bbox.yMax;
+        }
+        
+        if ( bbox.xMin > bbox.xMax )
+        {
+          bbox.xMin = 0;
+          bbox.yMin = 0;
+          bbox.xMax = 0;
+          bbox.yMax = 0;
+        }
+        
+        *abbox = bbox;
+      }
+   </pre></font>
+
+   <p>Now take a closer look, the <tt>compute_string_bbox</tt> can now
+      compute the bounding box of a transformed glyph string. For example,
+      we can do something like:</p>
+   
+   <pre><font color="blue">
+      FT_BBox    bbox;
+      FT_Matrix  matrix;
+      FT_Vector  delta;
+   
+      ... load glyph sequence
+      
+      ... setup "matrix" and "delta"
+      
+      <font color="gray">// transform glyphs</font>
+      for ( n = 0; n &lt; num_glyphs; n++ )
+        FT_Glyph_Transform( glyphs[n].image, &matrix, &delta );
+      
+      <font color="gray">// compute bounding box of transformed glyphs</font>
+      compute_string_bbox( &bbox );
+   </font></pre>
+
+  <h4>
+    b. Rendering a transformed glyph sequence:
+  </h4>
+  
+  <p>However, directly transforming the glyphs in our sequence is not an idea
+     if we want to re-use them in order to draw the text string with various
+     angles or transforms. It's better to perform the affine transformation
+     just before the glyph is rendered, as in the following code:</p>
+     
+   <font color="blue"><pre>
+      FT_Vector  start;
+      FT_Matrix  transform;
+   
+      <font color="gray">// get bbox of original glyph sequence</font>
+      compute_string_bbox( &string_bbox );
+   
+      <font color="gray">// compute string dimensions in integer pixels</font>
+      string_width  = (string_bbox.xMax - string_bbox.xMin)/64;
+      string_height = (string_bbox.yMax - string_bbox.yMin)/64;
+   
+      <font color="gray">// set up start position in 26.6 cartesian space</font>
+      start.x = (( my_target_width  - string_width )/2)*64;
+      start.y = (( my_target_height - string_height)/2)*64;
+      
+      <font color="gray">// set up transform (a rotation here)</font>
+      matrix.xx = (FT_Fixed)( cos(angle)*0x10000);
+      matrix.xy = (FT_Fixed)(-sin(angle)*0x10000);
+      matrix.yx = (FT_Fixed)( sin(angle)*0x10000);
+      matrix.yy = (FT_Fixed)( cos(angle)*0x10000);
+      
+      for ( n = 0; n &lt; num_glyphs; n++ )
+      {
+        FT_Glyph  image;
+        FT_Vector pen;
+        FT_BBox   bbox;
+        
+        <font color="gray">// create a copy of the original glyph</font>
+        error = FT_Glyph_Copy( glyphs[n].image, &image );
+        if (error) continue;
+
+        <font color="gray">// transform copy (this will also translate it to the correct
+        // position</font>
+        FT_Glyph_Transform( image, &matrix, &start );
+        
+        <font color="gray">// check bounding box, if the transformed glyph image
+        // is not in our target surface, we can avoid rendering it</font>
+        FT_Glyph_Get_CBox( image, ft_glyph_bbox_pixels, &bbox );
+        if ( bbox.xMax &lt;= 0 || bbox.xMin >= my_target_width  ||
+             bbox.yMax &lt;= 0 || bbox.yMin >= my_target_height )
+          continue;
+        
+        <font color="gray">// convert glyph image to bitmap (destroy the glyph copy !!)
+        //</font>
+        error = FT_Glyph_To_Bitmap( &image,
+                                    ft_render_mode_normal,
+                                    0,      <font color="gray">// no additional translation</font>
+                                    1 );    <font color="gray">// destroy copy in "image"</font>
+        if (!error)
+        {
+          FT_BitmapGlyph  bit = (FT_BitmapGlyph)image;
+          
+          my_draw_bitmap( bitmap->bitmap,
+                          bitmap->left,
+                          my_target_height - bitmap->top );
+                          
+          FT_Done_Glyph( image );
+        }
+      }
+   </pre></font>
+
+   <p>You'll notice a few changes compared to the original version of this
+      code:</p>
+      
+   <ul>
+     <li><p>
+       We keep the original glyph images untouched, by transforming a
+       copy.
+     </p></li>
+     
+     <li><p>
+       We perform clipping computations, in order to avoid rendering &
+       drawing glyphs that are not within our target surface
+     </p></li>
+     
+     <li><p>
+       We always destroy the copy when calling <tt>FT_Glyph_To_Bitmap</tt>
+       in order to get rid of the transformed scalable image. Note that
+       the image is destroyed even when the function returns an error
+       code (which is why <tt>FT_Done_Glyph</tt> is only called within
+       the compound statement.
+     </p></li>
+     
+     <li><p>
+       The translation of the glyph sequence to the start pen position is
+       integrated in the call to <tt>FT_Glyph_Transform</tt> intead of
+       <tt>FT_Glyph_To_Bitmap</tt>.
+     </p></li>
+  </ul>
+
+  <p>It's possible to call this function several times to render the string
+     width different angles, or even change the way "start" is computed in
+     order to move it to different place.</p>
+
+  <p>This code is the basis of the FreeType 2 demonstration program
+     named"<tt>ftstring.c</tt>". It could be easily extended to perform
+     advanced text layout or word-wrapping in the first part, without
+     changing the second one.</p>
+     
+  <p>Note however that a normal implementation would use a glyph cache in
+     order to reduce memory needs. For example, let's assume that our text
+     string is "FreeType". We would store three identical glyph images in
+     our table for the letter "e", which isn't optimal (especially when you
+     consider longer lines of text, or even whole pages..).
+  </p>
+
+  <hr>
+    
+  <h3>
+    6. Accessing metrics in design font units, and scaling them:
+  </h3>
+
+  <p>Scalable font formats usually store a single vectorial image, called
+     an "outline", for each in a face. Each outline is defined in an abstract
+     grid called the "design space", with coordinates expressed in nominal
+     "font units". When a glyph image is loaded, the font driver usually
+     scales the outline to device space according to the current character
+     pixel size found in a <tt>FT_Size</tt> object. The driver may also
+     modify the scaled outline in order to significantly improve its
+     appearance on a pixel-based surface (a process known as "hinting"
+     or "grid-fitting").</p>
+     
+  <p>This chapter describes how design coordinates are scaled to device
+     space, and how to read glyph outlines and metrics in font units. This
+     is important for a number of things:</p>
+     
+  <ul>
+    <li><p>
+      In order to perform "true" WYSIWYG text layout
+    </p></li>
+    
+    <li><p>
+      In order to access font content for conversion or analysis purposes
+    </p></li>
+  </ul>
+
+  <h4>a.Scaling distances to device space:</h4>
+  
+  <p>Design coordinates are scaled to device space using a simple scaling
+     transform, whose coefficients are computed with the help of the
+     <em><b>character pixel size</b></em>:</p>
+     
+  <pre><font color="purple">
+     device_x = design_x * x_scale
+     device_y = design_y * y_scale
+
+     x_scale  = pixel_size_x / EM_size
+     y_scale  = pixel_size_y / EM_size
+  </font></pre>
+
+  <p>Here, the value <b><tt>EM_size</tt></b> is font-specific and correspond
+     to the size of an abstract square of the design space (called the "EM"),
+     which is used by font designers to create glyph images. It is thus
+     expressed in font units. It is also accessible directly for scalable
+     font formats as <tt><b>face->units_per_EM</b></tt>. You should
+     check that a font face contains scalable glyph images by using the
+     <tt><b>FT_IS_SCALABLE(face)</b></tt> macro, which returns true when
+     appropriate.</p>
+
+  <p>When you call the function <tt><b>FT_Set_Pixel_Sizes</b></tt>, you're
+     specifying the value of <tt>pixel_size_x</tt> and <tt>pixel_size_y</tt>
+     you want to use to FreeType, which will immediately compute the values
+     of <tt>x_scale</tt> and <tt>y_scale</tt>.</p>
+
+  <p>When you call the function <tt><b>FT_Set_Char_Size</b></tt>, you're
+     specifying the character size in physical "points", which is used,
+     along with the device's resolutions, to compute the character pixel
+     size, then the scaling factors.</p>
+
+  <p>Note that after calling any of these two functions, you can access
+     the values of the character pixel size and scaling factors as fields
+     of the <tt><b>face->size->metrics</b></tt> structure. These fields are:</p>
+     
+  <center>
+  <table width="80%" cellpadding="5"><tr valign=top><td>
+  <b><tt>x_ppem</t></b>
+  </td><td>
+  <p>Which stands for "X Pixels Per EM", this is the size in integer pixels
+  of the EM square, which also is the <em>horizontal character pixel size</em>,
+  called <tt>pixel_size_x</tt> in the above example.</p>
+  </td></tr><tr valign=top><td>
+  <b><tt>y_ppem</tt></b>
+  </td><td>
+  <p>Which stands for "Y Pixels Per EM", this is the size in integer pixels
+  of the EM square, which also is the <em>vertical character pixel size</em>,
+  called <tt>pixel_size_y</tt> in the above example.</p>
+  </td></tr><tr valign=top><td>
+  <b><tt>x_scale</tt></b>
+  </td><td>
+  <p>This is a 16.16 fixed float scale that is used to directly
+  scale horizontal distances from design space to 1/64th of device pixels.
+  </p>
+  </td></tr><tr valign=top><td>
+  <b><tt>y_scale</tt></b>
+  </td><td>
+  <p>This is a 16.16 fixed float scale that is used to directly scale
+  vertical distances from design space to 1/64th of device pixels.</p>
+  </td></tr>
+  </table>
+  </center>
+
+  <p>Basically, this means that you can scale a distance expressed in
+     font units to 26.6 pixels directly with the help of the <tt>FT_MulFix</tt>
+     function, as in:</p>
+     
+  <pre><font color="blue">
+      <font color="gray">// convert design distances to 1/64th of pixels
+      //</font>
+      pixels_x = FT_MulFix( design_x, face->size->metrics.x_scale );
+      pixels_y = FT_MulFix( design_y, face->size->metrics.y_scale );
+  </font></pre>
+  
+  <p>However, you can also scale the value directly with more accuracy
+     by using doubles and the equations:</p>
+     
+  <pre><font color="blue">
+      FT_Size_Metrics*  metrics = &face->size->metrics;    // shortcut
+      double            pixels_x, pixels_y;
+      double            em_size, x_scale, y_scale;
+
+      <font color="gray">// compute floating point scale factors
+      //</font>
+      em_size = 1.0 * face->units_per_EM;
+      x_scale = metrics->x_ppem / em_size;
+      y_scale = metrics->y_ppem / em_size;
+      
+      <font color="gray">// convert design distances to floating point pixels
+      //</font>
+      pixels_x = design_x * x_scale;
+      pixels_y = design_y * y_scale;
+  </font></pre>
+  
+  <h4>
+    b. Accessing design metrics (glyph & global):
+  </h4>
+  
+  <p>You can access glyph metrics in font units simply by specifying the
+     <tt><b>FT_LOAD_NO_SCALE</b></tt> bit flag in <tt>FT_Load_Glyph</tt>
+     or <tt>FT_Load_Char</tt>. The metrics returned in
+     <tt>face->glyph->metrics</tt> will all be in font units.</p>
+  
+  <p>You can access unscaled kerning data using the
+     <tt><b>ft_kerning_mode_unscaled</b></tt> mode</p>
+
+  <p>Finally, a few global metrics are available directly in font units
+     as fields of the <tt>FT_Face</tt> handle, as described in chapter 3
+     of this section.</p>
+     
+  <hr>
+  
+  <h3>
+    Conclusion
+  </h3>
+  
+  <p>This is the end of the second section of the FreeType 2 tutorial,
+     you're now able to access glyph metrics, manage glyph images, and
+     render text much more intelligently (kerning, measuring, transforming
+     & caching).</p>
+  
+  <p>You have now sufficient knowledge to build a pretty decent text service
+     on top of FreeType 2, and you could possibly stop there if you want.</p>
+  
+  <p>The next section will deal with FreeType 2 internals (like modules,
+     vector outlines, font drivers, renderers), as well as a few font format
+     specific issues (mainly, how to access certain TrueType or Type 1 tables).
+     </p>
+</td></tr>
+</table>
+</center>
+
+</body>
+</html>