Google Git
Sign in
skia / third_party / freetype2 / refs/tags/VER-2-0-1 / . / docs / ft2faq.html
blob: 2442395e71af6273061fd9875a9aed4cf614d69f [file] [log] [blame]
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>FreeType 2 FAQ</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<font size=1>http://www.freetype.org</font><p>
<h1 align=center>
<a href="freetype.html">
<img src="image/freetype.jpg"
width=550 height=105
alt="The FreeType Project"
border=0></a>
<h1>The FreeType&nbsp;2 FAQ</h1>
</h1>
<center>
<table width="75%">
<tr><td>
<hr><p>
Document index
<ul>
<li><a href="#general">General</a>
<ul><p>
<li>
<a href="#general-dead">I thought the FreeType project was dead.
Is this true?</a>
</li>
<li>
<a href="#general-long">Why did it take so long to release
FreeType&nbsp;2?</a>
</li>
<li>
<a href="#general-unix">Is FreeType&nbsp;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&nbsp;2 backwards compatible
to FreeType&nbsp;1.x?</a>
</li>
<li>
<a href="#general-edit">Can I use FreeType&nbsp;2 to edit fonts
or create new ones?</a>
</li>
</p></ul>
</li>
<li><a href="#builds">Compilation & Configuration</a>
<ul><p>
<li>
<a href="#builds-compile">How do I compile the FreeType&nbsp;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&nbsp;2 files
in a single directory?</a>
</li>
</p></ul>
</li>
<li>
<a href="#autohint">The FreeType&nbsp;2 autohinter</a>
<ul><p>
<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&nbsp;2?</a>
</li>
<li>
<a href="#autohint-cjk">Why doesn't the auto-hinter work well
with CJK fonts?</a>
</li>
</p></ul>
</li>
<li>
<a href="#other">Other questions</a>
<ul><p>
<li>
<a href="#other-color">How can I set the color of text rendered
by FreeType?</a>
</li>
<li>
<a href="#other-depth">Can I use FreeType to draw text on a pixmap
with arbitrary depth?</a>
</li>
<li>
<a href="#other-size">I set the pixel size to 8x8, but the
resulting glyphs are larger than that. Why?</a>
</li>
<li>
<a href="#other-bbox">How can I compute the bounding box of a text
string without loading its glyphs?</a>
</li>
<li>
<a href="#other-antialias">Which anti-aliasing algorithm is
used in the FreeType&nbsp;2 renderer?</a>
</li>
<li>
<a href="#other-opentype">When will FreeType&nbsp;2 support
OpenType?</a>
</li>
</p></ul>
</li>
</ul>
<p><hr></p>
<table width="100%">
<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>
<p>Well, not exactly&nbsp;:-) 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&nbsp;1.x, and started
developing FreeType&nbsp;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>
<hr>
<a name="general-long">
<h3>
I.2 Why did it take so long to release FreeType&nbsp;2?
</h3>
<p>Several factors come to mind. The first one is that FreeType&nbsp;2
is a much more complex and dense project that was mostly developed
during 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&nbsp;:-)</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 are now distributing as
FreeType&nbsp;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 will
continue to as long as the specifications are available and that we find
an interest in it. For example, FreeType&nbsp;2 is to date the only
software library available on the market that supports the new Adobe
"CEF" font format.</p>
<hr>
<a name="general-unix">
<h3>
I.3 Is FreeType&nbsp;2 a Unix-only project?
</h3>
<p>Absolutely not, even though many people still seem to think
so&nbsp;:-) FreeType&nbsp;2, just like version&nbsp;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 developed 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>
<hr>
<a name="general-x11">
<h3>
I.4 When will X11/XFree support anti-aliased text?
</h3>
<p>This question isn't exactly related to FreeType as we have no direct
connection to the XFree people, but we have been asked so frequently
about it that it deserves a prominent place in this FAQ&nbsp;:-)</p>
<p>FreeType has been capable of anti-aliasing since version&nbsp;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>
X11 assumes that all glyph images are monochrome bitmaps, hence the
X&nbsp;font library and server are unable to send anything else to
the X&nbsp;server.
</li>
<li>
Even if the X&nbsp;font library/server was able to generate
anti-aliased bitmaps (and this has been already done through
extensions), the X&nbsp;rendering model doesn't allow translucent
composition of "gray" pixmaps onto an arbitrary drawable.
</li>
</ul>
<p>As both the font and rendering models of X11 are limited, it is
basically impossible to draw anti-aliased glyphs without performing
<em>huge</em> hacks within the server.</p>
<p>Note that Keith Packard, from XFree86 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 whether
legacy X applications will be able to display anti-aliased text is still
very uncertain.</p>
<hr>
<a name="general-ft1">
<h3>
I.5 Is FreeType&nbsp;2 backwards compatible with FreeType&nbsp;1.x?
</h3>
<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 independently on any system
(read: no namespace conflicts).</p>
<p>The FreeType&nbsp;2 API is a lot simpler than the one in&nbsp;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>
<hr>
<a name="general-edit">
<h3>
I.6 Can I use FreeType&nbsp;2 to edit fonts or create new ones?
</h3>
<p>The answer is a definitive <b>no</b>, 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 axes of development for this project
(like text-layout capabilities, glyph caching, etc.) that may be more
important to us at the moment.</p>
</td></tr>
</table>
<br>
<table width="100%">
<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&nbsp;2 library?
</h3>
<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 will summarize the process to a few cases:</p>
<h4>
a. Using the command-line&nbsp;2 build system
</h4>
<p>The engine comes with a sophisticated build system that is used to
configure and compile a build of the library. You will need <em>GNU
Make</em> installed on your platform (<b>Note:</b> It will
<em>not</em> work with other Make tools).</p>
<p>Basically, you will need to invoke <tt>make</tt> a first time in
the top-level FreeType&nbsp;2 directory in order to set up 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&nbsp; C++
compiler
</li>
<li>
<b><tt>make lcc</tt></b> will select the Win32-lcc compiler
</li>
</ul>
<p>Note that on Unix, when 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 will 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>
<h4>
b. Direct compilation
</h4>
<p>You can also directly compile the library from the command line by
using these simple rules:</p>
<ul>
<li>
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).
</li>
<li>
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.
</li>
<li>
Each component is normally compiled through a single C file that
<em>wraps</em> other sources in the component's directory. For
example, you should build the TrueType font driver by compiling
the file <tt>src/truetype/truetype.c</tt>. The list of
C&nbsp;files to compile for a feature-complete build of the
library is given in the <tt>BUILD</tt> document.
</li>
</ul>
<h4>
c. Using a graphical IDE
</h4>
<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>
<hr>
<a name="builds-config">
<h3>
II.2 How do I configure my build of the library?
</h3>
<p>Each build of the library is configured through two header files
located in <tt>include/freetype/config</tt>:</p>
<ul>
<li>
<tt>ftoption.h</tt>
<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.
</li>
<li>
<tt>ftmodule.h</tt>
<br>
This file contains the list of all the modules that are initially
registered (added) when the function <tt>FT_Init_FreeType()</tt> is
called. See the next answer to know how to change it and why it may
be important.
</li>
</ul>
<p>Alternatively, some specific implementations of some FreeType&nbsp;2
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>
<hr>
<a name="builds-modules">
<h3>
II.3 How do I select the modules I need in my build?
</h3>
<p>The function <tt>FT_Init_FreeType()</tt> creates a new instance of
the FreeType&nbsp;2 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>.
Normally, it is automatically generated by the build system by invoking
the "<tt><b>make modules</b></tt>" command in the top level
FreeType&nbsp;2 directory (Note: this 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
initialization sequence. For example, one could do something like:</p>
<ul>
<li>
Compile each module as a shared library (DLL or <tt>.so</tt>) 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).
</li>
<li>
Place these modules in a directory like
<tt>/usr/lib/freetype2/modules/</tt>.
</li>
<li>
Provide an implementation of <tt>ftinit.c</tt> that would scan the
directory for valid modules.
</li>
</ul>
<p>This example only emphasizes the flexibility that is left to
developers when building the library.</p>
<hr>
<a name="builds-flat">
<h3>
II.4 How do I compile all FreeType&nbsp;2 files in a single
directory?
</h3>
<p>Some projects may need, for the sake of simplicity or ease of
building, to compile the FreeType&nbsp;2 library with all source files
copied to a single directory. This is possible.</p>
<p>To do so, you have 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&nbsp;2
component with the macro <tt>FT_FLAT_COMPILE</tt>. This will change the
way <tt>#include</tt> works during the build.</p>
</td></tr>
</table>
<br>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="autohint">The FreeType&nbsp;2 auto-hinter
</h2>
</td></tr>
<tr><td>
<a name="autohint-license">
<h3>
III.1 Under which license is the FreeType&nbsp;2 auto-hinter released?
</h3>
<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>
<hr>
<a name="autohint-work">
<h3>
III.2 How does the auto-hinter work?
</h3>
<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&nbsp;:-)</p>
<p>To give a few details, the auto-hinter is used to perform
grid-fitting on scalable font formats that use B&eacute;zier outlines as
their primary glyph image format (this means nearly all scalable font
formats today). If a given font driver doesn't provide its own hinter,
the auto-hinter is used by default. If a format-specific hinter is
provided, it is still possible to use the auto-hinter using the
<tt>FT_LOAD_FORCE_AUTOHINT</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&nbsp;1/Type&nbsp;2 fonts, for example.</p>
<hr>
<a name="autohint-cjk">
<h3>
III.3 Why does the auto-hinter doesn't work correctly with CJK
fonts?
</h3>
<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 in the near future. Please be
patient.</p>
</td></tr>
</table>
<br>
<table width="100%">
<tr bgcolor="#CCCCEE"><td>
<h2 align=center>
<a name="other">Other questions
</h2>
</td></tr>
<tr><td>
<a name="other-depth">
<h3>
IV.1 Can I use FreeType to draw text on a pixmap with arbitratry depth?
</h3>
<p>Not directly, as FreeType is a font library, not a general purpose
graphics library or text rendering service. However, note that the
anti-aliased renderer allows you to convert a vectorial glyph outline
into a list of "spans" (i.e. horizontal pixel segments with same
coverage) that can be rendered through user-provided callbacks.</p>
<p>By providing the appropriate span callback, you can render
anti-aliased text to any kind of surface. You can also use any color or
fill pattern/image if you want to. This process is called <em>direct
rendering</em>. For more information, please read the documentation
contained in the following files:</p>
<ul>
<li>
<p><tt>&lt;freetype/ftimage.h&gt;</tt> contains the definition of
the <tt>FT_Raster_Params</tt> type used with direct rendering.</p>
</li>
<li>
<p><tt>&lt;freetype/ftoutln.h&gt;</tt> contains the definition of
the <tt>FT_Outline_Render()</tt> function that can be used to
convert vectorial outlines to span lists.</p>
</li>
</ul>
<p>Here's some code that uses them:</p>
<font color="blue"><pre>
FT_Raster_Params params;
FT_Outline outline;
... load vectorial glyph in "outline" ...
params.flags = ft_raster_flag_aa | ft_raster_flag_direct;
params.gray_spans = (FT_Raster_Span_Func)your_own_span_function_here;
params.user = your_own_data_pointer;
error = FT_Outline_Render( library, &amp;outline, &amp;params );</pre>
</font>
<p>Note that direct rendering is <em>not</em> available with monochrome
output, as the current renderer uses a two-pass algorithm to generate
glyphs with correct drop-out control.</p>
<hr>
<a name="other-color">
<h3>
IV.2 How can I set the color of text rendered by FreeType?
</h3>
<p>Basically, you can't do that, because FreeType is simply a font
library. In general, you will need to use your favorite graphics
library to draw the FreeType glyphs with the appropriate color.</p>
<p>Note that for anti-aliased glyphs, you can "set the color" by using
<em>direct rendering</em> as described in <a href="#other-depth">this
answer</a>.</p>
<hr>
<a name="other-size">
<h3>
IV.3 I set the pixel size to 8x8, but the resulting glyphs are larger
(or smaller) than that. Why?
</h3>
<p>A lot of people have difficulties to understand this topic, because
they think of glyphs as fixed-width resp. fixed-height "cells", like
those of fonts used in terminals/consoles. This assumption is simply
not valid with most "modern" font formats, even bitmapped-based ones
like <tt>PCF</tt> or <tt>BDF</tt>.</p>
<p>Be aware that the <em>character size</em> that is set either through
<tt>FT_Set_Char_Size()</tt> or <tt>FT_Set_Pixel_Sizes()</tt> isn't
directly related to the dimension of the glyph bitmaps generated.</p>
<p>Rather, the character size is indeed the size of <em>an abstract
square</em>, called the <em>EM</em>, used by typographers to design
fonts. Scaling two distinct fonts to the same character size, be it
expressed in points or pixels, will generally result in bitmaps with
<em>distinct dimensions</em>!</p>
<p>Note that historically, the EM corresponded to the width of a capital
"M" in Latin typefaces. However, later improvements in typography led
to designs that greatly detract from this rule. Today, it is not
possible to connect the EM size to a specific font "feature" in a
reliable way.</p>
<hr>
<a name="other-bbox">
<h3>
IV.4 How can I compute the bounding box of a given string of text
without loading its glyphs before?
</h3>
<p>A lot of people want to be able to compute the size in pixels of a
simple string of text with minimal overhead. For example, that can be
useful to draw centered text within a button. (to be continued...)</p>
<hr>
<a name="other-antialias">
<h3>
IV.5 Which anti-aliasing algorithm is used by FreeType&nbsp;2?</h3>
<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 no sub-sampling/filtering.</p>
<p>However, these two implementations are radically distinct and use
vastly different models. The FreeType&nbsp;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 FreeType&nbsp;2 anti-aliasing renderer is indeed <em>faster</em>
than the monochrome renderer for small character sizes (typically
&lt;20&nbsp;pixels). The reason is that the monochrome renderer must
perform two passes on the outline in order to perform drop-out control
according to the TrueType specification (we could drop this requirement
later though).</p>
<p>We will try to document its design in a later document, though this
is not a priority for now.</p>
<hr>
<a name="other-opentype">
<h3>
IV.6 When will FreeType&nbsp;2 support OpenType?
</h3>
<p>Well, the engine already reads OpenType/CFF files perfectly. What it
doesn't do is handle "OpenType Layout" tables yet.</p>
<p>FreeType&nbsp;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> to show its capabilities.</p>
<p>For FreeType&nbsp;2, we have decided that the layout operations
provided through these tables are better placed in a specific
text-layout library, (many people having asked for such a thing). This
new engine will not depend on FreeType2 explicitly 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&nbsp;release of FreeType has been
made.</p>
</td></tr>
</table>
<p><hr></p>
<a href="index.html">Back to FreeType homepage</a><p>
</td></tr>
</table>
</body>
</html>