ref: b190572be574f04b46bb28b77dc53f44a462a588
parent: 5fe4c00ed29e6d85f348a79d2dfd9ea8f9a88b27
author: David Turner <david@freetype.org>
date: Wed Jul 26 15:07:15 EDT 2000
updated documentation
--- /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 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 < 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 < 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>
+ © 2000 David Turner
+ (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
+ © 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 <freetype/ftglyph.h>
+ </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 < 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 < 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 < 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 < bbox.xMin)
+ bbox.xMin = glyph_bbox.xMin;
+
+ if (glyph_bbox.yMin < bbox.yMin)
+ bbox.yMin = glyph_bbox.yMin;
+
+ if (glyph_bbox.xMax > 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 < 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 < 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 < num_glyphs; n++ )
+ {
+ FT_BBox glyph_bbox;
+
+ FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox );
+
+ if (glyph_bbox.xMin < bbox.xMin)
+ bbox.xMin = glyph_bbox.xMin;
+
+ if (glyph_bbox.yMin < bbox.yMin)
+ bbox.yMin = glyph_bbox.yMin;
+
+ if (glyph_bbox.xMax > 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 < 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 < 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 <= 0 || bbox.xMin >= my_target_width ||
+ bbox.yMax <= 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>